@maccesar/titools 5.2.0 → 5.2.1

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

@@ -0,0 +1,83 @@
+// One application owner, with latest-request coalescing across native retirement.
+// A stop is accepted before its slot becomes reusable. Only sequenceend permits
+// the next complete publication; JavaScript never schedules individual notes.
+module.exports = function createSequenceOwner(synth, options) {
+  options = options || {}
+  var current = 0, pending = null, stopping = false, listening = false
+  function listen() {
+    if (!listening) {
+      synth.addEventListener('sequenceend', ended)
+      listening = true
+    }
+  }
+  function rejected(method, payload) {
+    if (options.rejected) options.rejected(method, payload)
+    return false
+  }
+  function publish() {
+    if (!pending) return true
+    var payload = pending
+    pending = null
+    var id = synth.playSequence(payload)
+    if (!Number.isInteger(id) || id <= 0) return rejected('playSequence', payload)
+    current = id
+    if (options.published) options.published(id, payload)
+    return true
+  }
+  function ended(event) {
+    if (event.sequenceId !== current) return
+    current = 0
+    stopping = false
+    if (pending) publish()
+    if (options.ended) options.ended(event)
+  }
+  function requestStop() {
+    if (!current || stopping) return true
+    stopping = true
+    if (synth.stopSequence({ sequenceId: current })) return true
+    // A naturally retired ID can already have its completion queued for JS.
+    // Its slot still needs event draining before a replacement publication.
+    if (synth.getSequenceState({ sequenceId: current }) === null) return true
+    stopping = false
+    return rejected('stopSequence', { sequenceId: current })
+  }
+  return {
+    submit: function(payload) {
+      listen()
+      pending = payload
+      if (!current) return publish()
+      if (!requestStop()) {
+        pending = null
+        return false
+      }
+      return true
+    },
+    update: function(changes) {
+      if (pending) {
+        if (changes.steps !== undefined) {
+          pending = changes
+          return true
+        }
+        var voice = changes.voice ? Object.assign({}, pending.voice || {}, changes.voice) : pending.voice
+        pending = Object.assign({}, pending, changes)
+        if (voice) pending.voice = voice
+        return true
+      }
+      if (!current || stopping) return false
+      return synth.updateSequence(Object.assign({ sequenceId: current }, changes))
+    },
+    stop: function() { pending = null; return requestStop() },
+    reset: function() {
+      pending = null
+      current = 0
+      stopping = false
+      if (listening) {
+        synth.removeEventListener('sequenceend', ended)
+        listening = false
+      }
+    },
+    id: function() { return current },
+    pending: function() { return pending !== null },
+    stopping: function() { return stopping }
+  }
+}

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

@@ -0,0 +1,25 @@
+// Compile an application score to the native, millisecond sequence contract.
+// Score envelopes include release; native length marks the release onset.
+module.exports = function sequenceScore(score) {
+  const quarters = { '1n':4, '2n':2, '2n.':3, '4n':1, '4n.':1.5, '8n':.5, '8n.':.75, '8t':1/3, '16n':.25, '16t':1/6 }
+  function noteFrequency(note) {
+    const m = /^(SOL|DO|RE|MI|FA|LA|SI|TI|[A-G])([#b]?)(-?\d+)?$/i.exec(note)
+    if (!m) return NaN
+    const pitch = {C:0,D:2,E:4,F:5,G:7,A:9,B:11,DO:0,RE:2,MI:4,FA:5,SOL:7,LA:9,SI:11,TI:11}[m[1].toUpperCase()]
+    return 440 * Math.pow(2, ((Number(m[3] === undefined ? 4 : m[3])+1)*12+pitch+(m[2]==='#'?1:m[2]==='b'?-1:0)-69)/12)
+  }
+  const voice = Object.assign({}, score)
+  for (const key of ['steps','bpm','swing','stepDuration','noteValue']) delete voice[key]
+  return { timeUnit:'ms', loop:false, swing:score.swing || 0, voice,
+    steps:score.steps.map(step => {
+      const duration = step.duration === undefined
+        ? ((step.noteValue || score.noteValue) ? 60000/(score.bpm || 120)*quarters[step.noteValue || score.noteValue] : score.stepDuration || 100)
+        : step.duration
+      if (step.rest) return {rest:true,duration}
+      const overrides = Object.assign({}, step)
+      for (const key of ['note','frequency','duration','noteValue']) delete overrides[key]
+      const release = step.release === undefined ? score.release === undefined ? Math.min(50,duration-1) : score.release : step.release
+      return { frequencies:[step.frequency === undefined ? noteFrequency(step.note) : step.frequency],
+        duration, length:Math.max(1,duration-release), overrides }
+    }) }
+}

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

@@ -0,0 +1,174 @@
+> Source snapshot: official TiSynthEngine 1.0.0 documentation at release source commit `e7cbbe8a6f9ab38088fd8029c7b43cef6501101f` (2026-10-24). Upstream `documentation/examples.md` SHA-256: `48104b9d413050d439ee605c92a2456a50b42c4c80e2d7c2c05706eecc7db215`.
+
+## Sustained game motor
+
+Assume one running engine owned by this service. The positive voice ID belongs to the app; do not reuse it during the session or share its counter with an independent audio owner. There is no `duration` or `*End` target on `noteOn`.
+
+```javascript
+if (!['noteOn', 'noteOff', 'updateVoice'].every(function (name) {
+  return typeof synth[name] === 'function'
+})) throw new Error('Held-voice APIs are required')
+
+var nextMotorId = 1
+var motorId = null
+var releaseTimers = new Set()
+
+function startMotor () {
+  if (motorId !== null) return true
+  var id = nextMotorId++
+  if (!synth.noteOn({ voiceId: id, frequency: 160, waveType: WAVE.NOISE,
+    noiseRate: 1500, lowPassHz: 600, attack: 80, release: 120,
+    filterType: 'bandpass', filterHz: 220, filterQ: 0.8, volume: 0.15 })) return false
+  motorId = id
+  return true
+}
+
+function changeMotor (boosted) {
+  if (motorId === null) return false
+  return synth.updateVoice({ voiceId: motorId,
+    filterHz: boosted ? 320 : 220, volume: boosted ? 0.18 : 0.15 })
+}
+
+function releaseMotorId (id, attempt) {
+  if (synth.noteOff({ voiceId: id })) return
+  if (attempt >= 2) {
+    closeMotorAudio()
+    Ti.API.warn('Release queue stayed full; audio shut down to prevent a stuck note')
+    return
+  }
+  var timer = setTimeout(function () {
+    releaseTimers.delete(timer)
+    releaseMotorId(id, attempt + 1)
+  }, 16)
+  releaseTimers.add(timer)
+}
+
+function stopMotor () {
+  if (motorId === null) return
+  var id = motorId
+  motorId = null
+  releaseMotorId(id, 0)
+}
+
+function closeMotorAudio () {
+  releaseTimers.forEach(function (timer) { clearTimeout(timer) })
+  releaseTimers.clear()
+  motorId = null
+  synth.shutdown()
+}
+```
+
+Wire `startMotor` to acceleration/key down, `changeMotor` to a boost change, and `stopMotor` to release or cancellation. Compatible updates ramp over 10 ms without retriggering: frequency, level, noise clock, low-pass, send and position are live controls. Source/filter type requires a new attack. Start spatial voices with coordinates before editing them; pan updates apply to stereo voices. A stolen ID accepts updates as a no-op; optional priority improves admission without reserving voices.
+
+## Native sequence with chords and edits
+
+Start the engine with enough sequence capacity, then store each positive ID. The default interval is a sixteenth note (0.25 beats); rests advance time and gates start release, which can overlap later steps.
+
+```javascript
+synth.setTempo({ bpm: 110 })
+var musicId = synth.playSequence({ swing: 0.12, loop: true, bus: 'music',
+  voice: { waveType: WAVE.TRIANGLE, attack: 8, release: 100, volume: 0.3 },
+  steps: [{ notes: [60, 64, 67], gate: 0.7 }, { rest: true },
+    { notes: [67], gate: 0.5, overrides: { volume: 0.22 } },
+    { notes: [64, 67, 72], duration: 0.5, length: 0.75 }]
+})
+if (musicId === 0) throw new Error('Sequence publication rejected')
+synth.setTempo({ bpm: 128 })
+if (!synth.updateSequence({ sequenceId: musicId, swing: 0.18, voice: { volume: 0.25 } })) Ti.API.warn('Edit rejected')
+var positionTimer = setInterval(function () {
+  var state = synth.getSequenceState({ sequenceId: musicId })
+  if (state) Ti.API.info(JSON.stringify(state))
+}, 200)
+function stopOnlySequence () {
+  if (!synth.stopSequence({ sequenceId: musicId })) Ti.API.warn('Stop rejected')
+}
+function closeSequenceAudio () {
+  clearInterval(positionTimer)
+  synth.shutdown()
+}
+```
+
+The UI timer presents state; native audio schedules every attack/release. For fixed-time cues use `timeUnit: 'ms'`, whose intervals and note lengths survive tempo changes. Edits enter at the next step, swing at the next pair. Up/down/updown modes reorder sounding steps by pitch; normal mode retains rests. A completed/stopped ID is retired; create a new sequence to play again. `sequenceend` identifies the owner, and releases/tails can outlive completion.
+
+## Chorus, delay, reverb and creative saturation
+
+This configures the selected share of a running engine; `applyTo` defaults to all categories. Check method presence and Boolean acceptance; partial section updates merge with the last accepted settings. Effects start disabled, input gain starts at 1, and no LFOs are added to voices implicitly.
+
+```javascript
+if (typeof synth.setMasterProcessing !== 'function') {
+  throw new Error('Master-processing API is required')
+}
+if (!synth.setMasterProcessing({
+  inputGain: 0.7,
+  chorus: { enabled: true, rate: 0.6, depth: 0.25, mix: 0.12 },
+  delay: { enabled: true, timeMs: 280, sync: 'off', feedback: 0.25, mix: 0.1 },
+  reverb: { enabled: true, decay: 1.4, damping: 0.6, mix: 0.14 },
+  saturation: { enabled: false }
+})) throw new Error('Processing rejected')
+
+// Sync follows the native transport tempo, initially 120 BPM.
+if (!synth.setMasterProcessing({ delay: { sync: 'eighth' } })) {
+  Ti.API.warn('Synced delay edit rejected')
+}
+
+function setCreativeDrive (enabled) {
+  return synth.setMasterProcessing({ saturation: { enabled: enabled, drive: 1.5, mix: 0.2 } })
+}
+
+function disableMasterEffects () {
+  return synth.setMasterProcessing({ chorus: { enabled: false }, delay: { enabled: false },
+    reverb: { enabled: false }, saturation: { enabled: false } })
+}
+```
+
+Call `setCreativeDrive(true)` only for a deliberate timbre change and check acceptance. `disableMasterEffects` closes input and drains bounded tails before exact bypass; it retains input gain 0.7. Set gain back to 1 after tails drain for a unity comparison. Panic stops all sequences, fades voices and invalidates histories. Select music/ambience categories or individual sends when gameplay effects should stay dry.
+
+## Two voice LFOs
+
+This square voice modulates cutoff and PWM independently. The original `lfoFreq`/`lfoDepth` pitch vibrato remains a separate control. All LFOs run natively; edits preserve their phases and ramp contributions over 10 ms.
+
+```javascript
+if (typeof synth.noteOn !== 'function' || typeof synth.updateVoice !== 'function') {
+  throw new Error('Held-voice APIs are required')
+}
+var modulatedId = 100001 // Reserve an unused ID from the owner's counter in an app.
+if (!synth.noteOn({ voiceId: modulatedId, note: 'A3', waveType: WAVE.SQUARE,
+  attack: 100, release: 250, pulseWidth: 0.5, volume: 0.2,
+  filterType: 'lowpass', filterHz: 1600, filterQ: 0.8,
+  modulations: [
+    { wave: 'sine', target: 'filterHz', rate: 0.4, depth: 0.12 },
+    { wave: 'triangle', target: 'pulseWidth', sync: 'eighth', depth: 0.15 }
+  ] })) throw new Error('Modulated voice rejected')
+
+function disableVoiceLfos () {
+  return synth.updateVoice({ voiceId: modulatedId, modulations: [] })
+}
+// Call disableVoiceLfos on the UI action and handle false.
+// Later release this ID with the bounded release policy above, or shut down its owner.
+```
+
+Use `target: 'fmDepth'` only with `WAVE.SINE`; a filter target requires an active filter and PWM requires `WAVE.SQUARE`. Free rates are 0 to 20 Hz; synced subdivisions follow native transport BPM. Depth is normalized, with cutoff/PWM/FM contributions clamped to safe parameter ranges. `modulations: []` disables both slots; omitting the field on update preserves them. Copy the same initial `modulations` array into a sequence's `voice` or a step's `overrides` to modulate transport notes. Timed tones/chords/patterns do not accept the new array.
+
+## Measure peaks and limiter reduction
+
+Enable diagnostics only while measuring and keep unavailable readings distinct from zero. A brief overload can disappear from the window meter while remaining in the accumulated maximum.
+
+```javascript
+if (!['setStatsEnabled', 'getStats', 'resetStats'].every(function (name) {
+  return typeof synth[name] === 'function'
+})) throw new Error('Statistics APIs are required')
+if (!synth.setStatsEnabled(true)) throw new Error('Diagnostics rejected')
+synth.resetStats()
+var mixTimer = setInterval(function () {
+  var stats = synth.getStats()
+  Ti.API.info(JSON.stringify({ preLimiterDbFS: stats.preLimiterPeakDb,
+    maximumReductionDb: stats.maxLimiterReductionDb, latestReductionDb: stats.limiterReductionDb }))
+}, 200)
+
+function closeMixMeter () {
+  clearInterval(mixTimer)
+  if (!synth.setStatsEnabled(false)) Ti.API.warn('Diagnostics disable rejected')
+}
+```
+
+Call `closeMixMeter` when its owner hides or closes. Display unavailable or unmeasured fields as unavailable. Reset deliberately before a comparison. These values measure digital peak protection, not speaker loudness, subjective quality or a guarantee that every audio deadline was met.

package/skills/ti-synthengine/references/android-sim80-correction.json

@@ -0,0 +1,162 @@
+{
+  "schemaVersion": 1,
+  "date": "2026-10-23",
+  "moduleVersion": "1.0.0 beta",
+  "status": "corrected-for-tested-Sim80-headphone-case",
+  "acceptanceComplete": false,
+  "listening": {
+    "accepted": true,
+    "reviewer": "Cesar",
+    "replyTranslation": "Clean, no perceptible distortion.",
+    "scenario": "Real Sim80, live synthesis, headphones, eight-output candidate",
+    "scope": "Subjective acceptance of this short scene, not every voice/effect or a ten-minute maximum-load pass."
+  },
+  "implementation": {
+    "platform": "Android ARM64",
+    "change": "Reuse FIR coefficients across eight consecutive samples per voice while preserving each sample partial-sum and reduction order. Bound tiles at sequence attacks. Keep the previous stereo and other-ABI paths.",
+    "gainQualityOrVoiceLimitsChanged": false,
+    "outputBufferChanged": false,
+    "publicApiChanged": false,
+    "diagnosticInterfacesInProduction": false
+  },
+  "comparisonWithIOS": {
+    "sharedBinauralAlgorithm": true,
+    "ipadMeasuredRate": 44100,
+    "ipadMeasuredBlockFrames": 1024,
+    "androidMeasuredRate": 48000,
+    "androidMeasuredBlockFrames": 256,
+    "ipadTaps": 128,
+    "androidTaps": 140,
+    "limits": "Different measured hardware/output configurations; larger blocks alone do not cure sustained CPU overload."
+  },
+  "profilingBeforeCorrection": {
+    "route": "speaker",
+    "volumeIndex": 80,
+    "callbacks": 1801,
+    "xruns": 73,
+    "cpuBlocksAboveDeadline": 455,
+    "withoutOnsetCpuBlocksAboveDeadline": 357,
+    "onsetCpuShare": 0.004458489684975288,
+    "spatialFirSamples": 1017,
+    "audioThreadSamples": 1566,
+    "scope": "Actual Sim80, flat250HzCPU sampling with inline symbol attribution, not DSP-only isolation."
+  },
+  "fourOutputCandidate": {
+    "speakerXruns": 1,
+    "speakerCpuP95LoadInterval": [
+      1.205,
+      1.21
+    ],
+    "manualHeadphoneXruns": 37,
+    "manualHeadphoneVolumeIndex": 120,
+    "manualHeadphoneCpuP95LoadInterval": [
+      1.62,
+      1.625
+    ],
+    "listening": "Improved but still a couple of perceived distorted moments.",
+    "limits": "Speaker profiling and manual headphone capture are distinct runs/routes, not a controlled route comparison."
+  },
+  "eightOutputCapture": {
+    "device": "Android CPH2639",
+    "route": "wired headphones",
+    "volumeIndex": 120,
+    "volumeMax": 160,
+    "sampleRate": 48000,
+    "callbackFrames": 256,
+    "burstFrames": 256,
+    "bufferFrames": 512,
+    "frames": 480000,
+    "capturedSeconds": 10,
+    "xruns": 0,
+    "routeStayedValid": true,
+    "callbacks": 1875,
+    "maxVoices": 32,
+    "maxTails": 25,
+    "wallP95LoadInterval": [
+      1.02,
+      1.025
+    ],
+    "cpuP95LoadInterval": [
+      0.965,
+      0.97
+    ],
+    "wallMaxNs": 9150154,
+    "cpuMaxNs": 8857462,
+    "wallBlocksAboveDeadline": 104,
+    "cpuBlocksAboveDeadline": 80,
+    "clockErrors": 0,
+    "pcmHash": "7f89b839f15ce44d",
+    "nonFiniteFrames": 0,
+    "peakLeft": 0.8500000238418579,
+    "peakRight": 0.8500000238418579,
+    "scope": "Private instrumented module with PCM capture/clocks and250Hzsampling. Observed output delivery passed this ten-second scene; callback overruns still prevent a strict render-deadline pass."
+  },
+  "verification": {
+    "streamingVsBlocked": "120000 standalone frames/sixrates8\u2013192k, ramps, wrap and complete state bit-identical on Android; varied short blocks also pass C and forcedAndroidNEON on ARM host.",
+    "renderer": "135onset/fullstate,20fractionaltransport/fullstate,9legacy renders, spatial regression and fullheld regression match or pass on ARM host.",
+    "review": "Independent source review found no critical/important issue in four/eight windows, clocks, tails, sends, stereo guard or bounded stack.",
+    "physicalAcceptance": false,
+    "stereoBypassChange": {
+      "scope": "One stereo voice, new fix versus immediately preceding205a renderer, same warmed process, both4slots; previous937screen separate",
+      "pairs": 10,
+      "medianRenderRatio": 1.0113211982131405,
+      "medianP95Ratio": 1.0053333333333334,
+      "ratios": [
+        1.0005653275429052,
+        1.0126349702109787,
+        1.0196281518419976,
+        1.0126315815643214,
+        1.0206466219701242,
+        1.0100108148619595,
+        0.996436735715484,
+        1.016768104985823,
+        1.0091023055656232,
+        0.9846528665539155
+      ],
+      "bitExact": true
+    },
+    "finalProductionClockHeldLegacy": "Byte-identical to the pre-correction renderer after restoring lazy scalar clock reads and forced inlining."
+  },
+  "productionSourceSha256": {
+    "android/jni/SynthOboeEngine.cpp": "cc7f050084871a79cb028b48081a8e51158a3a69f876c59e0f9de1a6ea7ecac6",
+    "shared/synth_spatial.h": "d628ef9c60776be463c5dc45a972c9f9bbb0d183656f0dc177211038ba39d75a",
+    "tests/spatial_regression.c": "2cf768e4dc18035010819b74837921c8b27ae391670acde0bf56197793c655c0"
+  },
+  "measuredPrivateArtifact": {
+    "apkSha256": "324dc75a4b6caddbf6205915287ad90f68f0c735ac9d395ffb6bfb4821cbd934",
+    "aarSha256": "156156df699eabc8647598b5da7fa4f0d20014c3a765b04120a43a0800e40d47",
+    "sourceSha256": {
+      "android/jni/SynthOboeEngine.cpp": "8b0fc7eb99bc1f0b1d76643776fcb7e8eb540f4ba5cd9379313e7f615670e1b0",
+      "shared/synth_spatial.h": "9184a9d81de04c5216c52b96a8860c33bfd3492081089b34df35743d51e90bbb"
+    },
+    "nativeHashes": {
+      "lib/arm64-v8a/liboboe.so": "2696179a9e302f4047ce04146de39f64930bdfaa75d51da63bc7af1a228b8d73",
+      "lib/arm64-v8a/libti.synthengine.so": "3c04735e3f4a60b4d5218fadb192121978c30e105f02115383ba68120635c272",
+      "lib/armeabi-v7a/liboboe.so": "6eebcff8923f11f79d10bd3404afccab9c8d9ba629709334fc76663894b0e914",
+      "lib/armeabi-v7a/libti.synthengine.so": "b07a4b3d2e1d32b71a5267cd47d52024f9f8414d2531867ebcb0281548402919",
+      "lib/x86/liboboe.so": "8846bdc73a1ad884e017c7f3082042184bb8c9876651f48e77faef24f7c7eec4",
+      "lib/x86/libti.synthengine.so": "b13a3adcc8681090d6c305ca7436d60e367ffbcabce0fec0c64861925fcb28cc",
+      "lib/x86_64/liboboe.so": "f1168819d87b8571bb7c8147176854a2e5783bae6e35d2a420d99dc19692db94",
+      "lib/x86_64/libti.synthengine.so": "c008b2eb71b38e271a39fc3c5a1d70698e60bd06da578c723637890291970e98"
+    }
+  },
+  "rawEvidenceArchive": "android-sim80-correction-evidence.zip",
+  "remaining": [
+    "Android ten-minute maximum-load criterion is still open; do not reinterpret this short Sim80 result as that acceptance.",
+    "The measured candidate still has80CPU/104wall callbacks above one deadline.",
+    "Whole-process192k memory, prior one-voice bypass screen, Android Sim20 renderer elapsed work and strict Sim80 presentation matching retain their prior limits."
+  ],
+  "publication": "Beta1.0.0, no release or push.",
+  "rawEvidenceArchiveSha256": "faff448de458ef0cb5299e234177f17a914f7801c27581ab969a9010a68c3c5f",
+  "productionAndroidBuild": {
+    "aarSha256": "7e98bf4fbc6fbe4d1f4a5d9f5a561137522e831fb54480ae0310dd22b60a0c2c",
+    "nativeSoSha256": {
+      "arm64-v8a": "631aaca4f4dabcedc33cf3bf1b23601de3da6291448a299e195cbf5b07f526e3",
+      "armeabi-v7a": "1a4100a25f920784dfc5bda91f30fa6f405e2b85deee51a8b14ce5502a2cf47c",
+      "x86": "8f4545e24cb7f35220445b6e8c04f561bbf5a6cbf55b755c8e8aeffe923e748d",
+      "x86_64": "96a8c5224129de2cd215c9d3b6a2cc50c08865f2de35bf95274026ea452a4a57"
+    },
+    "realFourAbiBuild": true,
+    "diagnosticCodeAbsent": true
+  }
+}