@maccesar/titools 5.2.4 → 5.3.0

package/README.md

@@ -172,7 +172,7 @@ The knowledge index is based on the latest Titanium SDK documentation. If your p
 | ti-ui            | UI/UX patterns                      | Complex layouts, ListViews, platform UI                                                                                                                                                                                                                                                              |
 | ti-game          | 2D games with the `ti.game` module  | Sprites, physics, tile maps, HUDs, camera, focused keyboard/mouse/gamepad actions, Apple Metal/Catalyst                                                                                                                                                                                              |
 | ti-game-assets   | Visual and sound assets             | Image generation/editing, synthesis variants, stereo placement, alpha cleanup, manifests, parallax and complete exports                                                                                                                                                                              |
-| ti-synthengine   | Sound design with `ti.synthengine`  | Tones, chords, retro/UI effects, alarms, sweeps, patterns, ADSR envelopes, resonant filters, FM, detune, binaural positioning, held voices, native sequences, master effects, voice LFOs, engine statistics, bounded attack variation, seeds, instrument/effect fidelity, mixing and troubleshooting |
+| ti-synthengine   | Sound design with `ti.synthengine`  | TiSynth 2.0 reusable Sound presets, independent playback controls, tones/chords, held notes, native repetitions/patterns, ADSR, FM, filters, binaural positioning, shared effects, variation, TypeScript and troubleshooting |
 | ti-admob-unified | Advertising, privacy and mediation  | Official `ti.admob.unified` guides, copy-ready library, banners/fullscreen, UMP/ATT and selected-provider configuration                                                                                                                                                                              |
 | ti-api           | Complete Titanium API reference     | Looking up properties, methods, events                                                                                                                                                                                                                                                               |
 | ti-guides        | SDK fundamentals                    | tiapp.xml, Hyperloop, distribution, JDK/Xcode compatibility, release notes                                                                                                                                                                                                                           |
@@ -184,7 +184,7 @@ Notes:
 - The first eight (`ti-reuse-first`, `ti-expert`, `purgetss`, `ti-ui`, `ti-game`, `ti-game-assets`, `ti-synthengine`, `ti-admob-unified`) are specialist workflow skills reflecting TiTools' Titanium conventions and native-module contracts.
 - `ti-reuse-first` runs before the others. It asks whether a thing needs to exist and what already does it — a search order that stops at the first rung that holds — and sweeps an existing `app/` for near-identical controllers, single-listener events, wrappers around one call, and layout recomputed in JavaScript. It is deliberately two-sided: it says when adding a module or a Widget is the right answer, so the bias does not simply invert.
 - `ti-game` documents the `ti.game` native module (2D sprite engine using OpenGL ES 2.0 on Android and Metal on iPhone, iPad and Mac Catalyst). Its API reference was verified against the module source and records the reviewed upstream commit and fork documentation snapshot; it applies to Alloy and Classic projects alike and does not depend on PurgeTSS.
-- `ti-synthengine` translates sound requests into checked JavaScript for published Android/iOS `ti.synthengine` 1.0.2 and local 1.1.0 candidates (public API 1.0.0). Its nineteen-method contract covers timed/held voices, identified native sequences, global tempo, selective categories/sends, master effects, live spatial/noise/filter controls and diagnostics. Two curated recipe guides cover retro cues and interactive instruments. Complete official-source mirrors, validation reports, bundled examples and raw evidence retain provenance; verified corrections are applied to official source prose before mirroring. The reviewed source commit/worktree, platform differences and scoped listening/performance acceptance are explicit in source notes.
+- `ti-synthengine` translates sound requests into checked JavaScript for published Android/iOS `ti.synthengine` 2.0.0. It covers reusable Sound definitions, independent held/repetition/pattern controls, atomic preset edits, temporary overrides, processing units and migration from supported direct methods. Practical references, curated recipes, runnable examples and TypeScript declarations support implementation and troubleshooting.
 - `ti-game-assets` treats images and sounds as essential game assets. It coordinates integrated `image_gen` artwork with `ti-synthengine` sound design, variants and stereo placement, and ships Pillow helpers for conservative alpha cleanup and per-world visual/audio manifests.
 - The latter five are documentation-mirror skills, audited against official sources via the internal `titools-skill-auditor`. See [Where the references come from](#where-the-references-come-from).
 - `purgetss` reference files are audited against the official PurgeTSS documentation and against the package source (the CLI and the generated `utilities.tss`), but its workflow conventions are opinionated.
@@ -546,46 +546,41 @@ frequency and pause/audio/input ownership remain application policies.
 
 ### ti-synthengine
 
-Sound design and synthesis with the public native `ti.synthengine` 1.0.2 release (public API 1.0.0) for Android and iOS. Local 1.1.0 candidates add capability-gated native per-attack variation while keeping API 1.0.0; they have not been published as releases. Read the [skill entry point](skills/ti-synthengine/SKILL.md) for task routing, exact API references and current source provenance.
+Sound design with public **TiSynth 2.0.0** for Android and iOS. Create reusable definitions with `createSound()`, then play finite effects, chords, held instruments, native repetitions or patterns. Returned controls own live edits and cancellation; definitions survive engine shutdown/start. Existing direct methods remain supported. Read the [skill entry point](skills/ti-synthengine/SKILL.md), [Sound interface](skills/ti-synthengine/references/sound-api.md) and [upgrade guide](skills/ti-synthengine/references/upgrade-2.0.0.md).
 
-Public repository: [macCesar/TiSynthEngine](https://github.com/macCesar/TiSynthEngine).
-Download [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),
+Download [Android 2.0.0](https://github.com/macCesar/TiSynthEngine/releases/tag/android-2.0.0)
+and [iOS 2.0.0](https://github.com/macCesar/TiSynthEngine/releases/tag/ios-2.0.0)
+from [macCesar/TiSynthEngine](https://github.com/macCesar/TiSynthEngine),
 copy the ZIPs into the Titanium app root and follow the [installation guide](skills/ti-synthengine/references/guide.md).
-Requires Titanium SDK 13.2.0.GA+, Android compile API35+, and iOS 15+; the Apple package also supports Mac Catalyst.
+Requires Titanium SDK 13.2.0.GA+, Android compile API 35+, and iOS 15+; the Apple package includes Mac Catalyst.
 
 When it activates:
+
 - `tiapp.xml` declares `ti.synthengine`, or code calls `require('ti.synthengine')`
-- Generated UI/game cues, instruments, alarms, chords, percussion, sweeps or binaural headphone placement
-- Sustained voices, simultaneous native sequences, shared tempo, selective effects/sends, priorities or live voice controls
-- Bounded native attack variation, deterministic seeds, complete effect playback or playable instrument adaptations
-- Rejected calls, startup glitches, voice/queue diagnostics, render-load measurements or source/artifact compatibility questions
+- UI/game cues, instruments, alarms, chords, percussion, ADSR, sweeps, FM, filters or binaural placement
+- Reusable Sound presets, atomic edits, native repetition/patterns, held-note controls or migration from direct methods
+- Shared effects, routing/sends, native attack variation, gain staging or audio diagnostics
 
 Example prompts:
+
 ```
-"Create a short sci-fi laser that sweeps left to right with ti.synthengine."
-"Build a playable xylophone without retriggering a bar on every touchmove."
-"Move a held spatial motor and change its noise clock and low-pass cutoff without restarting it."
-"Run music and a victory cue as independent native sequences, then cancel only the cue."
-"Apply reverb to music while keeping UI dry, and change the global tempo."
-"Explain what the Android Sim80 headphone result proves about performance."
-"Vary repeated impacts natively on local 1.1.0 and retain a clean fallback on published 1.0.2."
+"Create one reusable laser Sound and play it at each projectile's position."
+"Build a playable xylophone with independent note controls and touch-cancellation cleanup."
+"Repeat this complete swept shot natively, edit its interval and stop future attacks while sounding shots finish."
+"Run music and a victory pattern independently, then cancel only the victory control."
+"Migrate this app to createSound, getContract().version and setProcessing without changing envelopes or reverb time."
+"Change future preset executions with set(), and update only this playing repetition."
 ```
 
 Key rules:
-- Native variation requires both capability and schema announcements; [ranges, seeds and loop behavior](skills/ti-synthengine/references/native-variation.md) are distinct from live edits
-- Preserve complete effects and layer gains when adapting or repeating them; read [instruments and effects](skills/ti-synthengine/references/instruments-and-effects.md)
-- Read constants and exact ranges from the API; strict option dictionaries reject invalid fields or conflicting pitch sources
-- Timed tone/chord `duration` includes release. Native sequence intervals and note lengths are separate; held voices release through their IDs
-- Schedule successive sounds with `playSequence`, retain positive accepted IDs and cancel the owner's sequence. `stopAll()` is global panic
-- `setTempo` drives beat-based transport and synchronized modulation; millisecond sequences keep fixed timing
-- `bus`/`applyTo` select processed categories; explicit `effectSend` overrides that selection. One shared chain and final limiter remain global
-- Held spatial position, noise clock and one-pole cutoff support compatible 10 ms updates. A stereo voice cannot become spatial through an update
-- Omit both spatial coordinates for stereo; zero coordinates enable binaural center. Do not combine binaural coordinates with stereo pan fields
-- Start after layout, keep one lifecycle owner, handle Boolean acceptance and sequence IDs, release held notes on cancellation and shut down during teardown
-- Current platform metadata, zero-envelope and diagnostic differences are documented. Host checks and a short accepted listening scene do not establish complete physical maximum-load acceptance
-
-The [retro recipes](skills/ti-synthengine/references/recipes.md) and [interaction/instrument recipes](skills/ti-synthengine/references/recipes-interaction.md) preserve acoustic intent, overlap budgets and cleanup. [Source notes](skills/ti-synthengine/references/source-notes.md) identify the reviewed native commit and evidence limits.
+
+- Put synthesis/routing in `sound` and pitch/type/timing in `playback`; execution overrides are flat. `set()` validates atomic future revisions and replaces arrays completely.
+- Tone/chord playback returns Boolean acceptance; held, repeat and pattern playback return controls or `false`. Invalid Sound configurations throw descriptive errors. Keep controls with their interaction owners.
+- Finite `duration` includes release. Pattern `interval` and `length` remain separate; repetitions preserve finite-envelope interpretation and use integer millisecond intervals.
+- `setProcessing()` uses milliseconds for delay `time` and reverb `decay`. Direct `setMasterProcessing()` retains its original units. Runtime metadata uses `version`.
+- Preserve grouped chord gains, layer levels, overlap budgets, stereo/spatial rules and native variation bounds. Use one engine owner and clean up notes, controls, listeners and polling during teardown.
+
+The [retro recipes](skills/ti-synthengine/references/recipes.md) and [interaction recipes](skills/ti-synthengine/references/recipes-interaction.md) preserve acoustic intent and cleanup. [Instruments and effects](skills/ti-synthengine/references/instruments-and-effects.md) explains complete playback and adaptations. The [TypeScript declarations](skills/ti-synthengine/assets/index.d.ts) complement runtime validation. [Source notes](skills/ti-synthengine/references/source-notes.md) retain practical platform caveats; diagnose performance on the intended device and keep technical measurements separate from listening acceptance.
 
 ---
 
@@ -898,7 +893,7 @@ This pattern is documented across four bundled TiTools skills: `ti-ui`, `ti-expe
 | ti-game          | Native 2D Game Workflow       | 12 files (API, input, source notes, setup, physics, patterns, recipes, tile maps, debugging, roadmap)                                                                                                |
 | ti-game-assets   | Visual and Sound Assets       | 10 guides and a manifest example; alpha and contract validation scripts                                                                                                                              |
 | ti-admob-unified | Unified Advertising           | 20 Markdown references including production, rewarded interstitial, mediation parity, integration library guidance, provenance and game monetization; source/hash checks and official example assets |
-| ti-synthengine   | Native Sound Synthesis        | 17 Markdown references (14 official parts, 2 curated recipe guides, maintenance notes), complete validation reports/evidence and a reversible source hash manifest                                   |
+| ti-synthengine   | Native Sound Synthesis        | TiSynth 2.0 Sound interface and migration, native parameter reference, practical sound design/recipes, runnable example and TypeScript declarations |
 | ti-api           | Titanium API                  | 20 references for core/platform APIs and native modules                                                                                                                                              |
 | ti-guides        | SDK Fundamentals              | 16 references for setup, configuration, CLI and distribution                                                                                                                                         |
 | ti-howtos        | Native Integrations           | 18 references for platform features and integration workflows                                                                                                                                        |

package/agents/ti-pro.md

@@ -33,7 +33,7 @@ When invoked, research complex topics by consulting the applicable skills from t
 - `ti-ui` - UI/UX patterns, layouts, gestures
 - `ti-game-assets` - Visual and sound asset contracts, raster generation, alpha/export validation, synthesis variants and stereo coordination when assets are involved
 - `ti-game` - Native `ti.game` architecture and API when the module is declared
-- `ti-synthengine` - Native synthesis, held voices, identified sequences/tempo, selective processing, live controls and platform/evidence limits when the module is declared or requested
+- `ti-synthengine` - TiSynth 2.0 reusable Sound definitions, independent playback controls, direct-method migration, timing/processing units, synthesis and platform caveats when the module is declared or requested
 - `ti-admob-unified` - Official unified advertising/privacy/mediation module contract and provider setup when declared or requested
 - `ti-api`, `ti-guides`, `ti-howtos` - Exact Titanium APIs, SDK fundamentals and native integrations
 - `alloy-guides`, `alloy-howtos` - Alloy MVC, CLI, configuration and compiler workflows when the project is Alloy

package/commands/ti-audit.md

@@ -23,7 +23,7 @@ Project-type audit:
 Native-module audit:
 
 10. If the project declares `ti.game`, invoke `ti-game` — check for sprites moved from timers instead of native properties, levels sized from `Ti.Platform.displayCaps` instead of the `resize` event, sprites added one by one instead of in one array, and timers or sounds left running when the window closes.
-11. If the project declares `ti.synthengine`, invoke `ti-synthengine` — check exact option/pitch/envelope contracts, Boolean acceptance and positive sequence IDs, native successive-note scheduling, per-owner sequence cancellation, held-note release/cancellation and compatible live updates. Check shared tempo versus millisecond timing, category/send selection, overlap/priority budgets, one lifecycle owner, delayed startup and teardown. Consult current source notes before assuming platform metadata/envelopes or rejection diagnostics match; separate host/load reports from scoped physical listening acceptance.
+11. If the project declares `ti.synthengine`, invoke `ti-synthengine` — check the installed module's `version`, Sound preset structure, flat execution overrides, atomic definition edits, interpretation-specific option/pitch/envelope contracts and error handling. Distinguish finite Boolean acceptance from held/repetition/pattern controls or `false`; verify per-owner release/cancellation, pattern `end` listeners, shutdown invalidation and definition reuse. Check native timing versus JavaScript timers, finite duration versus pattern interval/length, `setProcessing` millisecond units versus direct processing units, shared tempo, category/send selection, variation, overlap/priority budgets and one lifecycle owner. Existing direct methods retain their identifiers/events/return contracts; audit against the path actually used. Consult practical platform caveats and separate runtime measurements from listening acceptance.
 
 12. If the project has game art/sound inventories or asset-generation/export workflows, invoke `ti-game-assets` — check contracts per set, master provenance/transparency, protected alpha cleanup, frame/pivot alignment, complete derived exports, parallax layers, sound variants and semantic event bindings. Consult `ti-game` and `ti-synthengine` equally in their applicable domains; do not require module installation or new sounds for an image-only task.
 

package/docs/examples.md

@@ -37,14 +37,21 @@ an audio or advertising module.
 
 ## Native synthesis — ti-synthengine
 
-- "Install the public TiSynthEngine 1.0.2 Android/iOS packages and start audio after the window layout settles."
-- "Move a held spatial motor, process only music with reverb, and stop one native sequence without cancelling unrelated sounds."
-- "Use native attack variation with local 1.1.0: bounded noise/filter ranges, deterministic seeds and an old-package fallback."
-- "Repeat this complete layered effect natively without changing its envelope, sweep timing or gains."
-
-Use the [synthesis skill](../skills/ti-synthengine/SKILL.md) for exact options,
-public downloads and scoped performance evidence. Native sequence scheduling,
-held-voice ownership and historical/private artifacts have distinct contracts.
+- "Install the public TiSynthEngine 2.0.0 Android/iOS packages and start audio after the window layout settles."
+- "Create a reusable laser Sound with flat per-shot pitch and position overrides."
+- "Move a held spatial motor through its note control, then release it on touch cancellation."
+- "Play music and a victory pattern independently; stop only the cue and wait for its end event before replacing it."
+- "Repeat this complete layered effect natively without changing envelopes, sweep timing or gains."
+- "Change a reusable preset with set(), reset an optional leaf with null and keep active executions unchanged."
+- "Migrate playTone and setMasterProcessing to Sound objects and setProcessing, preserving timing and reverb units."
+- "Add bounded native attack variation and diagnose voice pressure with enableStats/disableStats."
+
+Use the [synthesis skill](../skills/ti-synthengine/SKILL.md) for checked Sound
+presets, controls, public downloads and TypeScript declarations. Finite events,
+held notes, native repetitions and patterns have distinct returns and cleanup.
+The [upgrade guide](../skills/ti-synthengine/references/upgrade-2.0.0.md) maps
+supported direct methods to the Sound interface and explains `version` metadata
+and processing units.
 
 ## Advertising — ti-admob-unified
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@maccesar/titools",
-  "version": "5.2.4",
+  "version": "5.3.0",
   "description": "Titanium SDK skills and agents for AI coding assistants, including native game and sound synthesis modules",
   "main": "lib/index.js",
   "type": "module",

package/skills/ti-synthengine/SKILL.md

@@ -1,121 +1,91 @@
 ---
 name: ti-synthengine
-description: "Use when a Titanium app declares ti.synthengine in tiapp.xml, imports require('ti.synthengine'), or needs generated tones, chords, native sequences, sustained game motors, ADSR, sweeps, FM, resonant filters, noise, binaural spatialX/spatialY, held noteOn/noteOff/updateVoice, shared tempo, selective music/effects/ui/ambience processing, effectSend, priorities, chorus/delay/reverb/saturation, LFOs, sequenceend events, gain staging, statistics, bounded native per-attack variation, seeds or render-load diagnosis. Covers published Android/iOS 1.0.2 and local 1.1.0 candidates with public API 1.0.0. Not for audio-file decoding, sample streaming or unrelated synthesizers."
+description: "Use when a Titanium app declares ti.synthengine in tiapp.xml, imports require('ti.synthengine'), or needs TiSynth 2.0 createSound presets, play/noteOn controls, native repetitions or patterns, chords, ADSR, sweeps, FM, filters, noise, binaural spatialX/spatialY, attack variation, shared effects, gain staging or audio diagnostics. Also use for migrating direct playback calls to Sound objects, version metadata, processing units, TypeScript declarations and lifecycle cleanup. Not for audio-file decoding, sample streaming or unrelated synthesizers."
 ---
 
-# ti.synthengine — native sound synthesis for Titanium
-
-Act as an audio engineer and mobile sound designer. Translate the requested sound into acoustically reasoned JavaScript using the exact public contract.
-
-These references cover **published module 1.0.2 and local 1.1.0 candidates**,
-both with public API 1.0.0. They mirror the corrected official documentation
-at commit `b07c97c762be5905f132cecf33e9d60ea0c21316` (reviewed 2026-11-02).
-Native attack variation requires the local 1.1.0 packages; it is unavailable in
-the public 1.0.2 downloads. Read the [variation guide](references/native-variation.md)
-for both platform declarations, rebuilding and feature detection.
-Download matching [Android](https://github.com/macCesar/TiSynthEngine/releases/tag/android-1.0.2)
-and [iOS](https://github.com/macCesar/TiSynthEngine/releases/tag/ios-1.0.2)
-packages from the public [repository](https://github.com/macCesar/TiSynthEngine).
-Source/mirror hashes are in [source-snapshot.json](references/source-snapshot.json);
-artifact checksums and native findings are in [source notes](references/source-notes.md).
-The current [interactive example](assets/example/README.md) includes both helpers.
-Earlier private packages also used version 1.0.0: require current methods and
-install the official platform ZIPs rather than inferring capabilities from that
-version string or adding a second JavaScript audio scheduler.
+# ti.synthengine: sound design for Titanium
+
+Write JavaScript for the requested sound using TiSynth 2.0.0 on Android and iOS. Briefly explain the waveform, envelope, pitch and filter movement, and placement in the user's language. Prefer reusable Sound definitions and independent playback controls for new code. Existing direct methods remain supported. [source: references/sound-api.md] [source: references/upgrade-2.0.0.md]
 
 ## Required workflow
 
-Read the relevant references before writing or reviewing code. When updating the module or its documentation, compare with both native platforms and the shared DSP before synchronizing these mirrors; a snapshot is not an independent correctness oracle.
+Before writing or reviewing code, read the reference for the task. Use the Sound contract for new code and the direct API for exact native limits. A property list or TypeScript `number` alone cannot establish which combinations are valid.
 
 | Task | Read first |
 | --- | --- |
-| Any public method, option, default, return value or limit | [API](references/api.md) |
-| Download public releases, install, initialize, own or clean up an engine | [Guide](references/guide.md) |
-| Design an effect, instrument, reward, alarm or game motor | [Sound design](references/sound-design.md), [recipes](references/recipes.md), [examples](references/examples.md) |
-| Complete effect playback, playable adaptations, native repetition, importing layers and audition fidelity | [Instruments and effects](references/instruments-and-effects.md) |
-| Native per-attack variation, ranges, amount, seeds, chords, held starts and loop/revision behavior | [Variation](references/native-variation.md), [API](references/api.md) |
-| Variation memory/callback measurements, package scope and listening follow-up | [Variation verification](references/native-variation-validation.md) |
-| Historical variation design, feasibility and deferred API questions | [Historical proposal](references/native-variation-proposal.md); current behavior comes from the implemented guide |
-| Xylophone, memory pads, layered chords, FM instruments and interaction ownership | [Interaction recipes](references/recipes-interaction.md) |
-| Hold, edit, release or position a sustained voice | [API](references/api.md#noteonoptions), [advanced examples](references/advanced-examples.md#sustained-game-motor) |
-| Schedule simultaneous sequences, tempo, swing, edits and cancellation | [API transport](references/api.md#native-sequence-transport), [advanced examples](references/advanced-examples.md#native-sequence-with-chords-and-edits) |
-| Select categories, sends, shared effects and synchronized LFOs | [Processing API](references/api.md#setmasterprocessingoptions), [engine](references/audio-engine.md), [advanced examples](references/advanced-examples.md) |
-| Map headphone coordinates and stereo bypass | [Guide](references/guide.md#integrate-binaural-in-a-2d-app), [API](references/api.md) |
-| Interpret gain, clipping, statistics or render performance | [Recommendations](references/recommendations.md), [statistics](references/stats-performance.md), [engine](references/audio-engine.md) |
-| Diagnose rejection, silence, interruptions or glitches | [Troubleshooting](references/troubleshooting.md), [source notes](references/source-notes.md) |
-| Module 1.0.2 output, raw-profile migration, calibration, native CI and startup underrun limits | [Pipeline validation](references/audio-pipeline-validation.md), [engine](references/audio-engine.md), [source notes](references/source-notes.md) |
-| Accepted optimizations, rejected Apple runtime and physical performance limits | [Current performance review](references/performance-review.json), [engine](references/audio-engine.md), [source notes](references/source-notes.md) |
-| Android binaural performance correction and its listening/load limits | [Current Sim80 correction](references/android-sim80-correction.json), [source notes](references/source-notes.md), [unified host validation](references/unified-validation.json), [bypass comparison](references/unified-bypass-performance.json) |
-| Audit provenance and acceptance boundaries | [Snapshot](references/source-snapshot.json), [source notes](references/source-notes.md), [historical Studio report](references/studio-validation.json), [physical evidence](references/physical-validation.json), [Frontier measurements](references/frontier-physical-validation.json) |
-
-Cite factual guidance with `[source: references/<file>.md]`. If the relevant source cannot be read, prefix the claim with `FROM_MEMORY (unverified):`; do not invent Web Audio or other synthesizer option names.
-
-## Response contract
-
-Explain the waveform, envelope, pitch/filter motion and stereo choice briefly in the user's language. Include checked initialization if no engine owner exists, followed by focused production code. Comments and controls should explain meaningful sound choices. Obtain constants from the runtime:
+| Create reusable presets; play, hold, repeat, update or stop sounds | [Sound objects](references/sound-api.md) |
+| Migrate existing calls, metadata or processing units | [Upgrade to 2.0](references/upgrade-2.0.0.md) |
+| Install Android/iOS packages, initialize and own the engine | [Guide](references/guide.md) |
+| Check exact fields, ranges, defaults and supported direct methods | [API](references/api.md) |
+| Design a laser, instrument, reward, alarm or game motor | [Sound design](references/sound-design.md), [examples](references/examples.md) |
+| Preserve a complete effect or adapt it into a playable instrument | [Instruments and effects](references/instruments-and-effects.md) |
+| Retro cues, xylophone, memory pads, layered chords and interaction ownership | [Recipes](references/recipes.md), [interaction recipes](references/recipes-interaction.md) |
+| Held movement, native scores, effects and modulation examples | [Advanced examples](references/advanced-examples.md) |
+| Author bounded attack variation, amount, ranges and seeds | [Native variation](references/native-variation.md) |
+| Choose voice capacity, headroom, spatial processing or diagnostics | [Recommendations](references/recommendations.md), [audio engine](references/audio-engine.md) |
+| Diagnose rejection, silence, routes or platform differences | [Troubleshooting](references/troubleshooting.md), [source notes](references/source-notes.md) |
+| Check TypeScript signatures and narrow playback returns | [Declarations](assets/index.d.ts), [Sound objects](references/sound-api.md) |
+| Run the complete interactive example | [Example app](assets/example/README.md) |
+
+Cite factual guidance with `[source: references/<file>.md]`. If the required reference cannot be read, mark the claim `FROM_MEMORY (unverified):` and do not invent option names.
+
+## First sound
+
+Reuse the project's engine owner. If the project has none, start audio after the screen has settled and shut it down when its owner closes. Download matching [Android 2.0.0](https://github.com/macCesar/TiSynthEngine/releases/tag/android-2.0.0) and [iOS 2.0.0](https://github.com/macCesar/TiSynthEngine/releases/tag/ios-2.0.0) packages and follow the guide's installation/rebuild steps. The module requires Titanium SDK 13.2.0.GA+, Android compile API 35+, and iOS 15+. The Apple package includes Mac Catalyst. [source: references/guide.md]
 
 ```javascript
 const synth = require('ti.synthengine')
-const contract = synth.getDefaults()
-const WAVE = contract.waveTypes
-if (!synth.start({maxVoices: 32, maxSequences: 4,
-  mixingProfile: 'conservative', audioSession: 'ambient'})) {
-  throw new Error('Audio engine rejected startup')
+const contract = synth.getContract()
+if (!synth.start({ maxVoices: 16, maxSequences: 4,
+  mixingProfile: 'conservative', audioSession: 'ambient' })) {
+  throw new Error('Audio startup rejected')
 }
+const bell = synth.createSound({
+  sound: { waveType: contract.waveTypes.SINE, volume: 0.25, attack: 5, release: 120 },
+  playback: { type: 'tone', notes: ['A4'], duration: 400 }
+})
+if (!bell.play()) throw new Error('Bell rejected')
+bell.play({ notes: ['C5'], volume: 0.15 })
 ```
 
-Both local 1.1.0 platforms announce `capabilities.variation === true` and `variationSchemaVersion === 1`; require both before sending `variation`, even for amount zero. Published 1.0.2 does not accept that key. Android also announces native-sequence/processing/modulation flags and `limits.stepDurationMs`; iOS implements those operations without those Android-only metadata entries. Both return the sequence-capacity, priority and send limits. [source: references/api.md] [source: references/native-variation.md]
-
-Choose the actual required sequence capacity, 1–4; the snippet's four slots suit games with simultaneous music, effects and cues. One engine and render callback share up to 32 voices. Start after screen layout settles; the owning service/window shuts down on teardown. On iOS, `ambient` respects silent mode and mixes with other apps; `playback` is the default and ignores silent mode. Profile, voice/sequence capacity and session require shutdown before changing them. [source: references/api.md]
-
-## Scheduling contract
-
-- `playTone` is one timed event, `playChord` one simultaneous atomic chord, and `noteOn`/`noteOff`/`updateVoice` own sustained voices. `playSequence` is the only successive-sound scheduler. Do not add aliases or JavaScript note timers.
-- `playSequence(options)` returns a positive identifier or `0`. `updateSequence({sequenceId,...changes})`, `stopSequence({sequenceId})` and `setTempo({bpm})` return Boolean acceptance. `getSequenceState({sequenceId})` returns applied revision/position or `null` for unknown/retired IDs. Acceptance can precede callback application.
-- Sequence IDs do not repeat over module lifetime, including shutdown/start. Keep the accepted ID and cancel only the owner's sequence. An accepted stop does not immediately free capacity: coalesce replacement requests and publish the latest complete score after its matching `sequenceend`. A delayed event for an old ID must not change the new owner.
-- `setTempo({bpm})` accepts 20–300, initially 120. It changes on the next block while conserving musical position. Synced delays/LFOs follow this tempo; free controls keep milliseconds/hertz.
-- `timeUnit` is fixed for a sequence: `beats` by default, or `ms`. `stepDuration` defaults to 0.25 beats or 100 ms. `loop` defaults to false; circular Studio patterns explicitly pass true.
-- Up to 512 steps each carry exactly one of MIDI `notes` (12–119), `frequencies`, or `rest:true`. Pitch arrays hold 1–32 values and permit duplicates for unison. Root shaping belongs in `voice`; per-step shaping belongs in `overrides`.
-- Step `duration` changes the interval until the next attack. `gate`, initially 0.8, places release within that effective interval. Explicit `length` replaces gate and may overlap later attacks. Intervals and lengths follow the sequence time unit; ADSR remains in milliseconds without a sequence interval budget. Sweeps reach their target at note length and hold it during release.
-- Swing −0.75…0.75 shifts `swing * min(A,B)` within a pair and preserves its total. Structural edits enter next step; swing next pair. Modes are normal/up/down/updown; rests participate only in normal mode.
-- `sequenceend` carries `{sequenceId,reason:'completed'|'stopped'}` outside audio render. It does not establish audible silence: voice release and effect tails may remain.
-
-Preserve migrated score timing deliberately: a former total envelope of 150 ms with 25 ms release becomes `length:125` in a millisecond sequence, with `release:25`. Keep onset intervals separate. [source: references/api.md]
-
-## Native attack variation
-
-Variation samples compatible bounded parameters once per admitted attack, preserving authored envelopes, cadence, routes and voice counts. Read all eight source-dependent bounds before constructing ranges. Amount interpolates linearly from the authored value; pitch uses cents. Keep application gain consistent in authored volume and volume-range endpoints.
-
-An explicit seed repeats standalone selections; native loops advance their stream across attacks. Chords sample independently by voice ordinal. Sustained voices retain their selection through release; `updateVoice` rejects `variation`. Step dictionaries replace the whole inherited dictionary. Sequence revisions affect future attacks; root omission retains variation, and disabling inherited and explicit-step variation requires appropriate amount-zero replacements. Never add a JavaScript random sampler or note timer. Seeds reproduce parameters, not cross-platform noise PCM. [source: references/native-variation.md]
+`getContract().version` and `getDefaults().version` report the installed module version. Use `getContract().waveTypes` for constants and check required capabilities. On iOS, `ambient` respects silent mode and mixes with other apps; the default `playback` session ignores silent mode. [source: references/sound-api.md] [source: references/api.md]
 
-## Voices, routes and continuous controls
+## Definitions and executions
 
-`bus` selects `music`, `effects` (default), `ui` or `ambience`. `setMasterProcessing({applyTo:[...]})` selects processed categories, initially all four; an empty array selects none. An explicit `effectSend:0…1` overrides the category selection for that voice. There is one shared chorus/delay/reverb/saturation chain. Input gain and master volume remain global. Selected audio receives processing, rejoins dry audio, and passes one final stereo sample-peak protector. Effects and saturation start disabled. Disable closes input and retains bounded tails up to 30 seconds; panic invalidates histories. [source: references/api.md]
+- Store synthesis and routing in `sound`; store pitch, type and timing in `playback`. Pitch uses `notes` or `frequencies` arrays. When supplied, tone/held/repetition pitch arrays contain exactly one pitch; chords accept 1 to 32. [source: references/sound-api.md]
+- `createSound()` does not start a voice. `getPreset()` returns a detached copy. Use `Sound.set({ sound, playback })` to recursively merge objects, replace whole arrays and validate the complete change atomically for future executions. `null` removes an optional leaf when the result remains valid. Executions already playing keep their revisions. [source: references/sound-api.md]
+- Pass flat temporary overrides to `play(changes)` and `noteOn(changes)`. These calls reject nested preset dictionaries. Switching between `notes` and `frequencies` replaces the previous pitch source. Supplying both throws. [source: references/sound-api.md]
+- An explicit type on the call takes precedence over the preset's declared type. Otherwise, `steps` selects a pattern, multiple pitches select a chord, and one pitch selects a tone. Repetition and held playback need an explicit type, or `noteOn()` for held execution. A type change does not discard incompatible fields. [source: references/sound-api.md]
+- Invalid Sound configurations throw descriptive errors. Operational rejection returns `false`. Do not silently clamp values or retry malformed recipes. Direct methods retain their own return contracts. [source: references/sound-api.md]
 
-Sustained IDs are positive app-owned integers. Release on key up, touch cancellation, pause and teardown. Handle rejected release by retrying twice at 16 ms, then shut down/report if it still fails. These retry timers are lifecycle/error recovery, not a musical clock. Ended/stolen IDs accept edits as no-ops. [source: references/api.md]
+## Playback and ownership
 
-Compatible `updateVoice` fields include frequency, volume, vibrato, resonant filter targets, pulse width, FM, modulations, `noiseRate`, `lowPassHz`, stereo/spatial position and `effectSend`. Transitions take 10 ms and preserve phase, spatial history and the current envelope. `noiseRate:0` is white noise; `lowPassHz:0` bypasses its one-pole filter. Spatial updates require a voice started spatially; stereo `pan` applies to a stereo voice. Do not combine spatial coordinates with stereo pan fields. [source: references/api.md]
+| Interpretation | Accepted result | Owner's responsibility |
+| --- | --- | --- |
+| `tone` / `chord` | `true` | Finite event finishes naturally; no per-event control |
+| `held` / `noteOn()` | Note control | `update()` compatible live fields; `noteOff()` on release/cancel |
+| `repeat` | Repetition control | `update()` future attacks; `stop()` future repetition |
+| `pattern` | Pattern control | `update()`, `getState()`, `stop()`; own its `end` listener |
 
-`priority:0…3`, initially 0, controls eligible replacement under the shared voice pool. Higher priorities remain protected. Chords are admitted or discarded completely; there are no reserved per-category quotas. Gain is fixed per event, with initial chord compensation. Starting unrelated voices does not normalize earlier voices. [source: references/api.md]
+Every execution can return `false`. Check the result type before calling control methods, and keep each control with the interaction that created it. Shutdown invalidates controls; reusable definitions survive shutdown/start. Use `stopAll()` for global panic. [source: references/sound-api.md]
 
-Module 1.0.2 retains zero samples at final output: stereo-linked peak protection acts immediately, recovers exponentially with a 100 ms time constant and uses ceilings of 0.85, or 0.70 for `speakerSafe`. These are sample ceilings, not speaker or inter-sample guarantees; overload changes waveform shape. Master volume uses an independent linear 10 ms ramp on both platforms. iOS now applies the documented `raw` gain, so review existing raw mixes when upgrading. Native Android and Apple callback checks run in CI; device latency, listening and extended maximum-load acceptance remain separate. [source: references/audio-pipeline-validation.md]
+Release held notes when a touch is cancelled, the app pauses or the owner closes. If release is rejected, follow the guide's bounded retry policy. An accepted release retires the control. Compatible live edits preserve phase and envelope through native 10 ms transitions. Waveform, variation, routing category and attack/release cannot change through live note updates. [source: references/sound-api.md] [source: references/guide.md]
 
-`stopAll()` stops every native sequence, cancels future attacks, fades voices and invalidates effect histories. Use `stopSequence({sequenceId})` for one owner’s sequence. Android closes the engine on root activity destruction; explicit owner teardown remains required. Idle event polling stops when no control work remains and does not schedule musical attacks. [source: references/api.md] [source: references/guide.md] [source: references/audio-engine.md]
+Repetitions use the original finite renderer. Their integer `interval` runs from 1 to 60,000 ms, independently of tempo. An update keeps the next deadline; its new interval controls the following gap. `stop()` lets already admitted attacks finish. Patterns use the native clock, with up to 512 steps and 1 to 4 configured slots. Coalesce replacement scores while capacity is occupied and wait for the owned control's `end` event. `{ reason: 'completed' | 'stopped' }` marks transport retirement; release and effect tails may remain audible. [source: references/sound-api.md]
 
-## Sound and validation rules
+## Timing, processing and sound fidelity
 
-- Closed option dictionaries reject unknown keys, wrong types, non-finite/out-of-range values and fractional integer fields. Check acceptance at meaningful boundaries; never silently clamp native options.
-- A tone uses at most one of note/frequency; a chord uses exactly one notes/frequencies array. Tone/chord note names differ from sequence MIDI integers.
-- Timed tone/chord `duration` includes release: explicit attack must be shorter, release must fit after attack, and attack+decay must fit. `sustain < 1` requires decay. Held/sequence ADSR has its own documented rules.
-- FM requires sine; enabled filter fields require a filter type. `fmDepthEnd:0` is a real target, so omit it to disable a sweep. Plain tone FM ratio requires active depth; held/sequence FM-target modulation can start at zero depth.
-- WAVETABLE needs 2–64 samples in −1…1. `bitDepth` is 0 or integer 2–16. Pulse width shapes square voices. Read the exact discontinuous ranges and source rules in the API.
-- Up to two native sine/triangle LFOs target filterHz, pulseWidth or fmDepth. Free rates and tempo sync are distinct. Empty modulations disables them; omission on update preserves them.
-- Use noise for impacts/wind, square for retro rewards, triangle for bass/plucks, sine FM for bells/keys, and filtered saw/noise for moving textures. Keep gains modest enough for release overlap and coherent unison. Listen on the actual speaker/headphones before approving timbre.
+- Finite `duration` includes release; ADSR always uses milliseconds. Pattern root/step `interval` controls attack spacing and `length` controls sounding length, in beats or milliseconds according to `timeUnit`. Preserve those distinctions when adapting recipes. [source: references/sound-api.md]
+- `setVolume(number)` and `setTempo(number)` return Boolean acceptance. Tempo ranges from 20 to 300 BPM. `setProcessing()` uses milliseconds for both delay `time` and reverb `decay`; direct `setMasterProcessing()` retains seconds for reverb decay. Never copy its numeric decay unchanged into the new method. [source: references/upgrade-2.0.0.md]
+- `sound.bus` selects `music`, `effects`, `ui` or `ambience`; processing `applyTo` selects categories, and explicit `effectSend` overrides that selection. There is one shared chain. Keep layer gains and grouped chord admission/compensation when translating effects. [source: references/sound-api.md] [source: references/instruments-and-effects.md]
+- One engine shares up to 32 voices. Reserve overlap and release capacity; repeating attacks can be dropped under admission pressure. Higher priorities protect voices without per-category quotas. [source: references/api.md]
+- Omit spatial coordinates for stereo; two zeros still enable binaural center. Spatial coordinates conflict with stereo pan fields. A held voice must start spatially to accept live position changes. Headphone localization varies by listener and spectrum. [source: references/guide.md]
+- Native `sound.variation` samples bounded parameters once per admitted attack. Check capability/schema, source-dependent ranges and seed behavior; seeds reproduce parameter selection, not cross-platform noise PCM. Keep authored timing, envelopes and gains. [source: references/native-variation.md]
 
-Binaural coordinates span a headphone front plane. Omit both spatial keys to bypass; two zeros still enable binaural center. Map app percentages explicitly and preserve pitch/envelope recipes. Height perception depends on the listener and sound spectrum; output remains stereo without rear sources, room reflections or head tracking. [source: references/api.md]
+## Compatibility and diagnostics
 
-Timed zero attack/release and rejection diagnostics currently differ between native platforms. Check API acceptance directly; do not infer sample-identical envelopes or a complete rejection tally from validator parity. Read [source notes](references/source-notes.md) for independently rechecked findings. [source: references/api.md]
+Use [the upgrade guide](references/upgrade-2.0.0.md) when retaining direct `playTone`, `playChord`, `repeatTone`, sequence or positive-ID held methods. Their identifiers, event names and partial-update behavior remain distinct from Sound controls. Older binaries require method/capability detection; 1.0.2 lacks repetition and variation. Never send unsupported closed-dictionary keys, including disabled variation. [source: references/api.md] [source: references/native-variation.md]
 
-Diagnostics are opt-in. Preserve unavailable/null readings; poll UI slowly and clean up its timer. Render load is callback work divided by deadline, not app CPU. Historical host reports, validator parity and hash equality do not establish current physical real-time or listening acceptance. Keep technical results and César's auditory acceptance separate. [source: references/audio-engine.md] [source: references/source-notes.md]
+Use `enableStats()` / `disableStats()` for optional diagnostics. Poll slowly, clear the owner's timer and keep unavailable readings as `null`. Render load measures callback work relative to its deadline. It does not measure app CPU or establish listening acceptance. Check platform caveats before assuming identical envelopes or rejection counters. Listen on the target speaker/headphones before approving timbre. [source: references/audio-engine.md] [source: references/source-notes.md]
 
-Use `ti-game` for native movement/physics and `ti-game-assets` for related visual/audio asset production. Audio scheduling remains in TiSynthEngine; do not change gameplay or install on physical devices without the task's authorization.
+Use `ti-game` for native gameplay and `ti-game-assets` for related visual/audio asset preparation.