@maccesar/titools 5.2.3 → 5.2.5
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +96 -87
- package/docs/examples.md +10 -3
- package/package.json +2 -2
- package/skills/ti-synthengine/SKILL.md +50 -18
- package/skills/ti-synthengine/assets/example/README.md +19 -6
- package/skills/ti-synthengine/assets/example/app.js +69 -12
- package/skills/ti-synthengine/assets/index.d.ts +106 -0
- package/skills/ti-synthengine/references/advanced-examples.md +34 -9
- package/skills/ti-synthengine/references/api.md +327 -246
- package/skills/ti-synthengine/references/audio-engine.md +28 -14
- package/skills/ti-synthengine/references/audio-pipeline-validation.md +1 -1
- package/skills/ti-synthengine/references/examples.md +5 -5
- package/skills/ti-synthengine/references/guide.md +40 -21
- package/skills/ti-synthengine/references/instruments-and-effects.md +164 -0
- package/skills/ti-synthengine/references/native-tone-repetition-validation.md +59 -0
- package/skills/ti-synthengine/references/native-variation-proposal.md +182 -0
- package/skills/ti-synthengine/references/native-variation-validation.md +63 -0
- package/skills/ti-synthengine/references/native-variation.md +285 -0
- package/skills/ti-synthengine/references/recipes-interaction.md +3 -1
- package/skills/ti-synthengine/references/recipes.md +3 -2
- package/skills/ti-synthengine/references/recommendations.md +5 -5
- package/skills/ti-synthengine/references/sound-design.md +18 -16
- package/skills/ti-synthengine/references/source-notes.md +54 -37
- package/skills/ti-synthengine/references/source-snapshot.json +188 -144
- package/skills/ti-synthengine/references/stats-performance.md +1 -1
- package/skills/ti-synthengine/references/troubleshooting.md +43 -35
package/README.md
CHANGED
|
@@ -83,15 +83,15 @@ Why NPM?
|
|
|
83
83
|
|
|
84
84
|
### Which option should I use?
|
|
85
85
|
|
|
86
|
-
| | Plugin (Option A)
|
|
87
|
-
| ------------------- |
|
|
88
|
-
| **Claude Code** | Recommended
|
|
89
|
-
| **Gemini CLI** | Not available
|
|
90
|
-
| **Codex CLI** | Not available
|
|
91
|
-
| **Knowledge Index** | Not included
|
|
92
|
-
| **Auto-updates** | Marketplace (opt-in, enable in `/plugin`)
|
|
93
|
-
| **Slash commands** | `/ti-check`, `/ti-new-screen`, `/ti-audit`
|
|
94
|
-
| **Session hook** | Auto-detects Titanium projects (Alloy/Classic, PurgeTSS, `ti.game`, `ti.synthengine`) | Auto-update only
|
|
86
|
+
| | Plugin (Option A) | CLI (Option B) |
|
|
87
|
+
| ------------------- | ------------------------------------------------------------------------------------- | ---------------------------------- |
|
|
88
|
+
| **Claude Code** | Recommended | Supported |
|
|
89
|
+
| **Gemini CLI** | Not available | Supported |
|
|
90
|
+
| **Codex CLI** | Not available | Supported |
|
|
91
|
+
| **Knowledge Index** | Not included | Included (`titools sync`) |
|
|
92
|
+
| **Auto-updates** | Marketplace (opt-in, enable in `/plugin`) | SessionStart hook (daily) |
|
|
93
|
+
| **Slash commands** | `/ti-check`, `/ti-new-screen`, `/ti-audit` | Same three (`~/.claude/commands/`) |
|
|
94
|
+
| **Session hook** | Auto-detects Titanium projects (Alloy/Classic, PurgeTSS, `ti.game`, `ti.synthengine`) | Auto-update only |
|
|
95
95
|
|
|
96
96
|
Having both installed is fine: the CLI detects an enabled marketplace plugin and skips its own skill symlinks and command copies, so nothing shows up twice. `titools doctor` reports which channel is serving Claude Code.
|
|
97
97
|
|
|
@@ -148,11 +148,11 @@ The knowledge index provides always-available context (the documentation map). S
|
|
|
148
148
|
|
|
149
149
|
Together they work like this:
|
|
150
150
|
|
|
151
|
-
| Your Question | Knowledge Index Provides | Skills Activate
|
|
152
|
-
| ------------------------------- | ------------------------------- |
|
|
153
|
-
| "Create a login screen" | Context about project structure | `ti-expert`, `ti-ui`
|
|
154
|
-
| "Optimize ListView performance" | Points to docs location | `ti-ui` reads specific files
|
|
155
|
-
| "Implement push notifications" | API reference paths | `ti-expert`, `ti-howtos`
|
|
151
|
+
| Your Question | Knowledge Index Provides | Skills Activate |
|
|
152
|
+
| ------------------------------- | ------------------------------- | ---------------------------- |
|
|
153
|
+
| "Create a login screen" | Context about project structure | `ti-expert`, `ti-ui` |
|
|
154
|
+
| "Optimize ListView performance" | Points to docs location | `ti-ui` reads specific files |
|
|
155
|
+
| "Implement push notifications" | API reference paths | `ti-expert`, `ti-howtos` |
|
|
156
156
|
|
|
157
157
|
You do not need to explicitly invoke skills. The AI detects when to use them based on your question.
|
|
158
158
|
|
|
@@ -164,27 +164,27 @@ The knowledge index is based on the latest Titanium SDK documentation. If your p
|
|
|
164
164
|
|
|
165
165
|
## Skills overview
|
|
166
166
|
|
|
167
|
-
| Skill
|
|
168
|
-
|
|
|
169
|
-
| ti-reuse-first
|
|
170
|
-
| ti-expert
|
|
171
|
-
| purgetss
|
|
172
|
-
| ti-ui
|
|
173
|
-
| ti-game
|
|
174
|
-
| ti-game-assets
|
|
175
|
-
| ti-synthengine
|
|
176
|
-
| ti-admob-unified | Advertising, privacy and mediation
|
|
177
|
-
| ti-api
|
|
178
|
-
| ti-guides
|
|
179
|
-
| ti-howtos
|
|
180
|
-
| alloy-guides
|
|
181
|
-
| alloy-howtos
|
|
167
|
+
| Skill | Purpose | Best For |
|
|
168
|
+
| ---------------- | ----------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
169
|
+
| ti-reuse-first | Reuse before writing new code | Whether it should exist and what already does it; duplication sweeps |
|
|
170
|
+
| ti-expert | Architecture and implementation | Starting point for most tasks |
|
|
171
|
+
| purgetss | Alloy styling + asset automation | Utility classes; Alloy/Classic branding, images, colors, fonts and modules |
|
|
172
|
+
| ti-ui | UI/UX patterns | Complex layouts, ListViews, platform UI |
|
|
173
|
+
| ti-game | 2D games with the `ti.game` module | Sprites, physics, tile maps, HUDs, camera, focused keyboard/mouse/gamepad actions, Apple Metal/Catalyst |
|
|
174
|
+
| ti-game-assets | Visual and sound assets | Image generation/editing, synthesis variants, stereo placement, alpha cleanup, manifests, parallax and complete exports |
|
|
175
|
+
| ti-synthengine | Sound design with `ti.synthengine` | Tones, finite-tone repetition, chords, retro/UI effects, alarms, sweeps, ADSR, filters, FM, binaural positioning, held voices, native sequences, master effects, LFOs, statistics, bounded attack variation, seeds, TypeScript declarations, instrument/effect fidelity and troubleshooting |
|
|
176
|
+
| ti-admob-unified | Advertising, privacy and mediation | Official `ti.admob.unified` guides, copy-ready library, banners/fullscreen, UMP/ATT and selected-provider configuration |
|
|
177
|
+
| ti-api | Complete Titanium API reference | Looking up properties, methods, events |
|
|
178
|
+
| ti-guides | SDK fundamentals | tiapp.xml, Hyperloop, distribution, JDK/Xcode compatibility, release notes |
|
|
179
|
+
| ti-howtos | Native feature integration | Location, push, media, platform APIs |
|
|
180
|
+
| alloy-guides | Alloy MVC framework reference | Controllers, models, views, widgets |
|
|
181
|
+
| alloy-howtos | Alloy CLI, configuration, debugging | alloy.jmk, config.json, custom XML tags |
|
|
182
182
|
|
|
183
183
|
Notes:
|
|
184
184
|
- 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.
|
|
185
185
|
- `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.
|
|
186
186
|
- `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.
|
|
187
|
-
- `ti-synthengine` translates sound requests into checked JavaScript for
|
|
187
|
+
- `ti-synthengine` translates sound requests into checked JavaScript for published Android/iOS `ti.synthengine` 1.1.0 / API 1.1.0, with compatibility guidance for 1.0.2 / API 1.0.0. Its 25-method surface includes finite-tone repetition, held voices, identified native sequences, tempo, categories/sends, master effects, live controls and diagnostics. Two curated recipe guides cover retro cues and interactive instruments. Official-source mirrors, validation reports, bundled examples, TypeScript declarations and raw evidence retain provenance; verified corrections are applied to official source prose before mirroring. Source notes distinguish reviewed source commits, published artifacts, platform differences and scoped listening/performance evidence.
|
|
188
188
|
- `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.
|
|
189
189
|
- 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).
|
|
190
190
|
- `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.
|
|
@@ -195,12 +195,12 @@ Notes:
|
|
|
195
195
|
|
|
196
196
|
The Titanium documentation was rewritten during 2026, and v5.0.0 moved TiTools onto the new sources. No skill, command or flag was renamed and the references answer the same questions. What changed is what they are checked against.
|
|
197
197
|
|
|
198
|
-
| Source
|
|
199
|
-
|
|
200
|
-
| [`tidev/titanium-sdk`](https://github.com/tidev/titanium-sdk) → `apidoc/*.yml`
|
|
201
|
-
| [`tidev/titaniumsdk.com`](https://github.com/tidev/titaniumsdk.com) → `content/docs/` | `ti-guides`, `ti-howtos`, `alloy-guides`, `alloy-howtos` | The rewritten guides, and what [titaniumsdk.com](https://titaniumsdk.com) serves.
|
|
202
|
-
| `tidev/titaniumsdk.com` → `registry/sdk/<version>/`
|
|
203
|
-
| [`tidev/titanium-docs`](https://github.com/tidev/titanium-docs)
|
|
198
|
+
| Source | Feeds | Why it is the one |
|
|
199
|
+
| ------------------------------------------------------------------------------------- | -------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------- |
|
|
200
|
+
| [`tidev/titanium-sdk`](https://github.com/tidev/titanium-sdk) → `apidoc/*.yml` | `ti-api` | The API definitions the SDK team edits. Every other copy of the API is compiled from these. |
|
|
201
|
+
| [`tidev/titaniumsdk.com`](https://github.com/tidev/titaniumsdk.com) → `content/docs/` | `ti-guides`, `ti-howtos`, `alloy-guides`, `alloy-howtos` | The rewritten guides, and what [titaniumsdk.com](https://titaniumsdk.com) serves. |
|
|
202
|
+
| `tidev/titaniumsdk.com` → `registry/sdk/<version>/` | `ti-api`, as a cross-check | The API compiled per published release. It answers which version actually shipped an API, which the YAML alone cannot. |
|
|
203
|
+
| [`tidev/titanium-docs`](https://github.com/tidev/titanium-docs) | all five, as an archive | The previous corpus, now frozen. Kept for what the rewrite left out. |
|
|
204
204
|
|
|
205
205
|
### Why the API comes from the SDK
|
|
206
206
|
|
|
@@ -222,12 +222,12 @@ In addition to skills, this repository includes sub-agents for Claude Code. Sub-
|
|
|
222
222
|
|
|
223
223
|
Deep-dive research specialist that can combine the complete 13-skill TiTools catalog.
|
|
224
224
|
|
|
225
|
-
| Aspect | Details
|
|
226
|
-
| ---------------- |
|
|
227
|
-
| Location | `~/.claude/agents/ti-pro.md`
|
|
228
|
-
| Model | Sonnet (comprehensive analysis)
|
|
229
|
-
| Tools | Read, Grep, Glob, Bash
|
|
230
|
-
| Preloaded Skills | All 13 skills registered in `lib/config.js`
|
|
225
|
+
| Aspect | Details |
|
|
226
|
+
| ---------------- | ------------------------------------------- |
|
|
227
|
+
| Location | `~/.claude/agents/ti-pro.md` |
|
|
228
|
+
| Model | Sonnet (comprehensive analysis) |
|
|
229
|
+
| Tools | Read, Grep, Glob, Bash |
|
|
230
|
+
| Preloaded Skills | All 13 skills registered in `lib/config.js` |
|
|
231
231
|
|
|
232
232
|
When to use the agent vs skills:
|
|
233
233
|
|
|
@@ -306,16 +306,16 @@ You do not need to call skills explicitly. The AI reads skill descriptions and l
|
|
|
306
306
|
|
|
307
307
|
All skills include automatic project detection to ensure compatibility:
|
|
308
308
|
|
|
309
|
-
| Skill
|
|
310
|
-
|
|
|
311
|
-
| purgetss
|
|
312
|
-
| ti-reuse-first
|
|
313
|
-
| ti-expert
|
|
314
|
-
| ti-ui
|
|
315
|
-
| ti-game
|
|
316
|
-
| ti-game-assets
|
|
317
|
-
| ti-admob-unified | ti.admob.unified and mediation | Declared core/complement modules or requested ad/privacy/provider integration
|
|
318
|
-
| ti-synthengine
|
|
309
|
+
| Skill | What It Detects | How It Works |
|
|
310
|
+
| ---------------- | ------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------- |
|
|
311
|
+
| purgetss | PurgeTSS mode and project type | Checks PurgeTSS markers, then separates Alloy utilities from Classic standalone commands |
|
|
312
|
+
| ti-reuse-first | Existing app structure | Searches `app/lib/`, `app/controllers/`, `app/widgets/`, `purgetss/config.cjs` before proposing anything new |
|
|
313
|
+
| ti-expert | Alloy vs Classic | Checks for `app/` (Alloy) vs `Resources/` (Classic) structure |
|
|
314
|
+
| ti-ui | Titanium projects | Checks for `tiapp.xml` (both Alloy and Classic) |
|
|
315
|
+
| ti-game | ti.game module | Checks for `<module>ti.game</module>` in `tiapp.xml` or `require('ti.game')` |
|
|
316
|
+
| ti-game-assets | Game art/sound workflows | Reads asset inventories, generation/export workflows and requested visual or sound assets; no module install required for drawings |
|
|
317
|
+
| ti-admob-unified | ti.admob.unified and mediation | Declared core/complement modules or requested ad/privacy/provider integration |
|
|
318
|
+
| ti-synthengine | ti.synthengine module | Checks for `<module>ti.synthengine</module>` in `tiapp.xml` or `require('ti.synthengine')` |
|
|
319
319
|
|
|
320
320
|
Why this matters:
|
|
321
321
|
- PurgeTSS suggestions are provided when its project markers are detected or the user explicitly requests a standalone command
|
|
@@ -326,14 +326,14 @@ Why this matters:
|
|
|
326
326
|
|
|
327
327
|
`ti-reuse-first` runs first — it decides whether there is anything to build — and `ti-expert` is the architectural starting point for what survives that question. Together they coordinate the rest of the bundled catalog:
|
|
328
328
|
|
|
329
|
-
| Scope
|
|
330
|
-
|
|
|
331
|
-
| Whether to build it at all | `ti-reuse-first`, first
|
|
332
|
-
| Architecture and UI
|
|
333
|
-
| Game assets
|
|
334
|
-
| Native modules
|
|
335
|
-
| Exact SDK/API guidance
|
|
336
|
-
| Alloy MVC and tooling
|
|
329
|
+
| Scope | Skills |
|
|
330
|
+
| -------------------------- | --------------------------------------------------------------------------- |
|
|
331
|
+
| Whether to build it at all | `ti-reuse-first`, first |
|
|
332
|
+
| Architecture and UI | `ti-expert`, `ti-ui`, `purgetss` when configured |
|
|
333
|
+
| Game assets | `ti-game-assets` for visual and sound creation, preparation and integration |
|
|
334
|
+
| Native modules | `ti-game`, `ti-synthengine`, `ti-admob-unified` when declared or requested |
|
|
335
|
+
| Exact SDK/API guidance | `ti-api`, `ti-guides`, `ti-howtos` |
|
|
336
|
+
| Alloy MVC and tooling | `alloy-guides`, `alloy-howtos` for Alloy projects |
|
|
337
337
|
|
|
338
338
|
All thirteen ship with TiTools; no second skill package is required.
|
|
339
339
|
|
|
@@ -546,18 +546,19 @@ frequency and pause/audio/input ownership remain application policies.
|
|
|
546
546
|
|
|
547
547
|
### ti-synthengine
|
|
548
548
|
|
|
549
|
-
Sound design and synthesis with the public native `ti.synthengine` 1.0
|
|
549
|
+
Sound design and synthesis with the public native `ti.synthengine` 1.1.0 release (public API 1.1.0) for Android and iOS. It adds `repeatTone`, `updateTone`, `stopTone`, `updateNote`, `enableStats` and `disableStats`, plus capability-gated native attack variation. Published 1.0.2 / API 1.0.0 remains documented for compatibility; it does not support repetition or variation. Read the [skill entry point](skills/ti-synthengine/SKILL.md) for task routing, exact API references and source provenance.
|
|
550
550
|
|
|
551
551
|
Public repository: [macCesar/TiSynthEngine](https://github.com/macCesar/TiSynthEngine).
|
|
552
|
-
Download [Android 1.0
|
|
553
|
-
and [iOS 1.0
|
|
552
|
+
Download [Android 1.1.0](https://github.com/macCesar/TiSynthEngine/releases/tag/android-1.1.0)
|
|
553
|
+
and [iOS 1.1.0](https://github.com/macCesar/TiSynthEngine/releases/tag/ios-1.1.0),
|
|
554
554
|
copy the ZIPs into the Titanium app root and follow the [installation guide](skills/ti-synthengine/references/guide.md).
|
|
555
555
|
Requires Titanium SDK 13.2.0.GA+, Android compile API35+, and iOS 15+; the Apple package also supports Mac Catalyst.
|
|
556
556
|
|
|
557
557
|
When it activates:
|
|
558
558
|
- `tiapp.xml` declares `ti.synthengine`, or code calls `require('ti.synthengine')`
|
|
559
559
|
- Generated UI/game cues, instruments, alarms, chords, percussion, sweeps or binaural headphone placement
|
|
560
|
-
-
|
|
560
|
+
- Finite-tone repetition and future-attack edits, held voices, simultaneous native sequences, shared tempo, selective effects/sends, priorities or live voice controls
|
|
561
|
+
- Bounded native attack variation, deterministic seeds, complete effect playback or playable instrument adaptations
|
|
561
562
|
- Rejected calls, startup glitches, voice/queue diagnostics, render-load measurements or source/artifact compatibility questions
|
|
562
563
|
|
|
563
564
|
Example prompts:
|
|
@@ -568,20 +569,28 @@ Example prompts:
|
|
|
568
569
|
"Run music and a victory cue as independent native sequences, then cancel only the cue."
|
|
569
570
|
"Apply reverb to music while keeping UI dry, and change the global tempo."
|
|
570
571
|
"Explain what the Android Sim80 headphone result proves about performance."
|
|
572
|
+
"Vary repeated impacts natively on public 1.1.0 and retain a clean fallback on published 1.0.2."
|
|
573
|
+
"Repeat the original swept shot with repeatTone, edit its interval and stop future attacks without truncating sounding shots."
|
|
574
|
+
"Use updateNote and enableStats/disableStats, and check this recipe against the bundled TypeScript declarations."
|
|
571
575
|
```
|
|
572
576
|
|
|
573
577
|
Key rules:
|
|
578
|
+
- 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
|
|
579
|
+
- Preserve complete effects and layer gains when adapting or repeating them; read [instruments and effects](skills/ti-synthengine/references/instruments-and-effects.md)
|
|
574
580
|
- Read constants and exact ranges from the API; strict option dictionaries reject invalid fields or conflicting pitch sources
|
|
575
581
|
- Timed tone/chord `duration` includes release. Native sequence intervals and note lengths are separate; held voices release through their IDs
|
|
576
|
-
-
|
|
582
|
+
- Use `repeatTone` for the original finite-tone renderer and `playSequence` for ordered scores; retain each accepted ID. `stopTone` preserves admitted finite attacks, while `stopSequence` releases its emitted voices. `stopAll()` is global panic
|
|
583
|
+
- Native repetition requires its capability and methods, integer `intervalMs` 1–60,000, and capacity for overlaps. Its 32 slots are independent of sequence capacity; all attacks share the voice pool
|
|
584
|
+
- `updateTone` preserves the next deadline, validates merged recipes and changes future attacks. Independent gameplay calls and intentionally JavaScript-timed finite bursts remain supported; clear app-owned timers during teardown
|
|
585
|
+
- Use `updateNote`, `enableStats` and `disableStats` in new 1.1.0 code. `updateVoice` and `setStatsEnabled(Boolean)` remain deprecated equivalent aliases; feature-detect the aliases when supporting 1.0.2
|
|
577
586
|
- `setTempo` drives beat-based transport and synchronized modulation; millisecond sequences keep fixed timing
|
|
578
587
|
- `bus`/`applyTo` select processed categories; explicit `effectSend` overrides that selection. One shared chain and final limiter remain global
|
|
579
588
|
- Held spatial position, noise clock and one-pole cutoff support compatible 10 ms updates. A stereo voice cannot become spatial through an update
|
|
580
589
|
- Omit both spatial coordinates for stereo; zero coordinates enable binaural center. Do not combine binaural coordinates with stereo pan fields
|
|
581
|
-
- Start after layout, keep one lifecycle owner, handle Boolean acceptance and sequence IDs, release held notes on cancellation and shut down during teardown
|
|
590
|
+
- Start after layout, keep one lifecycle owner, handle Boolean acceptance and tone/sequence IDs, release held notes and owned repetitions on cancellation, and shut down during teardown
|
|
582
591
|
- 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
|
|
583
592
|
|
|
584
|
-
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.
|
|
593
|
+
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. The [official declarations](skills/ti-synthengine/assets/index.d.ts) provide TypeScript signatures alongside the runtime API. [Repetition validation](skills/ti-synthengine/references/native-tone-repetition-validation.md) separates native checks, transport storage and bounded host measurements from device/listening acceptance. [Source notes](skills/ti-synthengine/references/source-notes.md) identify the reviewed native commit and evidence limits.
|
|
585
594
|
|
|
586
595
|
---
|
|
587
596
|
|
|
@@ -736,11 +745,11 @@ Checks: skill directories exist, symlinks are valid (not broken), agent is insta
|
|
|
736
745
|
|
|
737
746
|
It also reports the marketplace plugin's state, which changes what "healthy" means:
|
|
738
747
|
|
|
739
|
-
| Plugin state
|
|
740
|
-
|
|
|
741
|
-
| Enabled
|
|
742
|
-
| Not installed
|
|
743
|
-
| Uninstalled, cache directory left
|
|
748
|
+
| Plugin state | What doctor reports |
|
|
749
|
+
| --------------------------------- | ---------------------------------------------------------------------- |
|
|
750
|
+
| Enabled | Claude Code is served by the plugin — missing mirrors are correct |
|
|
751
|
+
| Not installed | Skills reach Claude Code through npm mirrors — mirrors must be present |
|
|
752
|
+
| Uninstalled, cache directory left | Warns and prints the `rm -rf` that clears the leftover |
|
|
744
753
|
|
|
745
754
|
### titools sync
|
|
746
755
|
|
|
@@ -885,21 +894,21 @@ This pattern is documented across four bundled TiTools skills: `ti-ui`, `ti-expe
|
|
|
885
894
|
|
|
886
895
|
## Skill contents summary
|
|
887
896
|
|
|
888
|
-
| Skill
|
|
889
|
-
|
|
|
890
|
-
| ti-reuse-first
|
|
891
|
-
| ti-expert
|
|
892
|
-
| purgetss
|
|
893
|
-
| ti-ui
|
|
894
|
-
| ti-game
|
|
895
|
-
| ti-game-assets
|
|
896
|
-
| ti-admob-unified | Unified Advertising
|
|
897
|
-
| ti-synthengine
|
|
898
|
-
| ti-api
|
|
899
|
-
| ti-guides
|
|
900
|
-
| ti-howtos
|
|
901
|
-
| alloy-guides
|
|
902
|
-
| alloy-howtos
|
|
897
|
+
| Skill | SKILL.md | References |
|
|
898
|
+
| ---------------- | ----------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
899
|
+
| ti-reuse-first | Reuse Before You Write | 5 files (the ladder, Alloy reuse, indirection, PurgeTSS reuse, diagnostics) |
|
|
900
|
+
| ti-expert | Architecture + Implementation | 27 files (patterns, feedback surfaces, file type association, sharing, testing, security, etc.) |
|
|
901
|
+
| purgetss | Setup + Critical Rules | 39 files (Classic compatibility, grid, animations, icons, class-index, SVG pipeline, etc.) |
|
|
902
|
+
| ti-ui | UI Rules + Platform Diffs | 14 files (layouts, lists, gestures, etc.) |
|
|
903
|
+
| ti-game | Native 2D Game Workflow | 12 files (API, input, source notes, setup, physics, patterns, recipes, tile maps, debugging, roadmap) |
|
|
904
|
+
| ti-game-assets | Visual and Sound Assets | 10 guides and a manifest example; alpha and contract validation scripts |
|
|
905
|
+
| 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 |
|
|
906
|
+
| ti-synthengine | Native Sound Synthesis | 18 Markdown references (15 official parts, 2 curated recipe guides, maintenance notes), official TypeScript declarations, complete validation reports/evidence and a reversible source hash manifest |
|
|
907
|
+
| ti-api | Titanium API | 20 references for core/platform APIs and native modules |
|
|
908
|
+
| ti-guides | SDK Fundamentals | 16 references for setup, configuration, CLI and distribution |
|
|
909
|
+
| ti-howtos | Native Integrations | 18 references for platform features and integration workflows |
|
|
910
|
+
| alloy-guides | Alloy MVC | 11 references for controllers, views, models, styling and widgets |
|
|
911
|
+
| alloy-howtos | Alloy CLI and Debugging | 6 references for commands, configuration and practical workflows |
|
|
903
912
|
|
|
904
913
|
---
|
|
905
914
|
|
package/docs/examples.md
CHANGED
|
@@ -37,12 +37,19 @@ an audio or advertising module.
|
|
|
37
37
|
|
|
38
38
|
## Native synthesis — ti-synthengine
|
|
39
39
|
|
|
40
|
-
- "Install the public TiSynthEngine 1.
|
|
40
|
+
- "Install the public TiSynthEngine 1.1.0 Android/iOS packages and start audio after the window layout settles."
|
|
41
41
|
- "Move a held spatial motor, process only music with reverb, and stop one native sequence without cancelling unrelated sounds."
|
|
42
|
+
- "Use native attack variation with public 1.1.0: bounded noise/filter ranges, deterministic seeds and an old-package fallback."
|
|
43
|
+
- "Repeat this complete layered effect natively without changing its envelope, sweep timing or gains."
|
|
44
|
+
- "Use repeatTone for this finite shot, edit its interval with updateTone, and stop future attacks with stopTone while sounding shots finish."
|
|
45
|
+
- "Use updateNote and enableStats/disableStats, checking the bundled TypeScript declarations and a 1.0.2 alias fallback."
|
|
46
|
+
- "Keep these three standalone playTone calls as an intentional finite JavaScript burst and cancel their timers when the owner closes."
|
|
42
47
|
|
|
43
48
|
Use the [synthesis skill](../skills/ti-synthengine/SKILL.md) for exact options,
|
|
44
|
-
public downloads and scoped performance evidence.
|
|
45
|
-
|
|
49
|
+
public downloads, bundled TypeScript declarations and scoped performance evidence.
|
|
50
|
+
Native finite-tone repetitions, ordered sequences, held voices and standalone
|
|
51
|
+
JavaScript events have distinct ownership and timing contracts. Public 1.0.2 /
|
|
52
|
+
API 1.0.0 lacks repetition and variation; detect support before enabling them.
|
|
46
53
|
|
|
47
54
|
## Advertising — ti-admob-unified
|
|
48
55
|
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@maccesar/titools",
|
|
3
|
-
"version": "5.2.
|
|
3
|
+
"version": "5.2.5",
|
|
4
4
|
"description": "Titanium SDK skills and agents for AI coding assistants, including native game and sound synthesis modules",
|
|
5
5
|
"main": "lib/index.js",
|
|
6
6
|
"type": "module",
|
|
@@ -30,7 +30,7 @@
|
|
|
30
30
|
"sound-design",
|
|
31
31
|
"synthesizer"
|
|
32
32
|
],
|
|
33
|
-
"author": "
|
|
33
|
+
"author": "César Estrada <maccesar@gmail.com> (https://github.com/macCesar)",
|
|
34
34
|
"license": "MIT",
|
|
35
35
|
"repository": {
|
|
36
36
|
"type": "git",
|
|
@@ -1,24 +1,30 @@
|
|
|
1
1
|
---
|
|
2
2
|
name: ti-synthengine
|
|
3
|
-
description: "Use when a Titanium app declares ti.synthengine in tiapp.xml, imports require('ti.synthengine'), or needs generated tones, chords, native sequences,
|
|
3
|
+
description: "Use when a Titanium app declares ti.synthengine in tiapp.xml, imports require('ti.synthengine'), or needs generated tones, chords, repeatTone/updateTone/stopTone, native sequences, held noteOn/noteOff/updateNote, ADSR, sweeps, FM, resonant filters, noise, binaural spatialX/spatialY, shared tempo, selective music/effects/ui/ambience processing, effectSend, priorities, chorus/delay/reverb/saturation, LFOs, sequenceend events, gain staging, statistics with enableStats/disableStats, bounded native per-attack variation, seeds, TypeScript declarations or render-load diagnosis. Not for audio-file decoding, sample streaming or unrelated synthesizers."
|
|
4
4
|
---
|
|
5
5
|
|
|
6
6
|
# ti.synthengine — native sound synthesis for Titanium
|
|
7
7
|
|
|
8
8
|
Act as an audio engineer and mobile sound designer. Translate the requested sound into acoustically reasoned JavaScript using the exact public contract.
|
|
9
9
|
|
|
10
|
-
These references
|
|
11
|
-
|
|
12
|
-
|
|
13
|
-
|
|
14
|
-
and
|
|
10
|
+
These references cover **published Android/iOS module 1.1.0 with public API
|
|
11
|
+
1.1.0**, retaining compatibility guidance for published 1.0.2 / API 1.0.0.
|
|
12
|
+
Version 1.1.0 adds native finite-tone repetition, attack variation and the
|
|
13
|
+
recommended held-note/statistics method names. Version 1.0.2 supports the older
|
|
14
|
+
core methods and aliases but lacks repetition and rejects variation options.
|
|
15
|
+
Download matching [Android](https://github.com/macCesar/TiSynthEngine/releases/tag/android-1.1.0)
|
|
16
|
+
and [iOS](https://github.com/macCesar/TiSynthEngine/releases/tag/ios-1.1.0)
|
|
15
17
|
packages from the public [repository](https://github.com/macCesar/TiSynthEngine).
|
|
16
|
-
|
|
17
|
-
|
|
18
|
-
The
|
|
19
|
-
|
|
20
|
-
|
|
21
|
-
|
|
18
|
+
Read the [guide](references/guide.md) for both platform declarations, rebuilding
|
|
19
|
+
and installation; check the actual methods and feature metadata your app needs.
|
|
20
|
+
The reviewed source commit/state, reversible source/mirror hashes and release
|
|
21
|
+
artifact checksums are recorded in [source-snapshot.json](references/source-snapshot.json)
|
|
22
|
+
and [source notes](references/source-notes.md).
|
|
23
|
+
The current [interactive example](assets/example/README.md) includes both helpers
|
|
24
|
+
and native repetition controls. The bundled [TypeScript declarations](assets/index.d.ts)
|
|
25
|
+
mirror the official module types; read them with the API rather than substituting
|
|
26
|
+
type-checking for runtime acceptance. Earlier development packages reused API
|
|
27
|
+
version strings, so version checks alone do not establish every capability.
|
|
22
28
|
|
|
23
29
|
## Required workflow
|
|
24
30
|
|
|
@@ -29,6 +35,13 @@ Read the relevant references before writing or reviewing code. When updating the
|
|
|
29
35
|
| Any public method, option, default, return value or limit | [API](references/api.md) |
|
|
30
36
|
| Download public releases, install, initialize, own or clean up an engine | [Guide](references/guide.md) |
|
|
31
37
|
| Design an effect, instrument, reward, alarm or game motor | [Sound design](references/sound-design.md), [recipes](references/recipes.md), [examples](references/examples.md) |
|
|
38
|
+
| Complete effect playback, playable adaptations, importing layers and audition fidelity | [Instruments and effects](references/instruments-and-effects.md) |
|
|
39
|
+
| Repeat an original finite tone, edit its next attacks or cancel while sounding attacks finish | [Repetition API](references/api.md#finite-tone-repetition), [instruments and effects](references/instruments-and-effects.md#repeated-firing-uses-the-native-clock) |
|
|
40
|
+
| Repetition test coverage, transport memory and scoped host measurements | [Repetition verification](references/native-tone-repetition-validation.md) |
|
|
41
|
+
| TypeScript signatures, option dictionaries and return types | [Official declarations](assets/index.d.ts), [API](references/api.md) |
|
|
42
|
+
| Native per-attack variation, ranges, amount, seeds, chords, held starts and loop/revision behavior | [Variation](references/native-variation.md), [API](references/api.md) |
|
|
43
|
+
| Variation memory/callback measurements, package scope and listening follow-up | [Variation verification](references/native-variation-validation.md) |
|
|
44
|
+
| Historical variation design, feasibility and deferred API questions | [Historical proposal](references/native-variation-proposal.md); current behavior comes from the implemented guide |
|
|
32
45
|
| Xylophone, memory pads, layered chords, FM instruments and interaction ownership | [Interaction recipes](references/recipes-interaction.md) |
|
|
33
46
|
| Hold, edit, release or position a sustained voice | [API](references/api.md#noteonoptions), [advanced examples](references/advanced-examples.md#sustained-game-motor) |
|
|
34
47
|
| 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) |
|
|
@@ -57,13 +70,16 @@ if (!synth.start({maxVoices: 32, maxSequences: 4,
|
|
|
57
70
|
}
|
|
58
71
|
```
|
|
59
72
|
|
|
60
|
-
|
|
73
|
+
Both 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]
|
|
74
|
+
|
|
75
|
+
Use `updateNote` for held-note edits and `enableStats()` / `disableStats()` for diagnostics in new 1.1.0 code. `updateVoice` and `setStatsEnabled(Boolean)` remain deprecated equivalent aliases, without repeated warnings or a scheduled removal date. For 1.0.2 compatibility, detect and use its aliases; detect repetition and variation separately before enabling those features. [source: references/api.md]
|
|
61
76
|
|
|
62
77
|
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]
|
|
63
78
|
|
|
64
79
|
## Scheduling contract
|
|
65
80
|
|
|
66
|
-
- `playTone`
|
|
81
|
+
- `playTone` plays one finite event and returns Boolean acceptance; it rejects `intervalMs`. `playChord` plays one simultaneous atomic chord. Use `repeatTone` for ongoing native repetition of the original finite-tone recipe, `playSequence` for ordered scores, and `noteOn`/`noteOff`/`updateNote` for interaction-owned held voices.
|
|
82
|
+
- Independent gameplay calls and intentionally JavaScript-timed finite bursts remain supported. Keep their Boolean `playTone` returns and cancel app-owned timers on teardown. Native repetition and sequences own their ongoing sample-clock attacks; UI polling does not drive them.
|
|
67
83
|
- `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.
|
|
68
84
|
- 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.
|
|
69
85
|
- `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.
|
|
@@ -75,19 +91,35 @@ Choose the actual required sequence capacity, 1–4; the snippet's four slots su
|
|
|
75
91
|
|
|
76
92
|
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]
|
|
77
93
|
|
|
94
|
+
## Native finite-tone repetition
|
|
95
|
+
|
|
96
|
+
Require a present `contract.capabilities` map with `toneRepetition === true` and the presence of `repeatTone`, `updateTone` and `stopTone` before enabling native repetition. Published 1.0.2 lacks it. Keep an existing independent-event path or disable the unavailable control; converting a timed recipe to sequence length/sweeps changes its rendering interpretation. [source: references/api.md] [source: references/instruments-and-effects.md]
|
|
97
|
+
|
|
98
|
+
`repeatTone({intervalMs,...recipe})` requires an integer interval of 1–60,000 ms and returns a positive `toneId` or numeric `0`. It preserves the finite-tone envelope, endpoint sweeps, gain, routes and optional variation. The first attack starts at the first render opportunity; later deadlines preserve fractional samples across blocks and ignore tempo changes. There are 32 repetition slots independent of the 1–4 sequence slots, sharing the configured pool of at most 32 voices. Reserve capacity for overlaps, prior attacks after edits and other owners; publication does not guarantee admission of every future attack.
|
|
99
|
+
|
|
100
|
+
`updateTone({toneId,...changes})` requires a live ID and at least one change. It merges with the last accepted recipe and validates the complete result; `note` and `frequency` replace one another, while supplying both rejects the edit. Invalid edits retain the accepted recipe. Edits affect the next scheduled attack without moving its deadline; the new interval controls the following gap. Sounding attacks retain their original configuration. A supplied variation dictionary replaces the previous dictionary; `{amount:0}` disables future variation. The native stream/counter survives edits unless the seed identity changes. Dropped attacks consume no variation selection and produce no catch-up work.
|
|
101
|
+
|
|
102
|
+
`stopTone({toneId})` returns Boolean acceptance and cancels future attacks at the next block, including before the first attack. Already admitted finite voices finish their original lifetimes. Stop remains publishable when the ordinary command queue is full. Unknown/retired IDs reject edits and stops; IDs never repeat during module lifetime, including shutdown/start. There is no `toneend` event. Retain each layer's ID and cancel it on release, cancellation, preset change, pause and owner close. Global `stopAll`, shutdown and destruction invalidate repetitions and pending edits. [source: references/api.md] [source: references/native-variation.md]
|
|
103
|
+
|
|
104
|
+
## Native attack variation
|
|
105
|
+
|
|
106
|
+
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.
|
|
107
|
+
|
|
108
|
+
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; `updateNote` 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. Use the native sampler for this variation dictionary. Seeds reproduce parameters, not cross-platform noise PCM. [source: references/native-variation.md]
|
|
109
|
+
|
|
78
110
|
## Voices, routes and continuous controls
|
|
79
111
|
|
|
80
112
|
`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]
|
|
81
113
|
|
|
82
114
|
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]
|
|
83
115
|
|
|
84
|
-
Compatible `
|
|
116
|
+
Compatible `updateNote` 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]
|
|
85
117
|
|
|
86
118
|
`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]
|
|
87
119
|
|
|
88
120
|
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]
|
|
89
121
|
|
|
90
|
-
`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]
|
|
122
|
+
`stopAll()` stops every native sequence and finite-tone repetition, cancels future attacks, fades voices and invalidates effect histories. Use `stopSequence({sequenceId})` for one owner’s sequence or `stopTone({toneId})` for its finite repetition. 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]
|
|
91
123
|
|
|
92
124
|
## Sound and validation rules
|
|
93
125
|
|
|
@@ -101,8 +133,8 @@ Module 1.0.2 retains zero samples at final output: stereo-linked peak protection
|
|
|
101
133
|
|
|
102
134
|
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]
|
|
103
135
|
|
|
104
|
-
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]
|
|
136
|
+
Timed zero attack/release and rejection diagnostics currently differ between native platforms. Submit exact integer repetition intervals: Apple currently tolerates and truncates extremely near-integer values that Android rejects; see the documented [native interval edge](references/source-notes.md#known-native-interval-edge). 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]
|
|
105
137
|
|
|
106
|
-
Diagnostics are opt-in
|
|
138
|
+
Diagnostics are opt-in through `enableStats()` / `disableStats()`. 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]
|
|
107
139
|
|
|
108
140
|
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.
|
|
@@ -1,26 +1,28 @@
|
|
|
1
|
-
> Source snapshot: official TiSynthEngine
|
|
1
|
+
> Source snapshot: official TiSynthEngine documentation at commit `ec04f4e634075c41b55f66279eabcd78b9652d58` (2026-11-02). Published module 1.1.0; public API 1.1.0. Upstream `example/README.md` SHA-256: `e191a701a3a913c85b15503fd256e0aec085eb731a587b1bf4faa43865c81982`.
|
|
2
2
|
|
|
3
3
|
# Interactive example
|
|
4
4
|
|
|
5
|
-
The Classic Titanium app in [app.js](app.js) demonstrates the timed sounds, native sequences and statistics with the `sequenceend` event on Android and iOS. It
|
|
5
|
+
The Classic Titanium app in [app.js](app.js) demonstrates the timed sounds, native sequences and statistics with the `sequenceend` event on Android and iOS. It requires module version 1.1.0 and public API 1.1.0 for native finite-tone repetition, attack variation and the recommended note/statistics methods. Held voices, master processing and voice LFOs have copyable examples in the [advanced documentation](../../references/advanced-examples.md#sustained-game-motor); this reference app does not expose those newer controls. The default engine configuration is 16 voices, `conservative` mixing and the `playback` session; master volume starts at 100% and optional diagnostics start off.
|
|
6
6
|
|
|
7
7
|
## Run it
|
|
8
8
|
|
|
9
9
|
1. Create a Classic Titanium application with Android and/or iOS support. If the app uses Alloy, create a separate Classic test project and leave the Alloy-generated files in place.
|
|
10
|
-
2. Download the official [Android 1.0
|
|
10
|
+
2. Download the official [Android 1.1.0](https://github.com/macCesar/TiSynthEngine/releases/tag/android-1.1.0) and [iOS 1.1.0](https://github.com/macCesar/TiSynthEngine/releases/tag/ios-1.1.0) packages, or build the current module source. Source builds produce `android/dist/ti.synthengine-android-1.1.0.zip` and `ios/dist/ti.synthengine-iphone-1.1.0.zip`; select version `1.1.0` in both module entries when using them.
|
|
11
11
|
3. Put the archive for each target platform in the test app root. Add these entries inside its `tiapp.xml`:
|
|
12
12
|
|
|
13
13
|
```xml
|
|
14
14
|
<modules>
|
|
15
|
-
<module platform="android" version="1.0
|
|
16
|
-
<module platform="iphone" version="1.0
|
|
15
|
+
<module platform="android" version="1.1.0">ti.synthengine</module>
|
|
16
|
+
<module platform="iphone" version="1.1.0">ti.synthengine</module>
|
|
17
17
|
</modules>
|
|
18
18
|
```
|
|
19
19
|
|
|
20
|
+
Both packages report public API `1.1.0`; detect variation through both capability/schema announcements. Rebuild and reinstall after switching packages.
|
|
21
|
+
|
|
20
22
|
4. Copy the entire `example/` folder into the test app's `Resources/`, including [app.js](app.js), [sequenceScore.js](lib/sequenceScore.js) and [sequenceOwner.js](lib/sequenceOwner.js). It needs no images or audio files.
|
|
21
23
|
5. Build and run the test app with the Titanium CLI or your existing Titanium launch configuration. Use Titanium SDK 13.2.0.GA or newer, Android compile API 35 or newer, and iOS 15 or newer. See the [module installation guide](../../references/guide.md#install-the-module).
|
|
22
24
|
|
|
23
|
-
The example checks the installed API version, spatial limits and
|
|
25
|
+
The example checks the installed API version, spatial limits and the recommended enable/disable statistics methods before constructing the screen. If it requests current packages, replace the native module, then rebuild and reinstall the app; copying module files alone does not update an app already on a device.
|
|
24
26
|
|
|
25
27
|
Audio starts after the first layout settles. Sound controls report native rejections. If startup fails, the session buttons remain available to retry. Closing the window removes its sequence listener, clears startup/statistics timers, disables diagnostics and shuts down the engine. The example plays finite sounds in the foreground and does not demonstrate background audio. Turn diagnostics off before leaving it in the background.
|
|
26
28
|
|
|
@@ -82,3 +84,14 @@ node --test tests/example_app_regression.js
|
|
|
82
84
|
```
|
|
83
85
|
|
|
84
86
|
The example regression executes its real action callbacks with simulated Titanium UI/audio boundaries. It covers rejection feedback, placement/bypass, session restart and gain preservation, diagnostic cleanup and close-before-start. It does not render native audio or establish layout, perceived elevation, silent-mode behavior or sound quality. Use the device checklist above, including headphones and an output-route change, before claiming those results.
|
|
87
|
+
|
|
88
|
+
|
|
89
|
+
## Native attack variation
|
|
90
|
+
|
|
91
|
+
The ATTACK VARIATION button submits the same metal-strike recipe on each press. With `capabilities.variation === true` and `variationSchemaVersion === 1`, the renderer chooses pitch, FM depth and level once per admitted attack. Older packages receive the original recipe without the dictionary. This button uses independent timed events; the [variation guide](../../references/native-variation.md) separately demonstrates sustained ownership and native sequence retriggers. Physical listening acceptance remains separate from host correctness checks.
|
|
92
|
+
|
|
93
|
+
## Native finite-tone repetition
|
|
94
|
+
|
|
95
|
+
START REPEATING calls `repeatTone` once with a complete 105 ms square-wave shot and required `intervalMs: 200`. It retains the positive tone ID. EDIT REPEATING calls `updateTone` for that ID, keeping the next deadline and changing subsequent separation to 150 ms. STOP REPEATING calls `stopTone`, cancelling future attacks while admitted shots finish. Close, session changes and global Stop also release or invalidate ownership. There is no JavaScript attack timer for this demo.
|
|
96
|
+
|
|
97
|
+
`playTone` remains a standalone Boolean operation and rejects `intervalMs`; `repeatTone` always returns a numeric ID or 0 and requires the interval. Independent JavaScript calls remain supported, including finite bursts scheduled by an application's own event clock. See [the full contract and standalone burst example](../../references/api.md#finite-tone-repetition).
|