@codexo/exojs 0.13.0 → 0.14.0

package/dist/esm/audio/AudioBus.js

@@ -3,7 +3,7 @@ import { onAudioContextReady, isAudioContextReady, getAudioContext } from './aud
 
 /**
  * Hierarchical mixer node in the engine's audio routing graph. Each bus
- * owns three Web Audio nodes (input gain, optional filter chain, stereo
+ * owns three Web Audio nodes (input gain, optional effect chain, stereo
  * pan, output gain) and routes its output into its parent's input — the
  * root bus connects to the destination.
  *
@@ -14,8 +14,8 @@ import { onAudioContextReady, isAudioContextReady, getAudioContext } from './aud
  *
  * Volume is in 0..2 (1 = unity), pan is -1..1, mute is a boolean override.
  * {@link AudioBus.fadeIn} / {@link AudioBus.fadeOut} produce smooth ramps
- * over the output gain. Filter changes via {@link AudioBus.addFilter} /
- * {@link AudioBus.removeFilter} rebuild the chain in place.
+ * over the output gain. Effect changes via {@link AudioBus.addEffect} /
+ * {@link AudioBus.removeEffect} rebuild the chain in place.
  *
  * Setup is deferred until the global `AudioContext` is unlocked
  * (browser autoplay policy); operations that need live nodes are no-ops
@@ -27,7 +27,7 @@ class AudioBus {
     _volume;
     _muted;
     _pan;
-    _filters = [];
+    _effects = [];
     _setup = null;
     _scheduledStopId = null;
     _onAudioContextReady = (ctx) => {
@@ -43,8 +43,8 @@ class AudioBus {
         this._volume = clamp(options.volume ?? 1, 0, 2);
         this._muted = options.muted ?? false;
         this._pan = clamp(options.pan ?? 0, -1, 1);
-        if (options.filters) {
-            this._filters.push(...options.filters);
+        if (options.effects) {
+            this._effects.push(...options.effects);
         }
         if (isAudioContextReady()) {
             this._setupAudio(getAudioContext());
@@ -91,21 +91,21 @@ class AudioBus {
         return this._setup?.inputNode ?? null;
     }
     /**
-     * Append a filter to the end of the chain (before the pan stage). The
+     * Append a effect to the end of the chain (before the pan stage). The
      * chain is rebuilt in place; existing audio routes through the new
-     * filter on the next frame.
+     * effect on the next frame.
      */
-    addFilter(filter) {
-        this._filters.push(filter);
-        this._rebuildFilterChain();
+    addEffect(effect) {
+        this._effects.push(effect);
+        this._rebuildEffectChain();
         return this;
     }
-    /** Remove `filter` from the chain. No-op if not present. Caller still owns + must `destroy()` it. */
-    removeFilter(filter) {
-        const index = this._filters.indexOf(filter);
+    /** Remove `effect` from the chain. No-op if not present. Caller still owns + must `destroy()` it. */
+    removeEffect(effect) {
+        const index = this._effects.indexOf(effect);
         if (index !== -1) {
-            this._filters.splice(index, 1);
-            this._rebuildFilterChain();
+            this._effects.splice(index, 1);
+            this._rebuildEffectChain();
         }
         return this;
     }
@@ -156,10 +156,10 @@ class AudioBus {
     destroy() {
         onAudioContextReady.remove(this._onAudioContextReady);
         this._clearScheduledStop();
-        for (const filter of this._filters) {
-            filter.destroy();
+        for (const effect of this._effects) {
+            effect.destroy();
         }
-        this._filters.length = 0;
+        this._effects.length = 0;
         if (this._setup) {
             this._setup.inputNode.disconnect();
             this._setup.outputNode.disconnect();
@@ -179,11 +179,11 @@ class AudioBus {
         const inputNode = audioContext.createGain();
         const panNode = audioContext.createStereoPanner();
         const outputNode = audioContext.createGain();
-        // Internal chain: input → [filters...] → pan → output
+        // Internal chain: input → [effects...] → pan → output
         outputNode.gain.setTargetAtTime(this._muted ? 0 : this._volume, audioContext.currentTime, 0.01);
         panNode.pan.setTargetAtTime(this._pan, audioContext.currentTime, 0.01);
         this._setup = { audioContext, inputNode, outputNode, panNode };
-        this._rebuildFilterChain();
+        this._rebuildEffectChain();
         this._connectUpstream();
     }
     _connectUpstream() {
@@ -221,22 +221,22 @@ class AudioBus {
             });
         }
     }
-    _rebuildFilterChain() {
+    _rebuildEffectChain() {
         if (!this._setup)
             return;
         const { inputNode, panNode } = this._setup;
         // Disconnect current chain
         inputNode.disconnect();
-        for (const filter of this._filters) {
-            filter.inputNode.disconnect();
-            filter.outputNode.disconnect();
+        for (const effect of this._effects) {
+            effect.inputNode.disconnect();
+            effect.outputNode.disconnect();
         }
         panNode.disconnect();
-        // Rebuild: input → filter[0].input → filter[0].output → filter[1].input → ... → pan → output
+        // Rebuild: input → effect[0].input → effect[0].output → effect[1].input → ... → pan → output
         let prev = inputNode;
-        for (const filter of this._filters) {
-            prev.connect(filter.inputNode);
-            prev = filter.outputNode;
+        for (const effect of this._effects) {
+            prev.connect(effect.inputNode);
+            prev = effect.outputNode;
         }
         prev.connect(panNode);
         panNode.connect(this._setup.outputNode);

package/dist/esm/audio/AudioEffect.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Abstract base for all insertable audio effects in ExoJS. Each effect exposes
+ * stable {@link inputNode} and {@link outputNode} AudioNodes that an
+ * {@link AudioBus} or {@link Voice} connects into the Web Audio graph. Async
+ * effects (e.g., worklet-based) expose a {@link ready} promise that resolves
+ * once the effect is fully initialized.
+ */
+export declare abstract class AudioEffect {
+    /** The node where audio enters this effect. */
+    abstract get inputNode(): AudioNode;
+    /** The node where audio exits this effect. */
+    abstract get outputNode(): AudioNode;
+    /** Resolves when the effect is fully initialized. Defaults to immediately-resolved for sync effects. */
+    get ready(): Promise<void>;
+    /** Disconnects all audio nodes and releases resources. Must be called when the effect is no longer needed. */
+    abstract destroy(): void;
+}
+//# sourceMappingURL=AudioEffect.d.ts.map

package/dist/esm/audio/AudioEffect.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"AudioEffect.d.ts","sourceRoot":"","sources":["../../../src/audio/AudioEffect.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AACH,8BAAsB,WAAW;IAC/B,+CAA+C;IAC/C,aAAoB,SAAS,IAAI,SAAS,CAAC;IAC3C,8CAA8C;IAC9C,aAAoB,UAAU,IAAI,SAAS,CAAC;IAC5C,wGAAwG;IACxG,IAAW,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAEhC;IACD,8GAA8G;aAC9F,OAAO,IAAI,IAAI;CAChC"}

package/dist/esm/audio/AudioEffect.js

@@ -0,0 +1,16 @@
+/**
+ * Abstract base for all insertable audio effects in ExoJS. Each effect exposes
+ * stable {@link inputNode} and {@link outputNode} AudioNodes that an
+ * {@link AudioBus} or {@link Voice} connects into the Web Audio graph. Async
+ * effects (e.g., worklet-based) expose a {@link ready} promise that resolves
+ * once the effect is fully initialized.
+ */
+class AudioEffect {
+    /** Resolves when the effect is fully initialized. Defaults to immediately-resolved for sync effects. */
+    get ready() {
+        return Promise.resolve();
+    }
+}
+
+export { AudioEffect };
+//# sourceMappingURL=AudioEffect.js.map

package/dist/esm/audio/AudioEffect.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"AudioEffect.js","sources":["../../../../src/audio/AudioEffect.ts"],"sourcesContent":[null],"names":[],"mappings":"AAAA;;;;;;AAMG;MACmB,WAAW,CAAA;;AAM/B,IAAA,IAAW,KAAK,GAAA;AACd,QAAA,OAAO,OAAO,CAAC,OAAO,EAAE;IAC1B;AAGD;;;;"}

package/dist/esm/audio/AudioGenerator.d.ts

@@ -0,0 +1,91 @@
+import type { AudioManager } from './AudioManager';
+import type { Envelope } from './Envelope';
+import type { Playable, PlayOptions, Voice } from './Playable';
+import { SoundPoolStrategy } from './Sound';
+export type OscillatorType = 'sine' | 'square' | 'sawtooth' | 'triangle';
+/** Construction options for {@link AudioGenerator}. */
+export interface AudioGeneratorOptions {
+    /** Oscillator frequency in Hz. Default 440 (A4). */
+    frequency?: number;
+    /** Oscillator waveform. Default `'sine'`. */
+    type?: OscillatorType;
+    /** Pitch detune in cents. Default 0. */
+    detune?: number;
+    /** Optional ADSR envelope. Default `null` (no envelope). */
+    envelope?: Envelope | null;
+    /** Default volume applied to new voices. Range [0, 1]. Default 1. */
+    volume?: number;
+    /** Default muted flag (starts a voice at volume 0). Default false. */
+    muted?: boolean;
+    /** Maximum concurrent voices. Default 8. */
+    poolSize?: number;
+    /** Eviction strategy when the pool is full. Default `FirstInFirstOut`. */
+    poolStrategy?: SoundPoolStrategy;
+    /** Priority for the `LowestPriority` strategy. Default 0. */
+    priority?: number;
+}
+/**
+ * Procedural tone generator — produces audio from an `OscillatorNode` without
+ * any decoded asset. Good for prototyping, game-jam SFX, retro bleeps, and
+ * synth-style tones.
+ *
+ * `AudioGenerator` is a **data descriptor**: it holds the current synth settings
+ * (`frequency`, `type`, `detune`, `envelope`) and default playback parameters.
+ * Each `AudioManager.play(generator, options)` snapshots those settings into a
+ * fresh {@link AudioGeneratorVoice} and returns it. For per-note playback, set
+ * `generator.frequency` (or use {@link AudioGenerator.setNote}) before playing:
+ *
+ * ```ts
+ * generator.setNote(69);            // A4
+ * const voice = app.audio.play(generator);
+ * // ...later
+ * voice.frequency = 880;            // retune the live voice
+ * voice.stop();                     // triggers the envelope release, if any
+ * ```
+ *
+ * Routes through the manager's `sound` bus by default.
+ */
+export declare class AudioGenerator implements Playable {
+    /** Current oscillator frequency in Hz. Snapshotted into each new voice. */
+    frequency: number;
+    /** Current oscillator waveform. */
+    type: OscillatorType;
+    /** Current pitch detune in cents. */
+    detune: number;
+    /** Optional ADSR envelope applied to each voice. */
+    envelope: Envelope | null;
+    /** Default volume for new voices. Range [0, 1]. */
+    volume: number;
+    /** Default muted flag (starts a voice at volume 0). */
+    muted: boolean;
+    private _poolSize;
+    private _poolStrategy;
+    /** Priority for the `LowestPriority` eviction strategy. */
+    priority: number;
+    private readonly _activeVoices;
+    get poolSize(): number;
+    set poolSize(value: number);
+    get poolStrategy(): SoundPoolStrategy;
+    set poolStrategy(value: SoundPoolStrategy);
+    constructor(options?: AudioGeneratorOptions);
+    /** Set {@link AudioGenerator.frequency} from a MIDI note number (69 = A4 = 440 Hz). */
+    setNote(midiNote: number): this;
+    /** Frequency in Hz for a MIDI note number, without mutating the generator. */
+    static midiToFrequency(midiNote: number): number;
+    /**
+     * Implements {@link Playable}. Called by {@link AudioManager.play}.
+     *
+     * Snapshots the current synth settings into a new {@link AudioGeneratorVoice}.
+     * Returns an already-ended {@link NoopVoice} when the `AudioContext` is still
+     * locked by the autoplay policy — oscillators are ephemeral and cannot be
+     * deferred.
+     */
+    _createVoice(manager: AudioManager, options: PlayOptions): Voice;
+    /** Stop every currently active voice from this generator. */
+    stopAll(): this;
+    /** Stop all active voices. */
+    destroy(): void;
+    private _pruneEndedVoices;
+    private _pickEvictionVictim;
+}
+//# sourceMappingURL=AudioGenerator.d.ts.map

package/dist/esm/audio/AudioGenerator.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"AudioGenerator.d.ts","sourceRoot":"","sources":["../../../src/audio/AudioGenerator.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,gBAAgB,CAAC;AACnD,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AAE3C,OAAO,KAAK,EAAE,QAAQ,EAAE,WAAW,EAAE,KAAK,EAAE,MAAM,YAAY,CAAC;AAC/D,OAAO,EAAE,iBAAiB,EAAE,MAAM,SAAS,CAAC;AAE5C,MAAM,MAAM,cAAc,GAAG,MAAM,GAAG,QAAQ,GAAG,UAAU,GAAG,UAAU,CAAC;AAEzE,uDAAuD;AACvD,MAAM,WAAW,qBAAqB;IACpC,oDAAoD;IACpD,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,6CAA6C;IAC7C,IAAI,CAAC,EAAE,cAAc,CAAC;IACtB,wCAAwC;IACxC,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,4DAA4D;IAC5D,QAAQ,CAAC,EAAE,QAAQ,GAAG,IAAI,CAAC;IAC3B,qEAAqE;IACrE,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,sEAAsE;IACtE,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,4CAA4C;IAC5C,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,0EAA0E;IAC1E,YAAY,CAAC,EAAE,iBAAiB,CAAC;IACjC,6DAA6D;IAC7D,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAQD;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,qBAAa,cAAe,YAAW,QAAQ;IAC7C,2EAA2E;IACpE,SAAS,EAAE,MAAM,CAAC;IACzB,mCAAmC;IAC5B,IAAI,EAAE,cAAc,CAAC;IAC5B,qCAAqC;IAC9B,MAAM,EAAE,MAAM,CAAC;IACtB,oDAAoD;IAC7C,QAAQ,EAAE,QAAQ,GAAG,IAAI,CAAC;IACjC,mDAAmD;IAC5C,MAAM,EAAE,MAAM,CAAC;IACtB,uDAAuD;IAChD,KAAK,EAAE,OAAO,CAAC;IAEtB,OAAO,CAAC,SAAS,CAAS;IAC1B,OAAO,CAAC,aAAa,CAAoB;IACzC,2DAA2D;IACpD,QAAQ,EAAE,MAAM,CAAC;IAExB,OAAO,CAAC,QAAQ,CAAC,aAAa,CAA8B;IAE5D,IAAW,QAAQ,IAAI,MAAM,CAE5B;IAED,IAAW,QAAQ,CAAC,KAAK,EAAE,MAAM,EAEhC;IAED,IAAW,YAAY,IAAI,iBAAiB,CAE3C;IAED,IAAW,YAAY,CAAC,KAAK,EAAE,iBAAiB,EAE/C;gBAEkB,OAAO,GAAE,qBAA0B;IAatD,uFAAuF;IAChF,OAAO,CAAC,QAAQ,EAAE,MAAM,GAAG,IAAI;IAKtC,8EAA8E;WAChE,eAAe,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM;IAIvD;;;;;;;OAOG;IACI,YAAY,CAAC,OAAO,EAAE,YAAY,EAAE,OAAO,EAAE,WAAW,GAAG,KAAK;IA+CvE,6DAA6D;IACtD,OAAO,IAAI,IAAI;IAStB,8BAA8B;IACvB,OAAO,IAAI,IAAI;IAItB,OAAO,CAAC,iBAAiB;IAQzB,OAAO,CAAC,mBAAmB;CAiB5B"}

package/dist/esm/audio/AudioGenerator.js

@@ -0,0 +1,165 @@
+import { clamp } from '../math/utils.js';
+import { isAudioContextReady, getAudioContext } from './audio-context.js';
+import { AudioGeneratorVoice } from './AudioGeneratorVoice.js';
+import { NoopVoice } from './NoopVoice.js';
+import { SoundPoolStrategy } from './Sound.js';
+
+/**
+ * Procedural tone generator — produces audio from an `OscillatorNode` without
+ * any decoded asset. Good for prototyping, game-jam SFX, retro bleeps, and
+ * synth-style tones.
+ *
+ * `AudioGenerator` is a **data descriptor**: it holds the current synth settings
+ * (`frequency`, `type`, `detune`, `envelope`) and default playback parameters.
+ * Each `AudioManager.play(generator, options)` snapshots those settings into a
+ * fresh {@link AudioGeneratorVoice} and returns it. For per-note playback, set
+ * `generator.frequency` (or use {@link AudioGenerator.setNote}) before playing:
+ *
+ * ```ts
+ * generator.setNote(69);            // A4
+ * const voice = app.audio.play(generator);
+ * // ...later
+ * voice.frequency = 880;            // retune the live voice
+ * voice.stop();                     // triggers the envelope release, if any
+ * ```
+ *
+ * Routes through the manager's `sound` bus by default.
+ */
+class AudioGenerator {
+    /** Current oscillator frequency in Hz. Snapshotted into each new voice. */
+    frequency;
+    /** Current oscillator waveform. */
+    type;
+    /** Current pitch detune in cents. */
+    detune;
+    /** Optional ADSR envelope applied to each voice. */
+    envelope;
+    /** Default volume for new voices. Range [0, 1]. */
+    volume;
+    /** Default muted flag (starts a voice at volume 0). */
+    muted;
+    _poolSize;
+    _poolStrategy;
+    /** Priority for the `LowestPriority` eviction strategy. */
+    priority;
+    _activeVoices = [];
+    get poolSize() {
+        return this._poolSize;
+    }
+    set poolSize(value) {
+        this._poolSize = Math.max(1, Math.floor(value));
+    }
+    get poolStrategy() {
+        return this._poolStrategy;
+    }
+    set poolStrategy(value) {
+        this._poolStrategy = value;
+    }
+    constructor(options = {}) {
+        this.frequency = options.frequency ?? 440;
+        this.type = options.type ?? 'sine';
+        this.detune = options.detune ?? 0;
+        this.envelope = options.envelope ?? null;
+        this.volume = clamp(options.volume ?? 1, 0, 1);
+        this.muted = options.muted ?? false;
+        this._poolSize = Math.max(1, Math.floor(options.poolSize ?? 8));
+        this._poolStrategy = options.poolStrategy ?? SoundPoolStrategy.FirstInFirstOut;
+        this.priority = options.priority ?? 0;
+    }
+    /** Set {@link AudioGenerator.frequency} from a MIDI note number (69 = A4 = 440 Hz). */
+    setNote(midiNote) {
+        this.frequency = AudioGenerator.midiToFrequency(midiNote);
+        return this;
+    }
+    /** Frequency in Hz for a MIDI note number, without mutating the generator. */
+    static midiToFrequency(midiNote) {
+        return 440 * Math.pow(2, (midiNote - 69) / 12);
+    }
+    /**
+     * Implements {@link Playable}. Called by {@link AudioManager.play}.
+     *
+     * Snapshots the current synth settings into a new {@link AudioGeneratorVoice}.
+     * Returns an already-ended {@link NoopVoice} when the `AudioContext` is still
+     * locked by the autoplay policy — oscillators are ephemeral and cannot be
+     * deferred.
+     */
+    _createVoice(manager, options) {
+        const bus = options.bus ?? manager.sound;
+        if (!isAudioContextReady()) {
+            return new NoopVoice(bus);
+        }
+        this._pruneEndedVoices();
+        if (this._activeVoices.length >= this._poolSize) {
+            const victimIndex = this._pickEvictionVictim();
+            const victim = this._activeVoices[victimIndex];
+            if (victim) {
+                this._activeVoices.splice(victimIndex, 1);
+                victim.voice.stop();
+            }
+        }
+        const audioContext = getAudioContext();
+        const output = audioContext.createGain();
+        const detune = options.detune ?? this.detune;
+        const volume = clamp(options.muted ? 0 : (options.volume ?? (this.muted ? 0 : this.volume)), 0, 1);
+        const voice = new AudioGeneratorVoice({
+            audioContext,
+            output,
+            bus,
+            manager,
+            volume,
+            frequency: this.frequency,
+            type: this.type,
+            detune,
+            envelope: this.envelope,
+        });
+        const pooled = { voice, startedAt: audioContext.currentTime };
+        voice.onEnd.add(() => {
+            const index = this._activeVoices.indexOf(pooled);
+            if (index !== -1) {
+                this._activeVoices.splice(index, 1);
+            }
+        });
+        this._activeVoices.push(pooled);
+        return voice;
+    }
+    /** Stop every currently active voice from this generator. */
+    stopAll() {
+        const voices = [...this._activeVoices];
+        this._activeVoices.length = 0;
+        for (const pooled of voices) {
+            pooled.voice.stop();
+        }
+        return this;
+    }
+    /** Stop all active voices. */
+    destroy() {
+        this.stopAll();
+    }
+    _pruneEndedVoices() {
+        for (let i = this._activeVoices.length - 1; i >= 0; i--) {
+            if (this._activeVoices[i]?.voice.ended === true) {
+                this._activeVoices.splice(i, 1);
+            }
+        }
+    }
+    _pickEvictionVictim() {
+        if (this._poolStrategy === SoundPoolStrategy.LeastRecentlyUsed) {
+            // Oscillators are open-ended, so "closest to end" degenerates to oldest.
+            let oldest = 0;
+            let oldestTime = Infinity;
+            for (let i = 0; i < this._activeVoices.length; i++) {
+                const pooled = this._activeVoices[i];
+                if (pooled !== undefined && pooled.startedAt < oldestTime) {
+                    oldestTime = pooled.startedAt;
+                    oldest = i;
+                }
+            }
+            return oldest;
+        }
+        // FirstInFirstOut and LowestPriority (shared priority) → oldest.
+        return 0;
+    }
+}
+
+export { AudioGenerator };
+//# sourceMappingURL=AudioGenerator.js.map

package/dist/esm/audio/AudioGenerator.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"AudioGenerator.js","sources":["../../../../src/audio/AudioGenerator.ts"],"sourcesContent":[null],"names":[],"mappings":"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"}

package/dist/esm/audio/AudioGeneratorVoice.d.ts

@@ -0,0 +1,52 @@
+import type { OscillatorType } from './AudioGenerator';
+import { BaseVoice, type BaseVoiceInit } from './BaseVoice';
+import type { Envelope } from './Envelope';
+import type { RatePitched } from './Playable';
+/** Construction parameters for {@link AudioGeneratorVoice}. */
+export interface AudioGeneratorVoiceInit extends BaseVoiceInit {
+    frequency: number;
+    type: OscillatorType;
+    detune: number;
+    envelope: Envelope | null;
+}
+/**
+ * Active playback handle for one {@link AudioGenerator} play call, backed by an
+ * `OscillatorNode` plus a per-voice envelope gain. Each `AudioManager.play`
+ * creates an independent voice.
+ *
+ * Exposes the generator parameters (`frequency`, `type`), mixes in
+ * {@link RatePitched} (`detune` is real; `playbackRate` is stored but inert — an
+ * oscillator has no playback rate, retune via `frequency`/`detune`), and (via
+ * {@link BaseVoice}) {@link Spatializable}.
+ *
+ * Graph: `oscillator → envelopeGain → [panner] → output(volume) → bus`. The
+ * envelope shapes the ADSR; the output gain carries the overall volume.
+ *
+ * @internal
+ */
+export declare class AudioGeneratorVoice extends BaseVoice implements RatePitched {
+    private readonly _oscillator;
+    private readonly _envelopeGain;
+    private readonly _envelope;
+    private _frequency;
+    private _type;
+    private _detune;
+    private _playbackRate;
+    constructor(init: AudioGeneratorVoiceInit);
+    get frequency(): number;
+    set frequency(value: number);
+    get type(): OscillatorType;
+    set type(value: OscillatorType);
+    /**
+     * Stored but inert — an `OscillatorNode` has no playback rate. Retune via
+     * {@link AudioGeneratorVoice.frequency} or {@link AudioGeneratorVoice.detune}.
+     */
+    get playbackRate(): number;
+    set playbackRate(value: number);
+    get detune(): number;
+    set detune(value: number);
+    stop(fadeMs?: number): void;
+    protected _routeThroughPanner(panner: PannerNode): void;
+    protected _teardownSource(): void;
+}
+//# sourceMappingURL=AudioGeneratorVoice.d.ts.map

package/dist/esm/audio/AudioGeneratorVoice.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"AudioGeneratorVoice.d.ts","sourceRoot":"","sources":["../../../src/audio/AudioGeneratorVoice.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,kBAAkB,CAAC;AACvD,OAAO,EAAE,SAAS,EAAE,KAAK,aAAa,EAAE,MAAM,aAAa,CAAC;AAC5D,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AAC3C,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AAE9C,+DAA+D;AAC/D,MAAM,WAAW,uBAAwB,SAAQ,aAAa;IAC5D,SAAS,EAAE,MAAM,CAAC;IAClB,IAAI,EAAE,cAAc,CAAC;IACrB,MAAM,EAAE,MAAM,CAAC;IACf,QAAQ,EAAE,QAAQ,GAAG,IAAI,CAAC;CAC3B;AAED;;;;;;;;;;;;;;GAcG;AACH,qBAAa,mBAAoB,SAAQ,SAAU,YAAW,WAAW;IACvE,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAiB;IAC7C,OAAO,CAAC,QAAQ,CAAC,aAAa,CAAW;IACzC,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAkB;IAC5C,OAAO,CAAC,UAAU,CAAS;IAC3B,OAAO,CAAC,KAAK,CAAiB;IAC9B,OAAO,CAAC,OAAO,CAAS;IACxB,OAAO,CAAC,aAAa,CAAK;gBAEP,IAAI,EAAE,uBAAuB;IAmChD,IAAW,SAAS,IAAI,MAAM,CAE7B;IAED,IAAW,SAAS,CAAC,KAAK,EAAE,MAAM,EAKjC;IAED,IAAW,IAAI,IAAI,cAAc,CAEhC;IAED,IAAW,IAAI,CAAC,KAAK,EAAE,cAAc,EAKpC;IAMD;;;OAGG;IACH,IAAW,YAAY,IAAI,MAAM,CAEhC;IAED,IAAW,YAAY,CAAC,KAAK,EAAE,MAAM,EAEpC;IAED,IAAW,MAAM,IAAI,MAAM,CAE1B;IAED,IAAW,MAAM,CAAC,KAAK,EAAE,MAAM,EAK9B;IAMe,IAAI,CAAC,MAAM,CAAC,EAAE,MAAM,GAAG,IAAI;cA4BxB,mBAAmB,CAAC,MAAM,EAAE,UAAU,GAAG,IAAI;cAM7C,eAAe,IAAI,IAAI;CAU3C"}

package/dist/esm/audio/AudioGeneratorVoice.js

@@ -0,0 +1,141 @@
+import { BaseVoice } from './BaseVoice.js';
+
+/**
+ * Active playback handle for one {@link AudioGenerator} play call, backed by an
+ * `OscillatorNode` plus a per-voice envelope gain. Each `AudioManager.play`
+ * creates an independent voice.
+ *
+ * Exposes the generator parameters (`frequency`, `type`), mixes in
+ * {@link RatePitched} (`detune` is real; `playbackRate` is stored but inert — an
+ * oscillator has no playback rate, retune via `frequency`/`detune`), and (via
+ * {@link BaseVoice}) {@link Spatializable}.
+ *
+ * Graph: `oscillator → envelopeGain → [panner] → output(volume) → bus`. The
+ * envelope shapes the ADSR; the output gain carries the overall volume.
+ *
+ * @internal
+ */
+class AudioGeneratorVoice extends BaseVoice {
+    _oscillator;
+    _envelopeGain;
+    _envelope;
+    _frequency;
+    _type;
+    _detune;
+    _playbackRate = 1;
+    constructor(init) {
+        super(init);
+        const ctx = this._audioContext;
+        const now = ctx.currentTime;
+        this._frequency = init.frequency;
+        this._type = init.type;
+        this._detune = init.detune;
+        this._envelope = init.envelope;
+        this._envelopeGain = ctx.createGain();
+        this._envelopeGain.connect(this._output);
+        const oscillator = ctx.createOscillator();
+        oscillator.type = init.type;
+        oscillator.frequency.value = init.frequency;
+        oscillator.detune.value = init.detune;
+        oscillator.connect(this._envelopeGain);
+        oscillator.onended = () => this._finish();
+        if (this._envelope) {
+            this._envelope.trigger(this._envelopeGain.gain, now);
+        }
+        else {
+            this._envelopeGain.gain.value = 1;
+        }
+        oscillator.start(now);
+        this._oscillator = oscillator;
+    }
+    // -------------------------------------------------------------------------
+    // Generator parameters
+    // -------------------------------------------------------------------------
+    get frequency() {
+        return this._frequency;
+    }
+    set frequency(value) {
+        this._frequency = value;
+        if (!this._ended) {
+            this._oscillator.frequency.setTargetAtTime(value, this._audioContext.currentTime, 0.01);
+        }
+    }
+    get type() {
+        return this._type;
+    }
+    set type(value) {
+        this._type = value;
+        if (!this._ended) {
+            this._oscillator.type = value;
+        }
+    }
+    // -------------------------------------------------------------------------
+    // RatePitched
+    // -------------------------------------------------------------------------
+    /**
+     * Stored but inert — an `OscillatorNode` has no playback rate. Retune via
+     * {@link AudioGeneratorVoice.frequency} or {@link AudioGeneratorVoice.detune}.
+     */
+    get playbackRate() {
+        return this._playbackRate;
+    }
+    set playbackRate(value) {
+        this._playbackRate = value;
+    }
+    get detune() {
+        return this._detune;
+    }
+    set detune(value) {
+        this._detune = value;
+        if (!this._ended) {
+            this._oscillator.detune.setTargetAtTime(value, this._audioContext.currentTime, 0.01);
+        }
+    }
+    // -------------------------------------------------------------------------
+    // Stop (envelope-aware)
+    // -------------------------------------------------------------------------
+    stop(fadeMs) {
+        if (this._ended)
+            return;
+        if (fadeMs !== undefined && fadeMs > 0) {
+            super.stop(fadeMs);
+            return;
+        }
+        if (this._envelope) {
+            const now = this._audioContext.currentTime;
+            this._envelope.release(this._envelopeGain.gain, now);
+            const stopAt = now + this._envelope.releaseMs / 1000;
+            try {
+                this._oscillator.stop(stopAt);
+            }
+            catch {
+                // already stopped
+            }
+            // _finish runs on the oscillator's onended at stopAt.
+            return;
+        }
+        super.stop();
+    }
+    // -------------------------------------------------------------------------
+    // BaseVoice hooks
+    // -------------------------------------------------------------------------
+    _routeThroughPanner(panner) {
+        this._envelopeGain.disconnect();
+        this._envelopeGain.connect(panner);
+        panner.connect(this._output);
+    }
+    _teardownSource() {
+        this._oscillator.onended = null;
+        try {
+            this._oscillator.stop(0);
+        }
+        catch {
+            // already stopped
+        }
+        this._oscillator.disconnect();
+        this._envelopeGain.disconnect();
+    }
+}
+
+export { AudioGeneratorVoice };
+//# sourceMappingURL=AudioGeneratorVoice.js.map

package/dist/esm/audio/AudioGeneratorVoice.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"AudioGeneratorVoice.js","sources":["../../../../src/audio/AudioGeneratorVoice.ts"],"sourcesContent":[null],"names":[],"mappings":"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"}