@maccesar/titools 5.2.0 → 5.2.1

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

@@ -1,9 +1,12 @@
-> 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/examples.md` SHA-256: `53a8bd95215cc24a35776edb8686fa0d60c5399be0b4ff2685eee1563738f6cb`.
+> Source snapshot: official TiSynthEngine 1.0.0 documentation at release source commit `e7cbbe8a6f9ab38088fd8029c7b43cef6501101f` (2026-10-24). Upstream `documentation/examples.md` SHA-256: `48104b9d413050d439ee605c92a2456a50b42c4c80e2d7c2c05706eecc7db215`.
 
 # Examples
 
-Every snippet on this page uses the TiSynthEngine 1.0.0 contract. Unless a
-snippet includes startup code, it assumes the engine is already running.
+Every snippet on this page uses the TiSynthEngine 1.0.0 contract. Unless a snippet includes startup code, it assumes the engine is already running.
+
+Additional [curated recipes](recipes.md) provide application sound and interaction variants.
+
+For interactive instruments and native processing, begin with [held motors](advanced-examples.md#sustained-game-motor), [native sequences](advanced-examples.md#native-sequence-with-chords-and-edits), [master processing](advanced-examples.md#chorus-delay-reverb-and-creative-saturation) or [two LFOs](advanced-examples.md#two-voice-lfos). Use matching official packages and check method availability before enabling a feature.
 
 ```javascript
 var synth = require('ti.synthengine')
@@ -40,7 +43,7 @@ if (contract.apiVersion !== '1.0.0') {
 - [Wah and filtered laser](#wah-and-filtered-laser)
 - [Kick and hi-hat in one pattern](#kick-and-hi-hat-in-one-pattern)
 - [Detuned chords](#detuned-chords)
-- [Chain patterns with `patternend`](#chain-patterns-with-patternend)
+- [Chain sequences with `sequenceend`](#chain-sequences-with-sequenceend)
 - [Rules across keys](#rules-across-keys)
 - [Speaker-safe startup](#speaker-safe-startup)
 - [Validation at an input boundary](#validation-at-an-input-boundary)
@@ -60,10 +63,12 @@ function onPostLayout () {
   timer = setTimeout(function () {
     timer = null
     win.removeEventListener('postlayout', onPostLayout)
-    started = synth.startEngine({
+    started = synth.start({
       maxVoices: 16,
-      mixingProfile: 'conservative'
+      mixingProfile: 'conservative',
+      audioSession: 'ambient'
     })
+    if (!started) Ti.API.warn('Audio startup failed; keep playback controls disabled')
   }, 250)
 }
 
@@ -78,26 +83,21 @@ win.addEventListener('close', cleanup)
 win.open()
 ```
 
+The startup example uses `ambient` for game/UI feedback. On iOS it respects silent mode and mixes with other apps. The module default is `playback`; Android validates either value without changing its output. Shut down before changing the policy. Use the [interactive session controls](../assets/example/README.md#audio-session) to compare them.
+
 ## Built-in waveforms
 
 ```javascript
 var names = ['SINE', 'SQUARE', 'SAWTOOTH', 'TRIANGLE', 'NOISE']
-
-names.forEach(function (name, index) {
-  setTimeout(function () {
-    synth.playTone({
-      note: 'A4',
-      duration: 400,
-      attack: 8,
-      release: 100,
-      volume: 0.6,
-      waveType: WAVE[name]
-    })
-  }, index * 500)
+synth.playSequence({ timeUnit: 'ms', stepDuration: 500,
+  voice: { attack: 8, release: 100, volume: 0.6 },
+  steps: names.map(function (name) {
+    return { notes: [69], length: 300, overrides: { waveType: WAVE[name] } }
+  })
 })
 ```
 
-Noise ignores pitch, but `note` keeps the event shape valid.
+Noise ignores pitch; each sounding step still supplies one pitch array.
 
 ## Variable-rate filtered noise
 
@@ -116,8 +116,7 @@ synth.playTone({
 })
 ```
 
-`noiseRate` starts at 12 kHz and falls to 600 Hz. `lowPassHz` removes high
-frequency energy after the 8-bit source quantizer.
+`noiseRate` starts at 12 kHz and falls to 600 Hz. `lowPassHz` removes high frequency energy after the 8-bit source quantizer.
 
 ## Pulse-width sweep
 
@@ -151,8 +150,7 @@ synth.playTone({
 })
 ```
 
-The table repeats as a stepped cycle. `bitDepth: 8` quantizes each table value
-before filtering and the amplitude envelope.
+The table repeats as a stepped cycle. `bitDepth: 8` quantizes each table value before filtering and the amplitude envelope.
 
 ## Fixed controls on a chord
 
@@ -171,48 +169,25 @@ synth.playChord({
 })
 ```
 
-Chord voices share fixed shaping controls. Sweep fields such as
-`pulseWidthEnd` and `noiseRateEnd` are not accepted by `playChord()`.
+Chord voices share fixed shaping controls. Sweep fields such as `pulseWidthEnd` and `noiseRateEnd` are not accepted by `playChord()`.
 
 ## Wave-shaping pattern overrides
 
 ```javascript
-synth.playPattern({
+synth.playSequence({
+  timeUnit: 'ms',
   stepDuration: 210,
-  attack: 2,
-  release: 80,
-  volume: 0.48,
-  waveType: WAVE.NOISE,
-  noiseRate: 12000,
-  lowPassHz: 2600,
-  bitDepth: 8,
+  voice: { attack: 2, release: 80, volume: 0.48, waveType: WAVE.NOISE, noiseRate: 12000, lowPassHz: 2600, bitDepth: 8 },
   steps: [
-    { frequency: 120, duration: 180, release: 150, noiseRateEnd: 800 },
+    { frequencies: [120], duration: 180, overrides: { release: 150, noiseRateEnd: 800 } },
     { rest: true, duration: 100 },
-    {
-      note: 'A3',
-      duration: 300,
-      release: 120,
-      waveType: WAVE.SQUARE,
-      pulseWidth: 0.1,
-      pulseWidthEnd: 0.82,
-      lowPassHz: 0,
-      bitDepth: 0
-    },
-    {
-      note: 'D4',
-      duration: 360,
-      release: 160,
-      waveType: WAVE.WAVETABLE,
-      waveTable: [-1, -0.7, -0.1, 0.8, 1, 0.35, -0.25, -0.55]
-    }
+    { notes: [57], duration: 300, overrides: { release: 120, waveType: WAVE.SQUARE, pulseWidth: 0.1, pulseWidthEnd: 0.82, lowPassHz: 0, bitDepth: 0 } },
+    { notes: [62], duration: 360, overrides: { release: 160, waveType: WAVE.WAVETABLE, waveTable: [-1, -0.7, -0.1, 0.8, 1, 0.35, -0.25, -0.55] } }
   ]
 })
 ```
 
-Pattern roots provide inherited values. Each sounding step can override the
-source and any shaping control; a `WAVETABLE` step needs a local or inherited
-`waveTable`.
+Pattern roots provide inherited values. Each sounding step can override the source and any shaping control; a `WAVETABLE` step needs a local or inherited `waveTable`.
 
 ## Pitch sweep and pan movement
 
@@ -230,8 +205,7 @@ synth.playTone({
 })
 ```
 
-Set `frequencyEnd: 0` to keep the starting pitch. Set `panEnd` equal to `pan`
-when no stereo movement is wanted.
+Set `frequencyEnd: 0` to keep the starting pitch. Set `panEnd` equal to `pan` when no stereo movement is wanted.
 
 ## Vibrato
 
@@ -248,8 +222,7 @@ synth.playTone({
 })
 ```
 
-`lfoFreq` and `lfoDepth` are both in hertz. A depth of 6 Hz is gentle around
-E4; use your ears when moving the same setting to a much lower note.
+`lfoFreq` and `lfoDepth` are both in hertz. A depth of 6 Hz is gentle around E4; use your ears when moving the same setting to a much lower note.
 
 ## Chord with an even spread
 
@@ -279,79 +252,63 @@ synth.playChord({
 })
 ```
 
-Use `playChord` for a known simultaneous group. Launching four separate tones
-is not atomic and gives each one full event gain.
+Use `playChord` for a known simultaneous group. Launching four separate tones is not atomic and gives each one full event gain.
 
 ## Tempo, note values and swing
 
 ```javascript
-synth.playPattern({
-  bpm: 132,
+synth.setTempo({ bpm: 132 })
+synth.playSequence({
+  timeUnit: 'beats',
+  stepDuration: 0.5,
   swing: 0.12,
-  noteValue: '8n',
-  attack: 4,
-  release: 55,
-  volume: 0.55,
-  waveType: WAVE.SQUARE,
+  voice: { attack: 4, release: 55, volume: 0.55, waveType: WAVE.SQUARE },
   steps: [
-    { note: 'C4' },
-    { note: 'E4' },
+    { notes: [60] },
+    { notes: [64] },
     { rest: true },
-    { note: 'G4' },
-    { note: 'C5', noteValue: '4n' }
+    { notes: [67] },
+    { notes: [72], duration: 1 }
   ]
 })
 ```
 
-Swing offsets scheduled starts without changing voice durations: positive swing delays even steps and advances odd steps (zero-based); negative swing reverses those offsets. Each offset is the swing value times that step's duration, and a start before the call time is clamped to zero. This can overlap voices. Keep it subtle unless the lurch is the intended effect.
+Swing adjusts pairs of intervals by `swing * min(A, B)`: the first grows and the second shrinks by that amount, preserving the pair total. Negative values reverse the adjustment. The default is 0 and the range is −0.75…0.75.
 
 ## Millisecond pattern
 
 ```javascript
-synth.playPattern({
-  pan: -0.4,
-  panEnd: 0.4,
-  waveType: WAVE.TRIANGLE,
+synth.playSequence({
+  timeUnit: 'ms',
+  stepDuration: 100,
+  voice: { pan: -0.4, panEnd: 0.4, waveType: WAVE.TRIANGLE },
   steps: [
-    { note: 'C5', duration: 90 },
+    { notes: [72], duration: 90 },
     { rest: true, duration: 20 },
-    { note: 'D5', duration: 90 },
+    { notes: [74], duration: 90 },
     { rest: true, duration: 20 },
-    { note: 'E5', duration: 90 },
+    { notes: [76], duration: 90 },
     { rest: true, duration: 20 },
-    { note: 'G5', duration: 180 }
+    { notes: [79], duration: 180 }
   ]
 })
 ```
 
-Each `duration` sets both the voice length and the advance to the next step.
-The 90 ms tones followed by 20 ms rests put the first four notes 110 ms apart;
-the last tone lasts 180 ms. Rests provide actual silence. `release` only fades
-within a sounding step, not a separate gate. The pattern root does not accept
-`duration`, and `stepDuration` is only a fallback when a step has no timing.
+Each `duration` sets the interval until the next step. The 90 ms intervals followed by 20 ms rests place attacks 110 ms apart; a release can overlap a rest. Gate defaults to 0.8. Use `length` to choose note duration independently, while ADSR remains milliseconds.
 
 ## Step overrides
 
 ```javascript
-synth.playPattern({
-  bpm: 100,
-  noteValue: '8n',
-  attack: 10,
-  release: 90,
-  volume: 0.5,
-  waveType: WAVE.SINE,
+synth.setTempo({ bpm: 100 })
+synth.playSequence({
+  timeUnit: 'beats',
+  stepDuration: 0.5,
+  voice: { attack: 10, release: 90, volume: 0.5, waveType: WAVE.SINE },
   steps: [
-    { note: 'C4' },
-    {
-      note: 'E4',
-      waveType: WAVE.SAWTOOTH,
-      pan: -0.7,
-      panEnd: 0.7,
-      lfoFreq: 7,
-      lfoDepth: 10
-    },
+    { notes: [60] },
+    { notes: [64], overrides: { waveType: WAVE.SAWTOOTH, pan: -0.7, panEnd: 0.7, lfoFreq: 7, lfoDepth: 10 } },
     { rest: true },
-    { note: 'G4', volume: 0.75, noteValue: '4n' }
+    { notes: [67], duration: 1, overrides: { volume: 0.75 } }
   ]
 })
 ```
@@ -359,51 +316,37 @@ synth.playPattern({
 ## Noise percussion
 
 ```javascript
-synth.playPattern({
-  bpm: 116,
-  noteValue: '16n',
-  volume: 0.32,
-  waveType: WAVE.NOISE,
+synth.setTempo({ bpm: 116 })
+synth.playSequence({
+  timeUnit: 'beats',
+  stepDuration: 0.25,
+  voice: { volume: 0.32, waveType: WAVE.NOISE },
   steps: [
-    { frequency: 200, attack: 1, decay: 70, sustain: 0, release: 60 },
+    { frequencies: [200], overrides: { attack: 1, decay: 70, sustain: 0, release: 60 } },
     { rest: true },
-    { frequency: 200, attack: 1, decay: 32, sustain: 0, release: 25 },
-    { frequency: 200, attack: 1, decay: 32, sustain: 0, release: 25 },
+    { frequencies: [200], overrides: { attack: 1, decay: 32, sustain: 0, release: 25 } },
+    { frequencies: [200], overrides: { attack: 1, decay: 32, sustain: 0, release: 25 } },
     { rest: true },
-    { frequency: 200, attack: 1, decay: 52, sustain: 0, release: 44 }
+    { frequencies: [200], overrides: { attack: 1, decay: 52, sustain: 0, release: 44 } }
   ]
 })
 ```
 
-The steps retain the sixteenth-note grid. Short decay with `sustain: 0` makes
-each hit settle to silence before its step ends, without changing that grid.
-Every sounding step needs `frequency` or `note`, including a noise step. Do not
-write a primitive step such as `200`; primitive steps return
-`invalid_step_type`.
+The steps retain the sixteenth-note grid. Short decay with `sustain: 0` makes each hit settle to silence before its step ends, without changing that grid. Every sounding step needs `frequencies` or `notes`, including a noise step. Do not write a primitive step such as `200`; primitive steps reject the complete publication.
 
 ## Xylophone sketch
 
 ```javascript
-function playBar (note, pan) {
-  return synth.playTone({
-    note: note,
-    duration: 520,
-    attack: 2,
-    release: 430,
-    volume: 0.62,
-    waveType: WAVE.TRIANGLE,
-    pan: pan
-  })
-}
-
-playBar('C5', -0.7)
-setTimeout(function () { playBar('E5', -0.2) }, 130)
-setTimeout(function () { playBar('G5', 0.3) }, 260)
-setTimeout(function () { playBar('C6', 0.75) }, 390)
+synth.playSequence({ timeUnit: 'ms', stepDuration: 130,
+  voice: { attack: 2, release: 430, volume: 0.62, waveType: WAVE.TRIANGLE },
+  steps: [{ notes: [72], length: 90, overrides: { pan: -0.7 } },
+    { notes: [76], length: 90, overrides: { pan: -0.2 } },
+    { notes: [79], length: 90, overrides: { pan: 0.3 } },
+    { notes: [84], length: 90, overrides: { pan: 0.75 } }]
+})
 ```
 
-These are deliberately independent strikes. Their releases overlap, so leave
-headroom in `volume` and choose enough `maxVoices` for the tails.
+Native attacks are 130 ms apart. Each note releases after 90 ms and its 430 ms tail overlaps later strikes. Leave headroom and voice capacity for those tails.
 
 ## Simon-style pads
 
@@ -436,9 +379,7 @@ function playAllPads () {
 
 ## Pluck and electric piano
 
-`decay` and `sustain` turn a flat tone into an instrument. The electric piano
-adds an FM index that falls with the level, so the attack is bright and the
-tail is mellow.
+`decay` and `sustain` shape the tone into a plucked or struck sound. The electric piano also lowers the FM index as the level falls, giving it a bright attack and a mellow tail.
 
 ```javascript
 function pluck (note) {
@@ -489,94 +430,45 @@ synth.playTone({
 })
 ```
 
-A fractional `fmRatio` puts the overtones between harmonics, which reads as
-metal. `fmDepthEnd: 0` lets the brightness die away completely.
+A fractional `fmRatio` puts the overtones between harmonics, which reads as metal. `fmDepthEnd: 0` lets the brightness die away completely.
 
 ## Wah and filtered laser
 
 ```javascript
-synth.playTone({
-  note: 'A2',
-  duration: 1000,
-  attack: 10,
-  release: 200,
-  volume: 0.5,
-  waveType: WAVE.SAWTOOTH,
-  filterType: 'bandpass',
-  filterHz: 350,
-  filterHzEnd: 2400,
-  filterQ: 5
+synth.playSequence({ timeUnit: 'ms',
+  voice: { waveType: WAVE.SAWTOOTH },
+  steps: [{ notes: [45], duration: 1300, length: 800,
+    overrides: { attack: 10, release: 200, volume: 0.5,
+      filterType: 'bandpass', filterHz: 350, filterHzEnd: 2400, filterQ: 5 } },
+    { frequencies: [1600], duration: 340, length: 250,
+      overrides: { frequencyEnd: 160, attack: 2, release: 90, volume: 0.4,
+        filterType: 'lowpass', filterHz: 7000, filterHzEnd: 500, filterQ: 4 } }]
 })
-
-setTimeout(function () {
-  synth.playTone({
-    frequency: 1600,
-    frequencyEnd: 160,
-    duration: 340,
-    attack: 2,
-    release: 90,
-    volume: 0.4,
-    waveType: WAVE.SAWTOOTH,
-    filterType: 'lowpass',
-    filterHz: 7000,
-    filterHzEnd: 500,
-    filterQ: 4
-  })
-}, 1300)
 ```
 
-The cutoff sweep spans the whole event, so a longer note sweeps more slowly.
+Each sweep reaches its destination at `length`, then holds there through release. Intervals and note lengths remain fixed in milliseconds when the global tempo changes.
 
 ## Kick and hi-hat in one pattern
 
 Each step can carry its own envelope and filter.
 
 ```javascript
-synth.playPattern({
-  bpm: 110,
-  noteValue: '8n',
+synth.setTempo({ bpm: 110 })
+synth.playSequence({
+  timeUnit: 'beats',
+  stepDuration: 0.5,
   steps: [
-    {
-      frequency: 150,
-      frequencyEnd: 42,
-      noteValue: '4n',
-      attack: 1,
-      decay: 140,
-      sustain: 0.3,
-      release: 120,
-      volume: 0.85
-    },
-    {
-      frequency: 440,
-      waveType: WAVE.NOISE,
-      attack: 1,
-      decay: 30,
-      sustain: 0.25,
-      release: 45,
-      volume: 0.45,
-      filterType: 'highpass',
-      filterHz: 7000
-    },
+    { frequencies: [150], duration: 1, overrides: { frequencyEnd: 42, attack: 1, decay: 140, sustain: 0.3, release: 120, volume: 0.85 } },
+    { frequencies: [440], overrides: { waveType: WAVE.NOISE, attack: 1, decay: 30, sustain: 0.25, release: 45, volume: 0.45, filterType: 'highpass', filterHz: 7000 } },
     { rest: true },
-    {
-      frequency: 440,
-      waveType: WAVE.NOISE,
-      attack: 1,
-      decay: 30,
-      sustain: 0.25,
-      release: 45,
-      volume: 0.45,
-      filterType: 'highpass',
-      filterHz: 7000
-    }
+    { frequencies: [440], overrides: { waveType: WAVE.NOISE, attack: 1, decay: 30, sustain: 0.25, release: 45, volume: 0.45, filterType: 'highpass', filterHz: 7000 } }
   ]
 })
 ```
 
 ## Detuned chords
 
-Repeat a pitch with small offsets in `detunes` to make it beat and widen. Two
-copies 12 cents apart at 440 Hz beat about three times a second.
+Repeat a pitch with small offsets in `detunes` to make it beat and widen. Two copies 12 cents apart at 440 Hz beat about three times a second.
 
 ```javascript
 synth.playChord({
@@ -589,8 +481,8 @@ synth.playChord({
   waveType: WAVE.SINE
 })
 
-setTimeout(function () {
-  synth.playChord({
+// Alternative voicing:
+synth.playChord({
     notes: ['A3', 'E4', 'A3', 'E4', 'A3', 'E4'],
     detunes: [-9, -9, 0, 0, 9, 9],
     duration: 3200,
@@ -601,53 +493,34 @@ setTimeout(function () {
     filterType: 'lowpass',
     filterHz: 1500,
     panSpread: 0.8
-  })
-}, 2400)
+})
 ```
 
-Each repeated pitch is a voice. The second chord needs `maxVoices` of at least
-6.
+Each repeated pitch is a voice. The second chord needs `maxVoices` of at least 6.
 
-## Chain patterns with `patternend`
+## Chain sequences with `sequenceend`
 
-```javascript
-var jingles = [
-  [{ note: 'C5' }, { note: 'E5' }, { note: 'G5' }],
-  [{ note: 'G5' }, { note: 'E5' }, { note: 'C5' }]
-]
-var nextJingle = 0
-
-function playNextJingle () {
-  if (nextJingle >= jingles.length) return false
-  return synth.playPattern({
-    noteValue: '8n',
-    attack: 5,
-    release: 60,
-    volume: 0.5,
-    waveType: WAVE.SQUARE,
-    steps: jingles[nextJingle++]
-  })
-}
+Use one sequence containing all steps for uninterrupted, sample-clock phrasing. The asynchronous completion event is useful for presentation or launching an unrelated cue:
 
-function onPatternEnd (event) {
-  if (event.completed) playNextJingle()
+```javascript
+var jingleId = synth.playSequence({
+  stepDuration: 0.5,
+  voice: { attack: 5, release: 60, volume: 0.5, waveType: WAVE.SQUARE },
+  steps: [{ notes: [72] }, { notes: [76] }, { notes: [79] }]
+})
+function onSequenceEnd (event) {
+  if (event.sequenceId === jingleId && event.reason === 'completed') Ti.API.info('Jingle scheduled to completion')
 }
-
-synth.addEventListener('patternend', onPatternEnd)
-playNextJingle()
-
-// When the audio owner closes:
-synth.removeEventListener('patternend', onPatternEnd)
+synth.addEventListener('sequenceend', onSequenceEnd)
+// When the owner closes:
+synth.removeEventListener('sequenceend', onSequenceEnd)
 ```
 
-The event reports `completed: false` when another pattern replaces the running
-one, so a listener that only chains on `completed: true` never double-starts.
+A positive identifier acknowledges publication; 0 rejects the complete operation. Sequence completion does not guarantee audible silence: release envelopes and effect tails can continue.
 
 ## Rules across keys
 
-Some combinations are rejected even when every value is in range. This call
-returns `false` with `sustain_without_decay`, because a sustain below 1 with no
-decay would jump in level and click:
+Some combinations are rejected even when every value is in range. This call returns `false` with `sustain_without_decay`, because a sustain below 1 with no decay would jump in level and click:
 
 ```javascript
 // Rejected on purpose: sustain needs a decay.
@@ -660,7 +533,7 @@ synth.playTone({ note: 'A4', decay: 200, sustain: 0.5, duration: 800 })
 ## Speaker-safe startup
 
 ```javascript
-var accepted = synth.startEngine({
+var accepted = synth.start({
   maxVoices: 12,
   mixingProfile: 'speakerSafe'
 })
@@ -668,9 +541,7 @@ var accepted = synth.startEngine({
 if (accepted) synth.setVolume({ volume: 0.85 })
 ```
 
-This profile lowers source gain and the limiter ceiling. It cannot repair a
-speaker that physically struggles with a very low pitch, so test the real
-device and raise the pitch when needed.
+This profile lowers source gain and the limiter ceiling. It cannot repair a speaker that physically struggles with a very low pitch, so test the real device and raise the pitch when needed.
 
 ## Validation at an input boundary
 
@@ -686,9 +557,7 @@ function playUserFrequency (input) {
 }
 ```
 
-The native contract rejects bad values rather than clamping them. Validation in
-the app lets you give the user a specific message before the call reaches the
-module.
+The native contract rejects invalid values without clamping them. Validation in the app lets you give the user a specific message before the call reaches the module.
 
 ## Stop and clean up
 
@@ -699,14 +568,13 @@ synth.stopAll()
 synth.shutdown()
 ```
 
-`stopAll()` fades current voices but leaves pending pattern scheduling alone.
-`shutdown()` cancels the scheduler and releases the native stream.
+`stopAll()` stops all native sequences, fades current voices and invalidates effect histories. `shutdown()` also releases the native stream. To stop only one sequence owner, use `stopSequence({ sequenceId })`.
 
-The last committed interactive demo is in the upstream [`example/app.js`](https://github.com/macCesar/TiSynthEngine/blob/95901c98af5353b86d9dc7c60b29ab9186b038cd/example/app.js); that commit does not contain the pending statistics example. For additional retro effects, playable xylophone interaction, memory pads, layered polyphony and cancellable repetition, continue with [Curated sound and interaction recipes](recipes.md).
+Follow the [interactive demo setup and test checklist](../assets/example/README.md) to run [`example/app.js`](../assets/example/app.js). It includes headphone positioning, session selection, pattern completion/replacement and all three statistics methods. For a service-level statistics recipe, see [read engine statistics](guide.md#read-engine-statistics).
 
 ## Positioned headphone effect
 
-Check the installed coordinate limits and keep the engine running. This JavaScript places one generated noise effect above and to the right; it does not change other sound calls:
+With the engine running, check the installed coordinate limits. This example places one generated noise effect above and to the right. Other sound calls keep their existing placement:
 
 ```javascript
 if (!contract.limits.spatialX || !contract.limits.spatialY) {
@@ -725,3 +593,5 @@ if (!synth.playTone({
 ```
 
 For app switches, amplitude sliders, all nine screen positions and routing multiple effects through one service, use the [binaural integration guide](guide.md#integrate-binaural-in-a-2d-app). Omitting both coordinates disables binaural for that event; setting both to zero keeps it enabled at the front center.
+
+Continue with [advanced examples](advanced-examples.md).