@maccesar/titools 5.2.0 → 5.2.2

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

@@ -1,9 +1,8 @@
-> Source snapshot: official TiSynthEngine 1.0.0 beta documentation from the reviewed working tree based on `95901c98af5353b86d9dc7c60b29ab9186b038cd` (2026-10-14), including uncommitted statistics changes. Upstream `documentation/guide.md` SHA-256: `c5fb4ff34ec425487221b80d6793bda24aa328281ab9ccb02e65b0065e54842e`.
+> Source snapshot: official TiSynthEngine 1.0.0 documentation at release source commit `e7cbbe8a6f9ab38088fd8029c7b43cef6501101f` (2026-10-24). Upstream `documentation/guide.md` SHA-256: `dd03392e1d5f89e520f4be70dab2fbad8e86776bf3a60d6af93f0dc0695c8c69`.
 
 # Guide
 
-This guide covers the normal path from installing TiSynthEngine to releasing
-the native audio resources when the owning screen closes.
+Install TiSynthEngine, start it after layout settles, and release its native audio resources when the owning screen closes.
 
 <!-- TOC-START -->
 ## Contents
@@ -11,30 +10,35 @@ the native audio resources when the owning screen closes.
 - [Install the module](#install-the-module)
 - [Load and verify the contract](#load-and-verify-the-contract)
 - [Lifecycle](#lifecycle)
+- [Detect required capabilities](#detect-required-capabilities)
+- [Hold and edit a voice](#hold-and-edit-a-voice)
+- [Choose the musical transport](#choose-the-musical-transport)
+- [Add master effects](#add-master-effects)
 - [Play the first sound](#play-the-first-sound)
 - [Choose a pitch](#choose-a-pitch)
 - [Shape a tone](#shape-a-tone)
 - [Settle, filter and modulate](#settle-filter-and-modulate)
 - [Shape noise and waveforms](#shape-noise-and-waveforms)
 - [Play simultaneous notes](#play-simultaneous-notes)
-- [Play a pattern](#play-a-pattern)
-- [Know when a pattern ends](#know-when-a-pattern-ends)
+- [Play a sequence](#play-a-sequence)
+- [Know when a sequence ends](#know-when-a-sequence-ends)
 - [Master level and stopping](#master-level-and-stopping)
 - [Output route changes](#output-route-changes)
 - [Integrate binaural in a 2D app](#integrate-binaural-in-a-2d-app)
+- [Read engine statistics](#read-engine-statistics)
 - [Next steps](#next-steps)
+- [Diagnose mix headroom](#diagnose-mix-headroom)
 
 <!-- TOC-END -->
 
 ## Install the module
 
-For the unreleased beta, use the packages built from the current module source in `android/dist` and `ios/dist`. The [latest release](https://github.com/macCesar/TiSynthEngine/releases/latest) is a separate package snapshot; it does not update when source files change. The archive names are:
+Download both official packages from [Android 1.0.0](https://github.com/macCesar/TiSynthEngine/releases/tag/android-1.0.0) and [iOS 1.0.0](https://github.com/macCesar/TiSynthEngine/releases/tag/ios-1.0.0). For source builds, the matching archives are produced under `android/dist` and `ios/dist`:
 
 - `ti.synthengine-android-1.0.0.zip`
 - `ti.synthengine-iphone-1.0.0.zip`
 
-Put the archives in the Titanium project root or install them through the
-Titanium CLI. Pin the same version for both platforms:
+Put the archives in the Titanium project root or install them through the Titanium CLI. Pin the same version for both platforms:
 
 ```xml
 <modules>
@@ -43,13 +47,11 @@ Titanium CLI. Pin the same version for both platforms:
 </modules>
 ```
 
-TiSynthEngine requires Titanium SDK 13.2.0.GA or newer. Android projects must
-compile against API 35 or newer. The iOS module requires iOS 15 or newer.
+TiSynthEngine requires Titanium SDK 13.2.0.GA or newer. Android projects must compile against API 35 or newer. The iOS module requires iOS 15 or newer.
 
 ## Load and verify the contract
 
-Require the module once in the code that owns audio. Check `apiVersion` before
-starting the engine so a stale native archive fails with a useful message.
+Require the module once in the code that owns audio. Check `apiVersion` before starting. Also check the [spatial limits](#detect-the-installed-feature) and [statistics methods](#read-engine-statistics) if the app needs those features. Check [required capabilities](#detect-required-capabilities) for held voices, musical transport and master processing.
 
 ```javascript
 var synth = require('ti.synthengine')
@@ -60,15 +62,11 @@ if (contract.apiVersion !== '1.0.0') {
 }
 ```
 
-`getDefaults()` works before the stream starts. Call it again after startup if
-you need the frequency ceiling for input validation, because that ceiling
-depends on the output sample rate.
+`getDefaults()` works before the stream starts. Call it again after startup if you need the frequency ceiling for input validation, because that ceiling depends on the output sample rate.
 
 ## Lifecycle
 
-Opening a low-latency stream while Titanium lays out the first window can cause
-an underrun on some Android devices. Register `postlayout` before `open()`, wait
-for a short quiet period, and cancel the timer if the window closes first.
+Opening a low-latency stream while Titanium lays out the first window can cause an underrun on some Android devices. Register `postlayout` before `open()`, wait for a short quiet period, and cancel the timer if the window closes first.
 
 ```javascript
 var running = false
@@ -77,10 +75,12 @@ var startTimer = null
 function startAudio () {
   startTimer = null
   win.removeEventListener('postlayout', onPostLayout)
-  running = synth.startEngine({
+  running = synth.start({
     maxVoices: 16,
-    mixingProfile: 'conservative'
+    mixingProfile: 'conservative',
+    audioSession: 'ambient'
   })
+  if (!running) Ti.API.warn('TiSynthEngine could not start; keep playback controls disabled')
 }
 
 function onPostLayout () {
@@ -108,9 +108,61 @@ win.addEventListener('close', closeAudio)
 win.open()
 ```
 
-Use one owner for the engine. Start it once, pass a small audio service to the
-screens that need it, and call `shutdown()` from the owner. A second
-`startEngine()` call is harmless, but it makes ownership and cleanup unclear.
+Use one owner for the engine. Start it once, pass a small audio service to the screens that need it, and call `shutdown()` from the owner. While the engine is running, another valid `start()` call returns `true` and leaves the existing options in effect. Changing voice capacity, profile or session policy requires `shutdown()` and a new start. This example selects `ambient` for game/UI audio; the default remains `playback`. Android validates the session policy and leaves output unchanged.
+
+## Detect required capabilities
+
+Release 1.0.0 includes held voices, sample-clock sequences, stereo effects and two optional LFOs. Require the methods used by each feature before enabling its controls:
+
+```javascript
+function hasMethods (names) {
+  return names.every(function (name) { return typeof synth[name] === 'function' })
+}
+var supportsHeld = hasMethods(['noteOn', 'noteOff', 'updateVoice'])
+var supportsSequence = hasMethods(['playSequence', 'updateSequence', 'stopSequence', 'getSequenceState'])
+var supportsProcessing = hasMethods(['setMasterProcessing'])
+```
+
+Start the engine successfully before publishing held notes, sequence edits or processing. `getDefaults` and feature checks do not open the stream. Install matching packages for Android/iOS and rebuild the application when replacing a native module. Additional LFOs require the documented modulation contract; check acceptance of the complete configuration. Treat rejected configurations as unavailable rather than silently dropping their keys.
+
+## Hold and edit a voice
+
+Use `noteOn({ voiceId, ... })` when duration follows interaction: a piano key, motor, beam, pad or the last chord of a ceremony. Allocate a unique positive integer ID per attack, and release only that ID with `noteOff`. No duration or sweep-end fields are accepted. A chord held this way consists of separate IDs; unlike one `playChord` or sequence chord, separate `noteOn` calls have independent gain and publication.
+
+`updateVoice` changes compatible pitch, volume, cutoff/Q, vibrato, PWM/FM, LFO targets, noise clock, one-pole cutoff, effect send and stereo/spatial position with 10 ms ramps, without restarting oscillator/envelope phase or clearing spatial history. Source, table, filter type and ADSR are fixed at attack. Spatial edits require a voice started spatially; stereo pan edits require a stereo voice. See [complete fields](api.md#updatevoiceoptions). A note that has ended or been stolen accepts updates as a no-op; there is no note-finished event or reserved slot. A `true` return means accepted publication, not proof that the sound is still active.
+
+Release on touch end and cancellation as well as ordinary key up. Retry a rejected release twice at 16 ms outside the audio callback, then shut down and report failure if publication remains blocked. Cancel retries during teardown. The [held motor example](advanced-examples.md#sustained-game-motor) implements this ownership policy. For pause/owner close, invalidate app scheduling and shut down; require a new start before future notes.
+
+## Choose the musical transport
+
+Use `playSequence` for all successive native sounds. `playTone` and `playChord` handle independent timed events; `noteOn`/`noteOff` hold a sound for interaction. Start with `maxSequences: 1…4` to preallocate independent sequence capacity. All use the same pool of up to 32 voices.
+
+Store the positive identifier returned by `playSequence`, and include it in each update, stop or state query. 0 rejects publication. Three banks per sequence publish complete edits atomically. Structural edits enter at the next step; swing at the next pair. `setTempo({ bpm })` applies at the next block, preserving beat position. Beat sequences follow it; ms sequences keep fixed times. `stopSequence({ sequenceId })` releases only that owner's voices and leaves effect tails. A retired identifier returns null from `getSequenceState`.
+
+```javascript
+synth.setTempo({ bpm: 112 })
+var sequenceId = synth.playSequence({
+  stepDuration: 0.5, swing: 0.12, bus: 'music',
+  voice: { waveType: WAVE.SQUARE, volume: 0.55 },
+  steps: [{ notes: [60] }, { notes: [64], overrides: { pan: -0.4, panEnd: 0.4 } },
+    { rest: true }, { notes: [67], duration: 1, length: 0.8 }]
+})
+if (sequenceId === 0) throw new Error('Sequence rejected')
+// Stop this owner without affecting unrelated voices:
+synth.stopSequence({ sequenceId: sequenceId })
+```
+
+See [the full sequence contract](api.md#native-sequence-transport) for length, gate, variable durations, arpeggios, revisions and capacity rejection.
+
+## Add master effects
+
+The native chain is voices, fixed input gain, chorus, ping-pong delay, stereo Schroeder reverb, master volume, optional saturation, then the final limiter. The initial `inputGain` is 1 and chorus/delay/reverb/saturation are disabled. New notes have no extra LFOs unless requested. This preserves default render behavior without making effects exclusive to instruments or Studio.
+
+Chorus adds stereo movement, delay adds free or synchronized echoes, and reverb adds a damped tail. Saturation is optional creative drive. Select processed categories with `applyTo: ['music', 'ambience']`; a voice's explicit `effectSend` overrides that selection. One chain processes the selected share and one final limiter protects the recombined output.
+
+`setMasterProcessing` merges partial updates, validates the entire result and returns publication acceptance. Continuous controls ramp over 10 ms. Disabling an effect closes input gradually and keeps its tail, bounded to 30 seconds with a final fade, then restores exact bypass. It does not undo a non-unity input gain. `stopAll` invalidates histories and stops the native sequence; `shutdown` stops the stream and frees its buffers. See the [processing example](advanced-examples.md#chorus-delay-reverb-and-creative-saturation) and [field ranges](api.md#setmasterprocessingoptions).
+
+Delay and LFO sync follow global `setTempo` (initially 120); free settings retain milliseconds or hertz. The two extra voice LFOs target filter cutoff, square PWM or sine FM, with sine/triangle waves. They are independent of `lfoFreq`/`lfoDepth` pitch vibrato. See [two LFOs](advanced-examples.md#two-voice-lfos).
 
 ## Play the first sound
 
@@ -127,9 +179,7 @@ var accepted = synth.playTone({
 if (!accepted) Ti.API.warn('The tone was rejected')
 ```
 
-Calls that create or change sound return `true` when accepted and `false` when
-rejected. During development, handle that result and inspect logcat or the
-Xcode console for the structured validation warning.
+Timed and held sound calls and accepted edits return `true` when accepted and `false` when rejected. `playSequence` instead returns a positive sequence ID or `0`; state queries return their documented state or `null`, and lifecycle/cleanup methods follow their own return contracts. During development, handle the relevant result and inspect logcat or the Xcode console for the structured validation warning.
 
 ## Choose a pitch
 
@@ -140,13 +190,11 @@ synth.playTone({ frequency: 440 })
 synth.playTone({ note: 'A4' })
 ```
 
-Do not send both. Notes accept English names (`C#4`, `Bb3`) and solfege names
-(`DO4`, `FA#5`, `Sib3`). When the octave is omitted, octave 4 is used.
+Do not send both. Notes accept English names (`C#4`, `Bb3`) and solfege names (`DO4`, `FA#5`, `Sib3`). When the octave is omitted, octave 4 is used.
 
 ## Shape a tone
 
-The oscillator runs for `duration` milliseconds. `attack` controls the fade in
-and `release` controls the fade out; the time between them stays at full level.
+The oscillator runs for `duration` milliseconds. `attack` controls the fade in and `release` controls the fade out; the time between them stays at full level.
 
 ```javascript
 synth.playTone({
@@ -158,9 +206,7 @@ synth.playTone({
 })
 ```
 
-Explicit envelope values must fit inside `duration`. An attack equal to or
-longer than the duration is rejected, as is a release longer than the time left
-after attack.
+Explicit envelope values must fit inside `duration`. An attack equal to or longer than the duration is rejected, as is a release longer than the time left after attack.
 
 Tone options can also move during the event:
 
@@ -178,15 +224,11 @@ synth.playTone({
 })
 ```
 
-`frequencyEnd` creates a linear pitch sweep. `panEnd` moves the sound between
-channels. `lfoFreq` is the vibrato rate in hertz and `lfoDepth` is its depth in
-hertz.
+`frequencyEnd` creates a linear pitch sweep. `panEnd` moves the sound between channels. `lfoFreq` is the vibrato rate in hertz and `lfoDepth` is its depth in hertz.
 
 ## Settle, filter and modulate
 
-A flat envelope suits beeps. For plucks, keys and bells, add `decay` and
-`sustain`: the level falls from full scale to `sustain` over `decay`
-milliseconds and holds there until the release.
+A flat envelope suits beeps. For plucks, keys and bells, add `decay` and `sustain`: the level falls from full scale to `sustain` over `decay` milliseconds and holds there until the release.
 
 ```javascript
 synth.playTone({
@@ -200,13 +242,9 @@ synth.playTone({
 })
 ```
 
-`sustain` below 1 needs a nonzero `decay`, and `attack` plus `decay` must fit in
-`duration`. The 50 ms default attack counts, so set a short `attack` when the
-decay is long.
+`sustain` below 1 needs a nonzero `decay`, and `attack` plus `decay` must fit in `duration`. The 50 ms default attack counts, so set a short `attack` when the decay is long.
 
-`filterType` adds a resonant filter: `lowpass`, `highpass` or `bandpass`.
-`filterHz` is the cutoff, `filterQ` the resonance, and `filterHzEnd` sweeps the
-cutoff over the note.
+`filterType` adds a resonant filter: `lowpass`, `highpass` or `bandpass`. `filterHz` is the cutoff, `filterQ` the resonance, and `filterHzEnd` sweeps the cutoff over the note.
 
 ```javascript
 synth.playTone({
@@ -221,12 +259,9 @@ synth.playTone({
 })
 ```
 
-Any `filterHz`, `filterHzEnd` or `filterQ` without a `filterType` other than
-`none` is rejected with `filter_type_required`.
+Any `filterHz`, `filterHzEnd` or `filterQ` without a `filterType` other than `none` is rejected with `filter_type_required`.
 
-`fmDepth` makes a `SINE` voice an FM voice. `fmRatio` is the modulator
-frequency as a multiple of the carrier, and `fmDepthEnd` moves the modulation
-index over the note. Omit `fmDepthEnd` for no sweep; 0 is a real target.
+`fmDepth` makes a `SINE` voice an FM voice. `fmRatio` is the modulator frequency as a multiple of the carrier, and `fmDepthEnd` moves the modulation index over the note. Omit `fmDepthEnd` for no sweep; 0 is a real target.
 
 ```javascript
 synth.playTone({
@@ -241,8 +276,7 @@ synth.playTone({
 })
 ```
 
-`detune` shifts a pitch in cents. In a chord, `detunes` gives one offset per
-pitch, so repeating a note with small offsets thickens it:
+`detune` shifts a pitch in cents. In a chord, `detunes` gives one offset per pitch, so repeating a note with small offsets thickens it:
 
 ```javascript
 synth.playChord({
@@ -255,9 +289,7 @@ synth.playChord({
 
 ## Shape noise and waveforms
 
-Use `noiseRate` to hold each pseudo-random noise value instead of generating a
-new one every sample. A low rate sounds sparse and grainy; a high rate moves
-toward white noise. `noiseRateEnd` sweeps the update rate.
+Use `noiseRate` to hold each pseudo-random noise value instead of generating a new one every sample. A low rate sounds sparse and grainy; a high rate moves toward white noise. `noiseRateEnd` sweeps the update rate.
 
 ```javascript
 synth.playTone({
@@ -273,8 +305,7 @@ synth.playTone({
 })
 ```
 
-`lowPassHz` is a per-voice one-pole filter. `bitDepth` applies amplitude
-quantization from 2 to 16 bits. Zero disables either control.
+`lowPassHz` is a per-voice one-pole filter. `bitDepth` applies amplitude quantization from 2 to 16 bits. Zero disables either control.
 
 Square waves accept a duty cycle and a duty-cycle sweep:
 
@@ -289,8 +320,7 @@ synth.playTone({
 })
 ```
 
-For a caller-defined repeating shape, select `WAVETABLE` and provide 2 to 64
-samples from -1 to 1. The table is stepped rather than interpolated.
+For a caller-defined repeating shape, select `WAVETABLE` and provide 2 to 64 samples from -1 to 1. The table is stepped rather than interpolated.
 
 ```javascript
 synth.playTone({
@@ -317,11 +347,9 @@ synth.playChord({
 })
 ```
 
-The chord is placed on the audio queue atomically. Its voices also share a
-constant-power event gain. Several separate `playTone` calls are independent,
-can begin in different callbacks, and are hotter when summed.
+The chord is placed on the audio queue atomically. Its voices also share a constant-power event gain. Several separate `playTone` calls are independent, can begin in different callbacks, and are hotter when summed.
 
-Use `pans` when notes need deliberate positions. Supplied entries override `panSpread`; missing entries use the spread position, or remain centered when spread is 0. An array longer than the note array is rejected.
+Use `pans` to choose a position for each note. Supplied entries override `panSpread`; missing entries use the spread position, or remain centered when spread is 0. An array longer than the note array is rejected.
 
 ```javascript
 synth.playChord({
@@ -331,65 +359,34 @@ synth.playChord({
 })
 ```
 
-## Play a pattern
-
-A pattern contains 1 to 512 object steps. Each step must have exactly one of
-`note`, `frequency` or `rest: true`.
+## Play a sequence
 
 ```javascript
-synth.playPattern({
-  bpm: 126,
-  swing: 0.1,
-  noteValue: '8n',
-  waveType: contract.waveTypes.SQUARE,
-  steps: [
-    { note: 'C4' },
-    { note: 'E4' },
-    { rest: true },
-    { note: 'G4', noteValue: '4n', pan: 0.5 }
-  ]
+synth.setTempo({ bpm: 112 })
+var sequenceId = synth.playSequence({
+  stepDuration: 0.5, swing: 0.12, bus: 'music',
+  voice: { waveType: WAVE.SQUARE, volume: 0.55 },
+  steps: [{ notes: [60] }, { notes: [64], overrides: { pan: -0.4, panEnd: 0.4 } },
+    { rest: true }, { notes: [67], duration: 1, length: 0.8 }]
 })
+if (sequenceId === 0) throw new Error('Sequence rejected')
+// Stop this owner without affecting unrelated voices:
+synth.stopSequence({ sequenceId: sequenceId })
 ```
 
-Step timing is chosen in this order: step `duration`, step `noteValue`, pattern
-`noteValue`, pattern `stepDuration`, then the 100 ms default. A step also
-inherits the pattern's envelope, decay, sustain, volume, waveform, pan, sweep,
-vibrato, noise, filter, resonant filter, FM, detune, pulse-width, wavetable and
-quantization options. Values set on the step override the inherited value.
+## Know when a sequence ends
 
-Only one pattern scheduler is active. Starting another pattern cancels the
-pending steps of the previous pattern. It does not stop voices that have
-already started.
-
-## Know when a pattern ends
-
-Each accepted pattern produces one `patternend` event. `completed` is `true`
-when the pattern reaches its natural end and `false` when a newer pattern
-replaces it. Use it to chain jingles or to release state that follows a
-pattern.
-
-```javascript
-function onPatternEnd (event) {
-  if (event.completed) playNextJingle()
-}
-
-synth.addEventListener('patternend', onPatternEnd)
-```
-
-The listener belongs to the module, not to the pattern, so it outlives the
-screen unless you remove it. Add it to the same cleanup that calls
-`shutdown()`:
+Listen for `sequenceend`, whose payload is `{ sequenceId, reason: 'completed' | 'stopped' }`. Filter by the owner ID before changing UI. The event is asynchronous and may arrive while a release or effect tail remains audible. For a precise next attack, place it in the same native sequence; event chaining crosses JavaScript delivery latency. Remove the listener during owner cleanup. Identifiers survive internal slot reuse without referring to the new sequence.
 
 ```javascript
-function closeAudio () {
-  synth.removeEventListener('patternend', onPatternEnd)
-  if (running) synth.shutdown()
+function onSequenceEnd (event) {
+  if (event.sequenceId === sequenceId) Ti.API.info(event.reason)
 }
+synth.addEventListener('sequenceend', onSequenceEnd)
+// During owner cleanup:
+synth.removeEventListener('sequenceend', onSequenceEnd)
 ```
 
-`shutdown()` discards a pending pattern without an event, so a closing owner
-never receives a callback after cleanup.
-
 ## Master level and stopping
 
 ```javascript
@@ -397,32 +394,23 @@ synth.setVolume({ volume: 0.7 })
 synth.stopAll()
 ```
 
-Master volume is ramped to avoid a step in the output. `stopAll()` fades active
-voices, but it does not cancel future steps in the current pattern. Start a new
-pattern or call `shutdown()` when future scheduling must stop as well.
+Master volume is ramped to avoid a step in the output. `stopAll()` stops all native sequences, fades active voices and invalidates effect histories while leaving the engine available. Use `stopSequence({ sequenceId })` to stop only one owner and preserve unrelated sounds. `shutdown()` also stops the stream and releases its resources.
 
 ## Output route changes
 
-The native ports rebuild or resume their stream after headphones, Bluetooth or
-other output routes change. The note crossing the transition may end early;
-new notes can be played normally after the system settles. Do not restart the
-whole app for a route change.
+The native ports rebuild or resume their stream after headphones, Bluetooth or other output routes change. The note crossing the transition may end early; new notes can be played normally after the system settles. Do not restart the whole app for a route change.
 
-On iOS, `startEngine()` activates a `Playback` audio session by default. That
-ignores the silent switch and normally interrupts other audio. Pass
-`audioSession: 'ambient'` to respect the silent switch and mix with other apps;
-read [coexisting with other audio](recommendations.md#coexisting-with-other-audio)
-and test the final app on a device.
+On iOS, `start()` activates a `Playback` audio session by default. That ignores the silent switch and normally interrupts other audio. Pass `audioSession: 'ambient'` to respect the silent switch and mix with other apps; read [coexisting with other audio](recommendations.md#coexisting-with-other-audio) and test the final app on a device.
 
 ## Integrate binaural in a 2D app
 
 The JavaScript app chooses a position for each sound; the native module generates and filters that voice. Installing the module or enabling an app switch does not convert existing `pan` calls into binaural calls. Update every playback path that should use positioning, including explosions, impacts, shots, lasers and repeated motor/thrust events. A central audio service can do this once for all effects that supply their current source position. Calls bypassing that service keep their existing behavior.
 
-Keep the synthesis recipe (pitch, waveform, duration, envelope, filters, FM and volume). Replace its placement fields when submitting the event. This is per-event processing inside the native ports using the shared KEMAR FIR, rather than a global platform spatial-audio switch.
+Keep the synthesis recipe (pitch, waveform, duration, envelope, filters, FM and volume), and replace its placement fields when submitting the event. The native ports process each event with the shared KEMAR FIR; there is no global platform spatial-audio switch.
 
 ### Detect the installed feature
 
-During the unreleased 1.0.0 beta, the version string alone does not prove that an installed binary has binaural support. Check both coordinate limits before enabling the controls:
+Check both coordinate limits before enabling binaural controls to verify that the app loaded the expected native module:
 
 ```javascript
 var synth = require('ti.synthengine')
@@ -437,28 +425,28 @@ If the limits are absent, disable the binaural switch and keep stereo playback.
 
 `spatialX`/`spatialY` are signed directions from -1 to 1. A 0 to 100% amplitude slider scales the position derived from the object; it does not select a direction. At height 100%, an upper object remains above and a lower object remains below. At height 0%, both are at the front-center height, while binaural remains enabled. Direct direction sliders would instead need -100 to +100%, divided by 100.
 
-| App control | Effect |
-| --- | --- |
-| Binaural switch | Send spatial coordinates when on; omit both when off. |
+| App control                     | Effect                                                                                      |
+| ------------------------------- | ------------------------------------------------------------------------------------------- |
+| Binaural switch                 | Send spatial coordinates when on; omit both when off.                                       |
 | Horizontal amplitude, 0 to 100% | Scale each source's left/right coordinate; also controls stereo `pan` when binaural is off. |
-| Height amplitude, 0 to 100% | Scale each source's below/above coordinate; inactive in stereo mode. |
-| Master volume | Use `setVolume`; independent of direction and amplitude. |
+| Height amplitude, 0 to 100%     | Scale each source's below/above coordinate; inactive in stereo mode.                        |
+| Master volume                   | Use `setVolume`; independent of direction and amplitude.                                    |
 
-These are app preferences, not options for `startEngine` or additional native methods. Keep the app's chosen defaults and saved preferences; the module does not impose a 100% slider default. Persist them in the app if they should survive restart. A switch change applies to newly submitted events, without restarting the engine or repositioning voices already playing.
+Store these settings as app preferences; `start` does not accept them, and they have no separate native methods. Keep the app's chosen defaults and saved preferences; the module does not impose a 100% slider default. Persist them in the app if they should survive restart. A switch change applies to newly submitted events, without restarting the engine or repositioning voices already playing.
 
 With both amplitude controls at 100%, screen positions map as follows:
 
-| Position | `spatialX` | `spatialY` |
-| --- | ---: | ---: |
-| Top left | -1 | 1 |
-| Top center | 0 | 1 |
-| Top right | 1 | 1 |
-| Middle left | -1 | 0 |
-| Center | 0 | 0 |
-| Middle right | 1 | 0 |
-| Bottom left | -1 | -1 |
-| Bottom center | 0 | -1 |
-| Bottom right | 1 | -1 |
+| Position      | `spatialX` | `spatialY` |
+| ------------- | ---------: | ---------: |
+| Top left      |         -1 |          1 |
+| Top center    |          0 |          1 |
+| Top right     |          1 |          1 |
+| Middle left   |         -1 |          0 |
+| Center        |          0 |          0 |
+| Middle right  |          1 |          0 |
+| Bottom left   |         -1 |         -1 |
+| Bottom center |          0 |         -1 |
+| Bottom right  |          1 |         -1 |
 
 ### Convert screen positions when playing a tone
 
@@ -521,7 +509,7 @@ if (!playPositionedTone(explosion, 900, 100, 1000, 800)) {
 
 Connect a Titanium switch's `change` event to `audioSettings.binaural = event.value`; connect the two sliders' `change` events to `horizontalPercent` and `heightPercent`. Configure slider minimum 0 and maximum 100, and disable the height slider while the switch is off. Validate restored preference values as finite numbers within those ranges before using them. Do not pass these preference names to `playTone`: that would return `false` with `unsupported_option`.
 
-Supply the current position whenever an effect fires. A projectile launch cue can use the launch position; an impact uses the collision position. Repeated short motor events can use successive positions. A single active tone cannot move after submission because this API has no per-voice handle or position-update method. Stereo `panEnd` movement cannot be combined with binaural; do not continually retrigger long sounds every frame to imitate movement.
+Supply the current position whenever an effect fires. A projectile launch cue can use the launch position; an impact uses the collision position. Timed event positions remain fixed after submission. An identified sustained voice started spatially can instead change `spatialX`/`spatialY` through `updateVoice`, with 10 ms ramps and retained spatial history. A stereo voice cannot become spatial through an update. Stereo `panEnd` movement cannot be combined with binaural; do not continually retrigger long sounds every frame to imitate movement.
 
 ### Chords and patterns
 
@@ -537,21 +525,18 @@ if (!synth.playChord({
 })) Ti.API.warn('Spatial chord rejected')
 ```
 
-Pattern steps inherit coordinates from the root and can override either one. Remove conflicting stereo fields from both the root and every step; even `pan: 0` conflicts with a spatial coordinate. A step cannot opt out of inherited binaural by passing zero coordinates; use a pattern without spatial coordinates on its root for a mix of spatial and stereo steps.
+Sequence steps inherit coordinates from root `voice` and can override either one. Remove conflicting stereo fields from both root `voice` and every step override; even `pan: 0` conflicts with a spatial coordinate. A step cannot opt out of inherited binaural by passing zero coordinates; use a pattern without spatial coordinates in its root voice for a mix of spatial and stereo steps.
 
 ```javascript
-if (!synth.playPattern({
+if (!synth.playSequence({
+  timeUnit: 'ms',
   stepDuration: 300,
-  attack: 5,
-  release: 80,
-  volume: 0.3,
-  spatialX: 0,
-  spatialY: 1,
+  voice: { attack: 5, release: 80, volume: 0.3, spatialX: 0, spatialY: 1 },
   steps: [
-    { note: 'C4' },
-    { note: 'E4', spatialY: -1 },
+    { notes: [60] },
+    { notes: [64], overrides: { spatialY: -1 } },
     { rest: true },
-    { note: 'G4', spatialX: 1, spatialY: 0 }
+    { notes: [67], overrides: { spatialX: 1, spatialY: 0 } }
   ]
 })) Ti.API.warn('Spatial pattern rejected')
 ```
@@ -560,12 +545,59 @@ if (!synth.playPattern({
 
 Use stereo headphones and compare isolated broadband noise above/below before testing many collisions. Perceived elevation varies with the listener, headphones and spectrum; low sine tones are weak tests. The output is still stereo, with a front plane and no rear sources, distance attenuation, room reflections or head tracking. A 100% slider uses the modeled directional range; it does not guarantee strong localization for every person.
 
-CPU cost depends on concurrent spatial voices and their short tails, not the total number of effects over a game. Measure the intended device and realistic event overlap. Host replay is a comparison tool, not device CPU, battery, heat or underrun evidence. See [the renderer](audio-engine.md#binaural-front-plane-renderer) and [diagnostic checks](troubleshooting.md#binaural-does-not-change-the-position).
+Measure CPU cost on the intended device with realistic event overlap. The cost depends on concurrent spatial voices and their short tails; the total number of effects over a game does not determine it. Host replay supports comparisons but does not measure device CPU, battery, heat or underruns. See [the renderer](audio-engine.md#binaural-front-plane-renderer) and [diagnostic checks](troubleshooting.md#binaural-does-not-change-the-position).
+
+## Read engine statistics
+
+Basic counters are available without enabling optional diagnostics. Reads do not start audio or reset counters. Detect the methods if supporting older development packages that also report 1.0.0:
+
+```javascript
+var statsTimer = null
+var statsSupported = typeof synth.getStats === 'function' &&
+  typeof synth.setStatsEnabled === 'function' && typeof synth.resetStats === 'function'
+
+function readStats () {
+  var stats = synth.getStats()
+  Ti.API.info('Voices: ' + stats.activeVoices + '/' + stats.maxVoices)
+  Ti.API.info('Render load: ' + (stats.renderLoad === null
+    ? 'unmeasured' : (stats.renderLoad * 100).toFixed(1) + '%'))
+}
+
+function startDiagnostics () {
+  if (!statsSupported || statsTimer !== null) return false
+  if (!synth.setStatsEnabled(true)) return false
+  statsTimer = setInterval(readStats, 200)
+  return true
+}
+
+function stopDiagnostics () {
+  if (statsTimer !== null) clearInterval(statsTimer)
+  statsTimer = null
+  if (statsSupported) synth.setStatsEnabled(false)
+}
+
+// Read basic counters without enabling timing or signal meters:
+if (statsSupported) readStats()
+// When the user requests diagnostics: startDiagnostics()
+// When the diagnostic view hides, the app backgrounds or the owner closes:
+// stopDiagnostics()
+// To reset accumulated counters deliberately, without stopping playback:
+// if (statsSupported) synth.resetStats()
+```
+
+Integrate `stopDiagnostics()` into the existing owner's hide/background/close handlers, before shutdown. Resume polling only while the diagnostic view is active; do not add a second engine owner. Timing and output meters stay `null` until enabled and measured. Basic counters remain available when diagnostics are off. Android backend underrun/buffer/latency fields are best-effort and independent of that switch; iOS returns `null` for those backend fields. A zero underrun count does not prove clean sound.
+
+See the [complete field contract](api.md#getstats), [measurement limits](stats-performance.md) and [interactive statistics controls](../assets/example/README.md#statistics).
 
 ## Next steps
 
 - [API reference](api.md) for every accepted key and limit.
 - [Sound design](sound-design.md) for waveform, envelope, filter and FM recipes.
 - [Examples](examples.md) for copy-ready sounds and patterns.
-- [Troubleshooting](troubleshooting.md) when a call returns `false` or audio is
-  silent.
+- [Troubleshooting](troubleshooting.md) when a call returns `false` or audio is silent.
+
+## Diagnose mix headroom
+
+The current diagnostics add `preLimiterPeakDb` (maximum signal before final limiting, in dBFS) and `maxLimiterReductionDb` (greatest limiter attenuation in dB) accumulated since reset. Unlike the approximately 200 ms window reduction field, brief peaks remain visible between UI polls. Enable measurements, reset before the scenario and keep `null`/absent fields distinct from measured zero. The [measurement example](advanced-examples.md#measure-peaks-and-limiter-reduction) shows opt-in polling and cleanup.
+
+Fixed event/input gain does not normalize continuously by active voice count. Coherent overlapping notes, effects feedback or resonance can still exceed the ceiling; the limiter then acts on the whole stereo sum. Saturation is a separate creative processor, disabled initially. Physical loudness and small-speaker bass response are not measured by these digital meters.