@maccesar/titools 4.16.2 → 4.17.0

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

@@ -0,0 +1,236 @@
+> Source snapshot: official TiSynthEngine 1.0.0 documentation at commit `6685b81` (2026-08-29).
+
+# API reference
+
+Module id: `ti.synthengine`
+
+Public API version: `1.0.0`
+
+Android and iOS expose the same eight methods, defaults, limits, waveform
+values and validation behavior. Option objects are strict: an unknown key is
+rejected with `unsupported_option`.
+
+## Return values
+
+`startEngine`, `playTone`, `playChord`, `playPattern` and `setVolume` return a
+Boolean. `true` means the request was accepted. `false` means validation
+failed, the engine was unavailable, or the native command queue was full.
+
+`stopAll` and `shutdown` do not return a value. `getDefaults` returns the
+contract object described below.
+
+## `getDefaults()`
+
+Returns the installed contract without starting the audio stream.
+
+```javascript
+var contract = synth.getDefaults()
+```
+
+The result has this shape:
+
+```javascript
+{
+  apiVersion: '1.0.0',
+  defaults: {
+    maxVoices: 8,
+    mixingProfile: 'conservative',
+    frequency: 440,
+    duration: 500,
+    attack: 50,
+    release: 50,
+    volume: 1,
+    waveType: 0,
+    pan: 0,
+    panEnd: 0,
+    frequencyEnd: 0,
+    lfoFreq: 0,
+    lfoDepth: 0,
+    panSpread: 0,
+    bpm: 120,
+    swing: 0,
+    stepDuration: 100
+  },
+  limits: { /* ranges listed below */ },
+  mixingProfiles: ['conservative', 'raw', 'balanced', 'speakerSafe'],
+  waveTypes: {
+    SINE: 0,
+    SQUARE: 1,
+    SAWTOOTH: 2,
+    TRIANGLE: 3,
+    NOISE: 4
+  }
+}
+```
+
+The maximum frequency is `sampleRate * 0.45`. Before the stream opens, the
+reported fallback is 19,845 Hz. Read the object again after `startEngine()` if
+the precise device limit matters.
+
+## Limits
+
+All ranges include their endpoints.
+
+| Field | Minimum | Maximum | Unit or rule |
+| --- | ---: | ---: | --- |
+| `maxVoices` | 1 | 32 | integer voices |
+| `frequency` | 1 | `sampleRate * 0.45` | Hz |
+| `duration` | 1 | 60,000 | integer ms |
+| `attack` | 0 | 2,000 | integer ms; must be less than duration |
+| `release` | 0 | 4,000 | integer ms; must fit after attack |
+| `volume` | 0 | 2 | event or master multiplier |
+| `waveType` | 0 | 4 | integer waveform value |
+| `patternSteps` | 1 | 512 | object steps |
+| `pan`, `panEnd`, `pans[]` | -1 | 1 | left to right |
+| `panSpread` | 0 | 1 | chord stereo width |
+| `frequencyEnd` | 0 | `sampleRate * 0.45` | Hz; 0 disables the sweep |
+| `lfoFreq` | 0 | 20,000 | Hz; 0 disables vibrato |
+| `lfoDepth` | 0 | 20,000 | Hz |
+| `bpm` | 20 | 300 | beats per minute |
+| `swing` | -0.49 | 0.49 | alternating timing offset |
+| `stepDuration` | 1 | 60,000 | ms |
+
+The allowed `noteValue` strings are `1n`, `2n`, `4n`, `8n`, `16n` and `32n`.
+
+## `startEngine(options)`
+
+Starts the native stream. Calling it again while the engine is running returns
+`true` without rebuilding the stream.
+
+| Key | Type | Default | Description |
+| --- | --- | --- | --- |
+| `maxVoices` | integer | `8` | Size of the voice pool, from 1 to 32. |
+| `mixingProfile` | string | `conservative` | `conservative`, `balanced`, `speakerSafe` or `raw`. Matching is case-insensitive. |
+
+The profile and voice capacity stay fixed for the session. Call `shutdown()`
+before starting again with different values.
+
+## `playTone(options)`
+
+Plays one pitch. It uses 440 Hz when neither pitch field is present.
+
+| Key | Type | Default | Description |
+| --- | --- | ---: | --- |
+| `frequency` | number | `440` | Starting frequency in Hz. Cannot be combined with `note`. |
+| `note` | string | none | Note name. Cannot be combined with `frequency`. |
+| `duration` | integer | `500` | Total event length in ms. |
+| `attack` | integer | `50` | Fade-in time in ms. |
+| `release` | integer | `50` | Fade-out time in ms. |
+| `volume` | number | `1` | Event level multiplier. |
+| `waveType` | integer | `SINE` | One of the five waveform values. |
+| `pan` | number | `0` | Starting stereo position. |
+| `panEnd` | number | `0` | Ending stereo position. |
+| `frequencyEnd` | number | `0` | Ending frequency; 0 keeps the starting pitch. |
+| `lfoFreq` | number | `0` | Vibrato rate in Hz. |
+| `lfoDepth` | number | `0` | Vibrato depth in Hz. |
+
+## `playChord(options)`
+
+Starts 1 to 32 pitches as one atomic event. Exactly one pitch array is
+required.
+
+| Key | Type | Default | Description |
+| --- | --- | ---: | --- |
+| `frequencies` | number[] | required alternative | Frequencies in Hz. |
+| `notes` | string[] | required alternative | Note names. |
+| `duration` | integer | `500` | Total chord length in ms. |
+| `attack` | integer | `50` | Fade-in time in ms. |
+| `release` | integer | `50` | Fade-out time in ms. |
+| `volume` | number | `1` | Chord event level. |
+| `waveType` | integer | `SINE` | Waveform for every voice. |
+| `panSpread` | number | `0` | Even stereo spread from 0 to 1. |
+| `pans` | number[] | none | Per-note pan positions; overrides spread for supplied entries. |
+
+`pans` cannot contain more entries than the pitch array. `playChord` does not
+accept sweep or vibrato fields.
+
+## `playPattern(options)`
+
+Schedules a monophonic sequence. The required `steps` array must contain only
+objects. A string or number step is rejected with `invalid_step_type`.
+
+Pattern-level keys:
+
+| Key | Type | Default | Description |
+| --- | --- | ---: | --- |
+| `steps` | object[] | required | Between 1 and 512 steps. |
+| `bpm` | number | `120` | Tempo used by note values. |
+| `swing` | number | `0` | Alternating timing offset. |
+| `stepDuration` | number | `100` | Fallback step length in ms. |
+| `noteValue` | string | none | Shared musical step length. |
+| `attack` | integer | `50` | Inherited attack. |
+| `release` | integer | `50` | Inherited release. |
+| `volume` | number | `1` | Inherited event level. |
+| `waveType` | integer | `SINE` | Inherited waveform. |
+| `pan` | number | `0` | Inherited starting pan. |
+| `panEnd` | number | `0` | Inherited ending pan. |
+| `frequencyEnd` | number | `0` | Inherited sweep target. |
+| `lfoFreq` | number | `0` | Inherited vibrato rate. |
+| `lfoDepth` | number | `0` | Inherited vibrato depth. |
+
+Step keys:
+
+| Key | Type | Description |
+| --- | --- | --- |
+| `note` | string | Pitch name; exclusive with `frequency` and `rest`. |
+| `frequency` | number | Pitch in Hz; exclusive with `note` and `rest`. |
+| `rest` | Boolean | Must be exactly `true` for a rest. |
+| `duration` | integer | Step length in ms. |
+| `noteValue` | string | Step length derived from `bpm`. |
+| `attack`, `release`, `volume`, `waveType` | number | Override the pattern value for this step. |
+| `pan`, `panEnd`, `frequencyEnd`, `lfoFreq`, `lfoDepth` | number | Override motion or vibrato for this step. |
+
+Step timing precedence is `duration`, step `noteValue`, pattern `noteValue`,
+pattern `stepDuration`, then 100 ms. Only one pattern remains pending at a
+time. Starting another one cancels steps that have not fired.
+
+## `setVolume(options)`
+
+Changes the master level with a short smoothing ramp.
+
+| Key | Type | Default | Range |
+| --- | --- | ---: | ---: |
+| `volume` | number | `1` | 0 to 2 |
+
+## `stopAll()`
+
+Fades active voices over roughly 20 ms to avoid clicks. It does not cancel
+future pattern steps.
+
+## `shutdown()`
+
+Cancels the pending pattern, stops the native stream and releases its audio
+resources. Call it when the owner closes.
+
+## Strict validation
+
+Unknown keys and invalid values return `false` and produce one deduplicated
+native log entry:
+
+```text
+event=validation_warning method=playTone key=duraton reason=unsupported_option action=rejected value=200
+```
+
+Common reasons include:
+
+| Reason | Meaning |
+| --- | --- |
+| `unsupported_option` | The option name is not part of that method or step. |
+| `invalid_step_type` | A pattern step is not an object. |
+| `non_numeric_or_non_finite` | A numeric field is the wrong type, `NaN` or infinite. |
+| `not_integer` | An integer field contains a fractional number. |
+| `out_of_range` | A number falls outside the documented range. |
+| `not_string`, `not_array`, `not_boolean` | A field has the wrong container or primitive type. |
+| `invalid_note` | A note name cannot be parsed. |
+| `unsupported_note_value` | A note value is not one of the six supported values. |
+| `missing_required` | A required chord pitch array is absent. |
+| `missing_pitch_or_rest` | A pattern step has no pitch and is not a rest. |
+| `conflicting_pitch_fields` | A call or step provides more than one pitch source. |
+| `invalid_voice_count` | A chord has fewer than 1 or more than 32 pitches. |
+| `invalid_step_count` | A pattern has fewer than 1 or more than 512 steps. |
+| `too_many_values` | `pans` is longer than the chord. |
+| `attack_greater_or_equal_duration` | An explicit attack leaves no time for the event. |
+| `release_exceeds_remaining_duration` | An explicit release does not fit after attack. |
+
+Explicit values are not clamped. Read `getDefaults().limits` when accepting
+user input and decide in the app whether to reject or constrain it.

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

@@ -0,0 +1,217 @@
+> Source snapshot: official TiSynthEngine 1.0.0 documentation at commit `6685b81` (2026-08-29).
+
+# 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.
+
+## Signal path
+
+```text
+playTone / playChord / playPattern
+             |
+       strict validation
+             |
+   native command ring buffer
+             |
+ voice pool: oscillator * envelope * event gain * stereo pan
+             |
+       sum voices and steal tails
+             |
+      smoothed master volume
+             |
+ stereo-linked 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.
+
+## Oscillators
+
+The engine has five sources:
+
+| Waveform | Source behavior |
+| --- | --- |
+| `SINE` | Direct sinusoid. |
+| `SQUARE` | PolyBLEP band-limited discontinuity. |
+| `SAWTOOTH` | PolyBLEP band-limited discontinuity. |
+| `TRIANGLE` | Continuous triangle oscillator. |
+| `NOISE` | White-noise generator. |
+
+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.
+
+## 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.
+
+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.
+
+## Event gain
+
+In protected profiles, gain is fixed when an event starts:
+
+```text
+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.
+
+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 and noise | 0.539 | 0.311 |
+
+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.
+
+| 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.
+
+## Limiter
+
+A single stereo-linked peak limiter sits after master volume. 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` |
+
+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.
+
+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.
+
+## 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.
+
+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.
+
+## 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.
+
+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.
+
+## 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.
+
+`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.
+
+## 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.
+
+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`,
+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.
+
+`AVAudioSourceNode` requires iOS 13 or newer. The module archive contains device,
+simulator and Mac Catalyst slices.
+
+## Latency
+
+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.
+
+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.
+
+## Regression coverage
+
+The repository checks the public contract and both source ports without a
+device:
+
+```sh
+node tests/api_contract_regression.js
+node tests/default_profile_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 \
+  src/ti/synthengine/SynthDsp.java \
+  test/ti/synthengine/SynthDspRegression.java
+java -cp "$test_dir" ti.synthengine.SynthContractRegression
+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.