@maccesar/titools 5.1.0 → 5.2.0

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

@@ -1,4 +1,4 @@
-> Source snapshot: official TiSynthEngine 1.0.0 documentation at commit `6685b81` (2026-08-29).
+> 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`.
 
 # Audio engine
 
@@ -6,6 +6,29 @@ 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.
 
+<!-- TOC-START -->
+## Contents
+
+- [Signal path](#signal-path)
+- [Oscillators](#oscillators)
+- [Envelope](#envelope)
+- [Event gain](#event-gain)
+- [Mixing profiles](#mixing-profiles)
+- [Limiter](#limiter)
+- [Master volume and pan](#master-volume-and-pan)
+- [Voice pool](#voice-pool)
+- [Command queue](#command-queue)
+- [Shared DSP core](#shared-dsp-core)
+- [Android implementation](#android-implementation)
+- [iOS implementation](#ios-implementation)
+- [Latency](#latency)
+- [Route behavior](#route-behavior)
+- [Regression coverage](#regression-coverage)
+- [Binaural front-plane renderer](#binaural-front-plane-renderer)
+- [Engine statistics](#engine-statistics)
+
+<!-- TOC-END -->
+
 ## Signal path
 
 ```text
@@ -15,7 +38,9 @@ playTone / playChord / playPattern
              |
    native command ring buffer
              |
- voice pool: oscillator * envelope * event gain * stereo pan
+ 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
              |
@@ -32,7 +57,7 @@ them and renders the samples.
 
 ## Oscillators
 
-The engine has five sources:
+The engine has six sources:
 
 | Waveform | Source behavior |
 | --- | --- |
@@ -40,18 +65,68 @@ The engine has five sources:
 | `SQUARE` | PolyBLEP band-limited discontinuity. |
 | `SAWTOOTH` | PolyBLEP band-limited discontinuity. |
 | `TRIANGLE` | Continuous triangle oscillator. |
-| `NOISE` | White-noise generator. |
+| `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.
+
+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.
+
+| 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. |
+
+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.
+
 ## Envelope
 
-Each voice has a linear attack, a full-level middle section and a linear
-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. `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.
+
+```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.
 
 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
@@ -75,7 +150,7 @@ Waveforms are calibrated toward a common source RMS:
 | --- | ---: | ---: |
 | Sine | 0.440 | 0.311 |
 | Square | 0.311 | 0.311 |
-| Sawtooth, triangle and noise | 0.539 | 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
@@ -149,7 +224,18 @@ 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.
+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.
+
+## 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.
 
 ## Android implementation
 
@@ -165,11 +251,12 @@ ABIs are `arm64-v8a`, `armeabi-v7a`, `x86` and `x86_64`.
 
 iOS renders with `AVAudioEngine` and `AVAudioSourceNode`, using the active
 session's sample rate. The module configures the audio session as `Playback`,
-activates it, and observes route and engine configuration notifications. If a
-route change stops the graph, the port reactivates the session and resumes the
-existing renderer.
+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.
 
-`AVAudioSourceNode` requires iOS 13 or newer. The module archive contains device,
+The module targets iOS 15 or newer. The module archive contains device,
 simulator and Mac Catalyst slices.
 
 ## Latency
@@ -199,15 +286,18 @@ device:
 ```sh
 node tests/api_contract_regression.js
 node tests/default_profile_regression.js
+node tests/documentation_regression.js
 
 cd android
 test_dir=$(mktemp -d /tmp/ti-synth-test.XXXXXX)
 javac -d "$test_dir" \
   src/ti/synthengine/SynthContract.java \
   test/ti/synthengine/SynthContractRegression.java \
+  test/ti/synthengine/SynthSpatialContractRegression.java \
   src/ti/synthengine/SynthDsp.java \
   test/ti/synthengine/SynthDspRegression.java
 java -cp "$test_dir" ti.synthengine.SynthContractRegression
+java -cp "$test_dir" ti.synthengine.SynthSpatialContractRegression
 java -cp "$test_dir" ti.synthengine.SynthDspRegression
 ```
 
@@ -215,3 +305,134 @@ 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.
+
+The shared DSP core builds with any C99 compiler:
+
+```sh
+test_dir=$(mktemp -d /tmp/ti-synth-core.XXXXXX)
+cc -std=c99 -O2 -Wall -Wextra -o "$test_dir/dsp_core" \
+  tests/dsp_core_regression.c -lm
+"$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.
+
+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)
+JH=$(/usr/libexec/java_home)
+test_dir=$(mktemp -d /tmp/ti-synth-engine.XXXXXX)
+clang++ -std=c++17 -O1 -Wall -I"$OBOE" -I"$JH/include" -I"$JH/include/darwin" \
+  -DHAS_EXPRESSIVE -DENGINE_CPP='"../android/jni/SynthOboeEngine.cpp"' \
+  -Wl,-undefined,dynamic_lookup tests/engine_render_host.cpp \
+  -o "$test_dir/engine_render"
+"$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.
+
+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)
+clang -fobjc-arc -Wall -Wextra -framework Foundation \
+  tests/contract_corpus_ios.m ios/Classes/TiSynthengineContract.m \
+  -o "$test_dir/contract_corpus_ios"
+"$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.
+
+## 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.
+
+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.
+
+### Reproduce a host CPU comparison
+
+Compile `tests/spatial_benchmark_host.cpp` with the same Oboe/JDK includes and definitions as `engine_render_host.cpp` above, replacing the source filename and choosing an output such as `/tmp/spatial_benchmark`. Supply a whitespace-separated timeline, one event per line, with these 25 columns in order:
+
+```text
+timeMs frequency frequencyEnd durationMs attackMs releaseMs decayMs sustain waveType volume noiseRate noiseRateEnd lowPassHz pulseWidth lfoFreq lfoDepth filterTypeIndex filterHz filterHzEnd filterQ fmRatio fmDepth fmDepthEnd pan panEnd
+```
+
+The filter indices are 0=none, 1=lowpass, 2=highpass and 3=bandpass. This internal harness bypasses public contract validation, so only feed valid event recipes. In binaural mode every event uses its `pan` column as spatialX and a synthetic moving elevation `0.8 * sin(timeMs / 1000)`; the other pan column is irrelevant to that mode. This tests CPU, not the localization of the original timeline.
+
+```sh
+python3 tools/benchmark_spatial.py /tmp/spatial_benchmark /path/to/timeline.txt
+```
+
+The script compares stereo and binaural using a warmup and five measured trials, reporting the median by audio processing time. There is no hardware stream or JavaScript bridge. Results include peak level, non-finite/clipped frames, voice replacements and processing time; they do not measure device CPU, latency, underruns, heat or battery.
+
+## 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.
+
+Run portable telemetry and Java API tests with:
+
+```sh
+c++ -std=c++17 -O2 -Wall -Wextra -pthread tests/stats_regression.cpp -o /tmp/stats
+/tmp/stats
+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.