@maccesar/titools 5.2.4 → 5.3.0

package/skills/ti-synthengine/assets/example/README.md

@@ -1,91 +1,88 @@
-> 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 `example/README.md` SHA-256: `7906f208b287d31ac400f407f4f3509b7a12041274a4629ab287eea235954518`.
+> Source snapshot: official TiSynthEngine documentation at commit `9d74aa45f84d3f2822d4aab76874efe37d81257f` (2026-11-03). Published module 2.0.0. Upstream `example/README.md` SHA-256: `db0f5921699859a1dd6918f215a4d30b008dd933cae458f21033216d7f807dd0`.
 
 # Interactive example
 
-The Classic Titanium app in [app.js](app.js) demonstrates the timed sounds, native sequences and statistics with the `sequenceend` event on Android and iOS. It runs with the published 1.0.2 module packages, including binaural and statistics support, or the unpublished local 1.1.0 candidates for native attack variation. Held voices, master processing and voice LFOs have copyable examples in the [advanced documentation](../../references/advanced-examples.md#sustained-game-motor); this reference app does not expose those newer controls. The default engine configuration is 16 voices, `conservative` mixing and the `playback` session; master volume starts at 100% and optional diagnostics start off.
+The Classic Titanium app in [app.js](app.js) demonstrates the Sound object API on Android and iOS. It requires TiSynth 2.0.0, reported by `getContract().version`. `getDefaults().version` reports the same installed module version.
+
+The default configuration is 16 voices, `conservative` mixing and the `playback` session. Master volume starts at 100% and optional diagnostics start off. Creating a Sound does not reserve a voice.
 
 ## Run it
 
-1. Create a Classic Titanium application with Android and/or iOS support. If the app uses Alloy, create a separate Classic test project and leave the Alloy-generated files in place.
-2. Download the official [Android 1.0.2](https://github.com/macCesar/TiSynthEngine/releases/tag/android-1.0.2) and [iOS 1.0.2](https://github.com/macCesar/TiSynthEngine/releases/tag/ios-1.0.2) packages, or build the current module source. Source builds now produce local `android/dist/ti.synthengine-android-1.1.0.zip` and `ios/dist/ti.synthengine-iphone-1.1.0.zip` candidates; select version `1.1.0` in both module entries when using them.
-3. Put the archive for each target platform in the test app root. For the published packages, add these entries inside its `tiapp.xml`:
+1. Create a Classic Titanium application with Android and/or iOS support. For Alloy projects, keep the example in a separate Classic test app so the Alloy-generated files remain intact.
+2. Build and install the current module source for the target platforms. Select the version declared by that build in `tiapp.xml`; rebuilding and reinstalling the test app is necessary after changing module packages.
+3. Copy the entire `example/` directory into the app's `Resources/`, including `app.js` and every file under `lib/`. No images or audio files are needed.
+4. Run with Titanium SDK 13.2.0.GA or newer, Android compile API 35 or newer, and iOS 15 or newer. See the [installation guide](../../references/guide.md#install-the-module).
 
-```xml
-<modules>
-  <module platform="android" version="1.0.2">ti.synthengine</module>
-  <module platform="iphone" version="1.0.2">ti.synthengine</module>
-</modules>
-```
+The example checks the Sound contract, spatial limits and enable/disable statistics methods before constructing the screen. Audio starts after layout settles. If startup fails, session buttons remain available to retry. Closing the window retires its pattern listener, clears startup/statistics timers, disables diagnostics and shuts down the engine.
 
-For the local candidates, replace both `version="1.0.2"` declarations above with `version="1.1.0"`. They still report public API `1.0.0`; detect variation through both capability/schema announcements. Rebuild and reinstall after switching packages.
+This example plays foreground finite sounds and patterns. Sustained notes, master processing and voice LFOs have separate examples in the [advanced documentation](../../references/advanced-examples.md#sustained-game-motor).
 
-4. Copy the entire `example/` folder into the test app's `Resources/`, including [app.js](app.js), [sequenceScore.js](lib/sequenceScore.js) and [sequenceOwner.js](lib/sequenceOwner.js). It needs no images or audio files.
-5. Build and run the test app with the Titanium CLI or your existing Titanium launch configuration. Use Titanium SDK 13.2.0.GA or newer, Android compile API 35 or newer, and iOS 15 or newer. See the [module installation guide](../../references/guide.md#install-the-module).
+## Synthesis and sequencing
 
-The example checks the installed API version, spatial limits and all three statistics methods before constructing the screen. If it requests current packages, replace the native module, then rebuild and reinstall the app; copying module files alone does not update an app already on a device.
+`createSound({ sound, playback })` separates synthesis properties from interpretation and timing. `lib/soundPreset.js` converts the example's editable recipes to this schema without playing audio. Finite sounds call `Sound.play()` and preserve their Boolean acceptance result. Chords declare `type: 'chord'`, including a chord containing just one note.
+
+## Native finite-tone repetition
+
+```js
+var synth = require('ti.synthengine')
+var shot = synth.createSound({
+  sound: { waveType: synth.getContract().waveTypes.SQUARE, attack: 2, release: 40, volume: 0.1 },
+  playback: { type: 'repeat', frequencies: [1380], frequencyEnd: 340, duration: 105, interval: 200 }
+})
+if (synth.start({ maxVoices: 16, mixingProfile: 'conservative' })) {
+  synth.setVolume(1)
+  var repetition = shot.play()
+  if (repetition) {
+    repetition.update({ interval: 150, volume: 0.08 })
+    // Later: repetition.stop()
+  }
+}
+```
 
-Audio starts after the first layout settles. Sound controls report native rejections. If startup fails, the session buttons remain available to retry. Closing the window removes its sequence listener, clears startup/statistics timers, disables diagnostics and shuts down the engine. The example plays finite sounds in the foreground and does not demonstrate background audio. Turn diagnostics off before leaving it in the background.
+Finite `duration` includes release; envelope times and repetition `interval` are milliseconds. Per-call overrides do not change the Sound definition. Repetition controls keep private execution identity. An update preserves the next deadline and changes subsequent attacks; stopping cancels future attacks while admitted shots finish. There is no JavaScript attack timer. Close, session changes and STOP ALL also release or invalidate repetition ownership.
 
-## Synthesis and sequencing
+The screen retains its waveform, English/solfege pitch, stereo motion, vibrato, variable-rate noise, pulse-width, wavetable, quantization, chord, arpeggio, tempo/swing, percussion, decay/sustain, filter, FM and detune demonstrations. Master BOOST intentionally raises the bus above unity; 100% restores unity. Repeated taps can overlap voices and cause limiting or replacement.
 
-- Compare all six waveforms and equivalent English/solfege note names.
-- Try stereo pan, pitch sweep, vibrato, variable-rate noise, pulse width, custom wavetable and quantization.
-- Compare atomic chords with explicit pans, matched arpeggios, tempo/swing and noise percussion.
-- Hear decay/sustain, resonant filtering, FM bell/electric piano and detuned voices.
+## Native attack variation
 
-Keep system volume moderate while comparing sounds. Master BOOST intentionally raises the bus above unity; use the 100% control to restore it. Repeated taps overlap events and may cause limiting or voice replacement.
+ATTACK VARIATION retains its metal-strike recipe. When both `capabilities.variation === true` and `variationSchemaVersion === 1` are announced, the renderer chooses pitch, FM depth and level once per admitted attack. Otherwise the recipe omits variation. See the [variation guide](../../references/native-variation.md).
 
-## Headphone positioning
+## Sequence completion and cancellation
 
-Use stereo headphones. In the binaural section, compare each of the nine noise positions one at a time: left/right runs from -1 to 1, above/below from 1 to -1. The center still uses binaural processing. Elevation perception varies with the listener and headphones, so the controls cannot guarantee localization for each person.
+`lib/sequenceScore.js` compiles note-name scores to millisecond onsets and explicit release onsets. `soundPreset.js` maps step spacing to `playback.interval` or `steps[].interval`, keeps `length`, and places synthesis in `sound` or `steps[].sound`. The native sample clock schedules every attack.
 
-Select STEREO MODE and repeat points with the same horizontal position. Their height no longer affects placement because both spatial keys are omitted. BINAURAL MODE restores per-event coordinates. These two modes affect this section only; the ordinary stereo demos remain unchanged. An active voice keeps its original position.
+`lib/sequenceOwner.js` retains the pattern control returned by `Sound.play()`. Tap PATTERN END once to see `end: completed`. Tap repeatedly to request a stop, coalesce pending scores and publish only the newest complete score after the matching control emits `end`. Its callback receives `{ reason: 'completed' | 'stopped' }`, without native IDs. Late events from retired controls cannot change application ownership.
 
-SPATIAL CHORD places the whole chord above/right. SPATIAL PATTERN places three broadband hits above/left, below/center and above/right using per-step coordinates. Neither sends stereo pan fields while binaural is active. The output remains two channels on a front plane, without rear positioning, distance attenuation or head tracking. See the [app integration guide](../../references/guide.md#integrate-binaural-in-a-2d-app) for source mapping and amplitude sliders.
+A completed pattern can leave audible releases or shared effect tails. STOP ALL cancels future attacks and fades active voices. Changing sessions or closing the example shuts down its engine and cancels pending application publication.
 
-## Audio session
+## Headphone positioning
 
-On iOS, compare PLAYBACK SESSION and AMBIENT SESSION. Changing the selection shuts down the engine, silently cancels any pending pattern, starts the new policy and restores the selected master volume. It does not resume the previous sound. The policy is fixed while the stream runs; a second `start()` alone cannot change it.
+Use stereo headphones to compare the nine noise positions individually. Horizontal coordinates run from -1 to 1; vertical coordinates run from 1 above to -1 below. Center still uses binaural processing. Elevation perception varies by listener and headphones.
 
-On an iOS device, play music from another app and try a short sound in ambient mode; compare with playback. Also compare the device's silent mode where available. Ambient should respect silent mode and mix with other apps; playback ignores silent mode and normally interrupts their audio. Android validates both strings but does not change its output. Simulator behavior does not establish the physical silent-mode, interruption or route behavior.
+STEREO MODE omits both spatial coordinates and uses horizontal pan alone. BINAURAL MODE restores coordinates for new events; an active voice retains its original position. These modes affect only this section. SPATIAL CHORD places a whole chord above/right, and SPATIAL PATTERN places three broadband hits using per-step coordinates. Binaural events omit stereo pan fields.
 
-## Sequence completion and cancellation
+Output remains two channels on a front plane, without rear positioning, distance attenuation or head tracking. See the [integration guide](../../references/guide.md#integrate-binaural-in-a-2d-app).
 
-1. Tap PATTERN END and wait for `sequenceend: completed`.
-2. Tap it twice quickly. The example requests stop for its accepted sequence, coalesces repeated taps to the latest complete score, and publishes it only after the matching retirement event frees capacity. Native `sequenceend` events report `{ sequenceId, reason: 'completed' | 'stopped' }`.
-3. Selecting a session shuts down the engine and restarts it with the selected policy. Events already queued for JavaScript can still arrive.
-4. STOP ALL releases active voices and cancels future attacks. Closing the example shuts down its engine.
+## Audio session
 
-All successive attacks run on the native sample clock. The example compiles its note-name scores to millisecond sequences with explicit `duration` and `length`, preserving the original interval and release onset. Each sequence has one of `frequencies`, MIDI `notes`, or `rest: true` per step, with sound shaping in `voice`/`overrides`. Copy the entire `example/` folder, including `lib/sequenceScore.js` and `lib/sequenceOwner.js`, into a Classic app's Resources folder.
+PLAYBACK SESSION and AMBIENT SESSION shut down the existing stream, cancel pending patterns, start the selected policy and restore master volume. They do not resume old sounds; a second `start()` alone cannot change a running session's policy.
 
-Completion marks the final scheduled step; releases and shared effect tails can remain audible. See the [event contract](../../references/api.md#sequenceend-event).
+On physical iOS hardware, compare another app's music, silent mode and an output-route change. Ambient respects silent mode and mixes with other apps; playback ignores silent mode and normally interrupts them. Android accepts both strings without changing its output. Simulator results do not establish physical interruption or route behavior.
 
 ## Statistics
 
-- READ STATS takes a fresh snapshot without resetting counters or enabling diagnostics.
-- TOGGLE DIAGNOSTICS enables callback timing and signal meters, refreshing at 5 Hz. Toggle it off to stop the timer and optional measurements; basic counters remain available.
-- RESET STATS clears accumulated statistics without stopping voices, cancelling queued work or changing the diagnostic switch. The next callback applies render-owned resets.
-
-The panel shows active/peak/spatial/tail voices, pending commands, replacements, request/publication rejections, priority drops, callback load, stereo output peak and backend underruns. It displays `n/a` for unmeasured or unavailable values, keeping them distinct from zero. Signal windows need about 200 ms of output after enabling. Native snapshots also include RMS, limiter reduction, sample rate, buffer and latency fields; consult the [complete field reference](../../references/api.md#getstats) when integrating a full diagnostic view.
-
-Render load divides callback elapsed time by the audio budget for that block; it does not measure total app CPU. The panel multiplies the native fraction by 100, so a reading of 1.20% means that fraction of the block budget, not 120%.
+READ STATS takes a snapshot without resetting counters or enabling diagnostics. TOGGLE DIAGNOSTICS enables callback timing and signal meters, refreshing at 5 Hz; disabling it stops the timer and optional measurements while retaining basic counters. RESET STATS clears accumulated statistics without stopping voices or cancelling scheduled work.
 
-The shared final output stage retains zero samples. Master volume changes use a linear 10 ms ramp; overload can audibly change the mix. Even with zero voices, the stream renders silent blocks and runs output protection and any enabled diagnostics. Expect a small, changing baseline. The two decimal places are display formatting and do not guarantee that precision.
+The panel shows active/peak/spatial/tail voices, pending commands, replacements, request/publication rejections, priority drops, callback load, stereo peak and backend underruns. Unavailable measurements remain `n/a`, distinct from zero. Signal windows need about 200 ms after enabling diagnostics. See the [field reference](../../references/api.md#getstats).
 
-Compare readings on the same device with the same configuration and load; simulator and phone readings are not equivalent. Android backend metrics are best-effort. This iOS backend has no underrun/buffer/latency measurement, and a clean counter cannot establish sound quality.
+Render load is callback elapsed time divided by the budget for that block. It is not total app CPU. The stream continues rendering silence with zero voices. Compare measurements on the same device, route, configuration and load; a clean counter does not establish audio quality. Turn diagnostics off before leaving this foreground example in the background.
 
 ## Checks and limits
 
-Run these focused checks from the module repository root:
+From the module repository root:
 
 ```sh
-node tests/documentation_regression.js
-node --test tests/example_app_regression.js
+node --test tests/example_app_regression.js tests/sequence_owner_regression.js
 ```
 
-The example regression executes its real action callbacks with simulated Titanium UI/audio boundaries. It covers rejection feedback, placement/bypass, session restart and gain preservation, diagnostic cleanup and close-before-start. It does not render native audio or establish layout, perceived elevation, silent-mode behavior or sound quality. Use the device checklist above, including headphones and an output-route change, before claiming those results.
-
-
-## Native attack variation
-
-The **ATTACK VARIATION** button submits the same metal-strike recipe on each press. With `capabilities.variation === true` and `variationSchemaVersion === 1`, the renderer chooses pitch, FM depth and level once per admitted attack. Older packages receive the original recipe without the dictionary. This button uses independent timed events; the [variation guide](../../references/native-variation.md) separately demonstrates sustained ownership and native sequence retriggers. Physical listening acceptance remains separate from host correctness checks.
+These checks execute the real interactive callbacks and the current public adapter over native payload spies. They cover preserved synthesis parameters, rejection feedback, spatial bypass, repeated finite shots, session/gain restoration, diagnostics, native retirement coalescing, active updates, late events and close-before-start. Native validator replay and platform listening acceptance remain separate. Host checks do not establish layout, perceived elevation, silent-mode behavior or sound quality.

package/skills/ti-synthengine/assets/example/app.js

@@ -1,20 +1,23 @@
+var SoundPreset = require('lib/soundPreset')
 var sequenceScore = require('lib/sequenceScore')
 var Synth = require('ti.synthengine')
 
 var sequenceOwner = require('lib/sequenceOwner')(Synth, {
-  rejected: function() { setStatus('Request rejected · sequence publication', COLORS.red) }
+  rejected: function() { setStatus('Request rejected · sequence publication', COLORS.red) },
+  ended: onSequenceEnd
 })
 function publishSequence(options) { return sequenceOwner.submit(options) }
 
-var defaults = Synth.getDefaults()
-if (!defaults || defaults.apiVersion !== '1.0.0') {
-  throw new Error('TiSynthEngine 1.0.0 is required')
+var defaults = Synth.getContract()
+if (!defaults || defaults.version !== '2.0.0') {
+  throw new Error('TiSynthEngine 2.0.0 is required')
 }
 
 if (!defaults.limits || !defaults.limits.spatialX || !defaults.limits.spatialY
   || typeof Synth.getStats !== 'function' || typeof Synth.resetStats !== 'function'
-  || typeof Synth.setStatsEnabled !== 'function') {
-  throw new Error('Install the current TiSynthEngine 1.0.0 packages, then rebuild and reinstall this app')
+  || typeof Synth.enableStats !== 'function' || typeof Synth.disableStats !== 'function'
+  || typeof Synth.createSound !== 'function') {
+  throw new Error('Install the current TiSynthEngine Sound API packages, then rebuild and reinstall this app')
 }
 
 var WAVE = defaults.waveTypes
@@ -23,6 +26,11 @@ var engineRunning = false
 var startTimer = null
 var statsTimer = null
 var diagnosticsEnabled = false
+var repeatingTone = null
+var repeatingSound = Synth.createSound({
+  sound: { attack: 2, release: 40, waveType: WAVE.SQUARE, volume: 0.1 },
+  playback: { type: 'repeat', frequencies: [1380], frequencyEnd: 340, duration: 105, interval: 200 }
+})
 var selectedSession = 'playback'
 var masterVolume = 1
 var binauralEnabled = true
@@ -200,7 +208,7 @@ function makeHero() {
     height: Ti.UI.SIZE,
     top: dp(16)
   })
-  badgeRow.add(makeBadge('API 1.0.0', COLORS.indigo))
+  badgeRow.add(makeBadge('API 2.0.0', COLORS.indigo))
   badgeRow.add(makeBadge('ANDROID + iOS', COLORS.surfaceMuted))
   hero.add(badgeRow)
   hero.add(statusPill)
@@ -325,14 +333,14 @@ function makeCompactAction(options) {
 }
 
 function playMatchedSine(note) {
-  return Synth.playTone({
+  return Synth.createSound(SoundPreset.fromRecipe('tone', {
     note: note,
     duration: 600,
     attack: 10,
     release: 80,
     volume: 0.7,
     waveType: WAVE.SINE
-  })
+  })).play()
 }
 
 function playMatchedArpeggio(pitchKey, pitches) {
@@ -392,13 +400,45 @@ waveNames.forEach(function (name, index) {
         waveType: waveTypes[index]
       }
       if (waveTypes[index] === WAVE.WAVETABLE) options.waveTable = STEPPED_WAVE
-      return Synth.playTone(options)
+      return Synth.createSound(SoundPreset.fromRecipe('tone', options)).play()
     }
   }))
 })
 waveSection.add(Ti.UI.createView({ height: dp(12) }))
 scrollView.add(waveSection)
 
+// A repeated finite recipe retains its own control; there is no attack timer.
+function stopRepeatingTone() {
+  if (!repeatingTone) return true
+  if (!repeatingTone.stop()) return false
+  repeatingTone = null
+  return true
+}
+var repeatSection = makeSection('Finite-tone repetition',
+  'The same complete 105 ms shot repeats every 200 ms. Edit its future attacks; stop lets current shots finish.',
+  COLORS.teal)
+repeatSection.add(makeAction({
+  title: 'START REPEATING', color: COLORS.teal, pressedColor: COLORS.tealPressed,
+  onPress: function () {
+    if (repeatingTone) return true
+    var control = repeatingSound.play()
+    if (!control) return false
+    repeatingTone = control
+    return true
+  }
+}))
+repeatSection.add(makeAction({
+  title: 'EDIT REPEATING', color: COLORS.teal, pressedColor: COLORS.tealPressed,
+  onPress: function () {
+    return !!repeatingTone && repeatingTone.update({ interval: 150, volume: 0.08 })
+  }
+}))
+repeatSection.add(makeAction({
+  title: 'STOP REPEATING', color: COLORS.surfaceMuted, pressedColor: COLORS.surfaceRaised,
+  onPress: stopRepeatingTone
+}))
+scrollView.add(repeatSection)
+
 // ---------------------------------------------------------------------------
 // 2. Note names
 // ---------------------------------------------------------------------------
@@ -452,7 +492,7 @@ motionSection.add(makeAction({
   pressedColor: COLORS.tealPressed,
   status: 'Pan sweep · left to right',
   onPress: function () {
-    return Synth.playTone({
+    return Synth.createSound(SoundPreset.fromRecipe('tone', {
       frequency: 440,
       duration: 2000,
       attack: 20,
@@ -460,7 +500,7 @@ motionSection.add(makeAction({
       volume: 0.8,
       pan: -1.0,
       panEnd: 1.0
-    })
+    })).play()
   }
 }))
 motionSection.add(makeAction({
@@ -469,7 +509,7 @@ motionSection.add(makeAction({
   pressedColor: COLORS.pinkPressed,
   status: 'Pitch sweep · 200 to 900 Hz',
   onPress: function () {
-    return Synth.playTone({
+    return Synth.createSound(SoundPreset.fromRecipe('tone', {
       frequency: 200,
       frequencyEnd: 900,
       duration: 400,
@@ -477,7 +517,7 @@ motionSection.add(makeAction({
       release: 40,
       volume: 0.7,
       waveType: WAVE.SAWTOOTH
-    })
+    })).play()
   }
 }))
 motionSection.add(makeAction({
@@ -486,7 +526,7 @@ motionSection.add(makeAction({
   pressedColor: COLORS.orangePressed,
   status: 'LFO vibrato · 5 Hz',
   onPress: function () {
-    return Synth.playTone({
+    return Synth.createSound(SoundPreset.fromRecipe('tone', {
       frequency: 440,
       duration: 2000,
       attack: 20,
@@ -494,7 +534,7 @@ motionSection.add(makeAction({
       volume: 0.7,
       lfoFreq: 5,
       lfoDepth: 30
-    })
+    })).play()
   }
 }))
 motionSection.add(Ti.UI.createView({ height: dp(16) }))
@@ -515,7 +555,7 @@ retroSection.add(makeAction({
   pressedColor: COLORS.brownPressed,
   status: 'Filtered sample-and-hold noise sweep',
   onPress: function () {
-    return Synth.playTone({
+    return Synth.createSound(SoundPreset.fromRecipe('tone', {
       frequency: 120,
       duration: 760,
       attack: 1,
@@ -526,7 +566,7 @@ retroSection.add(makeAction({
       noiseRateEnd: 650,
       lowPassHz: 2500,
       bitDepth: 8
-    })
+    })).play()
   }
 }))
 retroSection.add(makeAction({
@@ -535,7 +575,7 @@ retroSection.add(makeAction({
   pressedColor: COLORS.orangePressed,
   status: 'Square pulse-width sweep',
   onPress: function () {
-    return Synth.playTone({
+    return Synth.createSound(SoundPreset.fromRecipe('tone', {
       note: 'A3',
       duration: 700,
       attack: 3,
@@ -544,7 +584,7 @@ retroSection.add(makeAction({
       waveType: WAVE.SQUARE,
       pulseWidth: 0.1,
       pulseWidthEnd: 0.86
-    })
+    })).play()
   }
 }))
 retroSection.add(makeAction({
@@ -553,7 +593,7 @@ retroSection.add(makeAction({
   pressedColor: COLORS.tealPressed,
   status: 'Custom stepped wavetable',
   onPress: function () {
-    return Synth.playTone({
+    return Synth.createSound(SoundPreset.fromRecipe('tone', {
       note: 'D4',
       duration: 680,
       attack: 4,
@@ -562,7 +602,7 @@ retroSection.add(makeAction({
       waveType: WAVE.WAVETABLE,
       waveTable: STEPPED_WAVE,
       bitDepth: 8
-    })
+    })).play()
   }
 }))
 retroSection.add(makeAction({
@@ -622,14 +662,14 @@ harmonySection.add(makeAction({
   pressedColor: COLORS.blue,
   status: 'C major triad · sine',
   onPress: function () {
-    return Synth.playChord({
+    return Synth.createSound(SoundPreset.fromRecipe('chord', {
       frequencies: [261.63, 329.63, 392.0],
       duration: 1200,
       attack: 20,
       release: 300,
       volume: 0.7,
       panSpread: 0.8
-    })
+    })).play()
   }
 }))
 harmonySection.add(makeAction({
@@ -638,7 +678,7 @@ harmonySection.add(makeAction({
   pressedColor: COLORS.indigoPressed,
   status: 'C major chord · square and wide',
   onPress: function () {
-    return Synth.playChord({
+    return Synth.createSound(SoundPreset.fromRecipe('chord', {
       notes: ['C4', 'E4', 'G4', 'C5'],
       duration: 1000,
       attack: 10,
@@ -646,7 +686,7 @@ harmonySection.add(makeAction({
       volume: 0.6,
       waveType: WAVE.SQUARE,
       pans: [-0.9, -0.3, 0.3, 0.9]
-    })
+    })).play()
   }
 }))
 harmonySection.add(Ti.UI.createView({ height: dp(16) }))
@@ -740,7 +780,7 @@ expressiveSection.add(makeAction({
   pressedColor: COLORS.greenPressed,
   status: 'Pluck · decay and sustain',
   onPress: function () {
-    return Synth.playTone({
+    return Synth.createSound(SoundPreset.fromRecipe('tone', {
       note: 'E4',
       duration: 900,
       attack: 2,
@@ -749,7 +789,7 @@ expressiveSection.add(makeAction({
       release: 380,
       volume: 0.6,
       waveType: WAVE.TRIANGLE
-    })
+    })).play()
   }
 }))
 expressiveSection.add(makeAction({
@@ -758,7 +798,7 @@ expressiveSection.add(makeAction({
   pressedColor: COLORS.orangePressed,
   status: 'Wah · band-pass cutoff sweep',
   onPress: function () {
-    return Synth.playTone({
+    return Synth.createSound(SoundPreset.fromRecipe('tone', {
       note: 'A2',
       duration: 1000,
       attack: 10,
@@ -769,7 +809,7 @@ expressiveSection.add(makeAction({
       filterHz: 350,
       filterHzEnd: 2400,
       filterQ: 5
-    })
+    })).play()
   }
 }))
 expressiveSection.add(makeAction({
@@ -778,7 +818,7 @@ expressiveSection.add(makeAction({
   pressedColor: COLORS.indigoPressed,
   status: 'Bell · FM index decays',
   onPress: function () {
-    return Synth.playTone({
+    return Synth.createSound(SoundPreset.fromRecipe('tone', {
       note: 'C5',
       duration: 2600,
       attack: 1,
@@ -790,7 +830,7 @@ expressiveSection.add(makeAction({
       fmRatio: 3.5,
       fmDepth: 4,
       fmDepthEnd: 0
-    })
+    })).play()
   }
 }))
 expressiveSection.add(makeAction({
@@ -799,7 +839,7 @@ expressiveSection.add(makeAction({
   pressedColor: COLORS.blue,
   status: 'Electric piano · FM index mellows',
   onPress: function () {
-    return Synth.playTone({
+    return Synth.createSound(SoundPreset.fromRecipe('tone', {
       note: 'E3',
       duration: 1800,
       attack: 3,
@@ -811,7 +851,7 @@ expressiveSection.add(makeAction({
       fmRatio: 1,
       fmDepth: 2.2,
       fmDepthEnd: 0.25
-    })
+    })).play()
   }
 }))
 expressiveSection.add(makeAction({
@@ -820,7 +860,7 @@ expressiveSection.add(makeAction({
   pressedColor: COLORS.pinkPressed,
   status: 'Thick chord · detuned voices',
   onPress: function () {
-    return Synth.playChord({
+    return Synth.createSound(SoundPreset.fromRecipe('chord', {
       notes: ['A3', 'E4', 'A3', 'E4', 'A3', 'E4'],
       detunes: [-9, -9, 0, 0, 9, 9],
       duration: 3200,
@@ -831,7 +871,7 @@ expressiveSection.add(makeAction({
       filterType: 'lowpass',
       filterHz: 1500,
       panSpread: 0.8
-    })
+    })).play()
   }
 }))
 
@@ -851,11 +891,11 @@ expressiveSection.add(makeAction({
         volume: [0.291, 0.3], fmDepth: [2.944, 3.456], pitchCents: [-12, 12]
       } }
     }
-    return Synth.playTone(options)
+    return Synth.createSound(SoundPreset.fromRecipe('tone', options)).play()
   }
 }))
 
-var patternEndLabel = makeText('sequenceend: no pattern yet', {
+var patternEndLabel = makeText('end: no pattern yet', {
   top: dp(8),
   left: dp(16),
   right: dp(16),
@@ -865,21 +905,20 @@ var patternEndLabel = makeText('sequenceend: no pattern yet', {
 
 function onSequenceEnd(event) {
   patternEndLabel.text = event.reason === 'completed'
-    ? 'sequenceend: completed'
-    : 'sequenceend: stopped'
+    ? 'end: completed'
+    : 'end: stopped'
   setStatus(patternEndLabel.text, event.reason === 'completed' ? COLORS.green : COLORS.yellow)
 }
 
-Synth.addEventListener('sequenceend', onSequenceEnd)
 
 expressiveSection.add(makeAction({
   title: 'PATTERN END\nTap once to finish; tap again quickly to replace',
   color: COLORS.yellow,
   pressedColor: COLORS.yellowPressed,
   textColor: COLORS.canvas,
-  status: 'Pattern running · waiting for sequenceend',
+  status: 'Pattern running · waiting for end',
   onPress: function () {
-    patternEndLabel.text = 'sequenceend: pattern running'
+    patternEndLabel.text = 'end: pattern running'
     return publishSequence(sequenceScore({
       bpm: 132,
       noteValue: '8n',
@@ -948,10 +987,10 @@ spatialPoints.forEach(function (point, index) {
     title: point[0] + '\nNoise burst',
     fontSize: 11, color: COLORS.teal, pressedColor: COLORS.tealPressed,
     onPress: function () {
-      return Synth.playTone(Object.assign({
+      return Synth.createSound(SoundPreset.fromRecipe('tone', Object.assign({
         frequency: 200, waveType: WAVE.NOISE, duration: 550,
         attack: 5, release: 200, volume: 0.3
-      }, placement(point[1], point[2])))
+      }, placement(point[1], point[2])))).play()
     }
   }))
 })
@@ -960,10 +999,10 @@ spatialSection.add(makeAction({
   color: COLORS.blueDark, pressedColor: COLORS.blue,
   onPress: function () {
     var position = binauralEnabled ? { spatialX: 0.7, spatialY: 1 } : { panSpread: 0, pans: [0.7, 0.7, 0.7] }
-    return Synth.playChord(Object.assign({
+    return Synth.createSound(SoundPreset.fromRecipe('chord', Object.assign({
       notes: ['C4', 'E4', 'G4'], duration: 1200, attack: 15, release: 300,
       volume: 0.4, waveType: WAVE.SAWTOOTH
-    }, position))
+    }, position))).play()
   }
 }))
 spatialSection.add(makeAction({
@@ -999,10 +1038,10 @@ var sessionLabel = makeText('Session: playback', { left: dp(16), right: dp(16),
     color: COLORS.blueDark, pressedColor: COLORS.blue,
     accessibilityHint: 'Restarts the engine with this session policy',
     onPress: function () {
-      sequenceOwner.reset(); Synth.shutdown()
+      repeatingTone = null; sequenceOwner.reset(); Synth.shutdown()
       engineRunning = false
       selectedSession = session
-      patternEndLabel.text = 'sequenceend: cancelled by shutdown (no event)'
+      patternEndLabel.text = 'end: cancelled by shutdown (no event)'
       return startAppCycles()
     }
   }))
@@ -1046,7 +1085,7 @@ statsSection.add(makeAction({
   title: 'TOGGLE DIAGNOSTICS', color: COLORS.orange, pressedColor: COLORS.orangePressed,
   accessibilityHint: 'Enables or disables timing and signal measurements',
   onPress: function () {
-    if (!Synth.setStatsEnabled(!diagnosticsEnabled)) return false
+    if (!(diagnosticsEnabled ? Synth.disableStats() : Synth.enableStats())) return false
     diagnosticsEnabled = !diagnosticsEnabled
     stopStatsPolling()
     if (diagnosticsEnabled) statsTimer = setInterval(refreshStats, 200)
@@ -1103,10 +1142,10 @@ boostRow.add(makeGridAction({
   title: 'STOP ALL\nRelease active voices',
   color: COLORS.redDark,
   pressedColor: COLORS.red,
-  status: 'Active voices fading; pending pattern steps remain',
-  accessibilityHint: 'Fades current voices without cancelling future pattern steps',
+  status: 'Future attacks cancelled; active voices fading',
+  accessibilityHint: 'Cancels future attacks and fades current voices',
   onPress: function () {
-    sequenceOwner.stop(); Synth.stopAll()
+    repeatingTone = null; sequenceOwner.stop(); Synth.stopAll()
   }
 }))
 controlSection.add(boostRow)
@@ -1128,7 +1167,7 @@ win.add(scrollView)
 // ---------------------------------------------------------------------------
 
 function setMasterVolume(volume) {
-  if (!Synth.setVolume({ volume: volume })) return false
+  if (!Synth.setVolume(volume)) return false
   masterVolume = volume
   return true
 }
@@ -1170,10 +1209,10 @@ function hideAndroidActionBar() {
 }
 
 function cleanup() {
+  if (!stopRepeatingTone()) Ti.API.warn('Repeating tone stop rejected; shutting down owner')
   stopStatsPolling()
-  Synth.setStatsEnabled(false)
+  Synth.disableStats()
   diagnosticsEnabled = false
-  Synth.removeEventListener('sequenceend', onSequenceEnd)
   win.removeEventListener('postlayout', onFirstPostLayout)
   win.removeEventListener('open', hideAndroidActionBar)
   win.removeEventListener('focus', hideAndroidActionBar)
@@ -1184,7 +1223,7 @@ function cleanup() {
     startTimer = null
   }
   if (engineRunning) {
-    sequenceOwner.reset(); Synth.shutdown()
+    repeatingTone = null; sequenceOwner.reset(); Synth.shutdown()
     engineRunning = false
   }
 }