rlo-engine 1.0.3 → 1.1.0

package/README.md

@@ -4,6 +4,17 @@ An optimized compiler and procedural Web Audio engine designed specifically for
 
 RLO converts sequence files (like MIDI) into 1D numerical arrays, bypassing the need for external parsing libraries or audio samples. Audio is synthesized dynamically at runtime using pure mathematics and the native Web Audio API.
 
+
+Demo PWA game using this library : https://github.com/SiliconStreetDev1/NeonBlitz
+
+🎮 **[PLAY NEON BLITZ DIRECTLY IN YOUR BROWSER HERE!](https://siliconstreetdev1.github.io/NeonBlitz/)** 🎮
+
+
+See JS13ksize working example:
+https://github.com/SiliconStreetDev1/NeonBlitzjs13k
+
+📜 **[View Changelog (v1.1.0 Update)](./CHANGELOG.md)**
+
 ### 🚀 Two Ways to Use the Engine
 
 This library uses a **Hybrid Architecture**. You can either install it directly via NPM for standard development, or clone it as a build-pipeline boilerplate to achieve high compression for JS13K competitions.
@@ -126,7 +137,7 @@ If you are using `RLOMusicPlayer`, it handles fetching and decompression automat
 The `.rlo` files generated by the CLI compiler are **gzipped binary buffers**. Here is the standard boilerplate to fetch, unzip, and decode them using native browser APIs:
 
 ```javascript
-import { RLOTranspiler } from "rlo-engine";
+import { decodeBinary } from "rlo-engine";
 
 async function loadAndPlayRLO(url, engine) {
   const res = await fetch(url);
@@ -137,7 +148,7 @@ async function loadAndPlayRLO(url, engine) {
   const buffer = await new Response(decompressedStream).arrayBuffer();
 
   // 2. Decode the binary buffer into the RloData object format
-  const trackData = RLOTranspiler._decodeBinary(buffer);
+  const trackData = decodeBinary(buffer);
 
   // 3. Play it!
   engine.playMusic(trackData); // Use playSequence(trackData) if using RLOCore
@@ -148,7 +159,7 @@ async function loadAndPlayRLO(url, engine) {
 
 ## Paradigm B: The JS13k Boilerplate (High Compression)
 
-For size-coding and JS13k developers. By cloning the repo and using the custom build pipeline, you bypass ES module boundaries, allowing the Terser minifier to mangle internal properties and strip out any synthesizers you don't actively use.
+For size-coding and JS13k developers. By cloning the repo and using the custom build pipeline, you bypass ES module boundaries, allowing the Terser minifier to mangle internal properties and strip out any synthesizers you don't actively use. **The current highly-optimized core engine sits at ~2.2KB Gzipped.**
 
 ### 1. Clone & Install
 
@@ -356,7 +367,7 @@ export class MyCustomSynth extends CoreSynthBase {
     const gain = this._gain(ctx, 0, masterGain);
 
     // 2. Create a sound wave (Oscillator)
-    const osc = this._osc(ctx, Osc.Square, freq, gain);
+    const osc = this._osc(ctx, "square", freq, gain);
 
     // 3. Mathematical Volume Envelope (ADSR)
     applyEnvelope(gain.gain, time, duration, {

package/dist/Core/AudioMath.d.ts

@@ -0,0 +1,29 @@
+export interface ADSREnvelope {
+    attack?: number;
+    decay?: number;
+    sustain?: number;
+    release?: number;
+    peak?: number;
+}
+/**
+ * Mathematically applies an Attack-Decay-Sustain-Release (ADSR) volume envelope to an AudioParam.
+ *
+ * @reason Why we use explicit `setValueAtTime` and `linearRampToValueAtTime`:
+ * Web Audio nodes often suffer from clicking/popping if values jump instantaneously.
+ * By using linear ramps, we ensure smooth zero-crossing transitions. Furthermore,
+ * the logic elegantly handles edge-cases where the note duration is shorter than
+ * the Attack or Decay phase by dynamically calculating partial peaks and
+ * preemptively jumping to the Release phase, preventing sustained hanging notes.
+ */
+export declare function applyEnvelope(gainParam: AudioParam, now: number, duration: number, opts: ADSREnvelope): void;
+/**
+ * Converts a scientific pitch notation string (e.g., "C4", "F#3") to frequency in Hz.
+ *
+ * @reason Why this is included but conditionally compiled:
+ * This parser is highly convenient for developers writing sequences manually via the API,
+ * allowing `Note("C4")` instead of `261.63`. However, the transpiler strips string notes
+ * during binary compilation, so we wrap this in `__ENABLE_NOTE_PARSER__` to allow Rollup
+ * to entirely remove the Regex from the JS13K build if unused.
+ */
+export declare function Note(pitch: string | number): number;
+//# sourceMappingURL=AudioMath.d.ts.map

package/dist/Core/AudioMath.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"AudioMath.d.ts","sourceRoot":"","sources":["../../Core/AudioMath.ts"],"names":[],"mappings":"AAAA,MAAM,WAAW,YAAY;IAC3B,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAED;;;;;;;;;GASG;AACH,wBAAgB,aAAa,CAC3B,SAAS,EAAE,UAAU,EACrB,GAAG,EAAE,MAAM,EACX,QAAQ,EAAE,MAAM,EAChB,IAAI,EAAE,YAAY,GACjB,IAAI,CAwBN;AAKD;;;;;;;;GAQG;AACH,wBAAgB,IAAI,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,GAAG,MAAM,CAYnD"}

package/dist/Core/AudioMath.js

@@ -0,0 +1,64 @@
+/**
+ * Mathematically applies an Attack-Decay-Sustain-Release (ADSR) volume envelope to an AudioParam.
+ *
+ * @reason Why we use explicit `setValueAtTime` and `linearRampToValueAtTime`:
+ * Web Audio nodes often suffer from clicking/popping if values jump instantaneously.
+ * By using linear ramps, we ensure smooth zero-crossing transitions. Furthermore,
+ * the logic elegantly handles edge-cases where the note duration is shorter than
+ * the Attack or Decay phase by dynamically calculating partial peaks and
+ * preemptively jumping to the Release phase, preventing sustained hanging notes.
+ */
+export function applyEnvelope(gainParam, now, duration, opts) {
+    const a = opts.attack ?? 0.05;
+    const d = opts.decay ?? 0.1;
+    const s = opts.sustain ?? 0.8;
+    const r = opts.release ?? 0.1;
+    const peak = opts.peak ?? 1.0;
+    gainParam.setValueAtTime(0, now);
+    const realDur = Math.max(0, duration);
+    if (realDur <= a) {
+        const partialPeak = peak * (realDur / (a || 1));
+        gainParam.linearRampToValueAtTime(partialPeak, now + realDur * 0.5);
+        gainParam.linearRampToValueAtTime(0, now + realDur);
+    }
+    else if (realDur <= a + d) {
+        gainParam.linearRampToValueAtTime(peak, now + a);
+        gainParam.linearRampToValueAtTime(0, now + realDur);
+    }
+    else {
+        gainParam.linearRampToValueAtTime(peak, now + a);
+        gainParam.linearRampToValueAtTime(peak * s, now + a + d);
+        const releaseStart = Math.max(now + a + d, now + realDur - r);
+        gainParam.setValueAtTime(peak * s, releaseStart);
+        gainParam.linearRampToValueAtTime(0, now + realDur);
+    }
+}
+const hasNoteParser = typeof __ENABLE_NOTE_PARSER__ !== "undefined" ? __ENABLE_NOTE_PARSER__ : true;
+/**
+ * Converts a scientific pitch notation string (e.g., "C4", "F#3") to frequency in Hz.
+ *
+ * @reason Why this is included but conditionally compiled:
+ * This parser is highly convenient for developers writing sequences manually via the API,
+ * allowing `Note("C4")` instead of `261.63`. However, the transpiler strips string notes
+ * during binary compilation, so we wrap this in `__ENABLE_NOTE_PARSER__` to allow Rollup
+ * to entirely remove the Regex from the JS13K build if unused.
+ */
+export function Note(pitch) {
+    if (typeof pitch === "number")
+        return pitch;
+    if (!hasNoteParser)
+        return 0;
+    const match = pitch.match(/^([a-gA-G])([#b]?)(\d)$/);
+    if (!match)
+        return 0;
+    const offsets = { C: -9, D: -7, E: -5, F: -4, G: -2, A: 0, B: 2 };
+    const [, note, accidental, octave] = match;
+    let semitone = offsets[note.toUpperCase()];
+    if (accidental === "#")
+        semitone++;
+    if (accidental === "b")
+        semitone--;
+    semitone += (parseInt(octave, 10) - 4) * 12;
+    return Number((440 * Math.pow(2, semitone / 12)).toFixed(2));
+}
+//# sourceMappingURL=AudioMath.js.map

package/dist/Core/AudioMath.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"AudioMath.js","sourceRoot":"","sources":["../../Core/AudioMath.ts"],"names":[],"mappings":"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"}

package/dist/Core/InstrumentMap.d.ts

@@ -0,0 +1,36 @@
+import { ISynthInstrument } from "../Instruments/ISynthInstrument.js";
+/**
+ * Helper synth that produces zero sound, used as a fallback or placeholder.
+ */
+export declare const SilentSynth: ISynthInstrument;
+/**
+ * Creates a raw mapping between explicit MIDI Program IDs (0-128) and Synthesizer instances.
+ *
+ * @reason Used primarily by the `crush` JS13k build where only 2 or 3 synths are bundled,
+ * avoiding the need for complex fuzzy-matching loops.
+ */
+export declare function createDirectMap(assignments: {
+    synth: ISynthInstrument;
+    ids: number[];
+}[]): ISynthInstrument[];
+/**
+ * Populates a 128-slot Array mapping MIDI Program IDs to Synthesizer instances.
+ *
+ * @reason The NPM library comes with 16 default synths. Standard MIDI files might
+ * request Program ID 44 (Contrabass), but we only have `StringSynth` mapped to 40-55.
+ * This function uses a fuzzy "closest neighbor" algorithm to automatically fill
+ * any missing gaps (e.g. mapping ID 44 to the nearest available synth ID). This guarantees
+ * that imported MIDI files will always produce sound, even if the user hasn't explicitly
+ * instantiated all 128 GM instruments.
+ */
+export declare function createInstrumentMap(modules: {
+    synth: ISynthInstrument;
+    start: number;
+    end: number;
+}[]): ISynthInstrument[];
+export declare function extendInstrumentMap(baseMap: ISynthInstrument[], overrides: {
+    synth: ISynthInstrument;
+    start: number;
+    end: number;
+}[]): ISynthInstrument[];
+//# sourceMappingURL=InstrumentMap.d.ts.map

package/dist/Core/InstrumentMap.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"InstrumentMap.d.ts","sourceRoot":"","sources":["../../Core/InstrumentMap.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,gBAAgB,EAAE,MAAM,oCAAoC,CAAC;AAEtE;;GAEG;AACH,eAAO,MAAM,WAAW,EAAE,gBAEzB,CAAC;AAEF;;;;;GAKG;AACH,wBAAgB,eAAe,CAAC,WAAW,EAAE;IAAE,KAAK,EAAE,gBAAgB,CAAC;IAAC,GAAG,EAAE,MAAM,EAAE,CAAA;CAAE,EAAE,GAAG,gBAAgB,EAAE,CAM7G;AAED;;;;;;;;;GASG;AACH,wBAAgB,mBAAmB,CAAC,OAAO,EAAE;IAAE,KAAK,EAAE,gBAAgB,CAAC;IAAC,KAAK,EAAE,MAAM,CAAC;IAAC,GAAG,EAAE,MAAM,CAAA;CAAE,EAAE,GAAG,gBAAgB,EAAE,CAuB1H;AAED,wBAAgB,mBAAmB,CAAC,OAAO,EAAE,gBAAgB,EAAE,EAAE,SAAS,EAAE;IAAE,KAAK,EAAE,gBAAgB,CAAC;IAAC,KAAK,EAAE,MAAM,CAAC;IAAC,GAAG,EAAE,MAAM,CAAA;CAAE,EAAE,GAAG,gBAAgB,EAAE,CAMzJ"}

package/dist/Core/InstrumentMap.js

@@ -0,0 +1,62 @@
+/**
+ * Helper synth that produces zero sound, used as a fallback or placeholder.
+ */
+export const SilentSynth = {
+    _playNote: () => { },
+};
+/**
+ * Creates a raw mapping between explicit MIDI Program IDs (0-128) and Synthesizer instances.
+ *
+ * @reason Used primarily by the `crush` JS13k build where only 2 or 3 synths are bundled,
+ * avoiding the need for complex fuzzy-matching loops.
+ */
+export function createDirectMap(assignments) {
+    const mapArray = new Array(129).fill(null);
+    assignments.forEach((a) => {
+        a.ids.forEach((id) => (mapArray[id] = a.synth));
+    });
+    return mapArray;
+}
+/**
+ * Populates a 128-slot Array mapping MIDI Program IDs to Synthesizer instances.
+ *
+ * @reason The NPM library comes with 16 default synths. Standard MIDI files might
+ * request Program ID 44 (Contrabass), but we only have `StringSynth` mapped to 40-55.
+ * This function uses a fuzzy "closest neighbor" algorithm to automatically fill
+ * any missing gaps (e.g. mapping ID 44 to the nearest available synth ID). This guarantees
+ * that imported MIDI files will always produce sound, even if the user hasn't explicitly
+ * instantiated all 128 GM instruments.
+ */
+export function createInstrumentMap(modules) {
+    const mapArray = new Array(129).fill(null);
+    modules.forEach((m) => {
+        for (let i = m.start; i <= m.end; i++)
+            mapArray[i] = m.synth;
+    });
+    for (let i = 0; i < 129; i++) {
+        if (mapArray[i] === null) {
+            let closest = null;
+            let minDiff = Infinity;
+            for (let j = 0; j < 129; j++) {
+                if (mapArray[j] !== null) {
+                    const diff = Math.abs(i - j);
+                    if (diff < minDiff) {
+                        minDiff = diff;
+                        closest = mapArray[j];
+                    }
+                }
+            }
+            mapArray[i] = closest;
+        }
+    }
+    return mapArray;
+}
+export function extendInstrumentMap(baseMap, overrides) {
+    const newMap = [...baseMap];
+    overrides.forEach((m) => {
+        for (let i = m.start; i <= m.end; i++)
+            newMap[i] = m.synth;
+    });
+    return newMap;
+}
+//# sourceMappingURL=InstrumentMap.js.map

package/dist/Core/InstrumentMap.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"InstrumentMap.js","sourceRoot":"","sources":["../../Core/InstrumentMap.ts"],"names":[],"mappings":"AAEA;;GAEG;AACH,MAAM,CAAC,MAAM,WAAW,GAAqB;IAC3C,SAAS,EAAE,GAAG,EAAE,GAAE,CAAC;CACpB,CAAC;AAEF;;;;;GAKG;AACH,MAAM,UAAU,eAAe,CAAC,WAAyD;IACvF,MAAM,QAAQ,GAAG,IAAI,KAAK,CAAC,GAAG,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IAC3C,WAAW,CAAC,OAAO,CAAC,CAAC,CAAC,EAAE,EAAE;QACxB,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,EAAE,EAAE,EAAE,CAAC,CAAC,QAAQ,CAAC,EAAE,CAAC,GAAG,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC;IAClD,CAAC,CAAC,CAAC;IACH,OAAO,QAAQ,CAAC;AAClB,CAAC;AAED;;;;;;;;;GASG;AACH,MAAM,UAAU,mBAAmB,CAAC,OAAkE;IACpG,MAAM,QAAQ,GAAG,IAAI,KAAK,CAAC,GAAG,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IAC3C,OAAO,CAAC,OAAO,CAAC,CAAC,CAAC,EAAE,EAAE;QACpB,KAAK,IAAI,CAAC,GAAG,CAAC,CAAC,KAAK,EAAE,CAAC,IAAI,CAAC,CAAC,GAAG,EAAE,CAAC,EAAE;YAAE,QAAQ,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,KAAK,CAAC;IAC/D,CAAC,CAAC,CAAC;IAEH,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,GAAG,EAAE,CAAC,EAAE,EAAE,CAAC;QAC7B,IAAI,QAAQ,CAAC,CAAC,CAAC,KAAK,IAAI,EAAE,CAAC;YACzB,IAAI,OAAO,GAAG,IAAI,CAAC;YACnB,IAAI,OAAO,GAAG,QAAQ,CAAC;YACvB,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,GAAG,EAAE,CAAC,EAAE,EAAE,CAAC;gBAC7B,IAAI,QAAQ,CAAC,CAAC,CAAC,KAAK,IAAI,EAAE,CAAC;oBACzB,MAAM,IAAI,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC;oBAC7B,IAAI,IAAI,GAAG,OAAO,EAAE,CAAC;wBACnB,OAAO,GAAG,IAAI,CAAC;wBACf,OAAO,GAAG,QAAQ,CAAC,CAAC,CAAC,CAAC;oBACxB,CAAC;gBACH,CAAC;YACH,CAAC;YACD,QAAQ,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC;QACxB,CAAC;IACH,CAAC;IACD,OAAO,QAAQ,CAAC;AAClB,CAAC;AAED,MAAM,UAAU,mBAAmB,CAAC,OAA2B,EAAE,SAAoE;IACnI,MAAM,MAAM,GAAG,CAAC,GAAG,OAAO,CAAC,CAAC;IAC5B,SAAS,CAAC,OAAO,CAAC,CAAC,CAAC,EAAE,EAAE;QACtB,KAAK,IAAI,CAAC,GAAG,CAAC,CAAC,KAAK,EAAE,CAAC,IAAI,CAAC,CAAC,GAAG,EAAE,CAAC,EAAE;YAAE,MAAM,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,KAAK,CAAC;IAC7D,CAAC,CAAC,CAAC;IACH,OAAO,MAAM,CAAC;AAChB,CAAC"}

package/dist/Core/RLOCore.d.ts

@@ -0,0 +1,49 @@
+import { RloData } from "../types.js";
+import { ISynthInstrument } from "../Instruments/ISynthInstrument.js";
+/**
+ * Options for playing a compiled RLO sequence.
+ */
+export interface PlaySequenceOptions {
+    loop?: boolean;
+    fadeInTime?: number;
+    playbackRate?: number;
+    volume?: number;
+}
+/**
+ * Base Engine Core responsible for the precise scheduling and timing of Web Audio nodes.
+ *
+ * @reason Why we use a Worker for the metronome:
+ * In modern browsers, `setTimeout` or `setInterval` on the main thread is throttled
+ * to ~1000ms if the user switches browser tabs (to save battery).
+ * By offloading the timing loop to a Web Worker, we guarantee that background tabs
+ * continue to schedule audio nodes perfectly at 50ms intervals without skipping a beat.
+ */
+export declare class RLOCore {
+    protected _ctx: AudioContext;
+    protected _isPlaying: boolean;
+    protected _timer: ReturnType<typeof setTimeout> | null;
+    protected _workerTimer: Worker | null;
+    protected _sequenceId: number;
+    protected _trkT: number;
+    protected _trkD: number;
+    protected _activeNodes: AudioNode[];
+    protected _volume: number;
+    protected _seekTarget: number | null;
+    playbackRate: number;
+    protected _instrumentMap: ISynthInstrument[];
+    protected _workerUrl: string | null;
+    constructor(audioContext: AudioContext, instrumentMap?: ISynthInstrument[]);
+    protected get _now(): number;
+    setVolume(vol: number): void;
+    seek(timeInSeconds: number): void;
+    stop(): void;
+    dispose(): void;
+    protected _createGain(): GainNode;
+    protected _applyLinearFade(gain: AudioParam, target: number, time: number): void;
+    protected _createCompressor(ctx?: AudioContext): DynamicsCompressorNode;
+    protected _createRouting(fadeInTime?: number): {
+        destination: AudioNode;
+    };
+    playSequence(track: RloData, loopOrOpts?: boolean | PlaySequenceOptions, oldFadeInTime?: number): void;
+}
+//# sourceMappingURL=RLOCore.d.ts.map

package/dist/Core/RLOCore.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"RLOCore.d.ts","sourceRoot":"","sources":["../../Core/RLOCore.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,MAAM,aAAa,CAAC;AACtC,OAAO,EAAE,gBAAgB,EAAE,MAAM,oCAAoC,CAAC;AAGtE;;GAEG;AACH,MAAM,WAAW,mBAAmB;IAClC,IAAI,CAAC,EAAE,OAAO,CAAC;IACf,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAKD;;;;;;;;GAQG;AACH,qBAAa,OAAO;IAClB,SAAS,CAAC,IAAI,EAAE,YAAY,CAAC;IAC7B,SAAS,CAAC,UAAU,EAAE,OAAO,CAAS;IACtC,SAAS,CAAC,MAAM,EAAE,UAAU,CAAC,OAAO,UAAU,CAAC,GAAG,IAAI,CAAQ;IAC9D,SAAS,CAAC,YAAY,EAAE,MAAM,GAAG,IAAI,CAAQ;IAC7C,SAAS,CAAC,WAAW,EAAE,MAAM,CAAK;IAClC,SAAS,CAAC,KAAK,EAAE,MAAM,CAAK;IAC5B,SAAS,CAAC,KAAK,EAAE,MAAM,CAAK;IAC5B,SAAS,CAAC,YAAY,EAAE,SAAS,EAAE,CAAM;IACzC,SAAS,CAAC,OAAO,EAAE,MAAM,CAAO;IAChC,SAAS,CAAC,WAAW,EAAE,MAAM,GAAG,IAAI,CAAQ;IAErC,YAAY,EAAE,MAAM,CAAO;IAElC,SAAS,CAAC,cAAc,EAAE,gBAAgB,EAAE,CAAC;IAC7C,SAAS,CAAC,UAAU,EAAE,MAAM,GAAG,IAAI,CAAQ;gBAE/B,YAAY,EAAE,YAAY,EAAE,aAAa,GAAE,gBAAgB,EAAO;IAgB9E,SAAS,KAAK,IAAI,IAAI,MAAM,CAE3B;IAEM,SAAS,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI;IAI5B,IAAI,CAAC,aAAa,EAAE,MAAM,GAAG,IAAI;IAMjC,IAAI,IAAI,IAAI;IAcZ,OAAO,IAAI,IAAI;IAYtB,SAAS,CAAC,WAAW,IAAI,QAAQ;IAIjC,SAAS,CAAC,gBAAgB,CAAC,IAAI,EAAE,UAAU,EAAE,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,IAAI;IAKhF,SAAS,CAAC,iBAAiB,CAAC,GAAG,GAAE,YAAwB,GAAG,sBAAsB;IAUlF,SAAS,CAAC,cAAc,CAAC,UAAU,GAAE,MAAU,GAAG;QAAE,WAAW,EAAE,SAAS,CAAA;KAAE;IAQrE,YAAY,CAAC,KAAK,EAAE,OAAO,EAAE,UAAU,GAAE,OAAO,GAAG,mBAA0B,EAAE,aAAa,GAAE,MAAU,GAAG,IAAI;CAkGvH"}

package/dist/Core/RLOCore.js

@@ -0,0 +1,188 @@
+import { Synthesizer } from "../Instruments/Synthesizer.js";
+const hasWorkerMetronome = typeof __ENABLE_WORKER_METRONOME__ !== "undefined" ? __ENABLE_WORKER_METRONOME__ : false;
+/**
+ * Base Engine Core responsible for the precise scheduling and timing of Web Audio nodes.
+ *
+ * @reason Why we use a Worker for the metronome:
+ * In modern browsers, `setTimeout` or `setInterval` on the main thread is throttled
+ * to ~1000ms if the user switches browser tabs (to save battery).
+ * By offloading the timing loop to a Web Worker, we guarantee that background tabs
+ * continue to schedule audio nodes perfectly at 50ms intervals without skipping a beat.
+ */
+export class RLOCore {
+    constructor(audioContext, instrumentMap = []) {
+        this._isPlaying = false;
+        this._timer = null;
+        this._workerTimer = null;
+        this._sequenceId = 0;
+        this._trkT = 0;
+        this._trkD = 0;
+        this._activeNodes = [];
+        this._volume = 0.5;
+        this._seekTarget = null;
+        this.playbackRate = 1.0;
+        this._workerUrl = null;
+        this._ctx = audioContext;
+        this._instrumentMap = instrumentMap;
+        if (hasWorkerMetronome) {
+            const blob = new Blob([
+                "let t=null;self.onmessage=e=>{let d=e.data;if(d=='start'){if(t)clearInterval(t);t=setInterval(()=>self.postMessage('tick'),50)}else if(d=='stop'&&t){clearInterval(t);t=null}};"
+            ], { type: "application/javascript" });
+            this._workerUrl = URL.createObjectURL(blob);
+            this._workerTimer = new Worker(this._workerUrl);
+        }
+    }
+    get _now() {
+        return this._ctx.currentTime;
+    }
+    setVolume(vol) {
+        this._volume = vol;
+    }
+    seek(timeInSeconds) {
+        if (this._trkD > 0) {
+            this._seekTarget = Math.max(0, timeInSeconds) % this._trkD;
+        }
+    }
+    stop() {
+        this._isPlaying = false;
+        this._sequenceId++;
+        if (this._timer)
+            clearTimeout(this._timer);
+        if (hasWorkerMetronome && this._workerTimer)
+            this._workerTimer.postMessage("stop");
+        const nodesToClean = this._activeNodes;
+        this._activeNodes = [];
+        while (nodesToClean.length) {
+            try {
+                nodesToClean.pop().disconnect();
+            }
+            catch (e) { }
+        }
+    }
+    dispose() {
+        this.stop();
+        if (hasWorkerMetronome && this._workerTimer) {
+            this._workerTimer.terminate();
+            this._workerTimer = null;
+        }
+        if (hasWorkerMetronome && this._workerUrl) {
+            URL.revokeObjectURL(this._workerUrl);
+            this._workerUrl = null;
+        }
+    }
+    _createGain() {
+        return this._ctx.createGain();
+    }
+    _applyLinearFade(gain, target, time) {
+        gain.setValueAtTime(time > 0 ? 0 : target, this._now);
+        if (time > 0)
+            gain.linearRampToValueAtTime(target, this._now + time);
+    }
+    _createCompressor(ctx = this._ctx) {
+        const c = ctx.createDynamicsCompressor();
+        c.threshold.value = -24;
+        c.knee.value = 12;
+        c.ratio.value = 8;
+        c.attack.value = 0.001;
+        c.release.value = 0.25;
+        return c;
+    }
+    _createRouting(fadeInTime = 0) {
+        const gain = this._createGain();
+        this._applyLinearFade(gain.gain, this._volume, fadeInTime);
+        gain.connect(this._ctx.destination);
+        this._activeNodes.push(gain);
+        return { destination: gain };
+    }
+    playSequence(track, loopOrOpts = true, oldFadeInTime = 0) {
+        let loop = true;
+        let fadeInTime = oldFadeInTime;
+        if (typeof loopOrOpts === "object") {
+            loop = loopOrOpts.loop ?? true;
+            fadeInTime = loopOrOpts.fadeInTime ?? 0;
+            this.playbackRate = loopOrOpts.playbackRate ?? this.playbackRate;
+            if (loopOrOpts.volume !== undefined)
+                this.setVolume(loopOrOpts.volume);
+        }
+        else {
+            loop = loopOrOpts;
+        }
+        this.stop();
+        if (this._ctx.state === "suspended")
+            this._ctx.resume();
+        this._isPlaying = true;
+        const currentSequenceId = ++this._sequenceId;
+        this._trkD = track.durationSecs;
+        const { destination } = this._createRouting(fadeInTime);
+        const synthesizer = new Synthesizer(this._ctx, destination, this._instrumentMap);
+        const lookaheadTime = 0.5;
+        this._trkT = -0.05 * this.playbackRate;
+        let lastScheduleTime = this._now;
+        let loopOffsetSecs = 0;
+        let notePtr = 0;
+        const notes = track.notes;
+        const len = notes.length;
+        const schedule = () => {
+            if (!this._isPlaying || this._sequenceId !== currentSequenceId)
+                return;
+            if (len === 0)
+                return; // Prevent infinite loop on empty tracks
+            const currentPhysicalTime = this._now;
+            const deltaPhysical = currentPhysicalTime - lastScheduleTime;
+            lastScheduleTime = currentPhysicalTime;
+            if (this._seekTarget !== null) {
+                this._trkT = this._seekTarget;
+                loopOffsetSecs = 0;
+                notePtr = 0;
+                while (notePtr < len && notes[notePtr + 1] < this._seekTarget) {
+                    notePtr += 5;
+                }
+                this._seekTarget = null;
+                // Duck the volume briefly to hide the 0.5s lookahead buffer overlap
+                const duckGain = destination;
+                if (duckGain.gain) {
+                    duckGain.gain.cancelScheduledValues(currentPhysicalTime);
+                    duckGain.gain.setValueAtTime(0.001, currentPhysicalTime);
+                    duckGain.gain.exponentialRampToValueAtTime(this._volume, currentPhysicalTime + 0.5);
+                }
+            }
+            else {
+                this._trkT += deltaPhysical * this.playbackRate;
+            }
+            const loopDurationSecs = track.durationSecs;
+            while (notePtr < len) {
+                const noteTrackTime = loopOffsetSecs + notes[notePtr + 1];
+                if (noteTrackTime >= this._trkT + lookaheadTime * this.playbackRate)
+                    break;
+                // The "Lag Chord" drop threshold:
+                // If a thread freeze occurred, drop notes that are more than 150ms in the past
+                if (this._trkT - noteTrackTime <= 0.15 * this.playbackRate) {
+                    const notePhysicalTime = currentPhysicalTime + Math.max(0, (noteTrackTime - this._trkT) / this.playbackRate);
+                    synthesizer._playNote(notes[notePtr + 4], notePhysicalTime, notes[notePtr], notes[notePtr + 2] / this.playbackRate, notes[notePtr + 3]);
+                }
+                notePtr += 5;
+            }
+            if (notePtr >= len) {
+                if (loop) {
+                    notePtr = 0;
+                    loopOffsetSecs += loopDurationSecs;
+                    schedule();
+                }
+                else {
+                    if (hasWorkerMetronome && this._workerTimer)
+                        this._workerTimer.postMessage("stop");
+                }
+                return;
+            }
+            if (!hasWorkerMetronome || !this._workerTimer) {
+                this._timer = setTimeout(schedule, 50);
+            }
+        };
+        if (hasWorkerMetronome && this._workerTimer) {
+            this._workerTimer.onmessage = () => schedule();
+            this._workerTimer.postMessage("start");
+        }
+        schedule();
+    }
+}
+//# sourceMappingURL=RLOCore.js.map

package/dist/Core/RLOCore.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"RLOCore.js","sourceRoot":"","sources":["../../Core/RLOCore.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,WAAW,EAAE,MAAM,+BAA+B,CAAC;AAa5D,MAAM,kBAAkB,GAAG,OAAO,2BAA2B,KAAK,WAAW,CAAC,CAAC,CAAC,2BAA2B,CAAC,CAAC,CAAC,KAAK,CAAC;AAEpH;;;;;;;;GAQG;AACH,MAAM,OAAO,OAAO;IAiBlB,YAAY,YAA0B,EAAE,gBAAoC,EAAE;QAfpE,eAAU,GAAY,KAAK,CAAC;QAC5B,WAAM,GAAyC,IAAI,CAAC;QACpD,iBAAY,GAAkB,IAAI,CAAC;QACnC,gBAAW,GAAW,CAAC,CAAC;QACxB,UAAK,GAAW,CAAC,CAAC;QAClB,UAAK,GAAW,CAAC,CAAC;QAClB,iBAAY,GAAgB,EAAE,CAAC;QAC/B,YAAO,GAAW,GAAG,CAAC;QACtB,gBAAW,GAAkB,IAAI,CAAC;QAErC,iBAAY,GAAW,GAAG,CAAC;QAGxB,eAAU,GAAkB,IAAI,CAAC;QAGzC,IAAI,CAAC,IAAI,GAAG,YAAY,CAAC;QACzB,IAAI,CAAC,cAAc,GAAG,aAAa,CAAC;QAEpC,IAAI,kBAAkB,EAAE,CAAC;YACvB,MAAM,IAAI,GAAG,IAAI,IAAI,CACnB;gBACE,iLAAiL;aAClL,EACD,EAAE,IAAI,EAAE,wBAAwB,EAAE,CACnC,CAAC;YACF,IAAI,CAAC,UAAU,GAAG,GAAG,CAAC,eAAe,CAAC,IAAI,CAAC,CAAC;YAC5C,IAAI,CAAC,YAAY,GAAG,IAAI,MAAM,CAAC,IAAI,CAAC,UAAU,CAAC,CAAC;QAClD,CAAC;IACH,CAAC;IAED,IAAc,IAAI;QAChB,OAAO,IAAI,CAAC,IAAI,CAAC,WAAW,CAAC;IAC/B,CAAC;IAEM,SAAS,CAAC,GAAW;QAC1B,IAAI,CAAC,OAAO,GAAG,GAAG,CAAC;IACrB,CAAC;IAEM,IAAI,CAAC,aAAqB;QAC/B,IAAI,IAAI,CAAC,KAAK,GAAG,CAAC,EAAE,CAAC;YACnB,IAAI,CAAC,WAAW,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,aAAa,CAAC,GAAG,IAAI,CAAC,KAAK,CAAC;QAC7D,CAAC;IACH,CAAC;IAEM,IAAI;QACT,IAAI,CAAC,UAAU,GAAG,KAAK,CAAC;QACxB,IAAI,CAAC,WAAW,EAAE,CAAC;QACnB,IAAI,IAAI,CAAC,MAAM;YAAE,YAAY,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC;QAC3C,IAAI,kBAAkB,IAAI,IAAI,CAAC,YAAY;YAAE,IAAI,CAAC,YAAY,CAAC,WAAW,CAAC,MAAM,CAAC,CAAC;QAEnF,MAAM,YAAY,GAAG,IAAI,CAAC,YAAY,CAAC;QACvC,IAAI,CAAC,YAAY,GAAG,EAAE,CAAC;QAEvB,OAAO,YAAY,CAAC,MAAM,EAAE,CAAC;YAC3B,IAAI,CAAC;gBAAC,YAAY,CAAC,GAAG,EAAG,CAAC,UAAU,EAAE,CAAC;YAAC,CAAC;YAAC,OAAO,CAAC,EAAE,CAAC,CAAA,CAAC;QACxD,CAAC;IACH,CAAC;IAEM,OAAO;QACZ,IAAI,CAAC,IAAI,EAAE,CAAC;QACZ,IAAI,kBAAkB,IAAI,IAAI,CAAC,YAAY,EAAE,CAAC;YAC5C,IAAI,CAAC,YAAY,CAAC,SAAS,EAAE,CAAC;YAC9B,IAAI,CAAC,YAAY,GAAG,IAAI,CAAC;QAC3B,CAAC;QACD,IAAI,kBAAkB,IAAI,IAAI,CAAC,UAAU,EAAE,CAAC;YAC1C,GAAG,CAAC,eAAe,CAAC,IAAI,CAAC,UAAU,CAAC,CAAC;YACrC,IAAI,CAAC,UAAU,GAAG,IAAI,CAAC;QACzB,CAAC;IACH,CAAC;IAES,WAAW;QACnB,OAAO,IAAI,CAAC,IAAI,CAAC,UAAU,EAAE,CAAC;IAChC,CAAC;IAES,gBAAgB,CAAC,IAAgB,EAAE,MAAc,EAAE,IAAY;QACvE,IAAI,CAAC,cAAc,CAAC,IAAI,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,MAAM,EAAE,IAAI,CAAC,IAAI,CAAC,CAAC;QACtD,IAAI,IAAI,GAAG,CAAC;YAAE,IAAI,CAAC,uBAAuB,CAAC,MAAM,EAAE,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC,CAAC;IACvE,CAAC;IAES,iBAAiB,CAAC,MAAoB,IAAI,CAAC,IAAI;QACvD,MAAM,CAAC,GAAG,GAAG,CAAC,wBAAwB,EAAE,CAAC;QACzC,CAAC,CAAC,SAAS,CAAC,KAAK,GAAG,CAAC,EAAE,CAAC;QACxB,CAAC,CAAC,IAAI,CAAC,KAAK,GAAG,EAAE,CAAC;QAClB,CAAC,CAAC,KAAK,CAAC,KAAK,GAAG,CAAC,CAAC;QAClB,CAAC,CAAC,MAAM,CAAC,KAAK,GAAG,KAAK,CAAC;QACvB,CAAC,CAAC,OAAO,CAAC,KAAK,GAAG,IAAI,CAAC;QACvB,OAAO,CAAC,CAAC;IACX,CAAC;IAES,cAAc,CAAC,aAAqB,CAAC;QAC7C,MAAM,IAAI,GAAG,IAAI,CAAC,WAAW,EAAE,CAAC;QAChC,IAAI,CAAC,gBAAgB,CAAC,IAAI,CAAC,IAAI,EAAE,IAAI,CAAC,OAAO,EAAE,UAAU,CAAC,CAAC;QAC3D,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,IAAI,CAAC,WAAW,CAAC,CAAC;QACpC,IAAI,CAAC,YAAY,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;QAC7B,OAAO,EAAE,WAAW,EAAE,IAAI,EAAE,CAAC;IAC/B,CAAC;IAEM,YAAY,CAAC,KAAc,EAAE,aAA4C,IAAI,EAAE,gBAAwB,CAAC;QAC7G,IAAI,IAAI,GAAG,IAAI,CAAC;QAChB,IAAI,UAAU,GAAG,aAAa,CAAC;QAC/B,IAAI,OAAO,UAAU,KAAK,QAAQ,EAAE,CAAC;YACnC,IAAI,GAAG,UAAU,CAAC,IAAI,IAAI,IAAI,CAAC;YAC/B,UAAU,GAAG,UAAU,CAAC,UAAU,IAAI,CAAC,CAAC;YACxC,IAAI,CAAC,YAAY,GAAG,UAAU,CAAC,YAAY,IAAI,IAAI,CAAC,YAAY,CAAC;YACjE,IAAI,UAAU,CAAC,MAAM,KAAK,SAAS;gBAAE,IAAI,CAAC,SAAS,CAAC,UAAU,CAAC,MAAM,CAAC,CAAC;QACzE,CAAC;aAAM,CAAC;YACN,IAAI,GAAG,UAAU,CAAC;QACpB,CAAC;QAED,IAAI,CAAC,IAAI,EAAE,CAAC;QACZ,IAAI,IAAI,CAAC,IAAI,CAAC,KAAK,KAAK,WAAW;YAAE,IAAI,CAAC,IAAI,CAAC,MAAM,EAAE,CAAC;QAExD,IAAI,CAAC,UAAU,GAAG,IAAI,CAAC;QACvB,MAAM,iBAAiB,GAAG,EAAE,IAAI,CAAC,WAAW,CAAC;QAC7C,IAAI,CAAC,KAAK,GAAG,KAAK,CAAC,YAAY,CAAC;QAEhC,MAAM,EAAE,WAAW,EAAE,GAAG,IAAI,CAAC,cAAc,CAAC,UAAU,CAAC,CAAC;QACxD,MAAM,WAAW,GAAG,IAAI,WAAW,CACjC,IAAI,CAAC,IAAI,EACT,WAAuB,EACvB,IAAI,CAAC,cAAc,CACpB,CAAC;QAEF,MAAM,aAAa,GAAG,GAAG,CAAC;QAC1B,IAAI,CAAC,KAAK,GAAG,CAAC,IAAI,GAAG,IAAI,CAAC,YAAY,CAAC;QACvC,IAAI,gBAAgB,GAAG,IAAI,CAAC,IAAI,CAAC;QACjC,IAAI,cAAc,GAAG,CAAC,CAAC;QACvB,IAAI,OAAO,GAAG,CAAC,CAAC;QAChB,MAAM,KAAK,GAAG,KAAK,CAAC,KAAK,CAAC;QAC1B,MAAM,GAAG,GAAG,KAAK,CAAC,MAAM,CAAC;QAEzB,MAAM,QAAQ,GAAG,GAAG,EAAE;YACpB,IAAI,CAAC,IAAI,CAAC,UAAU,IAAI,IAAI,CAAC,WAAW,KAAK,iBAAiB;gBAAE,OAAO;YACvE,IAAI,GAAG,KAAK,CAAC;gBAAE,OAAO,CAAC,wCAAwC;YAE/D,MAAM,mBAAmB,GAAG,IAAI,CAAC,IAAI,CAAC;YACtC,MAAM,aAAa,GAAG,mBAAmB,GAAG,gBAAgB,CAAC;YAC7D,gBAAgB,GAAG,mBAAmB,CAAC;YAEvC,IAAI,IAAI,CAAC,WAAW,KAAK,IAAI,EAAE,CAAC;gBAC9B,IAAI,CAAC,KAAK,GAAG,IAAI,CAAC,WAAW,CAAC;gBAC9B,cAAc,GAAG,CAAC,CAAC;gBACnB,OAAO,GAAG,CAAC,CAAC;gBACZ,OAAO,OAAO,GAAG,GAAG,IAAI,KAAK,CAAC,OAAO,GAAG,CAAC,CAAC,GAAG,IAAI,CAAC,WAAW,EAAE,CAAC;oBAC9D,OAAO,IAAI,CAAC,CAAC;gBACf,CAAC;gBACD,IAAI,CAAC,WAAW,GAAG,IAAI,CAAC;gBAExB,oEAAoE;gBACpE,MAAM,QAAQ,GAAG,WAAuB,CAAC;gBACzC,IAAI,QAAQ,CAAC,IAAI,EAAE,CAAC;oBACjB,QAAQ,CAAC,IAAI,CAAC,qBAAqB,CAAC,mBAAmB,CAAC,CAAC;oBACzD,QAAQ,CAAC,IAAI,CAAC,cAAc,CAAC,KAAK,EAAE,mBAAmB,CAAC,CAAC;oBACzD,QAAQ,CAAC,IAAI,CAAC,4BAA4B,CAAC,IAAI,CAAC,OAAO,EAAE,mBAAmB,GAAG,GAAG,CAAC,CAAC;gBACvF,CAAC;YACH,CAAC;iBAAM,CAAC;gBACN,IAAI,CAAC,KAAK,IAAI,aAAa,GAAG,IAAI,CAAC,YAAY,CAAC;YAClD,CAAC;YAED,MAAM,gBAAgB,GAAG,KAAK,CAAC,YAAY,CAAC;YAE5C,OAAO,OAAO,GAAG,GAAG,EAAE,CAAC;gBACrB,MAAM,aAAa,GAAG,cAAc,GAAG,KAAK,CAAC,OAAO,GAAG,CAAC,CAAC,CAAC;gBAE1D,IAAI,aAAa,IAAI,IAAI,CAAC,KAAK,GAAG,aAAa,GAAG,IAAI,CAAC,YAAY;oBAAE,MAAM;gBAE3E,kCAAkC;gBAClC,+EAA+E;gBAC/E,IAAI,IAAI,CAAC,KAAK,GAAG,aAAa,IAAI,IAAI,GAAG,IAAI,CAAC,YAAY,EAAE,CAAC;oBAC3D,MAAM,gBAAgB,GAAG,mBAAmB,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,CAAC,aAAa,GAAG,IAAI,CAAC,KAAK,CAAC,GAAG,IAAI,CAAC,YAAY,CAAC,CAAC;oBAC7G,WAAW,CAAC,SAAS,CAAC,KAAK,CAAC,OAAO,GAAG,CAAC,CAAC,EAAE,gBAAgB,EAAE,KAAK,CAAC,OAAO,CAAC,EAAE,KAAK,CAAC,OAAO,GAAG,CAAC,CAAC,GAAG,IAAI,CAAC,YAAY,EAAE,KAAK,CAAC,OAAO,GAAG,CAAC,CAAC,CAAC,CAAC;gBAC1I,CAAC;gBACD,OAAO,IAAI,CAAC,CAAC;YACf,CAAC;YAED,IAAI,OAAO,IAAI,GAAG,EAAE,CAAC;gBACnB,IAAI,IAAI,EAAE,CAAC;oBACT,OAAO,GAAG,CAAC,CAAC;oBACZ,cAAc,IAAI,gBAAgB,CAAC;oBACnC,QAAQ,EAAE,CAAC;gBACb,CAAC;qBAAM,CAAC;oBACN,IAAI,kBAAkB,IAAI,IAAI,CAAC,YAAY;wBAAE,IAAI,CAAC,YAAY,CAAC,WAAW,CAAC,MAAM,CAAC,CAAC;gBACrF,CAAC;gBACD,OAAO;YACT,CAAC;YACD,IAAI,CAAC,kBAAkB,IAAI,CAAC,IAAI,CAAC,YAAY,EAAE,CAAC;gBAC9C,IAAI,CAAC,MAAM,GAAG,UAAU,CAAC,QAAQ,EAAE,EAAE,CAAC,CAAC;YACzC,CAAC;QACH,CAAC,CAAC;QACF,IAAI,kBAAkB,IAAI,IAAI,CAAC,YAAY,EAAE,CAAC;YAC5C,IAAI,CAAC,YAAY,CAAC,SAAS,GAAG,GAAG,EAAE,CAAC,QAAQ,EAAE,CAAC;YAC/C,IAAI,CAAC,YAAY,CAAC,WAAW,CAAC,OAAO,CAAC,CAAC;QACzC,CAAC;QACD,QAAQ,EAAE,CAAC;IACb,CAAC;CACF"}

package/dist/Core/SequenceBuilder.d.ts

@@ -0,0 +1,23 @@
+import { RloData } from "../types.js";
+/**
+ * Fluent API for constructing RLO sequences programmatically without using a compiler.
+ *
+ * @reason This class directly pushes `[frequency, time, duration, velocity, instrument]`
+ * tuples into a flat `number[]` array. By avoiding intermediary JS Objects `{ note: 'C4', dur: 1 }`
+ * we completely eliminate Garbage Collection (GC) pauses during sequence generation,
+ * making it incredibly fast for procedural music generation at runtime.
+ */
+export declare class RLOSequenceBuilder {
+    private _notes;
+    private _duration;
+    addNote(opts: {
+        instrument: number;
+        pitch: string | number;
+        duration: number;
+        time?: number;
+        velocity?: number;
+    }): this;
+    setDuration(secs: number): this;
+    compile(): RloData;
+}
+//# sourceMappingURL=SequenceBuilder.d.ts.map

package/dist/Core/SequenceBuilder.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"SequenceBuilder.d.ts","sourceRoot":"","sources":["../../Core/SequenceBuilder.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,MAAM,aAAa,CAAC;AAGtC;;;;;;;GAOG;AACH,qBAAa,kBAAkB;IAC7B,OAAO,CAAC,MAAM,CAAgB;IAC9B,OAAO,CAAC,SAAS,CAAa;IAEvB,OAAO,CAAC,IAAI,EAAE;QAAE,UAAU,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAAC;QAAC,QAAQ,EAAE,MAAM,CAAC;QAAC,IAAI,CAAC,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;KAAE,GAAG,IAAI;IAQxH,WAAW,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI;IAI/B,OAAO,IAAI,OAAO;CAG1B"}

package/dist/Core/SequenceBuilder.js

@@ -0,0 +1,31 @@
+import { Note } from "./AudioMath.js";
+/**
+ * Fluent API for constructing RLO sequences programmatically without using a compiler.
+ *
+ * @reason This class directly pushes `[frequency, time, duration, velocity, instrument]`
+ * tuples into a flat `number[]` array. By avoiding intermediary JS Objects `{ note: 'C4', dur: 1 }`
+ * we completely eliminate Garbage Collection (GC) pauses during sequence generation,
+ * making it incredibly fast for procedural music generation at runtime.
+ */
+export class RLOSequenceBuilder {
+    constructor() {
+        this._notes = [];
+        this._duration = 0;
+    }
+    addNote(opts) {
+        const time = opts.time !== undefined ? opts.time : this._duration;
+        const freq = Note(opts.pitch);
+        const vel = opts.velocity ?? 1.0;
+        this._notes.push(freq, time, opts.duration, vel, opts.instrument);
+        this._duration = Math.max(this._duration, time + opts.duration);
+        return this;
+    }
+    setDuration(secs) {
+        this._duration = secs;
+        return this;
+    }
+    compile() {
+        return { durationSecs: this._duration, notes: this._notes };
+    }
+}
+//# sourceMappingURL=SequenceBuilder.js.map

package/dist/Core/SequenceBuilder.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"SequenceBuilder.js","sourceRoot":"","sources":["../../Core/SequenceBuilder.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,IAAI,EAAE,MAAM,gBAAgB,CAAC;AAEtC;;;;;;;GAOG;AACH,MAAM,OAAO,kBAAkB;IAA/B;QACU,WAAM,GAAa,EAAE,CAAC;QACtB,cAAS,GAAW,CAAC,CAAC;IAiBhC,CAAC;IAfQ,OAAO,CAAC,IAAyG;QACtH,MAAM,IAAI,GAAG,IAAI,CAAC,IAAI,KAAK,SAAS,CAAC,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC,SAAS,CAAC;QAClE,MAAM,IAAI,GAAG,IAAI,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;QAC9B,MAAM,GAAG,GAAG,IAAI,CAAC,QAAQ,IAAI,GAAG,CAAC;QACjC,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC,IAAI,EAAE,IAAI,EAAE,IAAI,CAAC,QAAQ,EAAE,GAAG,EAAE,IAAI,CAAC,UAAU,CAAC,CAAC;QAClE,IAAI,CAAC,SAAS,GAAG,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,SAAS,EAAE,IAAI,GAAG,IAAI,CAAC,QAAQ,CAAC,CAAC;QAChE,OAAO,IAAI,CAAC;IACd,CAAC;IACM,WAAW,CAAC,IAAY;QAC7B,IAAI,CAAC,SAAS,GAAG,IAAI,CAAC;QACtB,OAAO,IAAI,CAAC;IACd,CAAC;IACM,OAAO;QACZ,OAAO,EAAE,YAAY,EAAE,IAAI,CAAC,SAAS,EAAE,KAAK,EAAE,IAAI,CAAC,MAAM,EAAE,CAAC;IAC9D,CAAC;CACF"}

package/dist/Instruments/Analog/AnalogSynthBase.d.ts

@@ -1,17 +1,27 @@
 import { CoreSynthBase } from "../CoreSynthBase.js";
 export type AnalogCfg = {
-    v: number;
-    a: number;
-    r: number;
+    _peakVelocity: number;
+    _attackTimeSeconds: number;
+    _releaseTimeSeconds: number;
+    _maxDurationSeconds?: number;
 };
 /**
- * Abstract base class for sustained analog synthesizers.
- * Handles GainNode creation, Nyquist safety limits, and ADSR volume envelopes.
+ * Synthesizer instrument implementation.
+ *
+ * @reason Acoustic Design:
+ * Encapsulates the specific Web Audio node routing and ADSR parameters
+ * required to physically model this instrument within the 13KB limit.
+ *
+ * @reason Separation of Sustained vs Decaying Physics:
+ * Synthesizers like an Organ will sustain at peak volume infinitely as long as the key is held,
+ * whereas a Piano will physically decay to silence even if the key remains held down.
+ * This base class encapsulates the mathematical ADSR envelope logic specifically for
+ * infinite-sustain physics, ensuring derived classes only need to define the timbre (Oscillators/Filters).
  */
 export declare abstract class AnalogSynthBase extends CoreSynthBase {
-    protected _c: AnalogCfg;
+    protected _envelopeConfig: AnalogCfg;
     _playNote(ctx: AudioContext, masterGain: GainNode, time: number, freq: number, duration: number, velocity: number): void;
-    protected _cfg(d: number): AnalogCfg;
+    protected _getEnvelopeConfig(_decayTimeSeconds: number): AnalogCfg;
     /**
      * Set up the specific oscillators and filters for this instrument.
      * You must start() and stop() your own oscillators.

package/dist/Instruments/Analog/AnalogSynthBase.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"AnalogSynthBase.d.ts","sourceRoot":"","sources":["../../../Instruments/Analog/AnalogSynthBase.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AAEpD,MAAM,MAAM,SAAS,GAAG;IAAE,CAAC,EAAE,MAAM,CAAC;IAAC,CAAC,EAAE,MAAM,CAAC;IAAC,CAAC,EAAE,MAAM,CAAA;CAAE,CAAC;AAE5D;;;GAGG;AACH,8BAAsB,eAAgB,SAAQ,aAAa;IACzD,SAAS,CAAC,EAAE,EAAE,SAAS,CAA+B;IAE/C,SAAS,CACd,GAAG,EAAE,YAAY,EACjB,UAAU,EAAE,QAAQ,EACpB,IAAI,EAAE,MAAM,EACZ,IAAI,EAAE,MAAM,EACZ,QAAQ,EAAE,MAAM,EAChB,QAAQ,EAAE,MAAM,GACf,IAAI;IA+BP,SAAS,CAAC,IAAI,CAAC,CAAC,EAAE,MAAM,GAAG,SAAS;IAIpC;;;;OAIG;IACH,SAAS,CAAC,QAAQ,CAAC,eAAe,CAChC,GAAG,EAAE,YAAY,EACjB,IAAI,EAAE,QAAQ,EACd,IAAI,EAAE,MAAM,EACZ,IAAI,EAAE,MAAM,EACZ,QAAQ,EAAE,MAAM,EAChB,WAAW,EAAE,MAAM,EACnB,WAAW,EAAE,MAAM,EACnB,QAAQ,EAAE,MAAM,GACf,SAAS,GAAG,IAAI;CACpB"}
+{"version":3,"file":"AnalogSynthBase.d.ts","sourceRoot":"","sources":["../../../Instruments/Analog/AnalogSynthBase.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAe,MAAM,qBAAqB,CAAC;AAEjE,MAAM,MAAM,SAAS,GAAG;IAAE,aAAa,EAAE,MAAM,CAAC;IAAC,kBAAkB,EAAE,MAAM,CAAC;IAAC,mBAAmB,EAAE,MAAM,CAAC;IAAC,mBAAmB,CAAC,EAAE,MAAM,CAAA;CAAE,CAAC;AAEzI;;;;;;;;;;;;GAYG;AACH,8BAAsB,eAAgB,SAAQ,aAAa;IACzD,SAAS,CAAC,eAAe,EAAE,SAAS,CAAyG;IAEtI,SAAS,CACd,GAAG,EAAE,YAAY,EACjB,UAAU,EAAE,QAAQ,EACpB,IAAI,EAAE,MAAM,EACZ,IAAI,EAAE,MAAM,EACZ,QAAQ,EAAE,MAAM,EAChB,QAAQ,EAAE,MAAM,GACf,IAAI;IAgCP,SAAS,CAAC,kBAAkB,CAAC,iBAAiB,EAAE,MAAM,GAAG,SAAS;IAIlE;;;;OAIG;IACH,SAAS,CAAC,QAAQ,CAAC,eAAe,CAChC,GAAG,EAAE,YAAY,EACjB,IAAI,EAAE,QAAQ,EACd,IAAI,EAAE,MAAM,EACZ,IAAI,EAAE,MAAM,EACZ,QAAQ,EAAE,MAAM,EAChB,WAAW,EAAE,MAAM,EACnB,WAAW,EAAE,MAAM,EACnB,QAAQ,EAAE,MAAM,GACf,SAAS,GAAG,IAAI;CACpB"}