@maccesar/titools 5.2.5 → 5.4.0

package/skills/ti-synthengine/references/native-variation.md

@@ -1,27 +1,66 @@
-> Source snapshot: official TiSynthEngine documentation at commit `ec04f4e634075c41b55f66279eabcd78b9652d58` (2026-11-02). Published module 1.1.0; public API 1.1.0. Upstream `documentation/native-variation.md` SHA-256: `650d2c675dc4b4e09a85521812b7fedd3b02cb993a451378a8082e2b7782303a`.
+> Source snapshot: official TiSynthEngine documentation at commit `9d74aa45f84d3f2822d4aab76874efe37d81257f` (2026-11-03). Published module 2.0.0. Upstream `documentation/native-variation.md` SHA-256: `6cfd65b0741dea79d37bb5eee14d1bcb98445ee6b5db14a8c00e3ccfd00a5190`.
 
 # Native per-attack variation
 
 `variation` lets the engine choose bounded parameter values when it admits an attack. Repeated shots can have different pitch, noise color or filter settings without JavaScript randomization. Each voice keeps the chosen values for its lifetime; existing envelopes, sweeps and LFOs continue from that starting configuration.
 
-Android and iOS support this dictionary in the 1.1.0 packages, with public API version `1.1.0` and variation schema version `1`. The published 1.0.2 packages do not accept it.
+Android and iOS support this dictionary in TiSynth 2.0.0. The variation data schema is `1`. Store it in `sound.variation`; a pattern step can supply `steps[i].sound.variation`.
 
-## Select version 1.1.0
+<!-- TOC-START -->
+## Contents
 
-Install the matching Android and iOS 1.1.0 archives in the app and select them in `tiapp.xml`:
+- [Reuse a sound with variation](#reuse-a-sound-with-variation)
+- [Select the module version](#select-the-module-version)
+- [Detect support and start playback](#detect-support-and-start-playback)
+- [Supported locations](#supported-locations)
+- [Dictionary reference](#dictionary-reference)
+- [What amount means](#what-amount-means)
+- [Repeated independent effects](#repeated-independent-effects)
+- [Chords and application gain](#chords-and-application-gain)
+- [Sustained voices and explicit live edits](#sustained-voices-and-explicit-live-edits)
+- [Native loops and dictionary inheritance](#native-loops-and-dictionary-inheritance)
+- [Seeds and reproducibility](#seeds-and-reproducibility)
+- [Rejected configurations](#rejected-configurations)
+- [Studio and game integration](#studio-and-game-integration)
+- [Implementation and verification](#implementation-and-verification)
+
+<!-- TOC-END -->
+
+## Reuse a sound with variation
+
+```javascript
+var synth = require('ti.synthengine')
+var bell = synth.createSound({
+  sound: {
+    waveType: synth.getContract().waveTypes.SINE,
+    volume: 0.25, attack: 5, release: 120,
+    variation: { amount: 0.6, ranges: { volume: [0.18, 0.25], pitchCents: [-8, 8] } }
+  },
+  playback: { type: 'tone', notes: ['A4'], duration: 400 }
+})
+
+bell.play()
+bell.play({ notes: ['C5'] })
+```
+
+Call playback after engine startup. The detailed native dictionaries below explain source restrictions and inheritance. For Sound patterns, root variation belongs in `sound.variation` and a step replacement belongs in `steps[i].sound.variation`.
+
+## Select the module version
+
+Install the matching Android and iOS 2.0.0 archives in the app and select them in `tiapp.xml`:
 
 ```xml
 <modules>
-  <module platform="android" version="1.1.0">ti.synthengine</module>
-  <module platform="iphone" version="1.1.0">ti.synthengine</module>
+  <module platform="android" version="2.0.0">ti.synthengine</module>
+  <module platform="iphone" version="2.0.0">ti.synthengine</module>
 </modules>
 ```
 
-Rebuild and reinstall the application after replacing native modules. Copying module files alone does not update an installed app. Keep the published 1.0.2 archives separate; version 1.1.0 reports API `1.1.0`.
+Rebuild and reinstall the application after replacing native modules. Copying module files alone does not update an installed app. Keep historical released archives separate. The installed module version is available as `getDefaults().version`.
 
 ## Detect support and start playback
 
-Check both metadata fields. API version alone does not identify variation support. Omit the property completely when either announcement is missing, including when the requested amount is zero.
+Check both capability/schema fields, even when the module version matches the one you expect. Omit the property completely if either field is missing, including when the requested amount is zero.
 
 ```javascript
 var synth = require('ti.synthengine')
@@ -133,11 +172,11 @@ function fireLaser() {
 fireLaser()
 ```
 
-The engine samples after admission and before initializing filters, smoothing controls and trajectories. Rejected attacks do not consume a selection. Existing release tails, capacity policy and voice replacement still apply.
+The engine samples after admitting an attack, before initializing its filters, smoothing controls and trajectories. Rejected attacks consume no selection. Release tails, capacity policy and voice replacement remain unchanged.
 
 ## Chords and application gain
 
-One chord is one atomic publication. Each voice uses its position within that attack to obtain independent field samples; it does not reuse the first voice's result. If the chord cannot be admitted, none of its voices starts and no event is consumed.
+A chord is published atomically. Each voice's position within the attack determines its independent field samples, so later voices do not reuse the first voice's result. If the chord cannot be admitted, none of its voices starts and no event is consumed.
 
 Scale a volume range with the same application gain as the authored volume. Let the engine apply its existing chord compensation once.
 
@@ -234,7 +273,7 @@ if (supportsVariation && sequenceId > 0) {
 }
 ```
 
-Stop the owned sequence through the normal lifecycle when it is no longer needed. Stop/new play starts a new stream.
+Stop the owned sequence during normal lifecycle cleanup when it is no longer needed. Stopping and starting playback again creates a new stream.
 
 ## Seeds and reproducibility
 
@@ -276,10 +315,10 @@ Also check pitch corners near 1 Hz or the reported ceiling. A valid base pitch c
 
 Studio calls this control Variantes. Its displayed percentage maps linearly: 25% sends native amount `0.25`, 50% sends `0.5`, and 100% sends `1`. Studio prepares broader ranges for its editor. The games retain their authored range profiles.
 
-Frontier automatically applies authored ranges only to its eligible destruction sounds; Guardian applies them only to its two lasers. Both require the capability/schema pair and keep their existing recipes on older modules. Studio allows any source to opt in through compatible parameter ranges. See [Studio's control and preset guide](https://github.com/macCesar/TiSynth-Studio/blob/main/documentation/variation.md); the native contract in this document does not depend on a consumer app.
+Frontier automatically applies authored ranges only to its eligible destruction sounds; Guardian applies them only to its two lasers. Both require the capability/schema pair. Studio allows any source to opt in through compatible parameter ranges. See [Studio's control and preset guide](https://github.com/macCesar/TiSynth-Studio/blob/main/documentation/variation.md); the native contract in this document does not depend on a consumer app.
 
 ## Implementation and verification
 
-Both renderers use [`shared/synth_variation.h`](https://github.com/macCesar/TiSynthEngine/blob/7cd035409453b01df2736aef56f2316d94ca019c/shared/synth_variation.h): stable schema slots, integer-defined SplitMix64 finalization and exact uint32-to-uniform conversion. Parsing prepares a fixed 144-byte configuration outside the audio callback. The callback performs bounded arithmetic without allocation, locks, JavaScript calls or entropy services.
+Both renderers use [`shared/synth_variation.h`](https://github.com/macCesar/TiSynthEngine/blob/9d74aa45f84d3f2822d4aab76874efe37d81257f/shared/synth_variation.h): stable schema slots, integer-defined SplitMix64 finalization and exact uint32-to-uniform conversion. Parsing prepares a fixed 144-byte configuration outside the audio callback. The callback performs bounded arithmetic without allocation, locks, JavaScript calls or entropy services.
 
-Focused checks cover known vectors, both native validators, attack admission, chord ordinals, sustained stability, loops, revisions, rejection and old-renderer compatibility with controlled noise initialization. [Technical verification](native-variation-validation.md) records the measured memory/callback cost and its limits. Host results do not certify physical latency or listening quality on every device.
+Focused checks cover known vectors, both native validators, attack admission, chord ordinals, sustained stability, loops, revisions, rejection and old-renderer compatibility with controlled noise initialization. [Technical verification](https://github.com/macCesar/TiSynthEngine/blob/9d74aa45f84d3f2822d4aab76874efe37d81257f/documentation/native-variation-validation.md) records the measured memory/callback cost and its limits. Host results do not certify physical latency or listening quality on every device.

package/skills/ti-synthengine/references/recipes-interaction.md

@@ -1,10 +1,16 @@
 # Instrument, polyphony and expressive recipes
 
-These curated TiTools recipes use the same running engine and runtime `WAVE`
-constants as [the arcade recipes](recipes.md). Keep one owner, check native
-acceptance and use their [verification checklist](recipes.md#recipe-verification-checklist).
-The expressive envelope/filter/FM ranges are starting points verified against
-the public contract, not device-auditioned presets. Listen before shipping.
+These TiTools recipes use the supported direct interface in 2.0.0 and share
+the running engine and runtime `WAVE` constants from
+[the arcade recipes](recipes.md). Keep one engine owner, check native acceptance
+and follow the [verification checklist](recipes.md#recipe-verification-checklist).
+
+The envelope, filter and FM ranges are starting points checked against the
+public contract. They have not been auditioned on a device, so listen before
+shipping.
+
+For new reusable instruments, read [Sound definitions and controls](sound-api.md).
+Keep these recipes' gains, pitch arrays, envelopes and ownership when adapting them.
 
 ```javascript
 const synth = require('ti.synthengine')
@@ -114,9 +120,8 @@ In a Titanium view:
 - call `gesture.finish()` on both `touchend` and `touchcancel`;
 - keep visual pressed-state counts separate if multiple touches are supported.
 
-The audio release may continue after the finger leaves a bar. That is desired
-for a xylophone. `stopAll()` is a global panic: it also cancels every native
-sequence and invalidates shared effect histories. Use an owner's
+For a xylophone, let the audio release continue after the finger leaves a bar.
+`stopAll()` is a global panic: it also cancels every native sequence and invalidates shared effect histories. Use an owner's
 `stopSequence({ sequenceId })` when only that sequence should stop.
 
 ## Four-pad memory cues
@@ -169,8 +174,8 @@ function playMemoryBank (bankName) {
 
 ### Controlled timbre comparison
 
-For an honest A/B test, hold pitches, duration, envelope and pan constant.
-Change only waveform and its comparison level. Never pass a profile object
+For an A/B test, hold pitches, duration, envelope and pan constant. Change
+only the waveform and its comparison level. Never pass a profile object
 containing labels or other app metadata directly to `playChord()` because its
 options dictionary is closed.
 
@@ -202,8 +207,8 @@ function auditionTimbre (profileName) {
 
 ### Convert MIDI pitch to hertz
 
-The standard A4 = 440 Hz formula makes it easy to build interval recipes
-without embedding a long frequency table.
+Use the standard A4 = 440 Hz formula to build interval recipes without
+embedding a long frequency table.
 
 ```javascript
 function midiToHz (midi) {
@@ -337,9 +342,9 @@ This repeated chord uses one centered native sequence. The one-off layered chord
 
 ### Cancellable repetition
 
-The chord pulse above has an identified sequence owner. Repeated start requests coalesce until its matching `sequenceend` retirement frees the slot. Stop its sequence ID and cancel pending restarts when its window closes; its native sequence schedules subsequent chord attacks.
+The chord pulse above belongs to one identified sequence owner. Repeated start requests coalesce until the matching `sequenceend` event retires it and frees the slot. When its window closes, stop that sequence ID and cancel pending restarts. The native sequence schedules subsequent chord attacks.
 
-For repetition of an original finite tone in API 1.1.0, use `repeatTone({ intervalMs, ...recipe })`, retain its positive tone ID, edit future attacks with `updateTone`, and cancel with `stopTone`. Each independent layer retains its own tone ID and overlap budget. `stopTone` preserves admitted finite attacks; `stopSequence` releases its sequence's voices. Tone IDs have no completion event, so the sequence retirement/restart procedure above does not apply to them. Independent event calls and intentionally timed finite JavaScript bursts remain supported; cancel any app-owned timers at teardown. See [the repetition contract](api.md#finite-tone-repetition) and [complete effect fidelity](instruments-and-effects.md#repeated-firing-uses-the-native-clock).
+For direct repetition of an original finite tone, use `repeatTone({ intervalMs, ...recipe })`, retain its positive tone ID, edit future attacks with `updateTone`, and cancel with `stopTone`. Each independent layer retains its own tone ID and overlap budget. `stopTone` preserves admitted finite attacks; `stopSequence` releases its sequence's voices. Tone IDs have no completion event, so the sequence retirement/restart procedure above does not apply to them. Independent event calls and intentionally timed finite JavaScript bursts remain supported; cancel any app-owned timers at teardown. See [the repetition contract](api.md#finite-tone-repetition) and [complete effect fidelity](instruments-and-effects.md#repeated-firing-uses-the-native-clock).
 
 ```javascript
 function cleanupAudio () {
@@ -356,9 +361,9 @@ Call `shutdown()` only from the screen or service that owns the shared engine.
 
 ### Plucked marimba note
 
-A short attack, a decay that falls to a low sustain and a release that fits
-give the struck-and-ring shape of a mallet or plucked string. A sustain below 1
-needs a decay, and `attack + decay` must fit inside `duration`.
+A short attack followed by decay to a low sustain gives the strike and ring
+of a mallet or plucked string. Keep the release within the available duration.
+A sustain below 1 needs a decay, and `attack + decay` must fit inside `duration`.
 
 ```javascript
 synth.playTone({
@@ -412,9 +417,9 @@ synth.playTone({
 
 ### Electric piano
 
-Frequency modulation with a 1:1 ratio gives a tine-like tone. Letting the
-modulation index fall through `fmDepthEnd` makes the note mellow as it rings,
-which is what the ear expects from a struck tine. FM needs a sine carrier.
+Frequency modulation with a 1:1 ratio gives a tine-like tone. Reduce the
+modulation index through `fmDepthEnd` so the note mellows as it rings, as a
+struck tine does. FM needs a sine carrier.
 
 ```javascript
 synth.playTone({

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

@@ -1,11 +1,13 @@
 # Curated sound and interaction recipes
 
-These recipes use the core public contract shared by `ti.synthengine`
-1.0.2 / API 1.0.0 and 1.1.0 / API 1.1.0. They use only public option keys,
-keep every explicit envelope valid, and obtain
-waveforms from the runtime contract instead of hardcoding integers. Install the
-matching official Android/iOS packages and follow the owning-engine
-[installation and lifecycle guide](guide.md) before using them.
+These recipes use the supported direct native interface in `ti.synthengine` 2.0.0
+and earlier 1.x modules. For reusable definitions in new code, use
+[Sound objects](sound-api.md) while preserving how each recipe renders.
+
+The examples use public option keys and valid explicit envelopes. They read
+waveforms from the runtime contract instead of hardcoding integers. Install
+matching official Android/iOS packages and follow the
+[installation and lifecycle guide](guide.md) to set up the engine owner.
 
 Unless a section says otherwise, the snippets assume one owner has already
 started the engine:
@@ -16,13 +18,13 @@ const contract = synth.getDefaults()
 const WAVE = contract.waveTypes
 ```
 
-Treat levels as starting points, not mastering targets. Test on the actual
-phone speaker and leave headroom when release tails or independent events can
-overlap.
+Use the levels as starting points for listening tests, rather than final
+mastering targets. Test on the actual phone speaker and leave headroom for
+overlapping release tails or independent events.
 
-Instrument interactions, layered chords and expressive synthesis are in
-[the interaction recipes](recipes-interaction.md). Their standard synthesis
-starting ranges require listening on the target device before shipping.
+For instrument interactions, layered chords and expressive synthesis, see
+[the interaction recipes](recipes-interaction.md). Listen to those starting
+ranges on the target device before shipping.
 
 <!-- TOC-START -->
 ## Contents
@@ -166,8 +168,8 @@ if (!sequenceId) throw new Error('Sequence rejected')
 
 ### Fast four-note arpeggio
 
-Very short square notes with a small attack retain the hard cartridge-era
-edge while reducing uncontrolled clicks. The 10 ms rests keep the first three
+Very short square notes with a small attack keep the hard cartridge-era
+edge and reduce uncontrolled clicks. The 10 ms rests keep the first three
 40 ms notes on a 50 ms grid; the final note rings for 80 ms.
 
 ```javascript
@@ -404,8 +406,9 @@ if (!sequenceId) throw new Error('Sequence rejected')
 
 ### Hovering craft
 
-A triangle voice with strong sine vibrato creates a cyclical engine wobble. Slow stereo travel adds movement on headphones while pitch
-remains the primary cue on mono speakers.
+A triangle voice with strong sine vibrato creates a repeating engine wobble.
+Slow stereo travel adds movement on headphones; pitch remains the primary cue
+on mono speakers.
 
 ```javascript
 synth.playTone({

package/skills/ti-synthengine/references/recommendations.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/recommendations.md` SHA-256: `f72c3df9c36df0cbdb843bbe2c6799ae537324ece499fe6d1a2de80e43df5261`.
+> Source snapshot: official TiSynthEngine documentation at commit `9d74aa45f84d3f2822d4aab76874efe37d81257f` (2026-11-03). Published module 2.0.0. Upstream `documentation/recommendations.md` SHA-256: `0e7c55830b05ef21bdd1fd125e7d158ea5b598e02618202e65ddd8b8d2044cab`.
 
 # Recommendations
 
@@ -6,9 +6,9 @@ The defaults work for ordinary tones and chords. Use the guidance below when an
 
 ## Group simultaneous notes
 
-Use `playChord()` when pitches form one known simultaneous event. The chord is atomic. Protected profiles normalize per-voice source gain by the square root of the event voice count; `raw` bypasses that normalization. Separate `playTone()` calls are appropriate for independent touches and effects, but their start times and gain are independent too.
+Declare `playback.type: 'chord'` when pitches form one known simultaneous event. The chord is atomic. Protected profiles normalize per-voice source gain by the square root of the event voice count; `raw` bypasses that normalization. Separate tone executions suit independent effects, but their start times and gain are independent too.
 
-For keys or pads a user can trigger freely, keep each event around 0.4 to 0.7 until you have listened to the worst overlap. If every event needs gain above 1, consider `balanced` for the session before raising individual notes further.
+For freely triggered keys or pads, keep each event around 0.4 to 0.7 until you have listened to the worst overlap. If every event needs gain above 1, consider `balanced` for the session before raising individual notes further.
 
 ## Choose the mixing profile once
 
@@ -25,7 +25,7 @@ If a phone buzzes under `speakerSafe`, lower the event volume or raise the pitch
 
 ## Size `maxVoices` for real overlap
 
-`maxVoices` controls capacity. It does not make the engine louder or quieter.
+`maxVoices` sets voice capacity without changing event gain.
 
 | App behavior                       | Starting value |
 | ---------------------------------- | -------------: |
@@ -34,7 +34,7 @@ If a phone buzzes under `speakerSafe`, lower the event volume or raise the pitch
 | Chords, keys or long release tails |       16 to 24 |
 | Explicit stress testing            |             32 |
 
-Count release tails along with buttons pressed at the same instant. Replacement first selects the lowest eligible priority; higher-priority voices are protected. Among that priority, timed-only events steal the slot with the least time remaining; sustained/transport voices prefer a releasing slot, then the oldest attack. The short fade avoids a hard click; the stolen note still ends early.
+Count release tails as well as buttons pressed at the same instant. Replacement first selects the lowest eligible priority; higher-priority voices are protected. Among that priority, timed-only events steal the slot with the least time remaining; sustained/transport voices prefer a releasing slot, then the oldest attack. The short fade avoids a hard click; the stolen note still ends early.
 
 ## Keep one lifecycle owner
 
@@ -67,7 +67,7 @@ The resonant filter, FM and stacked detuned voices change level and spectrum mor
 - A resonance that keeps reaching the limiter makes the whole mix pump. Lower the volume or the Q before reaching for a different profile.
 - FM is not band-limited. A high carrier with a large `fmDepth` and `fmRatio` aliases. Keep carriers of bell-like sounds around 500 Hz, or lower the index.
 - A detuned stack is one voice per copy. Count them when choosing `maxVoices`. Protected profiles divide per-voice source gain by the square root of the event voice count; `raw` does not. Correlated or phase-aligned voices can still reinforce each other, so this is not a guarantee of constant loudness or peaks.
-- `sequenceend` reports completion or stopping by sequence identifier. Put contiguous notes into one sequence when sample timing matters; the event crosses JavaScript delivery latency.
+- A pattern control emits `end` on completion or stopping. Put contiguous notes into one pattern when sample timing matters; the event crosses JavaScript delivery latency.
 
 ## Validate values at the app boundary
 
@@ -87,7 +87,7 @@ Do not copy the frequency maximum into application code. It depends on the activ
 
 The same rule applies to `noiseRate`, `lowPassHz` and `filterHz`. Validate a custom `waveTable` as 2 to 64 finite values from -1 to 1, and remember that `bitDepth` accepts zero or an integer from 2 to 16. For `detune`, check the resulting pitch too: a shifted pitch that leaves the frequency range is rejected even when the cents value is in range.
 
-Check each method's documented return value during development: Boolean publication acceptance or a positive sequence ID, with 0 rejecting a sequence. Methods that emit structured validation warnings include the method, key and reason in the native log, but some sequence/control rejection paths do not log. Logging the return at the caller helps identify a stale preset or misspelled field without treating silence in the native log as acceptance.
+Check each method's documented return value during development. Sound playback returns finite acceptance, a playback control, or `false` on operational rejection; invalid Sound configurations throw. Direct native methods keep their documented Boolean or identifier returns. Methods that emit structured validation warnings include the method, key and reason in the native log, but some sequence/control rejection paths do not log. Logging the return at the caller helps identify a stale preset or misspelled field. A silent native log does not establish acceptance.
 
 ## Test the intended sound
 
@@ -111,13 +111,13 @@ Use the [integration guide](guide.md#integrate-binaural-in-a-2d-app) to convert
 
 ## Known limits
 
-- Use `noteOn` with app-supplied IDs for individual release and compatible live updates. Check the required methods before enabling controls; timed events do not return voice handles.
+- Keep the control returned by `sound.noteOn()` or held `play()` for release and compatible live updates. Finite tones and chords return no individual control.
 - Timed tones and chords last at most 60 seconds including release. Sequence intervals and explicit note lengths use the sequence unit, at most 300 beats or 60,000 ms; sequence ADSR remains in milliseconds and release may extend beyond the interval. Sustained `noteOn` voices last until release, replacement or shutdown.
 - The module synthesizes waveforms and does not play audio files.
 - One native transport supports up to four independent sequences, preallocated by `maxSequences`. All share at most 32 voices.
-- A single tone or chord has no completion event. Sequences emit `sequenceend` with their identifier and completed/stopped reason.
+- A single finite tone or chord has no completion event. A pattern control emits `end` with its completed/stopped reason.
 - Voice capacity and mixing profile remain fixed until shutdown.
-- Sequences run on the sample clock in beats or milliseconds. `duration` controls intervals; `length` independently controls note duration.
+- Patterns run on the sample clock in beats or milliseconds. Root and step `interval` control onset spacing; `length` independently controls note duration.
 - `lowPassHz` is a plain one-pole filter. The resonant filter has fixed 12 dB per octave and one exponential sweep; there is no filter envelope.
 - FM has one modulator and works only on `SINE`.
 - Binaural positions occupy a front plane. Spatial held voices support smooth live movement; there is no rear positioning, distance attenuation or head tracking. Output is two channels, without a multichannel 2.1/5.1 routing API.
@@ -128,10 +128,10 @@ Use a sample player or a dedicated music engine when a product needs streaming,
 
 ## Use effects and held voices deliberately
 
-Use `noteOn` for a sound whose duration follows interaction, such as a key, motor or beam; release its ID on touch end, cancellation, pause or scene teardown. Use `playSequence` for a finite musical cue or repeating grid. Neither needs JavaScript to keep an already accepted note alive. Both share the same 32-slot maximum with collision and interface tones; held notes can be stolen, and an accepted `updateNote` on a stolen ID is a no-op. Optional priority 0-3 affects stealing; it reserves no voices. There is no voice-finished event.
+Use `sound.noteOn()` for a sound whose duration follows interaction, such as a key, motor or beam; release its note control on touch end, cancellation, pause or scene teardown. Use a pattern definition for a finite musical cue or repeating grid. The native engine sustains notes and schedules attacks. Both share the same 32-voice maximum with collision and interface tones; held notes can be stolen, and updates to a stolen note are accepted as no-ops. Optional priority 0-3 affects stealing without reserving voices. There is no voice-finished event.
 
 Keep chorus/delay/reverb mixes modest when dialogue or short game feedback must remain distinct. By default they process all four categories, so enabling reverb for a victory chord also affects simultaneous shots and collisions. Select categories with `applyTo` and assign each voice a `bus`, or use explicit `effectSend` values to choose the processed share. All selected voices share one effects chain. Disabling effects lets tails drain for at most 30 seconds; use panic when immediate history invalidation is required. Start with saturation disabled and compare creative drive at matched levels. Do not use saturation as an automatic substitute for the final limiter.
 
 Fixed input/event gain does not decrease when unrelated voices start. If level dips, inspect `maxLimiterReductionDb` and `preLimiterPeakDb`, then consider same-pitch phase cancellation or the device's speaker protection. Eight coherent independent voices can still exceed the limiter threshold; module capacity is not a clean-mix loudness guarantee. See [measurement example](advanced-examples.md#measure-peaks-and-limiter-reduction).
 
-Measure the complete workload on each target device, including held voices, binaural, LFOs, all enabled effects and tails. The [historical statistics benchmark](stats-performance.md) predates these features; the [current technical report](studio-validation.json) includes an unmet full-chain host deadline criterion. Neither is a guarantee of game-frame rate, physical audio deadlines, heat or battery life.
+Measure the complete workload on each target device, including held voices, binaural, LFOs, all enabled effects and tails. The [historical statistics benchmark](https://github.com/macCesar/TiSynthEngine/blob/9d74aa45f84d3f2822d4aab76874efe37d81257f/documentation/stats-performance.md) predates these features; the [current technical report](https://github.com/macCesar/TiSynthEngine/blob/9d74aa45f84d3f2822d4aab76874efe37d81257f/docs/validation/studio-validation.json) includes an unmet full-chain host deadline criterion. Neither is a guarantee of game-frame rate, physical audio deadlines, heat or battery life.

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

@@ -0,0 +1,197 @@
+> Source snapshot: official TiSynthEngine documentation at commit `9d74aa45f84d3f2822d4aab76874efe37d81257f` (2026-11-03). Published module 2.0.0. Upstream `documentation/sound-api.md` SHA-256: `bb7bfe10a63aba700bdd3584e803436852e07200b82798f5f16c83383687a546`.
+
+# Sound objects: TiSynth 2.0.0
+
+TiSynth 2.0.0 provides reusable sound definitions and independent playback controls on Android and iOS. `createSound()` allocates no voice. Its definition survives `shutdown()` and can play again after `start()`. Rendering, gain, admission limits and scheduling use the existing native tone, chord, held, repetition and sequence paths.
+
+TiSynth uses one version: the installed module version. Both `getContract().version` and `getDefaults().version` report `2.0.0`. `getContract()` also describes `capabilities.soundObjects: true`, supported interpretations, property names and units.
+
+## First sound
+
+```javascript
+const synth = require('ti.synthengine')
+const contract = synth.getContract()
+if (contract.version !== '2.0.0') throw new Error('Sound objects require TiSynth 2.0.0')
+if (!synth.start({ maxVoices: 16, maxSequences: 4, mixingProfile: 'conservative', audioSession: 'ambient' })) {
+  throw new Error('Audio startup rejected')
+}
+const bell = synth.createSound({
+  name: 'Bell',
+  sound: { waveType: contract.waveTypes.SINE, volume: 0.25, attack: 5, release: 120 },
+  playback: { type: 'tone', notes: ['A4'], duration: 400 }
+})
+if (!bell.play()) throw new Error('Bell rejected')
+bell.play({ notes: ['C5'], volume: 0.15 })
+synth.setVolume(0.8)
+synth.setTempo(110)
+```
+
+Start the engine after the owning screen has settled, and call `shutdown()` when its audio owner closes. Follow the [lifecycle guidance](guide.md#lifecycle) and plan the [voice budget](recommendations.md). A later higher-priority event can replace a finite event that was accepted earlier.
+
+## Stored definitions and temporary overrides
+
+A preset has optional `name`, `sound` and `playback` dictionaries. `sound` holds synthesis and routing; `playback` holds pitch and interpretation. `getPreset()` returns a detached copy, preserving whether `type` was authored or inferred. Inputs are copied too.
+
+`Sound.set({ sound, playback })` recursively merges objects, replaces whole arrays and validates the complete result before replacing the stored definition. A failed change throws without partially applying it. `null` removes an optional leaf when the remaining preset is valid; it does not remove a whole `sound` or `playback` dictionary. Arrays, including `steps`, `notes`, `frequencies`, `waveTable`, `modulations` and variation ranges, replace the complete array; they do not concatenate. `set()` affects future executions; it does not edit controls already playing.
+
+`Sound.play(changes)` and `Sound.noteOn(changes)` accept **flat** overrides, such as `{ notes: ['D4'], volume: 0.2 }`. They do not accept nested `{ sound, playback }` arguments. An execution never mutates the stored preset. Repetition and pattern updates also accept `null` to remove an optional leaf when the complete resulting revision is valid. Such resets replace the native recipe without restarting its transport or repetition deadline. Held-note updates require concrete live values; use supported disabling values such as zero or an empty modulation array. Setting `notes` replaces a previously stored `frequencies` source and vice versa; supplying both together throws.
+
+```javascript
+const sound = synth.createSound({
+  sound: { volume: 0.3, pan: 0.2, variation: { amount: 1, ranges: { volume: [0.2, 0.3] } } },
+  playback: { notes: ['C4'], duration: 300 }
+})
+sound.set({ sound: { pan: null, variation: { amount: 0.5 } } })
+sound.set({ playback: { notes: ['D4'] } })
+const preset = sound.getPreset()
+// The volume range is retained; pan is absent; notes is now exactly ['D4'].
+if (preset.sound.pan !== undefined || preset.playback.notes.length !== 1) throw new Error('Unexpected preset')
+sound.play({ notes: ['E4'] })
+```
+
+Unknown keys, wrong types, incompatible fields and out-of-range values throw descriptive `TypeError`s before publication. Fields are never silently stripped to make a definition valid. Numeric ranges and waveform-dependent rules remain those in the [native reference](api.md#strict-validation). Operational failures, including an unavailable engine or a rejected publication, return `false`.
+
+## Interpretations and returns
+
+An explicit type on the call wins over the preset's declared type. If neither declares a type, `steps` infers a pattern, more than one pitch infers a chord, and otherwise a tone is inferred. Inference never writes a type into the stored preset. Repetition and held interpretation require an explicit type, or `noteOn()` for held execution.
+
+| Type or method | Accepted return | Playback fields | Native path |
+| --- | --- | --- | --- |
+| `tone` | `true` | `notes` or `frequencies`, `duration`, `frequencyEnd` | One finite tone |
+| `chord` | `true` | `notes` or `frequencies`, `duration` | Atomic finite chord, including an explicitly declared one-note chord |
+| `repeat` | Repetition control | Single pitch, `duration`, `frequencyEnd`, required `interval` | Native finite-tone repetition |
+| `pattern` | Pattern control | `steps`, `interval`, `timeUnit`, `gate`, `loop`, `swing`, `mode`, `tuning`, optional root `frequencyEnd` | Native sequence |
+| `held` or `Sound.noteOn()` | Note control | Single pitch only | Existing sustained voice |
+
+All executions can return `false` on operational rejection. Finite tones and chords expose no individual control or identifier. A declared type remains in force when pitches change: `type: 'tone'` with two notes throws; an explicit `type: 'chord'` with one note retains chord gain and admission behavior. Choosing another type does not discard incompatible preset fields: clear or replace them in the definition first.
+
+Use either `notes` as note names or integer MIDI notes 12 through 119, or `frequencies` in hertz. Tone, held and repetition use one-element arrays. Chords use 1 through 32 pitches. Numeric pitches in finite/held calls convert to native note names; pattern pitches remain MIDI integers. Keep duplicate pitches when unison is intentional.
+
+Each interpretation has restrictions beyond the shared sound-property allowlist below. Finite-tone endpoints cannot be used as held live controls, and the native chord validator rejects sweeps and modulations. Source rules require sine for FM, square for PWM, an active filter for filter targets, and compatible stereo or spatial controls. Use explicit `type: 'held'` when a definition contains held-only modulation or envelopes so construction validates the intended native path.
+
+## Held notes
+
+```javascript
+const heldSound = synth.createSound({
+  sound: { waveType: 0, volume: 0.2, fmRatio: 2, fmDepth: 1, attack: 10, release: 160,
+    modulations: [{ target: 'fmDepth', wave: 'sine', rate: 2, depth: 0.1 }] },
+  playback: { type: 'held', notes: ['C4'] }
+})
+const note = heldSound.play()
+if (note) {
+  note.update({ notes: ['D4'], volume: 0.15, fmDepth: 0 })
+  if (!note.noteOff()) throw new Error('Note release rejected; owner must retry or close audio')
+}
+const anotherNote = heldSound.noteOn({ notes: ['E4'] })
+if (anotherNote) anotherNote.noteOff()
+```
+
+Each start returns an independent `{ update, noteOff }` control with private identity. No `voiceId` is accepted or exposed. `noteOn()` always uses the single-note held path, even when called on a finite preset; finite `playback.duration` and `playback.frequencyEnd` are not applied to that held execution. Incompatible synthesis leaves, such as `sound.panEnd`, still throw rather than being discarded. It accepts flat synthesis and live pitch overrides, not `type`, `duration` or `frequencyEnd`.
+
+`Note.update()` accepts `notes` or `frequencies`, `volume`, `pan`, `lfoFreq`, `lfoDepth`, `noiseRate`, `lowPassHz`, `pulseWidth`, `filterHz`, `filterQ`, `fmRatio`, `fmDepth`, `spatialX`, `spatialY`, `effectSend` and `modulations`. Only compatible source controls can change; variation, waveform, attack/release, bus and priority are not live fields. Live FM depth can reach zero. Updates retain phase and envelope, using the existing native 10 ms transition. They validate the live patch without requiring attack-only settings again.
+
+Release on touch cancellation, pause and owner teardown. A rejected release remains retryable; the [held ownership guidance](guide.md#hold-and-edit-a-voice) describes bounded recovery. After an accepted release, that control no longer updates or releases a second time. Ended or stolen voices retain the native no-op edit behavior while their control generation remains valid.
+
+## Repetition
+
+```javascript
+const pulse = synth.createSound({
+  sound: { waveType: 1, volume: 0.15, attack: 2, release: 40 },
+  playback: { type: 'repeat', frequencies: [440], duration: 120, interval: 200 }
+})
+const repetition = pulse.play()
+if (repetition) {
+  repetition.update({ frequencies: [660], interval: 180 })
+  repetition.stop()
+}
+```
+
+A repetition exposes `{ update, stop }`. `interval` is integer milliseconds from 1 through 60000. Each attack retains finite-tone duration, envelope and sweep semantics. An update affects the next scheduled attack without moving its existing deadline; the edited interval controls the following gap. Already admitted attacks retain their original recipe. `stop()` cancels future attacks while admitted finite attacks finish. Repetition has no end event and uses its existing capacity independently of pattern slots. Shared voice admission still applies to each attack.
+
+## Patterns
+
+```javascript
+const melody = synth.createSound({
+  sound: { waveType: 3, volume: 0.2, attack: 5, release: 80, bus: 'music', priority: 2 },
+  playback: { type: 'pattern', timeUnit: 'beats', interval: 0.25, loop: false,
+    steps: [{ notes: ['C4'] }, { notes: [64], interval: 0.5, sound: { volume: 0.15 } },
+      { rest: true }, { notes: [60, 64, 67], length: 0.4 }] }
+})
+const pattern = melody.play()
+if (pattern) {
+  pattern.addEventListener('end', event => {
+    // event.reason is 'completed' or 'stopped'. Release and effects may remain audible.
+    Ti.API.info(event.reason)
+  })
+  pattern.update({ swing: 0.1 })
+  const state = pattern.getState()
+  if (state) Ti.API.info(state.step)
+  pattern.stop()
+}
+```
+
+A pattern exposes `{ update, stop, getState, addEventListener, removeEventListener }`. The event name is `end`; its payload is `{ reason: 'completed' | 'stopped' }`, with no native identifier. A control receives completion at most once. `getState()` returns the existing applied transport state with `sequenceId` removed, or `null` when unavailable. Removing a listener requires the same function reference.
+
+Root and per-step `interval` specify time until the next attack. `length` still controls sounding length; omitting it uses `gate`. A step contains exactly one of `notes`, `frequencies` or `rest: true`, with optional `interval`, `length`, `gate` and `sound`. Per-step `sound` supplies synthesis settings for that attack. Root `sound.detune` applies the pattern pitch rule. Root `playback.frequencyEnd` maps to the native voice endpoint, while a per-step endpoint belongs in `steps[i].sound.frequencyEnd`.
+
+`timeUnit` is `beats` by default or `ms`, and stays fixed during playback. Root interval defaults to 0.25 beats or 100 ms. Patterns contain up to 512 steps and 32 pitches per sounding step, with the existing swing, mode, revision and capacity rules. Updates replace arrays and preserve native revision scheduling; they do not restart transport. Pattern `stop()` remains accepted before its native slot is retired. Coalesce replacements and wait for the owned control's `end` event before publishing the next score when capacity is occupied. An `end` event marks transport retirement, not audible silence: release and processing tails may continue.
+
+## Units and processing
+
+| Quantity | Unit and meaning |
+| --- | --- |
+| `sound.attack`, `decay`, `release` | Milliseconds in every interpretation |
+| Tone, chord or repetition `playback.duration` | Total milliseconds including release, including the complete finite envelope |
+| Tone or repetition `playback.frequencyEnd` | Hertz; native finite sweep endpoint |
+| Repetition `playback.interval` | Integer milliseconds, independent of global tempo |
+| Pattern root/step `interval` and step `length` | Beats or milliseconds according to the pattern's `timeUnit` |
+| Pattern `frequencyEnd` | Hertz; native note-length sweep timing with release afterward |
+| `setTempo(number)` | Beats per minute, 20 through 300 |
+| `setProcessing().delay.time` | Milliseconds, 20 through 2000 |
+| `setProcessing().reverb.decay` | Milliseconds, 200 through 8000 |
+
+Finite and pattern envelopes are different native paths. Converting a finite total duration of 150 ms with 25 ms release to a millisecond pattern requires `length: 125` and `release: 25` to preserve that sounding lifetime; attack spacing is a separate `interval`. Do not replace grouped chords with independent tone starts or convert repetition into a sequence when preserving the original gain and envelope interpretation.
+
+```javascript
+synth.setProcessing({ inputGain: 1, applyTo: ['music'],
+  delay: { enabled: true, time: 250, feedback: 0.25, mix: 0.1 },
+  reverb: { enabled: true, decay: 1500, damping: 0.6, mix: 0.12 } })
+synth.enableStats()
+const statistics = synth.getStats()
+synth.disableStats()
+```
+
+`setProcessing()` uses the shared effects chain and strict native validation. Supply delay `time` and reverb `decay` in milliseconds. The adapter converts them to native `timeMs` and seconds-based decay. Other chorus/delay/reverb/saturation, `inputGain` and `applyTo` fields retain the [processing reference](api.md#setmasterprocessingoptions) ranges and semantics.
+
+`bus`, `effectSend` and `priority` belong to `sound`, including a step's `sound` where supported. Routes, sends, fixed per-event gain and chord grouping are unchanged. Sound creation does not enable diagnostics; use `enableStats()` and `disableStats()`, and retain unavailable readings as `null`.
+
+## Lifetime and errors
+
+A Sound is reusable across engine shutdown/start; a playback control is bound to the generation that created it. Shutdown invalidates old controls, which subsequently return `false` for updates/releases/stops and `null` for pattern state. They cannot affect a new execution or a reused app identifier. Stale completion/invalidation events cannot retire a new generation's pattern. Listener installation on an invalid pattern has no effect. `stopAll()` retains its global panic behavior; prefer an owned control for ordinary release or cancellation.
+
+The [upgrade guide](upgrade-2.0.0.md) records method mappings and metadata changes. Global `setVolume()` and `setTempo()` return Boolean acceptance. Sound and `setProcessing()` reject invalid configurations with descriptive errors.
+
+The [TypeScript declarations](../assets/index.d.ts) describe Sound definitions, controls and the supported direct methods. `Sound.play()` has a mixed return when the stored interpretation is not known at the call: narrow the result before calling a control method, or supply an explicit call `type`. Runtime validation remains authoritative for numeric ranges and combinations.
+
+## Property allowlists
+
+`getContract()` reports these shared structural allowlists. Native validators then apply each interpretation's compatibility rules.
+
+### Sound properties
+
+| Keys | Purpose |
+| --- | --- |
+| `attack`, `decay`, `sustain`, `release`, `volume`, `waveType` | Envelope, gain and source |
+| `pan`, `panEnd`, `pans`, `panSpread`, `spatialX`, `spatialY` | Stereo or spatial placement |
+| `lfoFreq`, `lfoDepth`, `noiseRate`, `noiseRateEnd`, `lowPassHz` | Vibrato and noise shaping |
+| `pulseWidth`, `pulseWidthEnd`, `waveTable`, `bitDepth` | Wave shaping |
+| `filterType`, `filterHz`, `filterHzEnd`, `filterQ` | Resonant filter |
+| `fmRatio`, `fmDepth`, `fmDepthEnd`, `detune`, `detunes`, `modulations` | Pitch, FM and compatible LFOs |
+| `bus`, `effectSend`, `priority`, `variation` | Routing, admission and native variation |
+
+### Playback properties
+
+| Keys | Purpose |
+| --- | --- |
+| `type`, `notes`, `frequencies`, `frequencyEnd`, `duration` | Interpretation, pitches and finite timing |
+| `interval`, `timeUnit`, `steps`, `gate`, `loop`, `swing`, `mode`, `tuning` | Repetition or pattern scheduling |