@maccesar/titools 5.2.4 → 5.3.0

package/skills/ti-synthengine/assets/example/lib/sequenceOwner.js

@@ -1,15 +1,8 @@
-// One application owner, with latest-request coalescing across native retirement.
-// A stop is accepted before its slot becomes reusable. Only sequenceend permits
-// the next complete publication; JavaScript never schedules individual notes.
+// Wait for native retirement before publishing the latest requested pattern.
+var SoundPreset = require('./soundPreset')
 module.exports = function createSequenceOwner(synth, options) {
   options = options || {}
-  var current = 0, pending = null, stopping = false, listening = false
-  function listen() {
-    if (!listening) {
-      synth.addEventListener('sequenceend', ended)
-      listening = true
-    }
-  }
+  var current = null, pending = null, stopping = false, recipe = null, listener = null
   function rejected(method, payload) {
     if (options.rejected) options.rejected(method, payload)
     return false
@@ -18,32 +11,40 @@ module.exports = function createSequenceOwner(synth, options) {
     if (!pending) return true
     var payload = pending
     pending = null
-    var id = synth.playSequence(payload)
-    if (!Number.isInteger(id) || id <= 0) return rejected('playSequence', payload)
-    current = id
-    if (options.published) options.published(id, payload)
+    var control = synth.createSound(SoundPreset.fromRecipe('pattern', payload)).play()
+    if (!control) return rejected('playSequence', payload)
+    current = control
+    recipe = payload
+    listener = function(event) {
+      if (current !== control) return
+      control.removeEventListener('end', listener)
+      current = null
+      listener = null
+      stopping = false
+      if (pending) publish()
+      if (options.ended) options.ended(event)
+    }
+    control.addEventListener('end', listener)
+    if (options.published) options.published(control, payload)
     return true
   }
-  function ended(event) {
-    if (event.sequenceId !== current) return
-    current = 0
-    stopping = false
-    if (pending) publish()
-    if (options.ended) options.ended(event)
-  }
   function requestStop() {
     if (!current || stopping) return true
     stopping = true
-    if (synth.stopSequence({ sequenceId: current })) return true
-    // A naturally retired ID can already have its completion queued for JS.
-    // Its slot still needs event draining before a replacement publication.
-    if (synth.getSequenceState({ sequenceId: current }) === null) return true
+    if (current.stop()) return true
+    // An ended pattern can have its completion queued for JavaScript.
+    if (current.getState() === null) return true
     stopping = false
-    return rejected('stopSequence', { sequenceId: current })
+    return rejected('stopSequence', {})
+  }
+  function merged(previous, changes) {
+    var voice = changes.voice ? Object.assign({}, previous.voice || {}, changes.voice) : previous.voice
+    var next = Object.assign({}, previous, changes)
+    if (voice) next.voice = voice
+    return next
   }
   return {
     submit: function(payload) {
-      listen()
       pending = payload
       if (!current) return publish()
       if (!requestStop()) {
@@ -54,28 +55,26 @@ module.exports = function createSequenceOwner(synth, options) {
     },
     update: function(changes) {
       if (pending) {
-        if (changes.steps !== undefined) {
-          pending = changes
-          return true
-        }
-        var voice = changes.voice ? Object.assign({}, pending.voice || {}, changes.voice) : pending.voice
-        pending = Object.assign({}, pending, changes)
-        if (voice) pending.voice = voice
+        pending = changes.steps !== undefined ? changes : merged(pending, changes)
         return true
       }
       if (!current || stopping) return false
-      return synth.updateSequence(Object.assign({ sequenceId: current }, changes))
+      var next = merged(recipe, changes)
+      var preset = SoundPreset.fromRecipe('pattern', next)
+      if (!current.update(Object.assign({}, preset.sound, preset.playback))) return false
+      recipe = next
+      return true
     },
     stop: function() { pending = null; return requestStop() },
     reset: function() {
       pending = null
-      current = 0
+      if (current && listener) current.removeEventListener('end', listener)
+      current = null
+      listener = null
+      recipe = null
       stopping = false
-      if (listening) {
-        synth.removeEventListener('sequenceend', ended)
-        listening = false
-      }
     },
+    getState: function() { return current ? current.getState() : null },
     id: function() { return current },
     pending: function() { return pending !== null },
     stopping: function() { return stopping }

package/skills/ti-synthengine/assets/example/lib/soundPreset.js

@@ -0,0 +1,34 @@
+// Convert an editable recipe to a Sound definition; this module never plays audio.
+exports.fromRecipe = function(type, recipe) {
+  var source = JSON.parse(JSON.stringify(recipe || {}))
+  var sound = type === 'pattern' ? source.voice || {} : {}
+  var playback = { type: type }
+  if (type === 'pattern') {
+    ;['timeUnit', 'gate', 'loop', 'swing', 'mode', 'tuning'].forEach(function(key) {
+      if (source[key] !== undefined) playback[key] = source[key]
+    })
+    if (sound.frequencyEnd !== undefined) {
+      playback.frequencyEnd = sound.frequencyEnd
+      delete sound.frequencyEnd
+    }
+    if (source.detune !== undefined) sound.detune = source.detune
+    if (source.stepDuration !== undefined) playback.interval = source.stepDuration
+    playback.steps = (source.steps || []).map(function(step) {
+      var result = {}
+      ;['notes', 'frequencies', 'rest', 'length', 'gate'].forEach(function(key) {
+        if (step[key] !== undefined) result[key] = step[key]
+      })
+      if (step.duration !== undefined) result.interval = step.duration
+      if (step.overrides !== undefined) result.sound = step.overrides
+      return result
+    })
+  } else {
+    Object.keys(source).forEach(function(key) {
+      if (key === 'note') playback.notes = [source[key]]
+      else if (key === 'frequency') playback.frequencies = [source[key]]
+      else if (['notes', 'frequencies', 'frequencyEnd', 'duration'].indexOf(key) >= 0) playback[key] = source[key]
+      else sound[key] = source[key]
+    })
+  }
+  return { sound: sound, playback: playback }
+}

package/skills/ti-synthengine/assets/index.d.ts

@@ -0,0 +1,226 @@
+/** TiSynthEngine 2.0.0 candidate. One module version for the entire public interface. */
+declare namespace synth {
+  type Bus = 'music' | 'effects' | 'ui' | 'ambience';
+  type FilterType = 'none' | 'lowpass' | 'highpass' | 'bandpass';
+  type Range = [number, number];
+  interface Variation {
+    amount?: number;
+    seed?: number;
+    ranges?: Partial<Record<'volume' | 'filterHz' | 'filterQ' | 'fmDepth' |
+      'noiseRate' | 'lowPassHz' | 'pulseWidth' | 'pitchCents', Range>>;
+  }
+  interface VoiceOptions {
+    attack?: number; decay?: number; sustain?: number; release?: number;
+    volume?: number; waveType?: number; pan?: number;
+    lfoFreq?: number; lfoDepth?: number; noiseRate?: number; lowPassHz?: number;
+    pulseWidth?: number; waveTable?: number[]; bitDepth?: number;
+    filterType?: FilterType; filterHz?: number; filterQ?: number;
+    fmRatio?: number; fmDepth?: number; spatialX?: number; spatialY?: number;
+    bus?: Bus; effectSend?: number; priority?: number; variation?: Variation;
+  }
+  type Pitch = { note?: string; frequency?: never } | { frequency?: number; note?: never };
+  interface FiniteOptions extends VoiceOptions {
+    duration?: number; panEnd?: number; frequencyEnd?: number;
+    noiseRateEnd?: number; pulseWidthEnd?: number; filterHzEnd?: number;
+    fmDepthEnd?: number; detune?: number;
+  }
+  type ToneOptions = FiniteOptions & Pitch;
+  type RepeatingToneOptions = ToneOptions & { intervalMs: number };
+  /** Partial changes merge with the latest accepted recipe; never retriggers immediately. */
+  type ToneUpdate = Partial<FiniteOptions> & Pitch & { toneId: number; intervalMs?: number };
+  interface Modulation {
+    target: 'filterHz' | 'pulseWidth' | 'fmDepth';
+    wave?: 'sine' | 'triangle'; rate?: number; sync?: string; depth?: number;
+  }
+  type NoteOptions = VoiceOptions & Pitch & { voiceId: number; detune?: number; modulations?: Modulation[] };
+  type NoteUpdate = Pick<VoiceOptions, 'volume' | 'pan' | 'lfoFreq' | 'lfoDepth' |
+    'noiseRate' | 'lowPassHz' | 'pulseWidth' | 'filterHz' | 'filterQ' |
+    'fmRatio' | 'fmDepth' | 'spatialX' | 'spatialY' | 'effectSend'> & Pitch &
+    { voiceId: number; modulations?: Modulation[] };
+  type ChordOptions = VoiceOptions & { duration?: number; detune?: number;
+    detunes?: number[]; pans?: number[]; panSpread?: number } &
+    ({ notes: string[]; frequencies?: never } | { frequencies: number[]; notes?: never });
+  interface StartOptions {
+    maxVoices?: number; maxSequences?: number;
+    mixingProfile?: 'conservative' | 'raw' | 'balanced' | 'speakerSafe';
+    audioSession?: 'playback' | 'ambient';
+  }
+  interface Defaults {
+    version: string;
+    capabilities: { variation: true; toneRepetition: true; [key: string]: boolean };
+    variationSchemaVersion: 1;
+    limits: Record<string, { min: number; max: number }>;
+    defaults: Record<string, unknown>;
+    waveTypes: Record<'SINE' | 'SQUARE' | 'SAWTOOTH' | 'TRIANGLE' | 'NOISE' | 'WAVETABLE', number>;
+    mixingProfiles: string[]; audioSessions: string[]; buses: Bus[]; filterTypes: FilterType[];
+  }
+  interface SequenceVoice extends Omit<FiniteOptions, 'duration' | 'detune'> { modulations?: Modulation[] }
+  type SequenceStep = { duration?: number; length?: number; gate?: number;
+    overrides?: SequenceVoice; bus?: Bus; effectSend?: number; priority?: number } &
+    ({ notes: number[]; frequencies?: never; rest?: never } |
+    { frequencies: number[]; notes?: never; rest?: never } |
+    { rest: true; notes?: never; frequencies?: never });
+  interface SequenceOptions {
+    timeUnit?: 'beats' | 'ms'; stepDuration?: number; gate?: number; loop?: boolean;
+    swing?: number; mode?: 'normal' | 'up' | 'down' | 'updown'; tuning?: number;
+    detune?: number; voice?: SequenceVoice; steps: SequenceStep[];
+    bus?: Bus; effectSend?: number; priority?: number;
+  }
+  interface SequenceState {
+    sequenceId: number; playing: boolean; step: number; beat: number;
+    position: number; bpm: number; revision: number;
+  }
+  /** Numbers are MIDI notes 12..119; strings are native note names. */
+  type Notes = string[] | number[];
+  type SoundType = 'tone' | 'chord' | 'repeat' | 'pattern' | 'held';
+  type ModernPitch = { notes?: Notes; frequencies?: never } | { frequencies?: number[]; notes?: never };
+  /** Shared allowlist; each interpretation also validates source-specific compatibility. */
+  interface SoundProperties extends VoiceOptions {
+    detune?: number; panEnd?: number; noiseRateEnd?: number; pulseWidthEnd?: number;
+    filterHzEnd?: number; fmDepthEnd?: number; detunes?: number[]; pans?: number[];
+    panSpread?: number; modulations?: Modulation[];
+  }
+  type TonePlayback = ModernPitch & { type?: 'tone'; duration?: number; frequencyEnd?: number };
+  type ChordPlayback = ({ notes: Notes; frequencies?: never } | { frequencies: number[]; notes?: never }) & { type: 'chord'; duration?: number };
+  type RepeatPlayback = ModernPitch & { type: 'repeat'; duration?: number; frequencyEnd?: number; interval: number };
+  type HeldPlayback = ModernPitch & { type: 'held' };
+  type PatternStep = { interval?: number; length?: number; gate?: number;
+    sound?: SoundProperties & { frequencyEnd?: number } } &
+    ({ notes: Notes; frequencies?: never; rest?: never } |
+    { frequencies: number[]; notes?: never; rest?: never } |
+    { rest: true; notes?: never; frequencies?: never });
+  interface PatternPlayback {
+    type?: 'pattern'; timeUnit?: 'beats' | 'ms'; interval?: number; gate?: number;
+    loop?: boolean; swing?: number; mode?: 'normal' | 'up' | 'down' | 'updown';
+    tuning?: number; frequencyEnd?: number; steps: PatternStep[];
+  }
+  type SoundPlayback = TonePlayback | ChordPlayback | RepeatPlayback | PatternPlayback | HeldPlayback;
+  interface SoundPreset { name?: string; sound?: SoundProperties; playback?: SoundPlayback }
+  /** Objects merge recursively; arrays replace. Null removes a leaf if the resulting preset is valid. */
+  type PresetPatch<T> = T extends unknown[] ? T | null : T extends object ?
+    { [K in keyof T]?: PresetPatch<T[K]> } : T | null;
+  interface SoundChanges {
+    name?: string;
+    sound?: PresetPatch<SoundProperties>;
+    playback?: PresetPatch<SoundPlayback>;
+  }
+  /** Execution overrides are flat, unlike the stored sound/playback definition. */
+  type RepeatChanges = PresetPatch<SoundProperties> & ModernPitch & {
+    type?: 'repeat'; duration?: number | null; frequencyEnd?: number | null; interval?: number;
+  };
+  type PatternChanges = PresetPatch<SoundProperties> & PresetPatch<Partial<PatternPlayback>>;
+  type SoundOverrides = SoundProperties & (TonePlayback | Partial<ChordPlayback> | HeldPlayback |
+    (ModernPitch & { type?: 'repeat'; duration?: number; frequencyEnd?: number; interval?: number }) |
+    Partial<PatternPlayback>);
+  type NoteChanges = Pick<VoiceOptions, 'volume' | 'pan' | 'lfoFreq' | 'lfoDepth' |
+    'noiseRate' | 'lowPassHz' | 'pulseWidth' | 'filterHz' | 'filterQ' | 'fmRatio' |
+    'fmDepth' | 'spatialX' | 'spatialY' | 'effectSend'> & ModernPitch & { modulations?: Modulation[] };
+  interface Note {
+    /** Ramps compatible live fields without retriggering. Attack-only fields are rejected. */
+    update(changes: NoteChanges): boolean;
+    /** Begins this note's release; false after release, shutdown or invalidation. */
+    noteOff(): boolean;
+  }
+  interface RepeatingPlaybackControl {
+    /** Applies at the next scheduled attack without moving its existing deadline. */
+    update(changes: RepeatChanges): boolean;
+    /** Cancels future attacks; already sounding finite attacks finish. */
+    stop(): boolean;
+  }
+  type PatternState = Omit<SequenceState, 'sequenceId'>;
+  interface PatternEndEvent { reason: 'completed' | 'stopped' }
+  interface PatternPlaybackControl {
+    update(changes: PatternChanges): boolean;
+    stop(): boolean;
+    getState(): PatternState | null;
+    /** Transport retirement, not a promise of audible silence. No native ID is exposed. */
+    addEventListener(name: 'end', listener: (event: PatternEndEvent) => void): void;
+    removeEventListener(name: 'end', listener: (event: PatternEndEvent) => void): void;
+  }
+  type PlaybackResult = boolean | Note | RepeatingPlaybackControl | PatternPlaybackControl;
+  interface Sound {
+    getPreset(): SoundPreset;
+    /** Validates before replacing the stored definition; affects future executions only. */
+    set(changes: SoundChanges): void;
+    play(changes: SoundOverrides & { type: 'held' }): Note | false;
+    play(changes: SoundOverrides & { type: 'pattern' }): PatternPlaybackControl | false;
+    play(changes: SoundOverrides & { type: 'repeat' }): RepeatingPlaybackControl | false;
+    play(changes: SoundOverrides & { type: 'tone' | 'chord' }): boolean;
+    /** The stored type can change through set(), so an omitted type has a mixed return. */
+    play(changes?: SoundOverrides): PlaybackResult;
+    noteOn(changes?: SoundProperties & ModernPitch): Note | false;
+  }
+  interface Contract extends Defaults {
+    capabilities: Defaults['capabilities'] & { soundObjects: true };
+    interpretations: SoundType[];
+    units: { envelope: 'ms'; duration: 'msIncludingRelease'; repetitionInterval: 'ms'; pattern: ('beats' | 'ms')[] };
+    soundProperties: (keyof SoundProperties)[];
+    playbackProperties: string[];
+  }
+  type Sync = 'off' | 'quarter' | 'eighth' | 'sixteenth' | 'quarterTriplet' | 'eighthTriplet' | 'sixteenthTriplet';
+  interface ProcessingOptions {
+    inputGain?: number; applyTo?: Bus[];
+    chorus?: { enabled?: boolean; rate?: number; depth?: number; mix?: number };
+    /** time is milliseconds; timeMs is a deprecated exclusive input spelling. */
+    delay?: { enabled?: boolean; sync?: Sync; feedback?: number; mix?: number } &
+      ({ time?: number; timeMs?: never } | { time?: never; timeMs?: number });
+    /** decay is milliseconds (200..8000), unlike setMasterProcessing's seconds. */
+    reverb?: { enabled?: boolean; decay?: number; damping?: number; mix?: number };
+    saturation?: { enabled?: boolean; drive?: number; mix?: number };
+  }
+  function createSound(preset: SoundPreset): Sound;
+  function getContract(): Contract;
+  /** Strict configuration errors throw; operational rejection returns false. */
+  function setProcessing(options: ProcessingOptions): boolean;
+  /** Installed module version, native defaults, limits and capabilities. */
+  function getDefaults(): Defaults;
+  function start(options?: StartOptions): boolean;
+  /** One finite attack. intervalMs is rejected; use repeatTone for repetition. */
+  /** @deprecated Use createSound(...).play(). The existing signature and behavior remain supported. */
+  function playTone(options: ToneOptions & { intervalMs?: never }): boolean;
+  /** Integer 1-60000 ms: positive module-owned ID, or 0 on rejection. */
+  /** @deprecated Use a Sound with playback.type repeat and its playback control. The existing signature and behavior remain supported. */
+  function repeatTone(options: RepeatingToneOptions): number;
+  /** @deprecated Use the repetition control update(). The existing signature and behavior remain supported. */
+  function updateTone(options: ToneUpdate): boolean;
+  /** Cancels future attacks at the next block; admitted attacks finish. */
+  /** @deprecated Use the repetition control stop(). The existing signature and behavior remain supported. */
+  function stopTone(options: { toneId: number }): boolean;
+  /** @deprecated Use a Sound with playback.type chord. The existing signature and behavior remain supported. */
+  function playChord(options: ChordOptions): boolean;
+  /** @deprecated Use Sound.noteOn() or a Sound with playback.type held. The existing signature and behavior remain supported. */
+  function noteOn(options: NoteOptions): boolean;
+  /** @deprecated Use Note.update(). The existing signature and behavior remain supported. */
+  function updateNote(options: NoteUpdate): boolean;
+  /** @deprecated Use updateNote; identical behavior and voiceId contract. */
+  function updateVoice(options: NoteUpdate): boolean;
+  /** @deprecated Use Note.noteOff(). The existing signature and behavior remain supported. */
+  function noteOff(options: { voiceId: number }): boolean;
+  /** @deprecated Use a Sound with playback.type pattern. The existing signature and behavior remain supported. */
+  function playSequence(options: SequenceOptions): number;
+  /** @deprecated Use the pattern control update(). The existing signature and behavior remain supported. */
+  function updateSequence(options: Partial<Omit<SequenceOptions, 'timeUnit'>> & { sequenceId: number }): boolean;
+  /** @deprecated Use the pattern control stop(). The existing signature and behavior remain supported. */
+  function stopSequence(options: { sequenceId: number }): boolean;
+  /** @deprecated Use the pattern control getState(). The existing signature and behavior remain supported. */
+  function getSequenceState(options: { sequenceId: number }): SequenceState | null;
+  function setTempo(bpm: number): boolean;
+  /** @deprecated Use setTempo(bpm); the dictionary signature remains supported. */
+  function setTempo(options: { bpm: number }): boolean;
+  function setVolume(volume: number): boolean;
+  /** @deprecated Use setVolume(volume); the dictionary signature remains supported. */
+  function setVolume(options: { volume: number }): boolean;
+  /** @deprecated Use setProcessing(); its reverb decay unit is milliseconds. The existing signature and behavior remain supported. */
+  function setMasterProcessing(options: Record<string, unknown>): boolean;
+  function enableStats(): boolean;
+  function disableStats(): boolean;
+  /** @deprecated Use enableStats or disableStats; identical diagnostic behavior. */
+  function setStatsEnabled(enabled: boolean): boolean;
+  function getStats(): Record<string, number | boolean | string | null>;
+  function resetStats(): void;
+  function stopAll(): void;
+  function shutdown(): void;
+  function addEventListener(name: 'sequenceend', listener: (event: { sequenceId: number; reason: 'completed' | 'stopped' }) => void): void;
+  function removeEventListener(name: 'sequenceend', listener: (event: { sequenceId: number; reason: 'completed' | 'stopped' }) => void): void;
+}
+export = synth;

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

@@ -1,11 +1,11 @@
-> Source snapshot: official TiSynthEngine documentation at commit `b07c97c762be5905f132cecf33e9d60ea0c21316` (2026-11-02). Published 1.0.2; local 1.1.0 candidates; public API 1.0.0. Upstream `documentation/examples.md` SHA-256: `637806516d2804c43427d187a37786cfcf2f0d28758762f01a570ba15194bae3`.
+> Source snapshot: official TiSynthEngine documentation at commit `9d74aa45f84d3f2822d4aab76874efe37d81257f` (2026-11-03). Published module 2.0.0. Upstream `documentation/examples.md` SHA-256: `ee8aed566a63062ae63ae78f0b96fa8d73c70ab2f50aed81081c26acc24718af`.
 
 ## Sustained game motor
 
-Assume one running engine owned by this service. The positive voice ID belongs to the app; do not reuse it during the session or share its counter with an independent audio owner. There is no `duration` or `*End` target on `noteOn`.
+This example assumes the service owns one running engine. The positive voice ID belongs to the app; do not reuse it during the session or share its counter with an independent audio owner. There is no `duration` or `*End` target on `noteOn`.
 
 ```javascript
-if (!['noteOn', 'noteOff', 'updateVoice'].every(function (name) {
+if (!['noteOn', 'noteOff', 'updateNote'].every(function (name) {
   return typeof synth[name] === 'function'
 })) throw new Error('Held-voice APIs are required')
 
@@ -25,7 +25,7 @@ function startMotor () {
 
 function changeMotor (boosted) {
   if (motorId === null) return false
-  return synth.updateVoice({ voiceId: motorId,
+  return synth.updateNote({ voiceId: motorId,
     filterHz: boosted ? 320 : 220, volume: boosted ? 0.18 : 0.15 })
 }
 
@@ -92,7 +92,7 @@ The UI timer presents state; native audio schedules every attack/release. For fi
 
 ## Chorus, delay, reverb and creative saturation
 
-This configures the selected share of a running engine; `applyTo` defaults to all categories. Check method presence and Boolean acceptance; partial section updates merge with the last accepted settings. Effects start disabled, input gain starts at 1, and no LFOs are added to voices implicitly.
+The example below configures the selected share of a running engine; `applyTo` defaults to all categories. Check method presence and Boolean acceptance; partial section updates merge with the last accepted settings. Effects start disabled, input gain starts at 1, and no LFOs are added to voices implicitly.
 
 ```javascript
 if (typeof synth.setMasterProcessing !== 'function') {
@@ -128,7 +128,7 @@ Call `setCreativeDrive(true)` only for a deliberate timbre change and check acce
 This square voice modulates cutoff and PWM independently. The original `lfoFreq`/`lfoDepth` pitch vibrato remains a separate control. All LFOs run natively; edits preserve their phases and ramp contributions over 10 ms.
 
 ```javascript
-if (typeof synth.noteOn !== 'function' || typeof synth.updateVoice !== 'function') {
+if (typeof synth.noteOn !== 'function' || typeof synth.updateNote !== 'function') {
   throw new Error('Held-voice APIs are required')
 }
 var modulatedId = 100001 // Reserve an unused ID from the owner's counter in an app.
@@ -141,23 +141,23 @@ if (!synth.noteOn({ voiceId: modulatedId, note: 'A3', waveType: WAVE.SQUARE,
   ] })) throw new Error('Modulated voice rejected')
 
 function disableVoiceLfos () {
-  return synth.updateVoice({ voiceId: modulatedId, modulations: [] })
+  return synth.updateNote({ voiceId: modulatedId, modulations: [] })
 }
 // Call disableVoiceLfos on the UI action and handle false.
 // Later release this ID with the bounded release policy above, or shut down its owner.
 ```
 
-Use `target: 'fmDepth'` only with `WAVE.SINE`; a filter target requires an active filter and PWM requires `WAVE.SQUARE`. Free rates are 0 to 20 Hz; synced subdivisions follow native transport BPM. Depth is normalized, with cutoff/PWM/FM contributions clamped to safe parameter ranges. `modulations: []` disables both slots; omitting the field on update preserves them. Copy the same initial `modulations` array into a sequence's `voice` or a step's `overrides` to modulate transport notes. Timed tones and chords do not accept the new array; native sequences accept it in `voice` or step `overrides`.
+Use `target: 'fmDepth'` only with `WAVE.SINE`; a filter target requires an active filter and PWM requires `WAVE.SQUARE`. Free rates are 0 to 20 Hz; synced subdivisions follow native transport BPM. Depth is normalized, with cutoff/PWM/FM contributions clamped to safe parameter ranges. `modulations: []` disables both slots; omitting the field on update preserves them. Copy the same initial `modulations` array into a sequence's `voice` or a step's `overrides` to modulate transport notes. Timed tones and chords do not accept this array; native sequences accept it in `voice` or step `overrides`.
 
 ## Measure peaks and limiter reduction
 
 Enable diagnostics only while measuring and keep unavailable readings distinct from zero. A brief overload can disappear from the window meter while remaining in the accumulated maximum.
 
 ```javascript
-if (!['setStatsEnabled', 'getStats', 'resetStats'].every(function (name) {
+if (!['enableStats', 'disableStats', 'getStats', 'resetStats'].every(function (name) {
   return typeof synth[name] === 'function'
 })) throw new Error('Statistics APIs are required')
-if (!synth.setStatsEnabled(true)) throw new Error('Diagnostics rejected')
+if (!synth.enableStats()) throw new Error('Diagnostics rejected')
 synth.resetStats()
 var mixTimer = setInterval(function () {
   var stats = synth.getStats()
@@ -167,7 +167,7 @@ var mixTimer = setInterval(function () {
 
 function closeMixMeter () {
   clearInterval(mixTimer)
-  if (!synth.setStatsEnabled(false)) Ti.API.warn('Diagnostics disable rejected')
+  if (!synth.disableStats()) Ti.API.warn('Diagnostics disable rejected')
 }
 ```
 
@@ -175,7 +175,7 @@ Call `closeMixMeter` when its owner hides or closes. Display unavailable or unme
 
 ## Bounded variation for repeated noise impacts
 
-The local 1.1.0 packages choose values once per admitted attack. This example keeps the noise source and envelope fixed, varies the initial noise/filter settings, and lets the authored sweep endpoints finish unchanged. Call it through the application's existing effect cadence after normal engine startup.
+The native engine chooses values once per admitted attack. This example keeps the noise source and envelope fixed, varies the initial noise/filter settings, and lets the authored sweep endpoints finish unchanged. Call it for actual gameplay events after normal engine startup. For periodic repetition, pass the finite recipe to `repeatTone` with `intervalMs` and retain its positive tone ID; use `stopTone` on cancellation.
 
 ```javascript
 var synth = require('ti.synthengine')