@maccesar/titools 5.1.0 → 5.2.0

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

@@ -17,6 +17,10 @@ Treat levels as starting points, not mastering targets. Test on the actual
 phone speaker and leave headroom when release tails or independent events can
 overlap.
 
+The recipes under "Expressive envelopes, filters and FM" pass the real
+contract, but they come from standard synthesis ranges and have not been
+auditioned on a device. Listen before shipping them.
+
 <!-- TOC-START -->
 ## Contents
 
@@ -24,6 +28,7 @@ overlap.
 - [Playable xylophone](#playable-xylophone)
 - [Four-pad memory cues](#four-pad-memory-cues)
 - [Polyphony and layered chords](#polyphony-and-layered-chords)
+- [Expressive envelopes, filters and FM](#expressive-envelopes-filters-and-fm)
 - [Preset architecture for strict contracts](#preset-architecture-for-strict-contracts)
 - [Recipe verification checklist](#recipe-verification-checklist)
 
@@ -105,19 +110,21 @@ were chosen for it.
 
 ### Three-note bonus cue
 
-Short ascending square notes read as collection or reward. `stepDuration`
-controls spacing; each step's `duration` controls its gate.
+Short ascending square notes read as collection or reward. A step's `duration`
+sets both its voice length and the time before the next step; it overrides
+`stepDuration` and `noteValue`. Explicit rests separate 95 ms notes by 110 ms.
 
 ```javascript
 synth.playPattern({
-  stepDuration: 110,
   attack: 2,
   release: 30,
   volume: 0.55,
   waveType: WAVE.SQUARE,
   steps: [
     { frequency: 523.25, duration: 95 },
+    { rest: true, duration: 15 },
     { frequency: 587.33, duration: 95 },
+    { rest: true, duration: 15 },
     { frequency: 659.25, duration: 130 }
   ]
 })
@@ -126,19 +133,22 @@ synth.playPattern({
 ### Fast four-note arpeggio
 
 Very short square notes with a small attack retain the hard cartridge-era
-edge while reducing uncontrolled clicks.
+edge while reducing uncontrolled clicks. The 10 ms rests keep the first three
+40 ms notes on a 50 ms grid; the final note rings for 80 ms.
 
 ```javascript
 synth.playPattern({
-  stepDuration: 50,
   attack: 5,
   release: 15,
   volume: 0.5,
   waveType: WAVE.SQUARE,
   steps: [
     { frequency: 261.63, duration: 40 },
+    { rest: true, duration: 10 },
     { frequency: 329.63, duration: 40 },
+    { rest: true, duration: 10 },
     { frequency: 392, duration: 40 },
+    { rest: true, duration: 10 },
     { frequency: 523.25, duration: 80 }
   ]
 })
@@ -147,8 +157,8 @@ synth.playPattern({
 ### Rapid score ticks
 
 Use one native pattern instead of ten JavaScript timers. Explicit attack and
-release values make every 60 ms step valid without relying on shortened
-defaults.
+release values make every 60 ms tone valid without relying on shortened
+defaults. A 10 ms rest after each tone places the ticks 70 ms apart.
 
 ```javascript
 var scoreSteps = []
@@ -160,10 +170,10 @@ for (var index = 0; index < 10; index++) {
     attack: 2,
     release: 20
   })
+  scoreSteps.push({ rest: true, duration: 10 })
 }
 
 synth.playPattern({
-  stepDuration: 70,
   volume: 0.42,
   waveType: WAVE.SQUARE,
   steps: scoreSteps
@@ -194,19 +204,20 @@ synth.playTone({
 ### Alternating warning alarm
 
 An octave-like high/low alternation is easy to identify even through a small
-speaker. The envelope fits exactly inside every 120 ms tone:
-`10 + 100 <= 120`.
+speaker. Each 120 ms tone has a fitted envelope (`10 + 100 <= 120`), followed
+by a 10 ms rest, so the pitch changes every 130 ms.
 
 ```javascript
 var warningSteps = []
 
 for (var pulse = 0; pulse < 5; pulse++) {
   warningSteps.push({ frequency: 800, duration: 120 })
+  warningSteps.push({ rest: true, duration: 10 })
   warningSteps.push({ frequency: 400, duration: 120 })
+  warningSteps.push({ rest: true, duration: 10 })
 }
 
 synth.playPattern({
-  stepDuration: 130,
   attack: 10,
   release: 100,
   volume: 0.45,
@@ -412,8 +423,8 @@ function auditionTimbre (profileName) {
 
 ### Convert MIDI pitch to hertz
 
-The standard A4 = 440 Hz formula makes it easy to build interval recipes and
-small detunings without embedding a long frequency table.
+The standard A4 = 440 Hz formula makes it easy to build interval recipes
+without embedding a long frequency table.
 
 ```javascript
 function midiToHz (midi) {
@@ -421,14 +432,14 @@ function midiToHz (midi) {
 }
 ```
 
-A cent is one hundredth of a semitone, so add `cents / 100` to the MIDI value
-before conversion.
+Detuning needs no conversion: `detune` on a tone or pattern and `detunes` on a
+chord take cents, one hundredth of a semitone.
 
 ### Build a wide layered chord
 
 The interval cycle `[0, 4, 7, ...]` stacks major-triad chord tones across
-octaves. Later layers repeat those tones with small cent offsets, which creates
-width and beating without requiring an unsupported detune option.
+octaves. Later layers repeat those tones with small cent offsets, passed as
+`detunes`, which creates width and beating.
 
 ```javascript
 var CHORD_INTERVALS = [0, 4, 7, 12, 16, 19, 24, 28, 31, 36]
@@ -446,15 +457,24 @@ function buildLayeredFrequencies (voiceCount) {
 
   for (var index = 0; index < count; index++) {
     var intervalIndex = index % CHORD_INTERVALS.length
-    var layer = Math.floor(index / CHORD_INTERVALS.length)
-    var cents = LAYER_DETUNE_CENTS[layer % LAYER_DETUNE_CENTS.length]
-    var midi = 60.12 + CHORD_INTERVALS[intervalIndex] + (cents / 100)
-    frequencies.push(midiToHz(midi))
+    frequencies.push(midiToHz(60.12 + CHORD_INTERVALS[intervalIndex]))
   }
 
   return frequencies
 }
 
+function buildLayerDetunes (voiceCount) {
+  var count = normalizeVoiceCount(voiceCount)
+  var detunes = []
+
+  for (var index = 0; index < count; index++) {
+    var layer = Math.floor(index / CHORD_INTERVALS.length)
+    detunes.push(LAYER_DETUNE_CENTS[layer % LAYER_DETUNE_CENTS.length])
+  }
+
+  return detunes
+}
+
 function buildSymmetricPans (voiceCount, spread) {
   var count = normalizeVoiceCount(voiceCount)
   var numericSpread = Number(spread)
@@ -477,6 +497,7 @@ function playLayeredChord (voiceCount) {
 
   return synth.playChord({
     frequencies: buildLayeredFrequencies(count),
+    detunes: buildLayerDetunes(count),
     duration: 800,
     attack: 35,
     release: 220,
@@ -558,6 +579,171 @@ win.addEventListener('close', cleanupAudio)
 Do not call `shutdown()` from a child control if another visible screen owns
 the shared engine.
 
+## Expressive envelopes, filters and FM
+
+### Plucked marimba note
+
+A short attack, a decay that falls to a low sustain and a release that fits
+give the struck-and-ring shape of a mallet or plucked string. A sustain below 1
+needs a decay, and `attack + decay` must fit inside `duration`.
+
+```javascript
+synth.playTone({
+  note: 'C5',
+  duration: 700,
+  attack: 2,
+  decay: 260,
+  sustain: 0.12,
+  release: 240,
+  waveType: WAVE.TRIANGLE,
+  volume: 0.62
+})
+```
+
+### Kick drum
+
+A sine that falls in pitch while its level decays reads as a drum. The pitch
+sweep is linear over the whole event.
+
+```javascript
+synth.playTone({
+  frequency: 150,
+  frequencyEnd: 45,
+  duration: 320,
+  attack: 1,
+  decay: 140,
+  sustain: 0.35,
+  release: 140,
+  volume: 0.9
+})
+```
+
+### Closed hi-hat
+
+White noise through a high-pass filter, with a decay that drops to a quiet
+tail. The filter fields only work together with a `filterType`.
+
+```javascript
+synth.playTone({
+  waveType: WAVE.NOISE,
+  duration: 90,
+  attack: 1,
+  decay: 20,
+  sustain: 0.3,
+  release: 60,
+  filterType: 'highpass',
+  filterHz: 6500,
+  volume: 0.45
+})
+```
+
+### Electric piano
+
+Frequency modulation with a 1:1 ratio gives a tine-like tone. Letting the
+modulation index fall through `fmDepthEnd` makes the note mellow as it rings,
+which is what the ear expects from a struck tine. FM needs a sine carrier.
+
+```javascript
+synth.playTone({
+  note: 'E3',
+  duration: 1400,
+  attack: 3,
+  decay: 700,
+  sustain: 0.25,
+  release: 500,
+  fmRatio: 1,
+  fmDepth: 2.2,
+  fmDepthEnd: 0.3,
+  volume: 0.55
+})
+```
+
+### Bell
+
+A non-integer ratio produces an inharmonic spectrum, and an index that decays
+to nothing leaves a pure ring. `fmDepthEnd: 0` is a real target, so it is
+accepted; omit the key when no sweep is wanted.
+
+```javascript
+synth.playTone({
+  note: 'A5',
+  duration: 2400,
+  attack: 1,
+  decay: 1800,
+  sustain: 0,
+  release: 500,
+  fmRatio: 3.5,
+  fmDepth: 4,
+  fmDepthEnd: 0,
+  volume: 0.5
+})
+```
+
+### Wah sweep
+
+A resonant band-pass opening on a sawtooth. The cutoff moves exponentially, so
+equal distances in pitch take equal time. Keep `filterQ` moderate: high values
+make the resonance peak loud enough to engage the limiter.
+
+```javascript
+synth.playTone({
+  note: 'A2',
+  duration: 900,
+  attack: 20,
+  release: 200,
+  waveType: WAVE.SAWTOOTH,
+  filterType: 'bandpass',
+  filterHz: 350,
+  filterHzEnd: 2200,
+  filterQ: 4,
+  volume: 0.7
+})
+```
+
+### Thick unison pad
+
+Repeat a pitch and spread the copies a few cents apart. The slow beating
+between them is what makes the sound wide. `detunes` is aligned with the
+pitches and can be shorter than the array.
+
+```javascript
+synth.playChord({
+  notes: ['A3', 'A3', 'A3', 'E4', 'E4', 'E4'],
+  detunes: [-9, 0, 9, -7, 0, 7],
+  pans: [-0.6, 0, 0.6, -0.4, 0, 0.4],
+  duration: 2400,
+  attack: 350,
+  release: 900,
+  waveType: WAVE.SAWTOOTH,
+  volume: 0.45
+})
+```
+
+### Chaining after a pattern
+
+`patternend` fires once for every accepted pattern. `completed` is true when it
+ran to its end and false when a newer pattern replaced it, so only the first
+case should start the next cue. `stopAll()` and `shutdown()` fire nothing.
+
+```javascript
+function onPatternEnd (event) {
+  if (event.completed) playOutroCue()
+}
+
+synth.addEventListener('patternend', onPatternEnd)
+
+synth.playPattern({
+  noteValue: '8n',
+  waveType: WAVE.SQUARE,
+  volume: 0.5,
+  steps: [{ note: 'C5' }, { note: 'E5' }, { note: 'G5' }, { note: 'C6' }]
+})
+
+function cleanupPatternEvents () {
+  synth.removeEventListener('patternend', onPatternEnd)
+}
+```
+
 ## Preset architecture for strict contracts
 
 Keep descriptive metadata outside the native options object. Build a new
@@ -600,8 +786,12 @@ Before returning or shipping a variation:
 - use exactly one pitch source for a tone and exactly one pitch array for a
   chord;
 - include a pitch field on every sounding pattern step, including noise;
+- treat each resolved step duration as both its voice length and timeline
+  advance; insert explicit rests when a shorter note needs a longer interval;
 - verify `attack < duration` and `release <= duration - attack` for every
-  explicit event or step;
+  explicit event or step, and `attack + decay <= duration` when a decay is set;
+- give `sustain` below 1 a `decay`, give filter fields a `filterType`, and give
+  FM a sine carrier and a depth;
 - keep all numbers finite and integer-only fields integral;
 - use `WAVE` constants, not copied numeric waveform values;
 - check Boolean results at important control boundaries;

package/skills/ti-synthengine/references/recommendations.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/recommendations.md` SHA-256: `0f09ee6ef0876b3a23021fddb509dfd1e1206d08e836acae8f32b58b6481c055`.
 
 # Recommendations
 
@@ -9,7 +9,8 @@ audio systems sharing one lifecycle.
 ## Group simultaneous notes
 
 Use `playChord()` when pitches form one known simultaneous event. The chord is
-atomic and its source gain accounts for its voice count. Separate `playTone()`
+atomic. Protected profiles normalize per-voice source gain by the square root
+of the event voice count; `raw` bypasses that normalization. Separate `playTone()`
 calls are appropriate for independent touches and effects, but their start
 times and gain are independent too.
 
@@ -65,28 +66,47 @@ play later sounds normally once the system has moved to the new route.
 ## Coexisting with other audio
 
 On iOS, the audio session is app-wide and the last component to configure it
-wins. TiSynthEngine selects `Playback`, which ignores the ring/silent switch and
-normally interrupts other apps. That behavior fits an instrument or an app
-whose sound must be heard.
+wins. By default TiSynthEngine selects `Playback`, which ignores the ring/silent
+switch and normally interrupts other apps. That behavior fits an instrument or
+an app whose sound must be heard.
 
-A game that should respect the silent switch may set Titanium's ambient
-category after the last engine startup:
+A game that should respect the silent switch and let other apps' music keep
+playing starts the engine with the ambient session:
 
 ```javascript
-if (Ti.Platform.osname !== 'android') {
-  Ti.Media.audioSessionCategory = Ti.Media.AUDIO_SESSION_CATEGORY_AMBIENT
-}
+synth.startEngine({ audioSession: 'ambient' })
 ```
 
-The order is important because `startEngine()` configures the session. Other
-native audio modules may configure it again. Test the final startup sequence,
-interruptions, background behavior and route changes on iOS before relying on
-an override.
+The engine applies the category at startup and again when it resumes after a
+route change. Other native audio modules may still configure the app-wide
+session later. Test the final startup sequence, interruptions, background
+behavior and route changes on iOS. Android accepts the option and ignores it.
 
 Android mixes independent output streams at the system level, but another app
 or stale test process can still consume low-latency resources. Force-stop old
 test builds when diagnosing a glitch that does not reproduce after reboot.
 
+## Keep resonance, FM and detune in check
+
+The resonant filter, FM and stacked detuned voices change level and spectrum
+more than the basic controls do.
+
+- A `lowpass` or `highpass` boosts the cutoff region by about `filterQ`, so Q
+  10 is roughly 20 dB. Raise Q in small steps and lower the event `volume` as
+  you go. `bandpass` keeps unity gain at its center when level must stay put.
+- A swept cutoff passes over every harmonic, so the level moves during the
+  sweep. Judge a wah or laser by the loudest moment, not the start.
+- A resonance that keeps reaching the limiter makes the whole mix pump. Lower
+  the volume or the Q before reaching for a different profile.
+- FM is not band-limited. A high carrier with a large `fmDepth` and `fmRatio`
+  aliases. Keep carriers of bell-like sounds around 500 Hz, or lower the index.
+- A detuned stack is one voice per copy. Count them when choosing `maxVoices`.
+  Protected profiles divide per-voice source gain by the square root of the
+  event voice count; `raw` does not. Correlated or phase-aligned voices can still
+  reinforce each other, so this is not a guarantee of constant loudness or peaks.
+- `patternend` follows the pattern scheduler. Use it to chain cues and release
+  state, not to line up audio to the sample.
+
 ## Validate values at the app boundary
 
 The native API rejects invalid values instead of clamping them. Use
@@ -106,6 +126,12 @@ function acceptedFrequency (raw) {
 Do not copy the frequency maximum into application code. It depends on the
 active sample rate and should be read again after startup.
 
+The same rule applies to `noiseRate`, `lowPassHz` and `filterHz`. Validate a
+custom `waveTable` as 2 to 64 finite values from -1 to 1, and remember that
+`bitDepth` accepts zero or an integer from 2 to 16. For `detune`, check the
+resulting pitch too: a shifted pitch that leaves the frequency range is
+rejected even when the cents value is in range.
+
 Check Boolean return values during development. A rejected call includes the
 method, key and reason in the native log. Logging that result at the caller is
 often enough to identify a stale preset or misspelled field.
@@ -134,6 +160,10 @@ Exercise the real worst case:
 An underrun counter only describes transport. A clean counter cannot tell you
 whether a waveform, pitch or mix is pleasant.
 
+## Binaural placement
+
+Use the [integration guide](guide.md#integrate-binaural-in-a-2d-app) to convert each effect source into signed spatial coordinates. Keep switch and amplitude percentages in the app, enable the controls only when both spatial limits are present, and test with headphones. Count concurrently spatial voices and replacement tails when measuring CPU.
+
 ## Known limits
 
 - There are no per-voice handles. A single active note cannot be edited or
@@ -141,10 +171,17 @@ whether a waveform, pitch or mix is pleasant.
 - Every event has a finite duration of at most 60 seconds. There is no looping.
 - The module synthesizes waveforms and does not play audio files.
 - Only one pattern scheduler is pending at a time.
-- There is no completion event for a note, chord or pattern.
-- The module emits no JavaScript events.
+- There is no completion event for a single note or chord. Patterns report
+  their end through `patternend`, which is the only event the module emits.
 - Voice capacity and mixing profile remain fixed until shutdown.
 - Pattern scheduling is timer-based, not sample-accurate.
+- `lowPassHz` is a plain one-pole filter. The resonant filter has fixed 12 dB
+  per octave and one exponential sweep; there is no filter envelope.
+- FM has one modulator and works only on `SINE`.
+- Binaural positions are fixed per event on a front plane; there is no per-voice movement, rear positioning, distance attenuation or head tracking. Output is two channels, without a multichannel 2.1/5.1 routing API.
+- There is no effects bus: no reverb, delay or chorus.
+- The module provides generic synthesis primitives, not cycle-accurate hardware
+  emulation.
 
 Use a sample player or a dedicated music engine when a product needs streaming,
 loop points, per-voice control or a synchronized composition timeline.