@maccesar/titools 5.2.5 → 5.3.0

package/skills/ti-synthengine/references/sound-design.md

@@ -1,4 +1,4 @@
-> Source snapshot: official TiSynthEngine documentation at commit `ec04f4e634075c41b55f66279eabcd78b9652d58` (2026-11-02). Published module 1.1.0; public API 1.1.0. Upstream `documentation/sound-design.md` SHA-256: `ac3f4552065051bc5291d8838945ed256ad3b0da7857e1f1cb5f54f5962ebfae`.
+> Source snapshot: official TiSynthEngine documentation at commit `9d74aa45f84d3f2822d4aab76874efe37d81257f` (2026-11-03). Published module 2.0.0. Upstream `documentation/sound-design.md` SHA-256: `41f294143b8a4bb8cbee550a66b51768c13a583c94e1f7f810dfdeb471f14922`.
 
 # Sound design with TiSynthEngine
 
@@ -67,7 +67,7 @@ Equal temperament keeps intervals consistent in every key. It also means a major
 
 ## Waveform and timbre
 
-Pitch says how fast the oscillator repeats. Waveform says how it moves within each cycle, which determines the harmonic content and perceived timbre.
+Pitch describes how fast the oscillator repeats. Waveform describes its motion within each cycle, which determines the harmonic content and perceived timbre.
 
 ### Sine
 
@@ -79,7 +79,7 @@ Pitch says how fast the oscillator repeats. Waveform says how it moves within ea
 
 ### Sawtooth
 
-`SAWTOOTH` contains both even and odd harmonics. It is the densest pitched waveform in the module and reads as buzzy or brassy. Use it for alarms, arcade leads and short sweeps. Square and sawtooth are band-limited with PolyBLEP to reduce aliasing at discontinuities.
+`SAWTOOTH` contains both even and odd harmonics. It is the densest pitched waveform in the module and sounds buzzy or brassy. Use it for alarms, arcade leads and short sweeps. Square and sawtooth are band-limited with PolyBLEP to reduce aliasing at discontinuities.
 
 ### Triangle
 
@@ -235,7 +235,7 @@ A rate around 4 to 7 Hz with a small depth sounds like musical vibrato. A fast r
 
 `filterType` adds a filter that removes or emphasizes part of the spectrum. It has 12 dB per octave of slope, twice as steep as the one-pole `lowPassHz` filter, and can be combined with it (`lowPassHz` runs first).
 
-- `lowpass` darkens the sound. A sawtooth through a closing low-pass reads as a zap or a sound moving away; an opening one reads as a swell.
+- `lowpass` darkens the sound. A sawtooth through a closing low-pass sounds like a zap or a sound moving away; an opening one sounds like a swell.
 - `highpass` thins the sound by removing body. It makes hats, hiss and tinny effects out of noise.
 - `bandpass` keeps one band around `filterHz`, which gives vocal, nasal and wah-like colors.
 
@@ -264,7 +264,7 @@ synth.playTone({
 
 FM makes rich, bright and metallic sounds from a plain sine. A second sine, the modulator, bends the pitch of the first one, the carrier. Turn it on with `fmDepth` or `fmDepthEnd`, on a `SINE` voice.
 
-- `fmRatio` is the modulator frequency as a multiple of the carrier's. Whole numbers (1, 2, 3) keep the added overtones on the harmonic series, so the pitch stays clear and the sound reads as organ- or piano-like. Fractional ratios such as 1.4142 or 3.5 put the overtones between harmonics, which reads as bells, glass and metal.
+- `fmRatio` is the modulator frequency as a multiple of the carrier's. Whole numbers (1, 2, 3) keep the added overtones on the harmonic series, so the pitch stays clear and the sound resembles an organ or piano. Fractional ratios such as 1.4142 or 3.5 put the overtones between harmonics, giving the sound the character of bells, glass and metal.
 - `fmDepth` is the modulation index and works like a brightness control. Around 0.5 to 1.5 it warms a sine, 2 to 5 makes it bright and rich, and values near 10 get harsh.
 - `fmDepthEnd` moves the index over the event. Starting high and ending low gives a bright attack that mellows, which is the signature of electric pianos, bells and mallets. Pair it with `decay` so the level falls with the brightness.
 
@@ -341,7 +341,7 @@ Different phones have different sample rates, speaker protection and acoustic re
 
 ## Recipes
 
-These recipes use only the 1.0.0 contract and keep explicit envelopes valid. Adjust pitch and volume to fit the app's other audio; the recipe values are starting points, not mastering targets.
+These recipes use the supported direct native parameter contract and keep explicit envelopes valid. Reusable definitions put synthesis fields in `sound` and pitches/timing in `playback`; see the [Sound interface](sound-api.md). Adjust pitch and volume to fit the app's other audio; the recipe values are starting points, not mastering targets.
 
 ### Interface click
 
@@ -593,7 +593,7 @@ synth.playTone({
 })
 ```
 
-The pitch drop is the punch and the decay is the thump. A phone speaker cannot reproduce 42 Hz, so raise `frequencyEnd` toward 70 for speaker playback.
+The pitch drop creates the punch, while the decay shapes the thump. A phone speaker cannot reproduce 42 Hz, so raise `frequencyEnd` toward 70 for speaker playback.
 
 ### Simon-style cues
 

package/skills/ti-synthengine/references/source-notes.md

@@ -1,172 +1,62 @@
-# Maintaining the synthesis snapshot
-
-These references cover **published module 1.1.0 with public API 1.1.0**. Older 1.0.2 packages retain API 1.0.0 and lack attack variation and finite-tone repetition. All sixteen official Markdown documents were reviewed; fourteen are mirrored into fifteen parts, with explicit index/notices exclusions. The snapshot anchors committed official sources at `ec04f4e634075c41b55f66279eabcd78b9652d58`: official prose corrections remove a stale local-package label and statistics-method count and document the verified native interval edge. Those documentation corrections are committed and pushed to official main; the already published 1.1.0 ZIPs retain their original documentation. Exact source/mirror hashes are in [source-snapshot.json](source-snapshot.json). Review date: 2026-11-02.
-
-## Public downloads and artifact provenance
-
-Both public 1.1.0 platform releases target `7cd035409453b01df2736aef56f2316d94ca019c`. Their ZIPs were downloaded on 2026-11-02; SHA-256 matches the GitHub asset digests and full ZIP CRC checks pass. Manifests declare module 1.1.0, minimum Titanium 13.2.0.GA, four Android ABIs and Apple Mac Catalyst support. Packaged `index.d.ts` files match the official source and the bundled [declaration asset](../assets/index.d.ts) byte for byte. Native manifest `apiversion` is separate from JavaScript `apiVersion`. No binary was installed on a device during this update.
-
-| Platform | Current public release | Package SHA-256 |
-| --- | --- | --- |
-| Android | [android-1.1.0](https://github.com/macCesar/TiSynthEngine/releases/tag/android-1.1.0) | `69dea7daaa8b5dd77f7a3d4d6e6ad801e2a0bd48f9e2c79b9caf584dd56e36eb` |
-| iOS / Mac Catalyst | [ios-1.1.0](https://github.com/macCesar/TiSynthEngine/releases/tag/ios-1.1.0) | `c426fed49d78926f8dd4e176addaebf0cb0fe4592c5eb48c842aef833ad798b4` |
-
-### Historical 1.0.2 artifact verification
-
-The following replacement packages were downloaded and verified on 2026-10-30 UTC (2026-10-29 locally). Their checks remain historical evidence; they are not the current 1.1.0 downloads.
-
-| Platform | Published release | Replacement package SHA-256 |
-| --- | --- | --- |
-| Android | [android-1.0.2](https://github.com/macCesar/TiSynthEngine/releases/tag/android-1.0.2) | `8698104f188782a77699fbd6308a779ca0b190833ceebf398557b628af1b8bbe` |
-| iOS / Mac Catalyst | [ios-1.0.2](https://github.com/macCesar/TiSynthEngine/releases/tag/ios-1.0.2) | `779e77d018d5b3f686d69cb1b4b0162281803ea12691487df565c1fd15175c58` |
-
-Both ZIPs passed full CRC checks and matched the GitHub asset SHA-256 digests at that verification. These hashes replace the original 1.0.2 packages' hashes; filenames and
-release URLs did not change. Manifests report module `ti.synthengine`, version
-`1.0.2`, minimum Titanium `13.2.0.GA`, four Android ABIs and Apple Mac Catalyst
-support. The manifest's native `apiversion` field is distinct from the JavaScript
-1.0.2 contract's `apiVersion: '1.0.0'`.
-
-All eight Android native libraries (inside the AAR) and three Apple static
-libraries match the preserved original 1.0.2 release packages byte for byte.
-Corrected guide, example and platform README HTML was inspected in both new
-packages. Source/package checks do not constitute a fresh device installation or
-listening acceptance. See the [guide](guide.md) for API35/iOS15 requirements,
-app-root ZIP installation and both `tiapp.xml` declarations.
-
-## Sources and permitted transformations
-
-Fourteen official Markdown documents are mirrored into fifteen parts, including the ordered examples/advanced-examples split. New references preserve the complete [instruments/effects guide](instruments-and-effects.md), [implemented variation contract](native-variation.md), [historical proposal](native-variation-proposal.md) and [variation verification](native-variation-validation.md). The proposal is historical design context, not an outstanding implementation plan. The current snapshot inventories all
-complete JSON reports, bundled example assets and linked raw-evidence archives.
-The historical [performance review](performance-review.json) and its raw archive are
-preserved alongside historical reports; none is replaced by a favorable summary.
-Read snapshot records for exact counts and hashes. Example JavaScript and raw
-reports/archives remain byte-identical to source.
-
-Each Markdown part and the example README have a committed-source provenance header and recorded navigation transformations. Verified API, timing, spatial, panic, processing and diagnostic corrections were applied to the official module documentation before synchronization. They are shared source content, not mirror-only errata. Remaining `link_fixes` record navigation and curated entry points; the source hash identifies the exact reviewed official text, including the committed prose corrections. Reversible `link_fixes` rebase links into the split advanced examples, preserve [curated recipes](recipes.md), and resolve current example links to bundled assets. The example README points back to this skill's current API and guides. All three example JavaScript files remain byte-identical to source; none requires a historical GitHub snapshot.
-
-The fidelity regression strips provenance/navigation, concatenates example parts, reverses declared transformations and compares the complete source hash. Raw records must remain byte-identical. Update transformations intentionally; never change hashes merely to hide unexplained source drift.
-
-## Protected curated content
-
-[Retro recipes](recipes.md) and [interaction/instrument recipes](recipes-interaction.md) are TiTools contributions. Preserve their acoustic intent, lifecycle ownership and entry links when upstream docs change. Their native sequence examples keep the original millisecond onsets and total envelopes through separate `duration` and `length`; no JavaScript timer schedules notes. The repeated chord is now one centered native chord sequence; the separate one-off layered chord retains its per-voice stereo pans.
-
-Focused executable recipe tests inspect submitted intervals, envelope lengths, pitch and cancellation IDs. They do not render audio or measure native callback timing.
-
-## Current contract and acceptance boundaries
-
-`start` configures one engine, up to 32 shared voices and one to four preallocated sequence slots. `playSequence` schedules scores and returns a positive sequence ID or zero. `repeatTone` preserves the complete finite renderer for one repeating recipe and returns a positive tone ID or zero; its 32 slots are independent of the sequence slots, while admitted attacks share the voice pool. Sequence edits, state queries and cancellation name that ID. Global `setTempo` governs beat timing and synchronized modulation; millisecond sequences retain fixed times. Finite playback is the default, and circular patterns explicitly opt into looping.
-
-Selective `music`, `effects`, `ui` and `ambience` categories feed one shared effect chain; an explicit per-voice send overrides category selection. Live spatial position, noise clock, low-pass cutoff and compatible continuous voice controls ramp over 10 ms while preserving history. Priorities protect higher-priority voices without reserved quotas. See the [API](api.md) for exact limits, source compatibility, return values and event delivery.
-
-### Module 1.0.1 and 1.0.2 corrections
-
-Michael Gangolf's [Android PR #1](https://github.com/macCesar/TiSynthEngine/pull/1)
-updates Oboe to 1.11.0, recovers closed streams after all stream errors, keeps a
-single demand-driven sequence-event poll chain and shuts down on root activity
-destruction. Removing the unused Java Thread inheritance changes no public API.
-The subsequent Apple correction polls only while sequence events or held-voice
-metadata need retirement and guards shutdown/restart reentry. Neither poller is
-a musical scheduler; explicit engine ownership/teardown remains required.
-
-Module 1.0.2 shares final output processing in `shared/synth_output.h`: zero
-retained samples, immediate stereo-linked sample protection, ceilings 0.85/0.70,
-100 ms exponential recovery and reset after two consecutive quiet stereo frames.
-Master volume ramps linearly over 10 ms on both platforms, independently of the
-protector. The iOS `raw` startup correction now applies its documented gain;
-existing raw mixes need review. Overload changes the waveform, and sample
-ceilings do not certify inter-sample peaks or speaker behavior.
-
-[Pipeline validation](audio-pipeline-validation.md) preserves the new production
-callback/CI checks, five-rate output comparisons and physical scope. Preset
-calibration measures both renderers and six scenarios at 1/2/4/8/16/32 voices;
-fixed-gain recommendations target the measured 1–8-voice configuration, with
-16/32 kept as stress diagnostics. It never edits Studio. The Android startup
-underrun remains unresolved, including independent silent Oboe reproduction.
-Route-wide latency, Bluetooth and extended maximum-load acceptance remain open.
-
-Official documentation corrections preserve panic cancellation (`stopAll` stops every
-sequence and invalidates effect histories), compatible live `updateVoice`
-noise/low-pass/spatial/send edits, and category selection with `applyTo` plus
-explicit `effectSend` overrides. The matching mirror-only errata were removed from the transformation list; curated recipe navigation remains reversible.
-Android and Apple production callback tests now run in CI; the historical Java
-DSP model is not the production audio oracle. No native binaries were installed
-or device/listening tests rerun during this skill update.
-
-### Historical evidence
-
-The [performance review](performance-review.json) documents the accepted
-control-thread changes: partial sequence-bank preparation and removal of idle
-allocations/orphan held-position metadata. The Apple rendering bundle was
-rejected after a physical stereo regression, and production returned to the
-stable callback. Earlier candidate timings and fidelity checks remain evidence
-of that rejected candidate, not a promised Apple render speedup. Current matched
-Apple bypass measurements and actual hardware/rate/block-size scope are in the
-report; global performance acceptance remains open.
-
-Historical statistics, Studio/unified transport, physical/Frontier measurements
-and Android FIR8 correction reports keep their original artifact and acceptance
-boundaries. The short Android Sim80 headphone result had zero backend xruns and
-accepted listening; it does not close the distinct ten-minute maximum-load,
-bypass, memory and strict Frontier presentation criteria. Current evidence and
-rejected candidates must not be combined into a general pass. This skill update
-did not rerun devices, install binaries or alter native source.
-
-The native differences below were rechecked against current sources on November 2 and are now documented accurately in the official API/engine guides as well as the mirrors. They describe implementation differences, not unresolved documentation contradictions:
-
-- iOS timed tone/chord command construction initially rounds accepted zero attack
-  and release to one sample before duration-budget trimming; Android preserves zero. Validator
-  acceptance does not establish identical sample envelopes.
-- iOS early tempo/sequence/processing rejections and incompatible held spatial/
-  modulation edits can bypass rejection counters. Android also leaves some
-  unknown/retired sequence-stop returns uncounted. The recorded reason sum is
-  consistent with recorded totals, not a complete API-call rejection tally.
-- Sequence cutoff coefficients currently refresh every 16 samples on Android
-  and every 8 samples on Apple; both use note length but do not promise identical
-  sample output. See [engine details](audio-engine.md).
-- Published 1.1.0 returns `capabilities.variation: true` and `variationSchemaVersion: 1` on both platforms. Android also reports native sequence/master processing/modulation flags and `limits.stepDurationMs`; iOS omits those additional entries. Published 1.0.2 does not accept variation. Both platforms return sequence-capacity, priority and send limits; use the [API](api.md) for exact beat/millisecond ranges.
-- Official examples now bind their waveform constants and document native sequence modulation, complete effect fidelity and publication ownership correctly. The mirrors preserve the same facts.
-
-
-These are official-documentation and skill corrections, not native implementation fixes. No module code, public range or hardware acceptance was changed.
-A validator corpus establishes accepted/rejected dictionaries, not sample-identical
-rendering on a physical device. Current source-first coverage ledgers and native locators are recorded in the maintainer's November 2 audit evidence.
-
-## Published 1.1.0 attack variation
-
-Both platforms validate eight bounded parameter ranges and select once per admitted attack. Require the capability/schema pair and omit the property entirely on published 1.0.2, including amount zero. The [variation guide](native-variation.md) preserves exact bounds, linear amount, pitch ratio, source prerequisites, per-chord ordinals, held stability, whole-dictionary step replacement, revision merging and deterministic seed identity. `updateNote` and its deprecated `updateVoice` alias reject the attack dictionary. Preserve all of the authored envelope, cadence, routing and layer gains.
-
-The [verification report](native-variation-validation.md) separates initial host/build checks from later consumer installations and scoped listening feedback. It records the 144-byte configuration and four-transport growth from 8,627,712 to 9,537,152 bytes, excluding other engine/bridge/process storage. Earlier 1.0.2 memory reports remain historical. Host callback timings do not prove device overhead or sustained acceptance.
-
-The earlier variation audit reran the paired production validators (156 cases per platform). This repetition update ran the focused shared scheduler, Android production renderer, Java bridge, Apple exact-render host and Android tone contract checks, plus official documentation/example and TiTools mirror/recipe checks. New source inspection verified sampling/admission and sequence seed identity. Historical renderer PCM, native build, consumer install and listening results were read with their original boundaries; they were not repeated or expanded into general device acceptance. No native source or binary was changed.
-
-All thirteen raw JSON/ZIP records moved upstream from `documentation/` to `docs/validation/` without changing bytes. Their distributed skill paths are preserved; the snapshot now records their actual upstream locations. All five ZIPs passed CRC checks. The three example JavaScript assets remain byte-identical; `app.js` now includes the capability-gated attack-variation action.
-
-## Finite-tone repetition and compatibility
-
-Read the complete [API](api.md#finite-tone-repetition), [effect fidelity guide](instruments-and-effects.md) and [repetition verification](native-tone-repetition-validation.md). Require `capabilities.toneRepetition === true` and the three repetition methods before enabling controls. `playTone` remains Boolean standalone playback and rejects `intervalMs`; independent event-driven calls and deliberate finite JavaScript bursts are supported, with application-owned timer cleanup. Native repetition provides a sample-clock cadence independent of tempo.
-
-`repeatTone` requires integer `intervalMs` 1–60,000. `updateTone` validates partial changes merged with the latest accepted recipe, keeps the next deadline and applies the new interval after that attack. Active voices retain their admitted recipe. `stopTone` cancels future attacks at the next render block, even under ordinary queue saturation, and lets admitted finite voices finish. There is no `toneend`; IDs are never reused over shutdown/start. Global stop and shutdown invalidate repetitions. A positive ID does not guarantee every future attack is admitted; reserve for overlapping finite lifetimes and other sounds.
-
-Each repetition retains its own admitted-attack variation stream. A replacement variation dictionary replaces the whole prior dictionary; amount zero disables future variation, seed changes restart the stream, and rejected attacks do not consume a selection. The new report separately records 617,744 Android and 620,048 Apple transport bytes and scoped host measurements; earlier sequence/variation storage and device evidence do not measure repetition overhead.
-
-Use `updateNote` for current held-voice edits and `enableStats`/`disableStats` for current diagnostics. `updateVoice` and `setStatsEnabled` remain deprecated compatibility aliases, without scheduled removal or repeated runtime warnings. Older 1.0.2 binaries need method detection and their original aliases; never send new closed-dictionary fields speculatively.
-
-### Known native interval edge
-
-The documented interval contract requires an integer. Android rejects `intervalMs: 1.0000000001`; the reviewed Apple validator accepts it within its 1e-9 integer tolerance and command conversion truncates it to 1. This was independently reproduced against the production validators. Always submit exact integer milliseconds; do not rely on Apple's acceptance. This native edge remains unresolved: no native source or published binary was changed by the skill update. It is separate from the existing platform zero-envelope and diagnostic differences above.
-
-The declaration asset is a byte-identical official aid, not a runtime validator: TypeScript `number` cannot prove finite/integer/range constraints or native state/capacity. Its original candidate comment is preserved as source text, while current release provenance is recorded above. Preserve historical API 1.0.0 wording inside dated variation reports/proposals rather than relabeling their evidence as current acceptance.
-
-## Upstream documents outside the mirror set
-
-The official index is replaced by this skill's task routing. Dependency/license notices remain in the official module and binary packages. Both are recorded with hashes and reasons in `excluded_documents`, so changed or newly added documents still require review.
-
-## Verification after a reviewed update
-
-Run the focused mirror/link and recipe tests, then:
-
-```sh
-node scripts/verify-module-snapshot.mjs --source /path/to/TiSynthEngine --skill ti-synthengine
-```
-
-The verifier checks source/mirror hashes, exclusions, new documents, base HEAD and the exact tracked/untracked worktree fingerprint. Refresh that fingerprint only after the source changes are finished. No npm version, publication or native-device acceptance follows from this procedure.
+# Source and platform caveats
+
+These references cover published TiSynthEngine 2.0.0, reviewed at
+`9d74aa45f84d3f2822d4aab76874efe37d81257f` on 2026-11-03. Both platform
+release ZIPs declare 2.0.0 and their packaged declarations match the bundled
+[TypeScript asset](../assets/index.d.ts). Read the [guide](guide.md) for
+installation and the [upgrade guide](upgrade-2.0.0.md) for migration.
+
+## Choose the correct interface
+
+Use [Sound objects](sound-api.md) for new code. The [direct API](api.md) remains
+supported, including its Boolean/ID return contracts and original option names.
+The [sound](recipes.md) and [interaction](recipes-interaction.md) recipes use
+that direct interface. Preserve their pitch, envelope, gain and timing when
+adapting them. A Sound definition survives shutdown, but its playback controls
+become invalid.
+Do not combine `sound`/`playback` presets with direct native dictionaries.
+
+Runtime metadata uses `version`, not `apiVersion`. Native module manifest
+`apiversion` is a separate Titanium ABI field. Older 1.0.2 binaries lack variation
+and repetition; detect methods/capabilities before sending new closed-dictionary
+fields. Native variation requires its capability and schema pair. Android reports
+some extra sequence/processing/modulation flags that iOS omits while supporting
+the methods; do not use those flags as a universal feature gate.
+
+`setProcessing()` reverb decay is milliseconds; direct `setMasterProcessing()`
+reverb decay remains seconds. See the [unit mapping](upgrade-2.0.0.md#names-and-units).
+
+## Native differences that affect decisions
+
+- Submit exact integer repetition intervals. The reviewed Apple validator accepts
+  values extremely close to an integer within its 1e-9 tolerance and truncates
+  them; Android rejects them. This is not a portable fractional interval feature.
+- Timed zero attack/release initially becomes one sample on Apple before duration
+  trimming; Android preserves zero. Matching validation does not establish
+  sample-identical envelopes.
+- Some early Apple rejections and unknown/retired Android sequence stops bypass
+  rejection counters. Recorded reason totals describe recorded failures, not
+  every rejected API call.
+- Sequence filter sweeps refresh every 16 samples on Android and every 8 on Apple.
+  Both use note length, but their PCM output is not guaranteed to match.
+
+Exact constraints and platform differences are in the [API](api.md) and
+[engine](audio-engine.md). Sound objects follow the same native source-compatibility rules.
+
+## Diagnose audio without overstating evidence
+
+Use the [statistics API](api.md#getstats) and [engine telemetry](audio-engine.md#engine-statistics).
+Keep unavailable readings as `null`, poll slowly, and cancel the owner's timer.
+Render load is callback work divided by its deadline, not whole-app CPU.
+Sample-peak ceilings do not certify speaker safety or inter-sample peaks.
+Start after layout settles; Android startup underruns, output routes, Bluetooth
+latency and sustained maximum load require their own device checks.
+
+The official [Sound validation record](https://github.com/macCesar/TiSynthEngine/blob/9d74aa45f84d3f2822d4aab76874efe37d81257f/documentation/sound-api-validation.md)
+separates validator, bridge, within-platform PCM, host allocation/GC and scoped
+physical evidence. Host dispatch timings are not Titanium bridge/device latency;
+byte-identical PCM comparisons are within each platform, not across platforms.
+Historical measurements retain their original revision and acceptance limits,
+including failed or inconclusive results. They do not certify every workload.
+Raw reports and reproduction tools remain in the native module repository
+for maintenance. You do not need those files to implement sounds.

package/skills/ti-synthengine/references/troubleshooting.md

@@ -1,8 +1,8 @@
-> Source snapshot: official TiSynthEngine documentation at commit `ec04f4e634075c41b55f66279eabcd78b9652d58` (2026-11-02). Published module 1.1.0; public API 1.1.0. Upstream `documentation/troubleshooting.md` SHA-256: `37fd3173ccfce393ab354713df66fbcc99c7281131ea45de1b3aae1e2d6f2160`.
+> Source snapshot: official TiSynthEngine documentation at commit `9d74aa45f84d3f2822d4aab76874efe37d81257f` (2026-11-03). Published module 2.0.0. Upstream `documentation/troubleshooting.md` SHA-256: `edf85de5fa08ead37820264f8381e1ef6e72d67c274fac0650dda723446dedbc`.
 
 # Troubleshooting
 
-Start with the method's documented return value and the native log. Most silent requests are contract rejections, a stale binary or an engine that never started.
+Start with the method's documented return value and the native log. Most requests that produce no sound are contract rejections or involve a stale binary or an engine that never started.
 
 ## A call returns `false`
 
@@ -12,7 +12,7 @@ For methods that emit structured validation warnings, inspect logcat or the Xcod
 event=validation_warning method=playTone key=duraton reason=unsupported_option action=rejected value=200
 ```
 
-Always check the return value: `playSequence` rejects with 0, while Boolean methods reject with `false`. Some sequence/control rejection paths do not emit a structured warning; absence of a new log entry does not establish acceptance.
+Always check the return value: `playSequence` rejects with 0, while Boolean methods reject with `false`. Some sequence/control rejection paths do not emit a structured warning. The absence of a new log entry does not establish acceptance.
 
 Common fixes:
 
@@ -47,27 +47,25 @@ The envelope and filter rules apply to the final values of each sounding event.
 
 For the shaping controls, check the discontinuous disabled values as well as the numeric range: `bitDepth` accepts 0 or 2 through 16, and `pulseWidthEnd` accepts 0 or 0.05 through 0.95. A `waveTable` must contain only finite values from -1 to 1.
 
-## The installed contract is wrong
+## The installed module version is wrong
 
 Check the native binary at startup:
 
 ```javascript
-var actual = synth.getDefaults().apiVersion
-if (actual !== '1.1.0') {
-  throw new Error('Expected TiSynthEngine 1.1.0, found ' + actual)
+var actual = synth.getDefaults().version
+if (actual !== '2.0.0') {
+  throw new Error('Expected TiSynthEngine 2.0.0, found ' + actual)
 }
 ```
 
-`apiVersion` describes the public contract, separately from the package version. Version 1.1.0 uses API 1.1.0; published 1.0.2 uses API 1.0.0. For version 1.1.0, confirm both entries in `tiapp.xml` pin module version 1.1.0. Then remove the application's build output and rebuild so Titanium does not reuse an archive from an earlier build. The module directories should be:
+`version` is the installed module version in both `getDefaults()` and `getContract()`. TiSynth has no independent API version. Pin both entries in `tiapp.xml` to the intended module version and rebuild the app so Titanium includes the new archive. For 2.0.0, the directories are:
 
 ```text
-modules/android/ti.synthengine/1.1.0/
-modules/iphone/ti.synthengine/1.1.0/
+modules/android/ti.synthengine/2.0.0/
+modules/iphone/ti.synthengine/2.0.0/
 ```
 
-Module version `1.1.0` reports API `1.1.0`. Check the capability/schema pair before using variation.
-
-For binaural, also inspect `getDefaults().limits.spatialX` and `.spatialY`. Use the official packages to avoid stale development binaries. Copying the package does not update an already installed app: rebuild and reinstall it.
+Check the required methods and capability/schema pair before using variation. For binaural, inspect `getDefaults().limits.spatialX` and `.spatialY`. Copying a package does not update an installed app: rebuild and reinstall it.
 
 ## Binaural does not change the position
 
@@ -85,7 +83,7 @@ The [integration guide](guide.md#integrate-binaural-in-a-2d-app) contains the Ja
 
 ## Statistics are missing or show `null`
 
-Older development packages can report 1.0.0 without statistics methods. Check `typeof synth.getStats`, `typeof synth.enableStats`, `typeof synth.disableStats` and `typeof synth.resetStats`; install the current packages, rebuild and reinstall the app if needed.
+The 2.0.0 module includes statistics methods. Check `typeof synth.getStats`, `typeof synth.enableStats`, `typeof synth.disableStats` and `typeof synth.resetStats`; install the current packages, rebuild and reinstall the app if needed.
 
 Basic voice/queue/rejection counters do not require diagnostics. Timing, output peak/RMS and limiter reduction require `enableStats()` and a measured callback/window. `null` means unmeasured or unavailable; keep it distinct from zero. The current iOS backend always reports `null` for underruns, output buffer size and estimated hardware latency. Android backend metrics are best-effort and independent of the diagnostic switch.
 
@@ -151,7 +149,7 @@ Compare several devices before changing the synthesis globally. A resonance on o
 
 ## Audio changes after connecting headphones
 
-Route recovery is automatic, but the sound crossing the hardware transition may end early. The operating system can also mute or fade the new route for a brief device-dependent interval. Wait for the route to settle and play a new sound; do not restart the app.
+The engine recovers routes automatically, but the sound crossing the hardware transition may end early. The operating system can also mute or fade the new route for a brief device-dependent interval. Wait for the route to settle and play a new sound; do not restart the app.
 
 If later sounds remain silent, capture the Android or Xcode log around the route change. Confirm that no screen lifecycle handler called `shutdown()` at the same time.
 
@@ -168,7 +166,7 @@ If later sounds remain silent, capture the Android or Xcode log around the route
 - Confirm the deployment target is iOS 15 or newer.
 - Check whether another module changes `AVAudioSession` after startup.
 - Test interruptions, phone calls, Bluetooth and route changes on hardware.
-- Use the matching device or simulator slice from the 1.1.0 archive.
+- Use the matching device or simulator slice from the 2.0.0 archive.
 
 ## What to include in a bug report
 
@@ -176,7 +174,7 @@ Include the platform, OS version, device model, Titanium SDK version, module ver
 
 ## Held notes, sequences or effects methods are missing
 
-Published 1.0.2 reports API version 1.0.0 and provides `updateVoice`; version 1.1.0 reports API 1.1.0 and recommends `updateNote`. Detect `noteOn`/`noteOff`/`updateNote`, all four sequence methods and `setMasterProcessing` according to the feature needed. Install matching current Android/iOS packages, rebuild and reinstall the consumer app. A stale development binary may report the same version without the complete release API. See [capability detection](guide.md#detect-required-capabilities).
+Use `createSound()` and its returned playback controls for held notes, repetitions and patterns. Detect `noteOn`/`noteOff`/`updateNote`, all four sequence methods and `setMasterProcessing` according to the feature needed. Install matching current Android/iOS packages, rebuild and reinstall the consumer app. A stale development binary may report the same version without the complete release API. See [capability detection](guide.md#detect-required-capabilities).
 
 ## A held voice does not release or update
 
@@ -198,7 +196,7 @@ Disabling effects closes input smoothly and lets bounded tails finish, then bypa
 
 ## A brief level dip is gone before the meter refreshes
 
-Enable diagnostics, reset deliberately, then inspect `preLimiterPeakDb` and `maxLimiterReductionDb`. They retain the native pre-limiter peak and greatest attenuation since reset, including brief interventions between UI polls. `limiterReductionDb` is a window measurement and can return to zero sooner. Older packages may omit the accumulated fields; disabled/unmeasured diagnostics return `null`. See [measurement example](advanced-examples.md#measure-peaks-and-limiter-reduction).
+Enable diagnostics, reset deliberately, then inspect `preLimiterPeakDb` and `maxLimiterReductionDb`. They retain the native pre-limiter peak and greatest attenuation since reset, including brief interventions between UI polls. `limiterReductionDb` is a window measurement and can return to zero sooner. Disabled or unmeasured diagnostics return `null`. See [measurement example](advanced-examples.md#measure-peaks-and-limiter-reduction).
 
 If accumulated attenuation remains near zero, investigate phase cancellation between repeated same-pitch oscillators, changing filters or the device speaker/protection path. Compatible released public held-note repetitions preserve predecessor phase; simultaneous unisons, timed calls and transport notes retain their existing phase behavior. Extra effects and resonance can consume headroom even when source gain is fixed. Compare matched levels through headphones and the physical speaker before changing the mix globally.
 
@@ -210,6 +208,6 @@ Compare one note with `SINE`, at a comfortable matched level, to distinguish the
 
 ## A variation dictionary is rejected or repeats the same sound
 
-Check both `capabilities.variation === true` and `variationSchemaVersion === 1` before sending the property. Published 1.0.2 packages reject it. Source restrictions and range ordering still apply at amount zero; near the frequency ceiling, validate tuning, detune, every chord pitch and active pitch endpoints together.
+Check both `capabilities.variation === true` and `variationSchemaVersion === 1` before sending the property. Source restrictions and range ordering still apply at amount zero; near the frequency ceiling, validate tuning, detune, every chord pitch and active pitch endpoints together.
 
 Repeated standalone calls with one explicit seed reproduce the selected parameters. Omit it for independent selections, or use a native sequence to retain an advancing stream across loops. A held voice samples only at attack, and `updateNote` rejects `variation`. For a running sequence, clear an inherited root dictionary with a valid amount-zero replacement; omitting it from a revision retains the merged value. See the [complete examples and rules](native-variation.md).

package/skills/ti-synthengine/references/upgrade-2.0.0.md

@@ -0,0 +1,40 @@
+> Source snapshot: official TiSynthEngine documentation at commit `9d74aa45f84d3f2822d4aab76874efe37d81257f` (2026-11-03). Published module 2.0.0. Upstream `documentation/upgrade-2.0.0.md` SHA-256: `d25459ad28ec6fea2e40796d09aa0d6348b0f2a177cd79e3ef223fbe3ae23172`.
+
+# Upgrade to TiSynth 2.0.0
+
+TiSynth 2.0.0 separates reusable sound definitions from playback. Existing direct methods remain supported with their signatures, return values, identifiers, events and behavior. Use Sound objects for new code.
+
+| Direct call | Sound interface |
+| --- | --- |
+| `playTone(options)` | A tone definition followed by `sound.play()` |
+| `playChord(options)` | A chord definition followed by `sound.play()` |
+| `noteOn({ voiceId, ... })` | `sound.noteOn()` or a held definition's `play()` |
+| `updateNote({ voiceId, ... })`, `noteOff({ voiceId })` | Returned note control's `update()` and `noteOff()` |
+| `repeatTone`, `updateTone`, `stopTone` | A repeat definition's `play()`, then the control's `update()` and `stop()` |
+| `playSequence`, `updateSequence`, `stopSequence`, `getSequenceState` | A pattern definition's `play()`, then the control's `update()`, `stop()` and `getState()` |
+| Global `sequenceend` with a `sequenceId` | The pattern control's `end` event with `{ reason }` |
+| `setMasterProcessing(options)` | `setProcessing(options)` with the units below |
+| `setVolume({ volume })`, `setTempo({ bpm })` | `setVolume(number)`, `setTempo(number)` |
+
+Put synthesis fields in `sound` and pitch arrays, type and timing in `playback`. Direct `note` and `frequency` become one-element `notes` and `frequencies` arrays. Use flat execution overrides and nested `{ sound, playback }` dictionaries for stored revisions.
+
+## Names and units
+
+- Repetition `intervalMs` becomes `playback.interval`, still integer milliseconds.
+- Pattern `stepDuration` becomes root `playback.interval`. Step `duration` becomes step `interval`; both keep the declared `timeUnit`, which defaults to beats. Step `length` keeps its sounding-length meaning.
+- Pattern `voice` becomes root `sound`; step `overrides` becomes step `sound`. Root sequence detune belongs in root `sound.detune`.
+- Processing delay `timeMs` becomes `time`, still milliseconds. Reverb `decay` changes from seconds in `setMasterProcessing()` to milliseconds in `setProcessing()`; multiply the value by 1000.
+- Finite `duration` still includes release. ADSR remains milliseconds. Converting a finite event into a pattern requires a deliberate length/gate conversion and can change sweeps or chord gain.
+- Replace runtime metadata `apiVersion` reads with `version`. There is one installed module version.
+
+`setProcessing()` accepts `timeMs` as an input alias for delay, but it cannot coexist with `time`. Reverb decay remains milliseconds in this method. The direct processing method retains its own units.
+
+## Ownership and errors
+
+Keep each Sound control with the interaction that owns it. Controls hide native playback identifiers and become invalid on shutdown; reusable definitions survive. Finite tones and chords return acceptance without a stop control.
+
+Sound validation throws descriptive errors. Operational playback rejection returns `false`. Direct methods keep their existing return contracts. `Sound.set()` validates an atomic revision for future executions and leaves active executions unchanged.
+
+The direct aliases `updateVoice` and `setStatsEnabled` remain supported. New code uses note controls and `enableStats()` / `disableStats()`.
+
+The [Sound reference](sound-api.md) documents current use. The [validation report](https://github.com/macCesar/TiSynthEngine/blob/9d74aa45f84d3f2822d4aab76874efe37d81257f/documentation/sound-api-validation.md) records the comparison against the source baseline.