@maccesar/titools 5.2.3 → 5.2.5

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

@@ -7,14 +7,15 @@ var sequenceOwner = require('lib/sequenceOwner')(Synth, {
 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')
+if (!defaults || defaults.apiVersion !== '1.1.0') {
+  throw new Error('TiSynthEngine 1.1.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.repeatTone !== 'function' || typeof Synth.updateTone !== 'function' || typeof Synth.stopTone !== 'function') {
+  throw new Error('Install the current TiSynthEngine 1.1.0 packages, then rebuild and reinstall this app')
 }
 
 var WAVE = defaults.waveTypes
@@ -23,6 +24,7 @@ var engineRunning = false
 var startTimer = null
 var statsTimer = null
 var diagnosticsEnabled = false
+var repeatingToneId = 0
 var selectedSession = 'playback'
 var masterVolume = 1
 var binauralEnabled = true
@@ -200,7 +202,7 @@ function makeHero() {
     height: Ti.UI.SIZE,
     top: dp(16)
   })
-  badgeRow.add(makeBadge('API 1.0.0', COLORS.indigo))
+  badgeRow.add(makeBadge('API 1.1.0', COLORS.indigo))
   badgeRow.add(makeBadge('ANDROID + iOS', COLORS.surfaceMuted))
   hero.add(badgeRow)
   hero.add(statusPill)
@@ -399,6 +401,40 @@ waveNames.forEach(function (name, index) {
 waveSection.add(Ti.UI.createView({ height: dp(12) }))
 scrollView.add(waveSection)
 
+// A repeated finite recipe uses its native owner ID; there is no attack timer.
+function stopRepeatingTone() {
+  if (!repeatingToneId) return true
+  if (!Synth.stopTone({ toneId: repeatingToneId })) return false
+  repeatingToneId = 0
+  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 (repeatingToneId) return true
+    var id = Synth.repeatTone({ frequency: 1380, frequencyEnd: 340,
+      duration: 105, attack: 2, release: 40, waveType: WAVE.SQUARE,
+      volume: 0.1, intervalMs: 200 })
+    if (!Number.isInteger(id) || id <= 0) return false
+    repeatingToneId = id
+    return true
+  }
+}))
+repeatSection.add(makeAction({
+  title: 'EDIT REPEATING', color: COLORS.teal, pressedColor: COLORS.tealPressed,
+  onPress: function () {
+    return !!repeatingToneId && Synth.updateTone({ toneId: repeatingToneId, intervalMs: 150, volume: 0.08 })
+  }
+}))
+repeatSection.add(makeAction({
+  title: 'STOP REPEATING', color: COLORS.surfaceMuted, pressedColor: COLORS.surfaceRaised,
+  onPress: stopRepeatingTone
+}))
+scrollView.add(repeatSection)
+
 // ---------------------------------------------------------------------------
 // 2. Note names
 // ---------------------------------------------------------------------------
@@ -835,6 +871,26 @@ expressiveSection.add(makeAction({
   }
 }))
 
+// Every press is a fresh native attack. Older packages receive the authored recipe.
+expressiveSection.add(makeAction({
+  title: 'ATTACK VARIATION\nMetal strike · native ranges',
+  color: COLORS.teal,
+  pressedColor: COLORS.tealPressed,
+  status: 'Metal strike · a new native selection on each attack',
+  onPress: function () {
+    var options = { frequency: 620, duration: 180, attack: 1, decay: 65,
+      sustain: 0.12, release: 110, waveType: WAVE.SINE,
+      fmRatio: 2.7, fmDepth: 3.2, fmDepthEnd: 0.4, volume: 0.3 }
+    if (defaults.capabilities && defaults.capabilities.variation === true
+      && defaults.variationSchemaVersion === 1) {
+      options.variation = { amount: 1, ranges: {
+        volume: [0.291, 0.3], fmDepth: [2.944, 3.456], pitchCents: [-12, 12]
+      } }
+    }
+    return Synth.playTone(options)
+  }
+}))
+
 var patternEndLabel = makeText('sequenceend: no pattern yet', {
   top: dp(8),
   left: dp(16),
@@ -979,7 +1035,7 @@ 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()
+      repeatingToneId = 0; sequenceOwner.reset(); Synth.shutdown()
       engineRunning = false
       selectedSession = session
       patternEndLabel.text = 'sequenceend: cancelled by shutdown (no event)'
@@ -1026,7 +1082,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)
@@ -1083,10 +1139,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()
+    repeatingToneId = 0; sequenceOwner.stop(); Synth.stopAll()
   }
 }))
 controlSection.add(boostRow)
@@ -1150,8 +1206,9 @@ 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)
@@ -1164,7 +1221,7 @@ function cleanup() {
     startTimer = null
   }
   if (engineRunning) {
-    sequenceOwner.reset(); Synth.shutdown()
+    repeatingToneId = 0; sequenceOwner.reset(); Synth.shutdown()
     engineRunning = false
   }
 }

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

@@ -0,0 +1,106 @@
+/** TiSynthEngine local 1.1.0 candidate, public API 1.1.0. */
+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 {
+    apiVersion: '1.1.0';
+    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;
+  }
+  function getDefaults(): Defaults;
+  function start(options?: StartOptions): boolean;
+  /** One finite attack. intervalMs is rejected; use repeatTone for repetition. */
+  function playTone(options: ToneOptions & { intervalMs?: never }): boolean;
+  /** Integer 1-60000 ms: positive module-owned ID, or 0 on rejection. */
+  function repeatTone(options: RepeatingToneOptions): number;
+  function updateTone(options: ToneUpdate): boolean;
+  /** Cancels future attacks at the next block; admitted attacks finish. */
+  function stopTone(options: { toneId: number }): boolean;
+  function playChord(options: ChordOptions): boolean;
+  function noteOn(options: NoteOptions): boolean;
+  function updateNote(options: NoteUpdate): boolean;
+  /** @deprecated Use updateNote; identical behavior and voiceId contract. */
+  function updateVoice(options: NoteUpdate): boolean;
+  function noteOff(options: { voiceId: number }): boolean;
+  function playSequence(options: SequenceOptions): number;
+  function updateSequence(options: Partial<Omit<SequenceOptions, 'timeUnit'>> & { sequenceId: number }): boolean;
+  function stopSequence(options: { sequenceId: number }): boolean;
+  function getSequenceState(options: { sequenceId: number }): SequenceState | null;
+  function setTempo(options: { bpm: number }): boolean;
+  function setVolume(options: { volume: number }): boolean;
+  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 1.0.2 documentation from reviewed working-tree based on commit `4a45f21230ffc5a8838fbd5fc108dd3ab470362a` (2026-10-29). Upstream `documentation/examples.md` SHA-256: `48104b9d413050d439ee605c92a2456a50b42c4c80e2d7c2c05706eecc7db215`.
+> Source snapshot: official TiSynthEngine documentation at commit `ec04f4e634075c41b55f66279eabcd78b9652d58` (2026-11-02). Published module 1.1.0; public API 1.1.0. Upstream `documentation/examples.md` SHA-256: `1b3be798d8f606381696d9e00cda330c11475402397e4760dcbc3041a39ef404`.
 
 ## 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`.
 
 ```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 })
 }
 
@@ -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/chords/patterns do not accept the new array.
+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,8 +167,33 @@ 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')
 }
 ```
 
 Call `closeMixMeter` when its owner hides or closes. Display unavailable or unmeasured fields as unavailable. Reset deliberately before a comparison. These values measure digital peak protection, not speaker loudness, subjective quality or a guarantee that every audio deadline was met.
+
+## Bounded variation for repeated noise impacts
+
+The 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 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')
+var contract = synth.getDefaults()
+var impact = {
+  waveType: contract.waveTypes.NOISE,
+  frequency: 200, duration: 240, attack: 2, release: 170,
+  volume: 0.20, noiseRate: 5000, noiseRateEnd: 900,
+  filterType: 'lowpass', filterHz: 2800, filterHzEnd: 500, filterQ: 0.8
+}
+if (contract.capabilities && contract.capabilities.variation === true
+    && contract.variationSchemaVersion === 1) {
+  impact.variation = {
+    amount: 0.6,
+    ranges: { noiseRate: [4200, 5800], filterHz: [2400, 3200] }
+  }
+}
+synth.playTone(impact)
+```
+
+Omit `seed` for successive native selections. An explicit seed repeats the selected parameters of standalone calls. The [variation reference](native-variation.md) includes chord gain, sustained ownership, native loop inheritance and revision examples. Its amount is linear; Studio divides the displayed percentage by 100 to obtain the same value.