@maccesar/titools 5.1.0 → 5.2.0

package/skills/ti-synthengine/references/stats-performance.md

@@ -0,0 +1,38 @@
+> 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/stats-performance.md` SHA-256: `798075f7bec08b4dafcaa46f1c43552d90ba23e2c85b49b4ab1d4ddf72c210df`.
+
+# Statistics host comparison
+
+Beta 1.0.0. Synthetic Android native render on Apple M1. Apple clang version 21.0.0 (clang-2100.3.34.2). Baseline commit `95901c98af5353b86d9dc7c60b29ab9186b038cd`. Both renderers use identical `-O3` flags.
+
+One warmup and ten alternating runs per configuration, 48 kHz, 32 slots, 256-frame callbacks, twenty seconds per run. Current modes query native snapshots at 5 Hz. Timing includes command publication and snapshot work; JavaScript/JNI, real scheduler jitter and hardware streams are excluded. macOS user-interactive QoS reduces core-selection variability. Values below are median percentage changes relative to the previous engine.
+
+The flagged sustained 32-voice binaural configuration was repeated in isolation with another warmup and ten alternating trials; its table row uses that repeat. The original trials are retained in the raw investigation.
+
+| Case | Output | Basic total | Basic p95 | Full total | Full p95 |
+| --- | --- | ---: | ---: | ---: | ---: |
+| silence | stereo | -73.13% | -72.45% | -71.89% | -70.92% |
+| oneVoice | stereo | -41.29% | -41.09% | -39.20% | -38.70% |
+| 32Voices | stereo | -5.48% | -6.61% | -4.88% | -4.25% |
+| steals | stereo | -7.01% | -6.01% | -0.42% | -1.47% |
+| chords | stereo | -17.88% | -3.59% | -16.64% | -3.15% |
+| patterns | stereo | -40.19% | -39.07% | -38.55% | -36.80% |
+| drain | stereo | -69.59% | -60.42% | -68.12% | -59.24% |
+| silence | binaural | -73.09% | -72.45% | -71.75% | -71.17% |
+| oneVoice | binaural | -16.36% | -19.86% | -13.44% | -17.71% |
+| 32Voices | binaural | -6.09% | -19.89% | -10.14% | -23.25% |
+| steals | binaural | +0.55% | -0.26% | -0.47% | -6.54% |
+| chords | binaural | -8.41% | -6.12% | -3.69% | +1.28% |
+| patterns | binaural | -11.76% | -9.16% | -9.53% | -7.40% |
+| drain | binaural | -45.49% | -22.73% | -50.18% | -21.98% |
+
+All mode/configuration hashes match sample for sample. The direct integration regression also compares float arrays, including a reset during playback. Full mode includes timing, stereo peak/RMS and limiter reduction; basic mode leaves those measurements disabled. Full mode has additional work compared with basic mode; the table measures each final configuration against the previous engine.
+
+Initial repeated silence regressions were about +5% basic and +19% full. Sparse sounds also crossed the investigation thresholds. The correction uses event-maintained occupancy to skip entirely empty voice/tail groups, in both Android and iOS, while retaining all requested meters. No DSP formulas or emitted samples were changed.
+
+The acceptance thresholds are increases above 2% total render time or 5% p95 elapsed block time. No final median exceeds either threshold. The sustained 32-voice binaural full-mode total changed from +5.01% in the original batch to -10.14% in the isolated repeat; this variability prevents treating the percentages as a precise overhead bound. No repeatable regression above the screening limits was established in that case.
+
+These are host measurements of the Android renderer and shared telemetry core. They do not execute the iOS callback, include bridge polling cost, establish physical underrun behavior, or demonstrate unchanged device heat, battery use or total app CPU. Both native modules are compiled separately; physical stereo/headphone listening and device performance remain separate acceptance work. No zero-impact claim is made.
+
+The patterns case replays timed native note publications; it does not run the Java or dispatch scheduler. The drain case repeatedly renders 1 ms voices plus the complete binaural FIR history. Shutdown/rejection/queue concurrency belongs to regression testing, not these timings.
+
+[Raw trials and investigation](stats-performance.json). Reproduce with `tests/stats_benchmark_host.cpp` and `tools/benchmark_stats.py`; see [engine test instructions](audio-engine.md#engine-statistics).

package/skills/ti-synthengine/references/troubleshooting.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/troubleshooting.md` SHA-256: `10949f8f18f9e97933bfb1f025a12217746648c01805ff0fafe2c8e064b1c0cc`.
 
 # Troubleshooting
 
@@ -25,6 +25,16 @@ Common fixes:
 | `out_of_range` | Compare the value with `getDefaults().limits`. |
 | `not_integer` | Use whole milliseconds and integer waveform values where required. |
 | `invalid_note` | Check spelling, accidental case and octave. |
+| `invalid_sample_count` | Supply 2 to 64 values in `waveTable`. |
+| `unsupported_value` | Use `none`, `lowpass`, `highpass` or `bandpass` for `filterType`. |
+| `sustain_without_decay` | Add a `decay` greater than 0, or remove `sustain`. |
+| `decay_exceeds_remaining_duration` | Shorten `attack` or `decay`, or lengthen `duration`. The default attack counts. |
+| `filter_type_required` | Set `filterType` to a filter, or remove `filterHz`, `filterHzEnd` and `filterQ`. |
+| `fm_requires_sine` | Use `SINE` for FM, or set `fmDepth` to 0 and remove `fmDepthEnd`. |
+| `fm_depth_required` | Set `fmDepth` or `fmDepthEnd`, or remove `fmRatio`. |
+| `conflicting_spatial_fields` | Remove `pan`, `panEnd`, `pans` and `panSpread` whenever sending `spatialX` or `spatialY`; check pattern root and steps. |
+| `too_many_values` | Pass no more `pans` or `detunes` than the chord has pitches. |
+| `missing_required` with `waveTable` | Add a table whenever `waveType` is `WAVETABLE`. |
 | envelope reason | Make attack and release fit inside total duration. |
 
 Warnings are deduplicated by method, key and reason. Repeating the same bad
@@ -34,6 +44,20 @@ An `overflow` warning means the command queue was full. Reduce the command
 burst or wait for the audio thread to consume queued work. Chords are rejected
 as a whole rather than partially started.
 
+The envelope and filter rules read the values a sounding event ends up with.
+In a pattern that means the step over the pattern root, so a `sustain` on the
+root is fine when each step supplies a `decay`, and a root `filterHz` is
+rejected when no step has a `filterType`. A `detune` that pushes the pitch, or
+`frequencyEnd`, outside the frequency range is rejected with `out_of_range`.
+
+`fmDepthEnd: 0` is valid. It sweeps the index down to nothing. Omit the key,
+rather than passing 0, when the index should not move.
+
+For the shaping controls, check the discontinuous disabled values as well
+as the numeric range: `bitDepth` accepts 0 or 2 through 16, and
+`pulseWidthEnd` accepts 0 or 0.05 through 0.95. A `waveTable` must contain only
+finite values from -1 to 1.
+
 ## The installed contract is wrong
 
 Check the native binary at startup:
@@ -54,6 +78,22 @@ modules/android/ti.synthengine/1.0.0/
 modules/iphone/ti.synthengine/1.0.0/
 ```
 
+For binaural, also inspect `getDefaults().limits.spatialX` and `.spatialY`. During the unreleased beta, two binaries can both report 1.0.0 while only one includes positioning. Copying the package does not update an already installed app: rebuild and reinstall it.
+
+## Binaural does not change the position
+
+Check the actual object sent to the native method, not only the settings screen:
+
+- Every effect that should be spatial sends `spatialX` and/or `spatialY`. A switch alone does not modify existing playback calls.
+- Values are finite numbers within -1 to 1, with positive Y above and negative Y below. A 0 to 100% height slider scales the source position; it does not put all sounds above.
+- Turning binaural off removes both coordinate keys. Sending zeros leaves binaural enabled at the front center.
+- No stereo placement fields remain, even with value 0 or through pattern inheritance. Handle the Boolean return value.
+- The installed contract reports both spatial limits and the device has the rebuilt app.
+- Use headphones and one broadband event at a time; with binaural off, points with the same X use the same horizontal placement regardless of Y.
+- Positions are fixed for active voices. Later calls can use updated coordinates, but there is no method to move a voice already playing.
+
+The [integration guide](guide.md#integrate-binaural-in-a-2d-app) contains the JavaScript conversion and explains switch/slider behavior.
+
 ## The first sound glitches
 
 Do not start the engine during the first layout. Add the `postlayout` listener
@@ -78,8 +118,9 @@ Check these in order:
 7. The app is not relying on a pattern that another `playPattern()` call
    replaced.
 
-On iOS, the module uses a `Playback` session, so the silent switch should not
-mute it. Another audio component can change the app-wide session after engine
+On iOS, the module uses a `Playback` session by default, so the silent switch
+should not mute it. With `audioSession: 'ambient'` the silent switch mutes it by
+design. Another audio component can change the app-wide session after engine
 startup; inspect the order if behavior differs from the simple example.
 
 ## A pattern stops or skips steps
@@ -102,6 +143,20 @@ steps: [
 ]
 ```
 
+## `patternend` never arrives
+
+The event fires once per accepted `playPattern`. Check, in order:
+
+1. The call returned `true`. A rejected pattern produces no event.
+2. The listener is on the module (`synth.addEventListener`), registered before
+   the pattern started and not removed by a cleanup that already ran.
+3. `shutdown()` was not called first. It discards a pending pattern silently.
+4. The pattern was not replaced. A newer accepted pattern delivers
+   `completed: false` for the old one instead of a natural end.
+
+The event arrives when the pattern ends, about 1 ms after the sum of its step
+lengths, not when you call. A 30 second pattern reports after 30 seconds.
+
 ## A chord is distorted or pumps
 
 Use one `playChord()` call for notes that should begin together. Several
@@ -110,6 +165,8 @@ Use one `playChord()` call for notes that should begin together. Several
 If the limiter engages repeatedly:
 
 - lower event volume;
+- lower `filterQ`, because a resonant low-pass or high-pass boosts its cutoff
+  by about Q;
 - use `conservative` instead of `balanced` or `raw`;
 - use `speakerSafe` on a small speaker;
 - avoid retriggering a long event before its previous release ends.
@@ -148,7 +205,7 @@ time.
 
 ## iOS-specific checks
 
-- Confirm the deployment target is iOS 13 or newer.
+- Confirm the deployment target is iOS 15 or newer.
 - Check whether another module changes `AVAudioSession` after startup.
 - Test interruptions, phone calls, Bluetooth and route changes on hardware.
 - Use the matching device or simulator slice from the 1.0.0 archive.