@maccesar/titools 5.2.3 → 5.2.5

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

@@ -1,4 +1,4 @@
-> Source snapshot: official TiSynthEngine 1.0.2 documentation from reviewed working-tree source based on `4a45f21230ffc5a8838fbd5fc108dd3ab470362a` (2026-10-29). Upstream `documentation/stats-performance.md` SHA-256: `3d6d35b9e0e49a778777d406418eaba04ebd57da871a322da28fae0190c5cb17`.
+> Source snapshot: official TiSynthEngine documentation at commit `ec04f4e634075c41b55f66279eabcd78b9652d58` (2026-11-02). Published module 1.1.0; public API 1.1.0. Upstream `documentation/stats-performance.md` SHA-256: `085142b6ade7b4f7b5965f6a638f967fdceba5ab1f26fb85e8cb496d5b886b6a`.
 
 # Statistics host comparison
 

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

@@ -1,8 +1,8 @@
-> Source snapshot: official TiSynthEngine 1.0.2 documentation from reviewed working-tree source based on `4a45f21230ffc5a8838fbd5fc108dd3ab470362a` (2026-10-29). Upstream `documentation/troubleshooting.md` SHA-256: `e2156e5dea77bda95d9f9305bf2c8c359d54d5832f56062cf2d2ebe6c2b583b9`.
+> Source snapshot: official TiSynthEngine documentation at commit `ec04f4e634075c41b55f66279eabcd78b9652d58` (2026-11-02). Published module 1.1.0; public API 1.1.0. Upstream `documentation/troubleshooting.md` SHA-256: `37fd3173ccfce393ab354713df66fbcc99c7281131ea45de1b3aae1e2d6f2160`.
 
 # Troubleshooting
 
-Start with the Boolean returned by the call and the native log. Most silent requests are contract rejections, a stale binary or an engine that never started.
+Start with the method's documented return value and the native log. Most silent requests are contract rejections, a stale binary or an engine that never started.
 
 ## A call returns `false`
 
@@ -16,26 +16,26 @@ Always check the return value: `playSequence` rejects with 0, while Boolean meth
 
 Common fixes:
 
-| Reason                              | Check                                                                                                                   |
-| ----------------------------------- | ----------------------------------------------------------------------------------------------------------------------- |
-| `unsupported_option`                | Remove or correct the named key. Every options object is strict.                                                        |
-| `invalid_step_type`                 | Make every pattern step an object, not a number or string.                                                              |
-| `conflicting_pitch_fields`          | Timed/held calls use mutually exclusive `note`/`frequency`; each sequence step uses exactly one `notes` array, `frequencies` array or `rest: true`.                                                                   |
-| `missing_pitch_or_rest`             | Add one pitch field or an explicit rest.                                                                                |
-| `out_of_range`                      | Compare the value with `getDefaults().limits`.                                                                          |
-| `not_integer`                       | Use integer milliseconds for timed tone/chord envelope fields and integer waveform values; native sequence intervals and lengths may be fractional.                                                      |
-| `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.                                                                      |
+| Reason                              | Check                                                                                                                                               |
+| ----------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `unsupported_option`                | Remove or correct the named key. Every options object is strict.                                                                                    |
+| `invalid_step_type`                 | Make every pattern step an object, not a number or string.                                                                                          |
+| `conflicting_pitch_fields`          | Timed/held calls use mutually exclusive `note`/`frequency`; each sequence step uses exactly one `notes` array, `frequencies` array or `rest: true`. |
+| `missing_pitch_or_rest`             | Add one pitch field or an explicit rest.                                                                                                            |
+| `out_of_range`                      | Compare the value with `getDefaults().limits`.                                                                                                      |
+| `not_integer`                       | Use integer milliseconds for timed tone/chord envelope fields and integer waveform values; native sequence intervals and lengths may be fractional. |
+| `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 call may return `false` without printing a new line each time.
 
@@ -43,7 +43,7 @@ An `overflow` warning means the command queue was full. Reduce the command burst
 
 The envelope and filter rules apply to the final values of each sounding event. In a native sequence, each step's `overrides` merges over root `voice`: root `voice.sustain` is valid when every sounding step supplies compatible decay, and `voice.filterHz` needs a non-none filter type after merging. Timed tones/chords enforce their total-duration envelope budget; held and sequence ADSR has no sequence-interval budget. 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.
+`fmDepthEnd: 0` is valid. It sweeps the index down to nothing. Omit the key when the index should not move; passing 0 sets a sweep target.
 
 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.
 
@@ -53,18 +53,20 @@ Check the native binary at startup:
 
 ```javascript
 var actual = synth.getDefaults().apiVersion
-if (actual !== '1.0.0') {
-  throw new Error('Expected TiSynthEngine 1.0.0, found ' + actual)
+if (actual !== '1.1.0') {
+  throw new Error('Expected TiSynthEngine 1.1.0, found ' + actual)
 }
 ```
 
-`apiVersion` describes the unchanged 1.0.0 API contract; it is not the module package version. Confirm both entries in `tiapp.xml` pin module version 1.0.2. Then remove the application's build output and rebuild so Titanium does not reuse an archive from an earlier build. The module directories should be:
+`apiVersion` describes the public contract, separately from the package version. Version 1.1.0 uses API 1.1.0; published 1.0.2 uses API 1.0.0. For version 1.1.0, confirm both entries in `tiapp.xml` pin module version 1.1.0. Then remove the application's build output and rebuild so Titanium does not reuse an archive from an earlier build. The module directories should be:
 
 ```text
-modules/android/ti.synthengine/1.0.2/
-modules/iphone/ti.synthengine/1.0.2/
+modules/android/ti.synthengine/1.1.0/
+modules/iphone/ti.synthengine/1.1.0/
 ```
 
+Module version `1.1.0` reports API `1.1.0`. Check the capability/schema pair before using variation.
+
 For binaural, also inspect `getDefaults().limits.spatialX` and `.spatialY`. Use the official packages to avoid stale development binaries. Copying the package does not update an already installed app: rebuild and reinstall it.
 
 ## Binaural does not change the position
@@ -77,15 +79,15 @@ Inspect the options sent to the native method as well as the settings screen:
 - 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.
-- Timed tones/chords and each sequence attack keep their specified position. A spatial held voice can move through `updateVoice({ voiceId, spatialX, spatialY })`; omitted coordinates retain their previous value, and the FIR ramps over 10 ms without clearing history. A stereo voice cannot be converted to spatial by an update.
+- Timed tones/chords and each sequence attack keep their specified position. A spatial held voice can move through `updateNote({ voiceId, spatialX, spatialY })`; omitted coordinates retain their previous value, and the FIR ramps over 10 ms without clearing history. A stereo voice cannot be converted to spatial by an update.
 
 The [integration guide](guide.md#integrate-binaural-in-a-2d-app) contains the JavaScript conversion and explains switch/slider behavior.
 
 ## Statistics are missing or show `null`
 
-Older development packages can report 1.0.0 without statistics methods. Check `typeof synth.getStats`, `typeof synth.setStatsEnabled` and `typeof synth.resetStats`; install the current packages, rebuild and reinstall the app if needed.
+Older development packages can report 1.0.0 without statistics methods. Check `typeof synth.getStats`, `typeof synth.enableStats`, `typeof synth.disableStats` and `typeof synth.resetStats`; install the current packages, rebuild and reinstall the app if needed.
 
-Basic voice/queue/rejection counters do not require diagnostics. Timing, output peak/RMS and limiter reduction require `setStatsEnabled(true)` and a measured callback/window. `null` means unmeasured or unavailable; keep it distinct from zero. The current iOS backend always reports `null` for underruns, output buffer size and estimated hardware latency. Android backend metrics are best-effort and independent of the diagnostic switch.
+Basic voice/queue/rejection counters do not require diagnostics. Timing, output peak/RMS and limiter reduction require `enableStats()` and a measured callback/window. `null` means unmeasured or unavailable; keep it distinct from zero. The current iOS backend always reports `null` for underruns, output buffer size and estimated hardware latency. Android backend metrics are best-effort and independent of the diagnostic switch.
 
 Read at a modest rate, such as 5 Hz, and stop polling and optional measurements when the diagnostic owner hides or closes. `getStats()` never resets counters; call `resetStats()` deliberately. See the [integration recipe](guide.md#read-engine-statistics).
 
@@ -110,7 +112,7 @@ If startup remains noisy, temporarily remove other launch work and increase the
 Check these in order:
 
 1. `start()` returned `true`.
-2. The tone, chord or pattern call returned `true`.
+2. A timed tone/chord or held-note call returned `true`, or `playSequence` returned a positive sequence ID.
 3. Master and event `volume` are above zero.
 4. The device media volume is up and the expected route is selected.
 5. `shutdown()` was not called by another owner.
@@ -166,7 +168,7 @@ If later sounds remain silent, capture the Android or Xcode log around the route
 - 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.2 archive.
+- Use the matching device or simulator slice from the 1.1.0 archive.
 
 ## What to include in a bug report
 
@@ -174,11 +176,11 @@ Include the platform, OS version, device model, Titanium SDK version, module ver
 
 ## Held notes, sequences or effects methods are missing
 
-The official release reports API version 1.0.0. Detect `noteOn`/`noteOff`/`updateVoice`, all four sequence methods and `setMasterProcessing` according to the feature needed. Install matching current Android/iOS packages, rebuild and reinstall the consumer app. A stale development binary may report the same version without the complete release API. See [capability detection](guide.md#detect-required-capabilities).
+Published 1.0.2 reports API version 1.0.0 and provides `updateVoice`; version 1.1.0 reports API 1.1.0 and recommends `updateNote`. Detect `noteOn`/`noteOff`/`updateNote`, all four sequence methods and `setMasterProcessing` according to the feature needed. Install matching current Android/iOS packages, rebuild and reinstall the consumer app. A stale development binary may report the same version without the complete release API. See [capability detection](guide.md#detect-required-capabilities).
 
 ## A held voice does not release or update
 
-Use the original positive `voiceId`, not the pitch or an ID that has already been reused. `noteOn` does not accept `duration` or temporal `*End` fields. `updateVoice` cannot change source, filter type, table, quantization, ADSR or stereo-versus-spatial mode; restart with a new ID when those attack-time settings must change. Noise clock, one-pole cutoff, effect send and compatible stereo/spatial position support live edits. Changed continuous parameters ramp for 10 ms.
+Use the original positive `voiceId`, not the pitch or an ID that has already been reused. `noteOn` does not accept `duration` or temporal `*End` fields. `updateNote` cannot change source, filter type, table, quantization, ADSR or stereo-versus-spatial mode; restart with a new ID when those attack-time settings must change. Noise clock, one-pole cutoff, effect send and compatible stereo/spatial position support live edits. Changed continuous parameters ramp for 10 ms.
 
 Check Boolean returns. A full public queue can reject `noteOff`; retry twice at 16 ms outside render, then shut down/report if still rejected. Cancel those retries on owner teardown. The [held motor example](advanced-examples.md#sustained-game-motor) implements this policy. Touch cancellation, pause and close need cleanup as well as normal key up.
 
@@ -205,3 +207,9 @@ If accumulated attenuation remains near zero, investigate phase cancellation bet
 `WAVETABLE` repeats the supplied values using a stepped lookup. A short table can sound grainy or buzzy even when its values describe a sine wave and `bitDepth` is 0. Its harmonic character changes with pitch and filtering; this does not require reverb, an LFO or creative saturation to be enabled.
 
 Compare one note with `SINE`, at a comfortable matched level, to distinguish the source's texture from the combined sound of overlapping notes. Read `preLimiterPeakDb` and `maxLimiterReductionDb` with diagnostics enabled to investigate mix headroom. No limiter reduction does not prove that the physical speaker, headphones or output processing are clean. Keep a subjective listening observation separate from a confirmed clipping or buffer-loss diagnosis.
+
+## A variation dictionary is rejected or repeats the same sound
+
+Check both `capabilities.variation === true` and `variationSchemaVersion === 1` before sending the property. Published 1.0.2 packages reject it. Source restrictions and range ordering still apply at amount zero; near the frequency ceiling, validate tuning, detune, every chord pitch and active pitch endpoints together.
+
+Repeated standalone calls with one explicit seed reproduce the selected parameters. Omit it for independent selections, or use a native sequence to retain an advancing stream across loops. A held voice samples only at attack, and `updateNote` rejects `variation`. For a running sequence, clear an inherited root dictionary with a valid amount-zero replacement; omitting it from a revision retains the merged value. See the [complete examples and rules](native-variation.md).