@maccesar/titools 5.2.0 → 5.2.2

package/skills/ti-synthengine/references/audio-engine.md

@@ -1,10 +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/audio-engine.md` SHA-256: `7b5707ee22e01a351af3633be14458726f8956069fb9355d1fb31cc4f7b9438a`.
+> Source snapshot: official TiSynthEngine 1.0.0 documentation at release source commit `e7cbbe8a6f9ab38088fd8029c7b43cef6501101f` (2026-10-24). Upstream `documentation/audio-engine.md` SHA-256: `2299982e6949f6f2efe7ddad6cc4d28ea1b54e0f31fff36617e0528c5823ac4d`.
 
 # Audio engine
 
-This page explains the native signal path behind the JavaScript API. You do not
-need it to play a sound, but it helps when choosing a mixing profile, sizing the
-voice pool or investigating device behavior.
+The native signal path explains how mixing profiles and voice capacity affect the output. Use this reference when choosing those settings or investigating device behavior; it is optional for basic playback.
 
 <!-- TOC-START -->
 ## Contents
@@ -25,112 +23,86 @@ voice pool or investigating device behavior.
 - [Route behavior](#route-behavior)
 - [Regression coverage](#regression-coverage)
 - [Binaural front-plane renderer](#binaural-front-plane-renderer)
+- [Own-platform performance verification](#own-platform-performance-verification)
 - [Engine statistics](#engine-statistics)
+- [Sustained voices](#sustained-voices)
+- [Native transport and processing](#native-transport-and-processing)
+- [Unified transport acceptance boundaries](#unified-transport-acceptance-boundaries)
 
 <!-- TOC-END -->
 
 ## Signal path
 
 ```text
-playTone / playChord / playPattern
-             |
-       strict validation
-             |
-   native command ring buffer
-             |
- voice pool: source (or FM) -> quantizer -> one-pole low-pass
-             -> state-variable filter -> envelope -> gain
-             -> stereo pan OR binaural FIR
-             |
-       sum voices and steal tails
-             |
-      smoothed master volume
-             |
- stereo-linked lookahead limiter
-             |
-        floating-point output
+playTone / playChord / noteOn     playSequence / updateSequence
+       strict commands          atomic preallocated score banks
+               \                 /
+                shared 32-voice renderer
+       source/FM -> quantizer -> filters -> envelope -> event gain
+                  stereo pan OR binaural FIR
+                             |
+            per-voice category selection / explicit send
+                   /                         \
+        selected share                    dry share
+ input gain -> chorus -> delay -> reverb   input gain
+        master -> optional saturation       master
+                   \                         /
+                     stereo recombination
+                  one final lookahead limiter
+                      floating-point output
 ```
 
-The audio callback does not allocate memory or wait on a lock. JavaScript and
-the pattern scheduler publish small commands; the real-time thread consumes
-them and renders the samples.
+The audio callback does not allocate memory or wait on a lock. JavaScript publishes control commands and immutable score banks; the real-time thread schedules and renders the samples.
 
 ## Oscillators
 
 The engine has six sources:
 
-| Waveform | Source behavior |
-| --- | --- |
-| `SINE` | Direct sinusoid. |
-| `SQUARE` | PolyBLEP band-limited discontinuity. |
-| `SAWTOOTH` | PolyBLEP band-limited discontinuity. |
-| `TRIANGLE` | Continuous triangle oscillator. |
-| `NOISE` | White or variable-rate sample-and-hold pseudo-random generator. |
-| `WAVETABLE` | Caller-supplied 2 to 64-sample stepped cycle. |
-
-Pitch can move linearly from `frequency` to `frequencyEnd`. A sine LFO adds
-`lfoDepth * sin(lfoPhase)` in hertz before the oscillator advances. This makes
-vibrato depth absolute in hertz rather than cents.
-
-Noise rate advances an independent phase accumulator. A zero `noiseRate` uses
-one new pseudo-random value per output sample; a positive rate holds that value
-until the accumulator crosses the next update. `noiseRateEnd` changes the
-increment linearly over the event.
-
-The source is optionally quantized to the selected `bitDepth` (2 to 16 bits)
-and then passes through a one-pole low-pass filter when `lowPassHz` is nonzero.
-Square waves use `pulseWidth` for the second PolyBLEP discontinuity and can
-interpolate that duty cycle toward `pulseWidthEnd`.
+| Waveform    | Source behavior                                                 |
+| ----------- | --------------------------------------------------------------- |
+| `SINE`      | Direct sinusoid.                                                |
+| `SQUARE`    | PolyBLEP band-limited discontinuity.                            |
+| `SAWTOOTH`  | PolyBLEP band-limited discontinuity.                            |
+| `TRIANGLE`  | Continuous triangle oscillator.                                 |
+| `NOISE`     | White or variable-rate sample-and-hold pseudo-random generator. |
+| `WAVETABLE` | Caller-supplied 2 to 64-sample stepped cycle.                   |
+
+Pitch can move linearly from `frequency` to `frequencyEnd`. A sine LFO adds `lfoDepth * sin(lfoPhase)` in hertz before the oscillator advances. This makes vibrato depth absolute in hertz rather than cents.
+
+Noise rate advances an independent phase accumulator. A zero `noiseRate` uses one new pseudo-random value per output sample; a positive rate holds that value until the accumulator crosses the next update. `noiseRateEnd` changes the increment linearly over the event.
+
+The source is optionally quantized to the selected `bitDepth` (2 to 16 bits) and then passes through a one-pole low-pass filter when `lowPassHz` is nonzero. Square waves use `pulseWidth` for the second PolyBLEP discontinuity and can interpolate that duty cycle toward `pulseWidthEnd`.
 
 ### Frequency modulation
 
-A `SINE` voice with a positive `fmDepth`, or with `fmDepthEnd`, is phase
-modulated: the carrier computes `sin(2 * pi * phase + depth * sin(2 * pi *
-modPhase))`. The modulator phase advances by the carrier's instantaneous phase
-increment times `fmRatio`, so pitch sweeps and vibrato keep the ratio. The
-index moves linearly from `fmDepth` to `fmDepthEnd` over the event. With a depth
-of exactly 0 and no end, the voice takes the plain sine path.
+A `SINE` voice with a positive `fmDepth`, or with `fmDepthEnd`, is phase modulated: the carrier computes `sin(2 * pi * phase + depth * sin(2 * pi * modPhase))`. The modulator phase advances by the carrier's instantaneous phase increment times `fmRatio`, so pitch sweeps and vibrato keep the ratio. The index moves linearly from `fmDepth` to `fmDepthEnd` over the event. With a depth of exactly 0 and no end, the voice takes the plain sine path.
 
-The modulated sine has constant amplitude, so event gain is unchanged. Nothing
-band-limits the sidebands, so a high carrier with a large index aliases.
+The modulated sine has constant amplitude, so event gain is unchanged. Nothing band-limits the sidebands, so a high carrier with a large index aliases.
 
 ### State-variable filter
 
-`filterType` selects a topology-preserving state-variable filter that runs
-after the one-pole `lowPassHz` stage. It is stable while its coefficients move,
-which is why a cutoff sweep cannot blow up even at high Q.
+`filterType` selects a topology-preserving state-variable filter that runs after the one-pole `lowPassHz` stage. It stays stable as its coefficients change, including during a cutoff sweep at high Q.
 
-| Output | Response |
-| --- | --- |
-| `lowpass` | 12 dB per octave, peak of about Q at the cutoff. |
+| Output     | Response                                         |
+| ---------- | ------------------------------------------------ |
+| `lowpass`  | 12 dB per octave, peak of about Q at the cutoff. |
 | `highpass` | 12 dB per octave, peak of about Q at the cutoff. |
-| `bandpass` | Unity gain at the center for every Q. |
+| `bandpass` | Unity gain at the center for every Q.            |
 
-The cutoff is held between 20 Hz and `sampleRate * 0.45`. With `filterHzEnd`
-the cutoff follows `from * (to / from) ^ t`, where `t` runs from 0 to 1 across
-the event, and coefficients are recomputed every eighth sample. Without a
-sweep they are computed once, when the note starts.
+The cutoff is held between 20 Hz and `sampleRate * 0.45`. For timed tones and chords, `filterHzEnd` follows `from * (to / from) ^ t`, where `t` runs from 0 to 1 across the event, and coefficients are recomputed every eighth sample. Native sequence cutoff sweeps instead use note length and then hold their target through release. The current Android renderer refreshes them every sixteenth sample, also forcing the target at the release deadline; the Apple renderer refreshes them every eighth sample. These renderer paths do not establish sample-identical platform output. Held live cutoff/Q and modulation updates have their own ramp/control paths. Without a sweep or live modulation, coefficients are computed once at note start.
 
 ## Envelope
 
-Each voice has a smoothstep attack, an optional smoothstep decay to `sustain`,
-a hold at that level and a smoothstep release. `duration` includes the whole
-envelope. Defaults are adjusted to fit a short event, while an explicit
-envelope that cannot fit is rejected by the contract.
+Each voice has a smoothstep attack, an optional smoothstep decay to `sustain`, a hold at that level and a smoothstep release. For timed tones and chords, `duration` includes the whole envelope: defaults are adjusted to fit a short event, while an explicit envelope that cannot fit is rejected. Held voices release on `noteOff`; sequence notes release at their gate/length deadline. Held/sequence ADSR has no timed-event duration budget, and their release may continue beyond the sequence interval.
 
 ```text
 base = attack ramp, then decay ramp from 1 to sustain, then sustain
 level = base * release ramp
 ```
 
-The release ramp multiplies the base level, so a release that begins during the
-decay is continuous. With `decay: 0` and `sustain: 1` the base is 1 after the
-attack and the result is the plain attack, hold and release shape. Voice-steal
-tails read the final level, so they stay continuous with the decay too.
+The release ramp multiplies the base level, so a release that begins during the decay is continuous. With `decay: 0` and `sustain: 1` the base is 1 after the attack and the result is the plain attack, hold and release shape. Voice-steal tails read the final level, so they stay continuous with the decay too.
 
-Voice stealing does not cut the old waveform at an arbitrary sample. The old
-voice contributes a short tail of roughly 6 ms while the slot begins the new
-event. `stopAll()` uses a release of roughly 20 ms for the same reason.
+When a slot is reused, the old voice contributes a short tail of roughly 6 ms while the new event begins, avoiding a cut at an arbitrary sample. `stopAll()` uses a release of roughly 20 ms to avoid the same discontinuity.
 
 ## Event gain
 
@@ -140,124 +112,80 @@ In protected profiles, gain is fixed when an event starts:
 voiceGain = waveformGain(waveType) * profileFactor / sqrt(eventVoiceCount)
 ```
 
-One tone and one pattern step have an event voice count of 1. A chord uses the
-number of pitches in that chord. Dividing by the square root of the count keeps
-the event close to constant power without changing gain sample by sample.
+One tone and one independently held note have an event voice count of 1. Chords, including sequence chords, use their initial pitch count for fixed event compensation. Adding or releasing other voices never rescales an existing event.
 
 Waveforms are calibrated toward a common source RMS:
 
-| Waveform | Base gain | Approximate output RMS |
-| --- | ---: | ---: |
-| Sine | 0.440 | 0.311 |
-| Square | 0.311 | 0.311 |
-| Sawtooth, triangle, noise and wavetable | 0.539 | signal-dependent |
+| Waveform                                | Base gain | Approximate output RMS |
+| --------------------------------------- | --------: | ---------------------: |
+| Sine                                    |     0.440 |                  0.311 |
+| Square                                  |     0.311 |                  0.311 |
+| Sawtooth, triangle, noise and wavetable |     0.539 |       signal-dependent |
 
-This calculation is why one three-note `playChord` and three `playTone` calls
-are not equivalent. A protected sine triad assigns about 0.254 to each chord
-voice (`0.440 / sqrt(3)`). Three separate tone events each receive 0.440, for a
-much hotter worst-case sum.
+This calculation is why one three-note `playChord` and three `playTone` calls are not equivalent. A protected sine triad assigns about 0.254 to each chord voice (`0.440 / sqrt(3)`). Three separate tone events each receive 0.440, for a much hotter worst-case sum.
 
 ## Mixing profiles
 
-The profile is fixed when `startEngine()` opens the stream.
+The profile is fixed when `start()` opens the stream.
 
-| Profile | Factor | Sine gain | Limiter ceiling | Intended use |
-| --- | ---: | ---: | ---: | --- |
-| `conservative` | 1 | 0.440 | 0.85 | Default headroom for polyphony and effects. |
-| `balanced` | `sqrt(2)` | 0.622 | 0.85 | Mostly one or two simultaneous voices. |
-| `speakerSafe` | `1 / sqrt(2)` | 0.311 | 0.70 | Small speakers and demanding low pitches. |
-| `raw` | no source reduction | 1.000 | 0.85 | App-controlled gain staging. |
+| Profile        |              Factor | Sine gain | Limiter ceiling | Intended use                                |
+| -------------- | ------------------: | --------: | --------------: | ------------------------------------------- |
+| `conservative` |                   1 |     0.440 |            0.85 | Default headroom for polyphony and effects. |
+| `balanced`     |           `sqrt(2)` |     0.622 |            0.85 | Mostly one or two simultaneous voices.      |
+| `speakerSafe`  |       `1 / sqrt(2)` |     0.311 |            0.70 | Small speakers and demanding low pitches.   |
+| `raw`          | no source reduction |     1.000 |            0.85 | App-controlled gain staging.                |
 
-`raw` lets one full-volume oscillator reach full scale before the master. Any
-overlap then relies on the limiter, so it is not a general-purpose loudness
-setting.
+`raw` lets one full-volume oscillator reach full scale before the master. Any overlap then relies on the limiter, so it is not a general-purpose loudness setting.
 
 ## Limiter
 
-A single stereo-linked peak limiter sits after master volume. Linking preserves
-the stereo image when only one channel has the largest peak.
+A single stereo-linked peak limiter sits after master volume and optional creative saturation. Linking preserves the stereo image when only one channel has the largest peak.
 
-| Parameter | Value |
-| --- | --- |
-| Lookahead | 10 ms |
-| Release | 100 ms, exponential |
-| Ceiling | 0.85, or 0.70 with `speakerSafe` |
+| Parameter | Value                            |
+| --------- | -------------------------------- |
+| Lookahead | 10 ms                            |
+| Release   | 100 ms, exponential              |
+| Ceiling   | 0.85, or 0.70 with `speakerSafe` |
 
-Lookahead gives the gain time to reach a safe value before the peak reaches the
-output. Below the ceiling the limiter converges back to unity. It is meant to
-catch exceptional sums, not to normalize every callback.
+Lookahead gives the gain time to reach a safe value before the peak reaches the output. Below the ceiling, the limiter converges back to unity. It catches exceptional sums without normalizing every callback.
 
-Repeated overlapping events can make any limiter audibly raise and lower the
-bus. A loop that starts a 300 ms chord every 100 ms is therefore a useful load
-test and a poor tonal reference. Judge the chord with one sustained event; use
-the overlapping loop only when testing scheduling, stealing and recovery.
+Overlapping events can trigger audible limiting when their sum exceeds the ceiling. Check the accumulated reduction measurement before attributing a volume dip to this protection: repeated same-pitch oscillators can also cancel one another even below the ceiling. Compatible public sustained-note repetitions preserve the phase of a releasing predecessor while retaining separate envelopes and tails. Timed calls, transport notes and simultaneous held unisons keep their existing phase policy.
 
 ## Master volume and pan
 
-`setVolume()` ramps the master rather than applying a discontinuous gain step.
-Per-event `volume` is multiplied before the bus. Values up to 2 are valid, but
-values above 1 use headroom and make limiting more likely.
+`setVolume()` ramps the master to avoid a discontinuous gain step. Per-event `volume` is multiplied before the bus. Values up to 2 are valid, but values above 1 use headroom and make limiting more likely.
 
-Pan uses equal-power coefficients. A centered sound feeds both channels; the
-sum does not simply double. `panEnd` interpolates the position across a tone or
-pattern step. Chords use `panSpread` or the explicit `pans` array.
+Pan uses equal-power coefficients. A centered sound feeds both channels; the sum does not simply double. `panEnd` interpolates the position across a tone or sequence note. Chords use `panSpread` or the explicit `pans` array.
 
 ## Voice pool
 
-`maxVoices` reserves between 1 and 32 active voice slots. The setting controls
-capacity, not event gain. When every slot is occupied, the voice with the least
-time remaining is faded and its slot is reused.
+`maxVoices` reserves between 1 and 32 active voice slots. The setting controls capacity and leaves event gain unchanged. Replacement first considers the lowest eligible priority (0-3); higher-priority voices are protected. Among that priority, timed-only replacement selects least remaining duration; sustained/transport replacement prefers releasing voices, then oldest attack. A reused slot receives a short fade tail; no category owns reserved slots.
 
-A chord is one command with up to 32 pitches. If its size exceeds the session's
-voice capacity, slots with the least time remaining are reused. For normal apps,
-choose the largest real overlap plus room for release tails.
+A chord is an atomic group of up to 32 pitches. If capacity or priority cannot accommodate every pitch, the entire group is dropped. When any held/transport voice is active, that policy also applies to incoming timed tones/chords. For normal apps, choose the largest real overlap plus room for release tails.
 
 ## Command queue
 
-Both ports use a 128-slot single-consumer ring buffer. Producers are serialized
-with a lock that the audio callback never touches. When note commands cannot be
-queued, the public call returns `false` and logs an `overflow` warning.
+Both ports use a 128-slot single-consumer ring buffer. Producers are serialized with a lock that the audio callback never touches. When note commands cannot be queued, the public call returns `false` and logs an `overflow` warning.
 
-`playChord()` publishes its note data and advances the queue index once. The
-consumer receives the complete event or nothing. `stopAll` and `shutdown` have
-a control fallback so cleanup is not lost under queue pressure.
+`playChord()` publishes its note data and advances the queue index once. The consumer receives the complete event or nothing. `stopAll` and `shutdown` have a control fallback so cleanup is not lost under queue pressure.
 
-Pattern timing runs outside the audio callback. A platform timer places each
-step on the command queue. The sequence is suitable for game cues and simple
-musical patterns, but it is not a sample-accurate composition timeline. The
-same timer fires `patternend`, about 1 ms after the sum of the step lengths,
-and the event is handed to the JavaScript runtime asynchronously.
+`playSequence` runs inside the sample-clock callback; JavaScript publishes entire configurations rather than individual notes. Scheduled releases execute independently of public command-queue capacity. `sequenceend` records are delivered outside the callback and retain their sequence identifier when slots are reused.
 
 ## Shared DSP core
 
-The envelope, the state-variable filter, the sweep helpers, the FM sine and
-the cents conversion live once, in `shared/synth_core.h`. It is plain C,
-header-only and allocation-free. The Android renderer includes it from
-`android/jni/SynthOboeEngine.cpp` and the iOS renderer from
-`ios/Classes/TiSynthengineModule.m`, so both platforms run the same code. Voice
-management, mixing and the limiter are still separate per platform.
+The envelope, the state-variable filter, the sweep helpers, the FM sine and the cents conversion live once, in `shared/synth_core.h`. It is plain C, header-only and allocation-free. The Android renderer includes it from `android/jni/SynthOboeEngine.cpp` and the iOS renderer from `ios/Classes/TiSynthengineModule.m`, so both platforms run the same code. Backend voice integration, mixing and the limiter remain separate per platform. Held envelopes/ramps, transport, master effects, extra modulation and compatible retrigger support also have shared C cores.
 
 ## Android implementation
 
-Android renders in C++ through Oboe. The stream requests floating-point output,
-low-latency performance and exclusive sharing when the device supports it. If
-exclusive access is unavailable, Oboe can use shared mode.
+Android renders in C++ through Oboe. The stream requests floating-point output, low-latency performance and exclusive sharing when the device supports it. If exclusive access is unavailable, Oboe can use shared mode.
 
-The renderer mixes in the data callback and targets a small device buffer. A
-route or stream error triggers a reopen on the current output. The supported
-ABIs are `arm64-v8a`, `armeabi-v7a`, `x86` and `x86_64`.
+The renderer mixes in the data callback and targets a small device buffer. A route or stream error triggers a reopen on the current output. The supported ABIs are `arm64-v8a`, `armeabi-v7a`, `x86` and `x86_64`.
 
 ## iOS implementation
 
-iOS renders with `AVAudioEngine` and `AVAudioSourceNode`, using the active
-session's sample rate. The module configures the audio session as `Playback`,
-or `Ambient` when `startEngine()` receives `audioSession: 'ambient'`, activates
-it, and observes route and engine configuration notifications. If a route
-change stops the graph, the port reapplies the category, reactivates the
-session and resumes the existing renderer.
+iOS renders with `AVAudioEngine` and `AVAudioSourceNode`, using the active session's sample rate. The module configures the audio session as `Playback`, or `Ambient` when `start()` receives `audioSession: 'ambient'`, activates it, and observes route and engine configuration notifications. If a route change stops the graph, the port reapplies the category, reactivates the session and resumes the existing renderer.
 
-The module targets iOS 15 or newer. The module archive contains device,
-simulator and Mac Catalyst slices.
+The module targets iOS 15 or newer. The module archive contains device, simulator and Mac Catalyst slices.
 
 ## Latency
 
@@ -265,23 +193,17 @@ End-to-end latency contains three main pieces:
 
 1. The fixed 10 ms limiter lookahead.
 2. The hardware and operating-system output buffer.
-3. JavaScript or platform timer scheduling before the command reaches audio.
+3. JavaScript publication and callback-boundary latency for a newly submitted event; accepted sequence steps then follow the sample clock.
 
-Immediate calls are suitable for interface and game feedback. A visual or
-musical event that must align to a known future time should be scheduled ahead
-by the app instead of relying on a JavaScript callback at that instant.
+Immediate calls are suitable for interface and game feedback. A visual or musical event that must align to a known future time should be scheduled ahead by the app instead of relying on a JavaScript callback at that instant.
 
 ## Route behavior
 
-Connecting headphones or changing another output route can interrupt the
-hardware stream. The ports recover automatically, though the event crossing
-the transition may be cut short and the operating system may keep the new
-route muted briefly. Start later sounds normally after the route settles.
+Connecting headphones or changing another output route can interrupt the hardware stream. The ports recover automatically, though the event crossing the transition may be cut short and the operating system may keep the new route muted briefly. Start later sounds normally after the route settles.
 
 ## Regression coverage
 
-The repository checks the public contract and both source ports without a
-device:
+The repository checks the public contract and both source ports without a device:
 
 ```sh
 node tests/api_contract_regression.js
@@ -301,10 +223,7 @@ java -cp "$test_dir" ti.synthengine.SynthSpatialContractRegression
 java -cp "$test_dir" ti.synthengine.SynthDspRegression
 ```
 
-The DSP suite covers stable RMS from 1 through 32 voices, limiter transparency
-and recovery, waveform discontinuities, envelope endpoints, master smoothing,
-voice stealing and representative dense chords. Device tests remain necessary
-for route changes, startup underruns and speaker acoustics.
+The DSP suite covers stable RMS from 1 through 32 voices, limiter transparency and recovery, waveform discontinuities, envelope endpoints, master smoothing, voice stealing and representative dense chords. Device tests remain necessary for route changes, startup underruns and speaker acoustics.
 
 Three more checks cover the shared core, the Android engine and the iOS contract.
 
@@ -317,18 +236,9 @@ cc -std=c99 -O2 -Wall -Wextra -o "$test_dir/dsp_core" \
 "$test_dir/dsp_core"
 ```
 
-It checks that the envelope equals the original attack, hold and release shape
-for every attack and release combination when decay is off, the decay and
-sustain endpoints and continuity, the response of each filter type (slope,
-cutoff and the resonance peak), stability of every filter type under a cutoff
-sweep on noise, FM sidebands against the Bessel function values and the cents
-conversion.
+It checks that the envelope equals the original attack, hold and release shape for every attack and release combination when decay is off, the decay and sustain endpoints and continuity, the response of each filter type (slope, cutoff and the resonance peak), stability of every filter type under a cutoff sweep on noise, FM sidebands against the Bessel function values and the cents conversion.
 
-The Android engine renders on the host. `tests/engine_render_host.cpp` compiles
-`SynthOboeEngine.cpp` without opening an audio stream and drives the same
-command and callback path Oboe uses. It needs the Oboe headers, which any
-Gradle cache that built the module has, and the JDK's `jni.h`, so it is a local
-check and does not run in CI:
+The Android engine renders on the host. `tests/engine_render_host.cpp` compiles `SynthOboeEngine.cpp` without opening an audio stream and drives the same command and callback path Oboe uses. It needs the Oboe headers, which any Gradle cache that built the module has, and the JDK's `jni.h`, so it is a local check and does not run in CI:
 
 ```sh
 OBOE=$(find ~/.gradle -path '*oboe-1.10.0/prefab/modules/oboe/include' | head -1)
@@ -341,18 +251,9 @@ clang++ -std=c++17 -O1 -Wall -I"$OBOE" -I"$JH/include" -I"$JH/include/darwin" \
 "$test_dir/engine_render"
 ```
 
-It renders decay and sustain levels, filter attenuation, an opening cutoff
-sweep, FM sidebands and an FM index that decays to nothing, plus voice stealing
-and `stopAll` with every control active. Built without `-DHAS_EXPRESSIVE` it
-renders only the original controls and prints one hash per scenario, so the
-same file can be built against an older copy of the engine and the hashes
-compared.
+It renders decay and sustain levels, filter attenuation, an opening cutoff sweep, FM sidebands and an FM index that decays to nothing, plus voice stealing and `stopAll` with every control active. Built without `-DHAS_EXPRESSIVE` it renders only the original controls and prints one hash per scenario, so the same file can be built against an older copy of the engine and the hashes compared.
 
-The iOS contract replays the cases that the Java contract test writes to
-`tests/contract_corpus.jsonl`. The Java test fails when that file no longer
-matches the Java contract; regenerate it from `android/` with
-`-Dsynth.corpus.out=../tests/contract_corpus.jsonl`. On macOS, run the iOS
-side from the repository root:
+The iOS contract replays the cases that the Java contract test writes to `tests/contract_corpus.jsonl`. The Java test fails when that file no longer matches the Java contract; regenerate it from `android/` with `-Dsynth.corpus.out=../tests/contract_corpus.jsonl`. On macOS, run the iOS side from the repository root:
 
 ```sh
 test_dir=$(mktemp -d /tmp/ti-synth-ios.XXXXXX)
@@ -362,14 +263,39 @@ clang -fobjc-arc -Wall -Wextra -framework Foundation \
 "$test_dir/contract_corpus_ios"
 ```
 
-The iOS renderer shares the DSP math through the same header, but nothing
-renders its output on the host, so check it on a device.
+The iOS renderer uses the same DSP header. Its actual Objective-C render body has a host PCM/state comparison described below; device scheduling and audible output require separate checks.
 
 ## Binaural front-plane renderer
 
 `shared/synth_spatial.h` runs the same allocation-free FIR processor in both native ports, after each voice envelope and before summation/master/limiter. Nine stereo impulse responses from Gardner and Martin's MIT KEMAR measurements form a compact front-plane grid. The complete 128-sample source responses at 44.1 kHz are interpolated across direction and linearly resampled once at voice onset to the output rate. A single front-response energy calibration preserves directional differences. At 48 kHz the convolution uses 140 padded taps per ear. Buffers are reserved with the voice/tail pools; there are no runtime downloads, callback allocations, or additional callback locks.
 
-Spatial voice-steal and stop tails copy the filter history as well as oscillator state. After the source envelope or fade ends, both ports drain the FIR with zero input for `taps - 1` samples before freeing the voice; this preserves even 1 ms events. Ordinary voices bypass the FIR. CPU cost grows with spatial voices, including short replacement tails. A fixed position avoids changing the filter during an event. The intended output-rate range is 8 to 192 kHz. Interpolated generic HRTFs provide directional cues, not guaranteed individual localization.
+Spatial voice-steal and stop tails copy the filter history as well as oscillator state. After the source envelope or fade ends, both ports drain the FIR with zero input for `taps - 1` samples before freeing the voice; this preserves even 1 ms events. Ordinary voices bypass the FIR. CPU cost grows with spatial voices, including short replacement tails. Spatial held updates prepare coefficients outside audio, then ramp the FIR over 10 ms while retaining history. The intended output-rate range is 8 to 192 kHz. Interpolated generic HRTFs provide directional cues, but localization varies by listener.
+
+Android ARM64 reuses coefficients across eight consecutive samples, with four-sample and streaming fallbacks for partial blocks and position ramps. Tiles stop before native sequence attacks and retain per-sample clocks, gates, phase, history and mixing order. Apple retains its original streaming renderer. The proposed Apple adaptation was bit exact and faster in host/binaural tests but was removed after a reproducible physical stereo timing regression. Output buffers and lookahead latency are unchanged.
+
+## Own-platform performance verification
+
+The [performance review](performance-review.json) separates measured host improvements, exact compatibility checks and pending device acceptance. Its [raw evidence](performance-review-evidence.zip) retains rejected prototypes and the investigation of idle/stereo regressions. The Apple FIR, stable-control cache and exact idle-effects bypass were evaluated as one atomic candidate and then rejected after physical 32-stereo timing regressed. All three production changes were removed together; the full-score publication and control-memory fixes remain.
+
+Matched 48 kHz/1024-frame iPad full-load runs completed 600 audio seconds without callback deadline misses, with p95 load upper bounds 0.427 for the reference and 0.383 for the rejected initial candidate. The original Apple callback was restored because 32-stereo bypass p95 regressed reproducibly, including continuous-voice windows. Android Sim20/Sim80 frame presentation remains near 60 FPS, while occasional Sim80 output underruns persist in both versions. Compact 48 kHz iPad memory growth is about 18.2 MiB in both versions; no material RAM saving or physical 192 kHz acceptance is claimed. These results and qualified listening observations are recorded separately in the review.
+
+`tools/build_ios_render_host.py` compiles the actual Objective-C render-block body and voice/transport helpers on macOS. It replaces hardware/session/Titanium startup and fixes only the noise-seed/disabled-diagnostic clock. Output and semantic state are compared against a separately archived reference from the same platform. This is an Apple renderer test; it does not execute AVAudioEngine or establish iPad scheduling, route recovery, footprint or listening acceptance.
+
+```sh
+mkdir -p /tmp/synth-reference
+git archive 7ab3110 | tar -x -C /tmp/synth-reference
+python3 tools/build_ios_render_host.py --source /tmp/synth-reference --output /tmp/apple-reference
+python3 tools/build_ios_render_host.py --output /tmp/apple-candidate
+python3 tools/compare_ios_render.py /tmp/apple-reference /tmp/apple-candidate
+python3 tools/benchmark_performance_review.py --baseline /tmp/apple-reference --candidate /tmp/apple-candidate --output /tmp/apple-performance.json
+/tmp/apple-candidate --metadata
+```
+
+The build tool defaults to the module's Apple Release `-Os` optimization. The comparator streams PCM for every fixture block and full original voice/tail, FIR/filter, limiter, effect-buffer and transport state at fixture checkpoints. Cases include five engine rates, zero/short/irregular blocks, all sources, held updates, replacements, send and position ramps, four sequences, effects, panic, drain and later re-enabling. A deliberately changed phase increment was rejected as a negative control.
+
+Finish compilation and fidelity checks before timing. The benchmark uses fixed matched warmups and at least ten alternating pairs; CPU and elapsed totals, p95, maxima and process high-water memory remain separate. Investigate repeatable total regressions above 2% or p95 regressions above 5%. Short-process or single-kernel gains do not establish whole-app performance. The Android producer harness exercises the actual JNI publication with supplied JVM array accessors, so its numbers exclude Java validation and VM allocation time.
+
+Full-score producers reserve a free bank without copying the previous score. Generic partial-bank callers still inherit the latest accepted bank, and publication retains its ownership, validation and mailbox checks. The iOS producer commits an already prepared score once; Android prepares its complete packet at native publication. Empty completion polls and empty metadata pruning avoid transient objects. Accepted edits of unknown iOS IDs do not create retained spatial metadata. Sequence capacity, diagnostics, event delivery cadence and public defaults are unchanged.
 
 The shared processor check is `cc -std=c99 -O2 -Wall -Wextra -Wpedantic tests/spatial_regression.c -lm -o /tmp/spatial_regression` followed by `/tmp/spatial_regression`. `tests/spatial_engine_host.cpp` uses the same compile flags as `engine_render_host.cpp` and verifies native left/right rendering, elevation changes, stealing and stopping. Java spatial validation is checked by `SynthSpatialContractRegression`; the common Java/iOS corpus also covers spatial acceptance and conflicts.
 
@@ -391,26 +317,11 @@ The script compares stereo and binaural using a warmup and five measured trials,
 
 ## Engine statistics
 
-The [statistics API](api.md#getstats) has the same shape on both platforms.
-`shared/synth_stats.h` owns telemetry math and publication. Voice transitions
-update render-owned occupancy and maxima, including primary FIR draining and
-external replacement/stop tails. Whole empty groups can then be skipped without
-changing the signal. Producers are serialized separately from the renderer;
-querying queue depth does not include future scheduled pattern steps.
-
-The callback publishes atomic words behind a sequence counter. Readers retry a
-snapshot if publication overlaps their read; the callback never waits for them.
-Eight-byte alignment and a compile-time lock-free assertion also cover Android's
-32-bit ABIs. Reset/enable requests are consumed at callback boundaries. A new
-control generation hides stale optional measurements immediately. Shutdown waits
-for the backend callback to stop before clearing occupancy. Queries allocate
-result objects on the calling thread. Pattern publication and shutdown share a
-control monitor; that monitor is never taken by the audio callback.
-
-Diagnostic timing uses a monotonic host clock only while enabled. Stereo peak,
-RMS and maximum limiter reduction accumulate over approximately 200 ms of final
-float output; logarithms are calculated at window boundaries. These readings do
-not diagnose physical distortion, latency, heat, battery use or overall app CPU.
+The [statistics API](api.md#getstats) has the same shape on both platforms. `shared/synth_stats.h` owns telemetry math and publication. Voice transitions update render-owned occupancy and maxima, including primary FIR draining and external replacement/stop tails. Whole empty groups can then be skipped without changing the signal. Producers are serialized separately from the renderer; querying queue depth does not include future scheduled pattern steps.
+
+The callback publishes atomic words behind a sequence counter. Readers retry a snapshot if publication overlaps their read; the callback never waits for them. Eight-byte alignment and a compile-time lock-free assertion also cover Android's 32-bit ABIs. Reset/enable requests are consumed at callback boundaries. A new control generation hides stale optional measurements immediately. Shutdown waits for the backend callback to stop before clearing occupancy. Queries allocate result objects on the calling thread. Pattern publication and shutdown share a control monitor; that monitor is never taken by the audio callback.
+
+Diagnostic timing uses a monotonic host clock only while enabled. Stereo peak, RMS and maximum limiter reduction accumulate over approximately 200 ms of final float output; logarithms are calculated at window boundaries. These readings do not diagnose physical distortion, latency, heat, battery use or overall app CPU.
 
 Run portable telemetry and Java API tests with:
 
@@ -420,19 +331,35 @@ c++ -std=c++17 -O2 -Wall -Wextra -pthread tests/stats_regression.cpp -o /tmp/sta
 python3 tests/run_stats_java.py
 ```
 
-`tests/stats_engine_host.cpp` uses the Oboe/JDK host flags shown above. It tests
-native occupancy, reset while playing, saturated queues, binaural drain,
-shutdown and exact output equality with diagnostics enabled/disabled. This
-native integration harness requires local Oboe headers; portable shared tests
-and the stopped-engine Java API tests also run in CI. iOS builds use the same
-telemetry core, but host Android renders do not execute the iOS audio callback.
-
-`tests/stats_benchmark_host.cpp` extends the spatial replay harness with silence,
-one/32 voices, replacement pressure, chords, scheduled note publications and
-short FIR drains in stereo/binaural. Build it twice with identical `-O3` flags:
-once against the previous engine using `-DSTATS_BASELINE`, and once against the
-current engine. Run `python3 tools/benchmark_stats.py BASELINE CURRENT` for one
-warmup and ten alternating trials/configuration, including current snapshots at
-5 Hz. The harness verifies identical output hashes across all modes. See the
-[measured comparison and limitations](stats-performance.md) before interpreting
-host percentages as a device guarantee.
+`tests/stats_engine_host.cpp` uses the Oboe/JDK host flags shown above. It tests native occupancy, reset while playing, saturated queues, binaural drain, shutdown and exact output equality with diagnostics enabled/disabled. This native integration harness requires local Oboe headers; portable shared tests and the stopped-engine Java API tests also run in CI. iOS builds use the same telemetry core, but host Android renders do not execute the iOS audio callback.
+
+`tests/stats_benchmark_host.cpp` extends the spatial replay harness with silence, one/32 voices, replacement pressure, chords, scheduled note publications and short FIR drains in stereo/binaural. Build it twice with identical `-O3` flags: once against the previous engine using `-DSTATS_BASELINE`, and once against the current engine. Run `python3 tools/benchmark_stats.py BASELINE CURRENT` for one warmup and ten alternating trials/configuration, including current snapshots at 5 Hz. The harness verifies identical output hashes across all modes. The [measured comparison and limitations](stats-performance.md) explain what the host percentages establish and which results still require device tests.
+
+## Sustained voices
+
+`noteOn`, `noteOff` and `updateVoice` use the existing bounded native command queue. Voice storage, smoothing ramps and identity snapshots are preallocated. The callback owns envelopes, oscillator/filter state and replacement decisions; it does not allocate or acquire producer locks. `shared/synth_held.h` supplies the same held ADSR, current-level release and independent 10 ms linear parameter ramps to both renderers. Held attack/decay counters stop advancing after those stages, avoiding sample-counter overflow on long notes.
+
+IDs are app-supplied positive 32-bit integers. Atomic 32-bit identity snapshots and queued attacks let producers validate update source compatibility without reading mutable DSP state. The callback checks compatibility again. A full queue rejects note release with `false`; the caller owns its bounded retry and shutdown policy. See the [sustained contract](api.md#noteonoptions) for immutable configuration and supported updates.
+
+Run `tests/held_core_regression.c` with C11 for shared envelope/ramp/identity checks. `tests/held_engine_host.cpp` uses the same build flags as `engine_render_host.cpp`; it covers long notes, release stages, phase-preserving targets, source capabilities, replacement, stale IDs, queue saturation and 32 mixed-source spatial voices. The Java held contract regression and the shared Java/iOS corpus verify the public option shapes. Host rendering and successful builds do not establish device audio quality or touch responsiveness.
+
+
+## Native transport and processing
+
+`shared/synth_transport.h` owns up to four independent sequences and one global tempo/beat/millisecond clock; `shared/synth_sequence.h` advances each traversal with compensated sample increments. Beat lengths follow tempo changes; millisecond lengths remain constant. A serialized producer prepares sorted traversal and all pitches before publishing one of three immutable banks. The callback accepts tempo at the block boundary and structure at a step boundary; swing changes at a pair boundary. Transport voices share the sustained pool, retain owner identifiers and absolute note deadlines beyond internal slot reuse and release independently of the public command queue. See the [public transport contract](api.md#native-sequence-transport).
+
+`shared/synth_effects.h` supplies chorus, ping-pong delay, damped Schroeder reverb and optional saturation; `shared/synth_modulation.h` supplies two phase-preserving LFOs. Buffers allocate at engine initialization and free after the audio backend stops. Epoch tags on 16-sample pages invalidate histories during panic without walking delay memory; recovery clears at most one short page on a first write. Effects start disabled and default rendering follows exact bypass. Enabled effects drain on disable, bounded to 30 seconds. No new external DSP dependency is used.
+
+Pre-limiter peak and maximum limiter reduction accumulate natively until reset, so polling cannot miss a brief intervention. The callback tracks linear extrema and converts to decibels once per block. Existing output peak/RMS and reduction windows remain approximately 200 ms. Diagnostics are optional; host measurements do not establish device audio deadlines or listening acceptance.
+
+Portable checks: compile and run `tests/sequence_core_regression.c`, `tests/effects_core_regression.c` and `tests/modulation_core_regression.c` with C11, optimization and libm. The transport test checks ten minutes at five sample rates against calculated event times, plus edits, swing, rests, chords and publication pressure. Effects tests check bypass, tails, panic, automation, memory and stability at 16, 44.1, 48, 96 and 192 kHz. On macOS, `tests/studio_contract_ios.m` validates the new iOS configuration contract without Titanium.
+
+`tools/calibrate_studio.py --studio-root PATH` renders Studio presets through the native Android callback at maximum master gain with new effects and modulation disabled. It measures eight independent notes, coherent unisons and repeated attacks with release overlap across low, middle and high registers, then adjusts only a fixed preset gain. The target is at most -6 dBFS before the limiter and at most 0.1 dB limiter reduction; this does not promise zero reduction for arbitrary 32-voice combinations. The report records each scenario before and after calibration. Listening and device performance remain separate acceptance checks.
+
+Device feedback superseded that headroom target for Studio's initial Cristal preset: its fixed gain is restored to 1 because the calibrated setting made a fresh Android installation barely audible. This adds 10.83 dB without saturation or voice-count normalization. Three coherent factory notes remain below the limiter ceiling at maximum master; eight independent coherent notes can require limiting. The calibration recommendations remain recorded separately from this active preset exception.
+
+The [Studio technical validation report](studio-validation.json) records the calibration and corrected full-chain host benchmark, including failed deadline acceptance and pending device checks. Its host performance result must not be presented as hardware realtime acceptance.
+
+## Unified transport acceptance boundaries
+
+The 1.0.0 contract uses one renderer, at most 32 voices and capacity for 1-4 sequences. `bus` categories and per-voice sends share one effects chain. These API changes do not establish complete multiplatform ten-minute maximum-load acceptance; the measured iPad result and Android limits are recorded separately in [physical validation](physical-validation.json) and [the performance summary](stats-performance.md). Host timing, bypass comparisons, memory accounting, actual Android/iOS builds and the remaining device/listening checks are separate evidence. Historical Studio benchmarks below predate these changes and remain historical observations. At 192 kHz, the revised effects buffers use approximately 13.1 MiB; the maximum sequence pool uses approximately 8.23 MiB before renderer voices/queues. Total native accounting must include those remaining structures and recovery peaks; the target is at most 32 MiB additional memory.