@maccesar/titools 5.2.2 → 5.2.4

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

@@ -1,4 +1,4 @@
-> Source snapshot: official TiSynthEngine 1.0.0 documentation at release source commit `e7cbbe8a6f9ab38088fd8029c7b43cef6501101f` (2026-10-24). Upstream `documentation/stats-performance.md` SHA-256: `3d6d35b9e0e49a778777d406418eaba04ebd57da871a322da28fae0190c5cb17`.
+> Source snapshot: official TiSynthEngine documentation at commit `b07c97c762be5905f132cecf33e9d60ea0c21316` (2026-11-02). Published 1.0.2; local 1.1.0 candidates; public API 1.0.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.0 documentation at release source commit `e7cbbe8a6f9ab38088fd8029c7b43cef6501101f` (2026-10-24). Upstream `documentation/troubleshooting.md` SHA-256: `939960cde5860569699916208c0d3b352e60ba2a7603b5046dcefa9970294b70`.
+> Source snapshot: official TiSynthEngine documentation at commit `b07c97c762be5905f132cecf33e9d60ea0c21316` (2026-11-02). Published 1.0.2; local 1.1.0 candidates; public API 1.0.0. Upstream `documentation/troubleshooting.md` SHA-256: `bf70a08eee09033b5aaa8cf18b9ef97392f4e6ee318c595ef433a31e6baa33b8`.
 
 # 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.
 
@@ -58,13 +58,15 @@ if (actual !== '1.0.0') {
 }
 ```
 
-Confirm both entries in `tiapp.xml` pin 1.0.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:
+`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:
 
 ```text
-modules/android/ti.synthengine/1.0.0/
-modules/iphone/ti.synthengine/1.0.0/
+modules/android/ti.synthengine/1.0.2/
+modules/iphone/ti.synthengine/1.0.2/
 ```
 
+When testing local native-variation candidates, select module version `1.1.0` for both platforms instead; the corresponding directories end in `/1.1.0/`. The candidates are unpublished and still report API `1.0.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
@@ -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.0 archive.
+- Use the matching device or simulator slice from the 1.0.2 archive.
 
 ## What to include in a bug report
 
@@ -178,7 +180,7 @@ The official release reports API version 1.0.0. Detect `noteOn`/`noteOff`/`updat
 
 ## 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. Source, filter type, table, quantization and ADSR require a new attack. Compatible `updateVoice` controls include live noise clock, one-pole cutoff, spatial position for a spatial voice, stereo pan for a stereo voice, modulation and explicit effect send, in addition to pitch/volume/filter/vibrato/FM/pulse targets. Changed continuous controls ramp for 10 ms while retaining phase, envelope and spatial history; `noiseRate: 0` means white noise and `lowPassHz: 0` bypasses that filter.
+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.
 
 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 `updateVoice` 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).