@maccesar/titools 4.16.2 → 4.17.0

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

@@ -0,0 +1,348 @@
+> Source snapshot: official TiSynthEngine 1.0.0 documentation at commit `6685b81` (2026-08-29).
+
+# 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.
+
+```javascript
+var synth = require('ti.synthengine')
+var contract = synth.getDefaults()
+var WAVE = contract.waveTypes
+
+if (contract.apiVersion !== '1.0.0') {
+  throw new Error('TiSynthEngine 1.0.0 is required')
+}
+```
+
+<!-- TOC-START -->
+## Contents
+
+- [Start once after layout](#start-once-after-layout)
+- [Five waveforms](#five-waveforms)
+- [Pitch sweep and pan movement](#pitch-sweep-and-pan-movement)
+- [Vibrato](#vibrato)
+- [Chord with an even spread](#chord-with-an-even-spread)
+- [Chord with explicit pans](#chord-with-explicit-pans)
+- [Tempo, note values and swing](#tempo-note-values-and-swing)
+- [Millisecond pattern](#millisecond-pattern)
+- [Step overrides](#step-overrides)
+- [Noise percussion](#noise-percussion)
+- [Xylophone sketch](#xylophone-sketch)
+- [Simon-style pads](#simon-style-pads)
+- [Speaker-safe startup](#speaker-safe-startup)
+- [Validation at an input boundary](#validation-at-an-input-boundary)
+- [Stop and clean up](#stop-and-clean-up)
+
+<!-- TOC-END -->
+
+## Start once after layout
+
+```javascript
+var started = false
+var timer = null
+
+function onPostLayout () {
+  if (timer !== null) clearTimeout(timer)
+  timer = setTimeout(function () {
+    timer = null
+    win.removeEventListener('postlayout', onPostLayout)
+    started = synth.startEngine({
+      maxVoices: 16,
+      mixingProfile: 'conservative'
+    })
+  }, 250)
+}
+
+function cleanup () {
+  win.removeEventListener('postlayout', onPostLayout)
+  if (timer !== null) clearTimeout(timer)
+  if (started) synth.shutdown()
+}
+
+win.addEventListener('postlayout', onPostLayout)
+win.addEventListener('close', cleanup)
+win.open()
+```
+
+## Five 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)
+})
+```
+
+Noise ignores pitch, but `note` keeps the event shape valid.
+
+## Pitch sweep and pan movement
+
+```javascript
+synth.playTone({
+  frequency: 180,
+  frequencyEnd: 1200,
+  pan: -0.9,
+  panEnd: 0.9,
+  duration: 950,
+  attack: 5,
+  release: 160,
+  volume: 0.55,
+  waveType: WAVE.SAWTOOTH
+})
+```
+
+Set `frequencyEnd: 0` to keep the starting pitch. Set `panEnd` equal to `pan`
+when no stereo movement is wanted.
+
+## Vibrato
+
+```javascript
+synth.playTone({
+  note: 'E4',
+  duration: 1600,
+  attack: 100,
+  release: 300,
+  volume: 0.7,
+  waveType: WAVE.SINE,
+  lfoFreq: 5.2,
+  lfoDepth: 6
+})
+```
+
+`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
+
+```javascript
+synth.playChord({
+  notes: ['C4', 'E4', 'G4', 'C5'],
+  duration: 1200,
+  attack: 120,
+  release: 360,
+  volume: 0.65,
+  waveType: WAVE.TRIANGLE,
+  panSpread: 0.85
+})
+```
+
+## Chord with explicit pans
+
+```javascript
+synth.playChord({
+  frequencies: [261.63, 329.63, 392, 523.25],
+  duration: 900,
+  attack: 20,
+  release: 240,
+  volume: 0.62,
+  waveType: WAVE.SINE,
+  pans: [-0.8, -0.25, 0.25, 0.8]
+})
+```
+
+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,
+  swing: 0.12,
+  noteValue: '8n',
+  attack: 4,
+  release: 55,
+  volume: 0.55,
+  waveType: WAVE.SQUARE,
+  steps: [
+    { note: 'C4', duration: 150 },
+    { note: 'E4', duration: 150 },
+    { rest: true },
+    { note: 'G4', duration: 150 },
+    { note: 'C5', duration: 280, noteValue: '4n' }
+  ]
+})
+```
+
+Positive swing lengthens one step and shortens the next. Negative swing flips
+that relationship. Keep it subtle unless the lurch is the intended effect.
+
+## Millisecond pattern
+
+```javascript
+synth.playPattern({
+  stepDuration: 110,
+  pan: -0.4,
+  panEnd: 0.4,
+  waveType: WAVE.TRIANGLE,
+  steps: [
+    { note: 'C5', duration: 90 },
+    { note: 'D5', duration: 90 },
+    { note: 'E5', duration: 90 },
+    { note: 'G5', duration: 180 }
+  ]
+})
+```
+
+`stepDuration` controls spacing. Per-step `duration` controls how long the
+sound itself lasts. The pattern root does not accept `duration`.
+
+## Step overrides
+
+```javascript
+synth.playPattern({
+  bpm: 100,
+  noteValue: '8n',
+  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
+    },
+    { rest: true },
+    { note: 'G4', volume: 0.75, noteValue: '4n' }
+  ]
+})
+```
+
+## Noise percussion
+
+```javascript
+synth.playPattern({
+  bpm: 116,
+  noteValue: '16n',
+  volume: 0.32,
+  waveType: WAVE.NOISE,
+  steps: [
+    { frequency: 200, duration: 70, attack: 1, release: 60 },
+    { rest: true },
+    { frequency: 200, duration: 32, attack: 1, release: 25 },
+    { frequency: 200, duration: 32, attack: 1, release: 25 },
+    { rest: true },
+    { frequency: 200, duration: 52, attack: 1, release: 44 }
+  ]
+})
+```
+
+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`.
+
+## 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)
+```
+
+These are deliberately independent strikes. Their releases overlap, so leave
+headroom in `volume` and choose enough `maxVoices` for the tails.
+
+## Simon-style pads
+
+```javascript
+var simonPitches = [329.63, 440, 554.37, 659.25]
+
+function playPad (index) {
+  return synth.playTone({
+    frequency: simonPitches[index],
+    duration: 340,
+    attack: 6,
+    release: 90,
+    volume: 0.62,
+    waveType: WAVE.SQUARE
+  })
+}
+
+function playAllPads () {
+  return synth.playChord({
+    frequencies: simonPitches,
+    duration: 480,
+    attack: 8,
+    release: 120,
+    volume: 0.58,
+    waveType: WAVE.SQUARE,
+    pans: [-0.75, -0.25, 0.25, 0.75]
+  })
+}
+```
+
+## Speaker-safe startup
+
+```javascript
+var accepted = synth.startEngine({
+  maxVoices: 12,
+  mixingProfile: 'speakerSafe'
+})
+
+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.
+
+## Validation at an input boundary
+
+```javascript
+function playUserFrequency (input) {
+  var limits = synth.getDefaults().limits.frequency
+  var frequency = Number(input)
+
+  if (!isFinite(frequency)) return false
+  if (frequency < limits.min || frequency > limits.max) return false
+
+  return synth.playTone({ frequency: frequency })
+}
+```
+
+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.
+
+## Stop and clean up
+
+```javascript
+synth.stopAll()
+
+// Later, when the audio owner closes:
+synth.shutdown()
+```
+
+`stopAll()` fades current voices but leaves pending pattern scheduling alone.
+`shutdown()` cancels the scheduler and releases the native stream.
+
+The complete interactive demo is `example/app.js` in the upstream TiSynthEngine repository. For additional retro effects, playable xylophone interaction, memory pads, layered polyphony and cancellable repetition, continue with [Curated sound and interaction recipes](recipes.md).

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

@@ -0,0 +1,252 @@
+> Source snapshot: official TiSynthEngine 1.0.0 documentation at commit `6685b81` (2026-08-29).
+
+# Guide
+
+This guide covers the normal path from installing TiSynthEngine to releasing
+the native audio resources when the owning screen closes.
+
+## Install the module
+
+Use the archive for each target platform:
+
+- `ti.synthengine-android-1.0.0.zip`
+- `ti.synthengine-iphone-1.0.0.zip`
+
+Put the archives in the Titanium project root or install them through the
+Titanium CLI. Pin the same version for both platforms:
+
+```xml
+<modules>
+  <module platform="android" version="1.0.0">ti.synthengine</module>
+  <module platform="iphone" version="1.0.0">ti.synthengine</module>
+</modules>
+```
+
+TiSynthEngine requires Titanium SDK 13.3.1.GA or newer. The iOS renderer
+requires iOS 13 or newer.
+
+## Load and verify the contract
+
+Require the module once in the code that owns audio. Check `apiVersion` before
+starting the engine so a stale native archive fails with a useful message.
+
+```javascript
+var synth = require('ti.synthengine')
+var contract = synth.getDefaults()
+
+if (contract.apiVersion !== '1.0.0') {
+  throw new Error('TiSynthEngine 1.0.0 is required; found ' + contract.apiVersion)
+}
+```
+
+`getDefaults()` works before the stream starts. Call it again after startup if
+you need the frequency ceiling for input validation, because that ceiling
+depends on the output sample rate.
+
+## Lifecycle
+
+Opening a low-latency stream while Titanium lays out the first window can cause
+an underrun on some Android devices. Register `postlayout` before `open()`, wait
+for a short quiet period, and cancel the timer if the window closes first.
+
+```javascript
+var running = false
+var startTimer = null
+
+function startAudio () {
+  startTimer = null
+  win.removeEventListener('postlayout', onPostLayout)
+  running = synth.startEngine({
+    maxVoices: 16,
+    mixingProfile: 'conservative'
+  })
+}
+
+function onPostLayout () {
+  if (startTimer !== null) clearTimeout(startTimer)
+  startTimer = setTimeout(startAudio, 250)
+}
+
+function closeAudio () {
+  win.removeEventListener('postlayout', onPostLayout)
+  win.removeEventListener('close', closeAudio)
+
+  if (startTimer !== null) {
+    clearTimeout(startTimer)
+    startTimer = null
+  }
+
+  if (running) {
+    synth.shutdown()
+    running = false
+  }
+}
+
+win.addEventListener('postlayout', onPostLayout)
+win.addEventListener('close', closeAudio)
+win.open()
+```
+
+Use one owner for the engine. Start it once, pass a small audio service to the
+screens that need it, and call `shutdown()` from the owner. A second
+`startEngine()` call is harmless, but it makes ownership and cleanup unclear.
+
+## Play the first sound
+
+```javascript
+var accepted = synth.playTone({
+  note: 'A4',
+  duration: 300,
+  attack: 8,
+  release: 80,
+  volume: 0.8,
+  waveType: contract.waveTypes.SINE
+})
+
+if (!accepted) Ti.API.warn('The tone was rejected')
+```
+
+Calls that create or change sound return `true` when accepted and `false` when
+rejected. During development, handle that result and inspect logcat or the
+Xcode console for the structured validation warning.
+
+## Choose a pitch
+
+`playTone` accepts one of these fields:
+
+```javascript
+synth.playTone({ frequency: 440 })
+synth.playTone({ note: 'A4' })
+```
+
+Do not send both. Notes accept English names (`C#4`, `Bb3`) and solfege names
+(`DO4`, `FA#5`, `Sib3`). When the octave is omitted, octave 4 is used.
+
+## Shape a tone
+
+The oscillator runs for `duration` milliseconds. `attack` controls the fade in
+and `release` controls the fade out; the time between them stays at full level.
+
+```javascript
+synth.playTone({
+  note: 'C4',
+  duration: 1100,
+  attack: 180,
+  release: 420,
+  waveType: contract.waveTypes.TRIANGLE
+})
+```
+
+Explicit envelope values must fit inside `duration`. An attack equal to or
+longer than the duration is rejected, as is a release longer than the time left
+after attack.
+
+Tone options can also move during the event:
+
+```javascript
+synth.playTone({
+  frequency: 220,
+  frequencyEnd: 880,
+  pan: -0.8,
+  panEnd: 0.8,
+  lfoFreq: 5.5,
+  lfoDepth: 8,
+  duration: 1200,
+  release: 180,
+  waveType: contract.waveTypes.SAWTOOTH
+})
+```
+
+`frequencyEnd` creates a linear pitch sweep. `panEnd` moves the sound between
+channels. `lfoFreq` is the vibrato rate in hertz and `lfoDepth` is its depth in
+hertz.
+
+## Play simultaneous notes
+
+Use `playChord` when notes belong to one musical event:
+
+```javascript
+synth.playChord({
+  notes: ['C4', 'E4', 'G4'],
+  duration: 900,
+  attack: 25,
+  release: 220,
+  panSpread: 0.7,
+  waveType: contract.waveTypes.SINE
+})
+```
+
+The chord is placed on the audio queue atomically. Its voices also share a
+constant-power event gain. Several separate `playTone` calls are independent,
+can begin in different callbacks, and are hotter when summed.
+
+Use `pans` when every note needs a deliberate position. Missing entries remain
+centered, and an array longer than the note array is rejected.
+
+```javascript
+synth.playChord({
+  frequencies: [261.63, 329.63, 392],
+  pans: [-0.75, 0, 0.75],
+  duration: 700
+})
+```
+
+## Play a pattern
+
+A pattern contains 1 to 512 object steps. Each step must have exactly one of
+`note`, `frequency` or `rest: true`.
+
+```javascript
+synth.playPattern({
+  bpm: 126,
+  swing: 0.1,
+  noteValue: '8n',
+  waveType: contract.waveTypes.SQUARE,
+  steps: [
+    { note: 'C4' },
+    { note: 'E4' },
+    { rest: true },
+    { note: 'G4', noteValue: '4n', pan: 0.5 }
+  ]
+})
+```
+
+Step timing is chosen in this order: step `duration`, step `noteValue`, pattern
+`noteValue`, pattern `stepDuration`, then the 100 ms default. A step also
+inherits the pattern's envelope, volume, waveform, pan, sweep and vibrato
+options. Values set on the step override the inherited value.
+
+Only one pattern scheduler is active. Starting another pattern cancels the
+pending steps of the previous pattern. It does not stop voices that have
+already started.
+
+## Master level and stopping
+
+```javascript
+synth.setVolume({ volume: 0.7 })
+synth.stopAll()
+```
+
+Master volume is ramped to avoid a step in the output. `stopAll()` fades active
+voices, but it does not cancel future steps in the current pattern. Start a new
+pattern or call `shutdown()` when future scheduling must stop as well.
+
+## Output route changes
+
+The native ports rebuild or resume their stream after headphones, Bluetooth or
+other output routes change. The note crossing the transition may end early;
+new notes can be played normally after the system settles. Do not restart the
+whole app for a route change.
+
+On iOS, `startEngine()` activates a `Playback` audio session. That ignores the
+silent switch and normally interrupts other audio. If the app needs different
+session behavior, read [coexisting with other audio](recommendations.md#coexisting-with-other-audio)
+and test the final app on a device.
+
+## Next steps
+
+- [API reference](api.md) for every accepted key and limit.
+- [Sound design](sound-design.md) for waveform and envelope recipes.
+- [Examples](examples.md) for copy-ready sounds and patterns.
+- [Troubleshooting](troubleshooting.md) when a call returns `false` or audio is
+  silent.