@codexo/exojs 0.13.0 → 0.14.0

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

@@ -0,0 +1,53 @@
+import { AudioEffect } from './AudioEffect';
+/** Construction options for {@link BiquadEffect}. */
+export interface BiquadEffectOptions {
+    /** Filter response. Default `'lowpass'`. */
+    type?: BiquadFilterType;
+    /** Center / cutoff frequency in Hz. Range 0..nyquist. Default 1000. */
+    frequency?: number;
+    /** Quality factor (resonance / bandwidth). Default 1. */
+    resonance?: number;
+    /** Gain in dB — only used by `peaking`, `lowshelf`, `highshelf`. Default 0. */
+    gain?: number;
+    /** Fine frequency offset in cents. Default 0. */
+    detune?: number;
+}
+/**
+ * Native biquad filter effect backed by a single `BiquadFilterNode` — the most
+ * common audio-shaping need, covering `lowpass` / `highpass` / `bandpass` /
+ * `notch` / `peaking` / `lowshelf` / `highshelf` / `allpass` via one `type`
+ * parameter. Insert it on an {@link AudioBus} (`bus.addEffect`) or a
+ * {@link Voice} (`voice.addEffect`).
+ *
+ * The single node serves as both {@link inputNode} and {@link outputNode}.
+ */
+export declare class BiquadEffect extends AudioEffect {
+    private _node;
+    private _type;
+    private _frequency;
+    private _resonance;
+    private _gain;
+    private _detune;
+    private readonly _onAudioContextReady;
+    constructor(options?: BiquadEffectOptions);
+    get inputNode(): AudioNode;
+    get outputNode(): AudioNode;
+    /** Filter response type. */
+    get type(): BiquadFilterType;
+    set type(value: BiquadFilterType);
+    /** Center / cutoff frequency in Hz. */
+    get frequency(): number;
+    set frequency(value: number);
+    /** Quality factor (resonance / bandwidth). */
+    get resonance(): number;
+    set resonance(value: number);
+    /** Gain in dB — applies to `peaking`, `lowshelf`, and `highshelf` types. */
+    get gain(): number;
+    set gain(value: number);
+    /** Fine frequency offset in cents. */
+    get detune(): number;
+    set detune(value: number);
+    destroy(): void;
+    private _setup;
+}
+//# sourceMappingURL=BiquadEffect.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"BiquadEffect.d.ts","sourceRoot":"","sources":["../../../src/audio/BiquadEffect.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,WAAW,EAAE,MAAM,eAAe,CAAC;AAE5C,qDAAqD;AACrD,MAAM,WAAW,mBAAmB;IAClC,4CAA4C;IAC5C,IAAI,CAAC,EAAE,gBAAgB,CAAC;IACxB,uEAAuE;IACvE,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,yDAAyD;IACzD,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,+EAA+E;IAC/E,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,iDAAiD;IACjD,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED;;;;;;;;GAQG;AACH,qBAAa,YAAa,SAAQ,WAAW;IAC3C,OAAO,CAAC,KAAK,CAAiC;IAC9C,OAAO,CAAC,KAAK,CAAmB;IAChC,OAAO,CAAC,UAAU,CAAS;IAC3B,OAAO,CAAC,UAAU,CAAS;IAC3B,OAAO,CAAC,KAAK,CAAS;IACtB,OAAO,CAAC,OAAO,CAAS;IACxB,OAAO,CAAC,QAAQ,CAAC,oBAAoB,CAGnC;gBAEiB,OAAO,GAAE,mBAAwB;IAepD,IAAW,SAAS,IAAI,SAAS,CAGhC;IAED,IAAW,UAAU,IAAI,SAAS,CAGjC;IAED,4BAA4B;IAC5B,IAAW,IAAI,IAAI,gBAAgB,CAElC;IAED,IAAW,IAAI,CAAC,KAAK,EAAE,gBAAgB,EAGtC;IAED,uCAAuC;IACvC,IAAW,SAAS,IAAI,MAAM,CAE7B;IAED,IAAW,SAAS,CAAC,KAAK,EAAE,MAAM,EAGjC;IAED,8CAA8C;IAC9C,IAAW,SAAS,IAAI,MAAM,CAE7B;IAED,IAAW,SAAS,CAAC,KAAK,EAAE,MAAM,EAGjC;IAED,4EAA4E;IAC5E,IAAW,IAAI,IAAI,MAAM,CAExB;IAED,IAAW,IAAI,CAAC,KAAK,EAAE,MAAM,EAG5B;IAED,sCAAsC;IACtC,IAAW,MAAM,IAAI,MAAM,CAE1B;IAED,IAAW,MAAM,CAAC,KAAK,EAAE,MAAM,EAG9B;IAEe,OAAO,IAAI,IAAI;IAM/B,OAAO,CAAC,MAAM;CASf"}

package/dist/esm/audio/BiquadEffect.js

@@ -0,0 +1,110 @@
+import { onAudioContextReady, isAudioContextReady, getAudioContext } from './audio-context.js';
+import { AudioEffect } from './AudioEffect.js';
+
+/**
+ * Native biquad filter effect backed by a single `BiquadFilterNode` — the most
+ * common audio-shaping need, covering `lowpass` / `highpass` / `bandpass` /
+ * `notch` / `peaking` / `lowshelf` / `highshelf` / `allpass` via one `type`
+ * parameter. Insert it on an {@link AudioBus} (`bus.addEffect`) or a
+ * {@link Voice} (`voice.addEffect`).
+ *
+ * The single node serves as both {@link inputNode} and {@link outputNode}.
+ */
+class BiquadEffect extends AudioEffect {
+    _node = null;
+    _type;
+    _frequency;
+    _resonance;
+    _gain;
+    _detune;
+    _onAudioContextReady = (ctx) => {
+        onAudioContextReady.remove(this._onAudioContextReady);
+        this._setup(ctx);
+    };
+    constructor(options = {}) {
+        super();
+        this._type = options.type ?? 'lowpass';
+        this._frequency = options.frequency ?? 1000;
+        this._resonance = options.resonance ?? 1;
+        this._gain = options.gain ?? 0;
+        this._detune = options.detune ?? 0;
+        if (isAudioContextReady()) {
+            this._setup(getAudioContext());
+        }
+        else {
+            onAudioContextReady.add(this._onAudioContextReady);
+        }
+    }
+    get inputNode() {
+        if (!this._node)
+            throw new Error('BiquadEffect not yet initialized.');
+        return this._node;
+    }
+    get outputNode() {
+        if (!this._node)
+            throw new Error('BiquadEffect not yet initialized.');
+        return this._node;
+    }
+    /** Filter response type. */
+    get type() {
+        return this._type;
+    }
+    set type(value) {
+        this._type = value;
+        if (this._node)
+            this._node.type = value;
+    }
+    /** Center / cutoff frequency in Hz. */
+    get frequency() {
+        return this._frequency;
+    }
+    set frequency(value) {
+        this._frequency = value;
+        if (this._node)
+            this._node.frequency.setTargetAtTime(value, this._node.context.currentTime, 0.01);
+    }
+    /** Quality factor (resonance / bandwidth). */
+    get resonance() {
+        return this._resonance;
+    }
+    set resonance(value) {
+        this._resonance = value;
+        if (this._node)
+            this._node.Q.setTargetAtTime(value, this._node.context.currentTime, 0.01);
+    }
+    /** Gain in dB — applies to `peaking`, `lowshelf`, and `highshelf` types. */
+    get gain() {
+        return this._gain;
+    }
+    set gain(value) {
+        this._gain = value;
+        if (this._node)
+            this._node.gain.setTargetAtTime(value, this._node.context.currentTime, 0.01);
+    }
+    /** Fine frequency offset in cents. */
+    get detune() {
+        return this._detune;
+    }
+    set detune(value) {
+        this._detune = value;
+        if (this._node)
+            this._node.detune.setTargetAtTime(value, this._node.context.currentTime, 0.01);
+    }
+    destroy() {
+        onAudioContextReady.remove(this._onAudioContextReady);
+        this._node?.disconnect();
+        this._node = null;
+    }
+    _setup(ctx) {
+        const node = ctx.createBiquadFilter();
+        node.type = this._type;
+        node.frequency.setValueAtTime(this._frequency, ctx.currentTime);
+        node.Q.setValueAtTime(this._resonance, ctx.currentTime);
+        node.gain.setValueAtTime(this._gain, ctx.currentTime);
+        node.detune.setValueAtTime(this._detune, ctx.currentTime);
+        this._node = node;
+    }
+}
+
+export { BiquadEffect };
+//# sourceMappingURL=BiquadEffect.js.map

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

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

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

@@ -0,0 +1,41 @@
+import type { AudioBus } from './AudioBus';
+import { BaseVoice, type BaseVoiceInit } from './BaseVoice';
+import { Sound } from './Sound';
+/** Construction parameters for {@link InputVoice}. */
+export interface InputVoiceInit extends BaseVoiceInit {
+    sourceNode: MediaStreamAudioSourceNode;
+    stream: MediaStream;
+}
+/**
+ * Live control handle for an {@link AudioInput} (microphone / WebRTC stream),
+ * created via {@link AudioManager.open}. Unlike a {@link Playable} voice it is
+ * **analysis-only by default** — its output is not routed to a bus, so it never
+ * causes feedback. Tap it for visualisation/beat-detection (`new AudioAnalyser({
+ * source: inputVoice })`), opt into monitoring with {@link InputVoice.routeTo},
+ * or capture it with {@link InputVoice.record}.
+ *
+ * A live stream cannot be seeked, paused, looped, or rate-shifted, so it only
+ * mixes in {@link Spatializable} (via {@link BaseVoice}) on top of the base
+ * Voice surface (volume / fade / stop / effects / output tap / bus).
+ *
+ * @internal
+ */
+export declare class InputVoice extends BaseVoice {
+    private readonly _sourceNode;
+    private readonly _stream;
+    constructor(init: InputVoiceInit);
+    /**
+     * Make the live input audible by routing it to a bus (monitoring). Use
+     * sparingly — routing a microphone to the speakers risks feedback.
+     */
+    routeTo(bus: AudioBus): this;
+    /**
+     * Record `durationMs` of the live input and resolve with a playable
+     * {@link Sound}. Uses `MediaRecorder` under the hood, then decodes the
+     * captured blob into an `AudioBuffer`.
+     */
+    record(durationMs: number): Promise<Sound>;
+    protected _routeThroughPanner(panner: PannerNode): void;
+    protected _teardownSource(): void;
+}
+//# sourceMappingURL=InputVoice.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"InputVoice.d.ts","sourceRoot":"","sources":["../../../src/audio/InputVoice.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AAC3C,OAAO,EAAE,SAAS,EAAE,KAAK,aAAa,EAAE,MAAM,aAAa,CAAC;AAC5D,OAAO,EAAE,KAAK,EAAE,MAAM,SAAS,CAAC;AAEhC,sDAAsD;AACtD,MAAM,WAAW,cAAe,SAAQ,aAAa;IACnD,UAAU,EAAE,0BAA0B,CAAC;IACvC,MAAM,EAAE,WAAW,CAAC;CACrB;AAED;;;;;;;;;;;;;GAaG;AACH,qBAAa,UAAW,SAAQ,SAAS;IACvC,OAAO,CAAC,QAAQ,CAAC,WAAW,CAA6B;IACzD,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAc;gBAEnB,IAAI,EAAE,cAAc;IAQvC;;;OAGG;IACI,OAAO,CAAC,GAAG,EAAE,QAAQ,GAAG,IAAI;IAQnC;;;;OAIG;IACU,MAAM,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,KAAK,CAAC;cAgCpC,mBAAmB,CAAC,MAAM,EAAE,UAAU,GAAG,IAAI;cAM7C,eAAe,IAAI,IAAI;CAG3C"}

package/dist/esm/audio/InputVoice.js

@@ -0,0 +1,85 @@
+import { decodeAudioData } from './audio-context.js';
+import { BaseVoice } from './BaseVoice.js';
+import { Sound } from './Sound.js';
+
+/**
+ * Live control handle for an {@link AudioInput} (microphone / WebRTC stream),
+ * created via {@link AudioManager.open}. Unlike a {@link Playable} voice it is
+ * **analysis-only by default** — its output is not routed to a bus, so it never
+ * causes feedback. Tap it for visualisation/beat-detection (`new AudioAnalyser({
+ * source: inputVoice })`), opt into monitoring with {@link InputVoice.routeTo},
+ * or capture it with {@link InputVoice.record}.
+ *
+ * A live stream cannot be seeked, paused, looped, or rate-shifted, so it only
+ * mixes in {@link Spatializable} (via {@link BaseVoice}) on top of the base
+ * Voice surface (volume / fade / stop / effects / output tap / bus).
+ *
+ * @internal
+ */
+class InputVoice extends BaseVoice {
+    _sourceNode;
+    _stream;
+    constructor(init) {
+        // Analysis-only: do not connect to the bus until routeTo() is called.
+        super({ ...init, autoConnect: false });
+        this._sourceNode = init.sourceNode;
+        this._stream = init.stream;
+        this._sourceNode.connect(this._output);
+    }
+    /**
+     * Make the live input audible by routing it to a bus (monitoring). Use
+     * sparingly — routing a microphone to the speakers risks feedback.
+     */
+    routeTo(bus) {
+        if (this._ended)
+            return this;
+        this._tail().disconnect();
+        this._bus = bus;
+        this._connectOutput();
+        return this;
+    }
+    /**
+     * Record `durationMs` of the live input and resolve with a playable
+     * {@link Sound}. Uses `MediaRecorder` under the hood, then decodes the
+     * captured blob into an `AudioBuffer`.
+     */
+    async record(durationMs) {
+        const recorder = new MediaRecorder(this._stream);
+        const chunks = [];
+        recorder.addEventListener('dataavailable', event => {
+            if (event.data.size > 0)
+                chunks.push(event.data);
+        });
+        return new Promise((resolve, reject) => {
+            recorder.addEventListener('stop', () => {
+                void (async () => {
+                    try {
+                        const blob = new Blob(chunks, { type: recorder.mimeType || 'audio/webm' });
+                        const buffer = await decodeAudioData(await blob.arrayBuffer());
+                        resolve(new Sound(buffer));
+                    }
+                    catch (error) {
+                        reject(error instanceof Error ? error : new Error(String(error)));
+                    }
+                })();
+            });
+            recorder.addEventListener('error', () => reject(new Error('Recording failed.')));
+            recorder.start();
+            setTimeout(() => {
+                if (recorder.state !== 'inactive')
+                    recorder.stop();
+            }, Math.max(0, durationMs));
+        });
+    }
+    _routeThroughPanner(panner) {
+        this._sourceNode.disconnect();
+        this._sourceNode.connect(panner);
+        panner.connect(this._output);
+    }
+    _teardownSource() {
+        this._sourceNode.disconnect();
+    }
+}
+
+export { InputVoice };
+//# sourceMappingURL=InputVoice.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"InputVoice.js","sources":["../../../../src/audio/InputVoice.ts"],"sourcesContent":[null],"names":[],"mappings":";;;;AAWA;;;;;;;;;;;;;AAaG;AACG,MAAO,UAAW,SAAQ,SAAS,CAAA;AACtB,IAAA,WAAW;AACX,IAAA,OAAO;AAExB,IAAA,WAAA,CAAmB,IAAoB,EAAA;;QAErC,KAAK,CAAC,EAAE,GAAG,IAAI,EAAE,WAAW,EAAE,KAAK,EAAE,CAAC;AACtC,QAAA,IAAI,CAAC,WAAW,GAAG,IAAI,CAAC,UAAU;AAClC,QAAA,IAAI,CAAC,OAAO,GAAG,IAAI,CAAC,MAAM;QAC1B,IAAI,CAAC,WAAW,CAAC,OAAO,CAAC,IAAI,CAAC,OAAO,CAAC;IACxC;AAEA;;;AAGG;AACI,IAAA,OAAO,CAAC,GAAa,EAAA;QAC1B,IAAI,IAAI,CAAC,MAAM;AAAE,YAAA,OAAO,IAAI;AAC5B,QAAA,IAAI,CAAC,KAAK,EAAE,CAAC,UAAU,EAAE;AACzB,QAAA,IAAI,CAAC,IAAI,GAAG,GAAG;QACf,IAAI,CAAC,cAAc,EAAE;AACrB,QAAA,OAAO,IAAI;IACb;AAEA;;;;AAIG;IACI,MAAM,MAAM,CAAC,UAAkB,EAAA;QACpC,MAAM,QAAQ,GAAG,IAAI,aAAa,CAAC,IAAI,CAAC,OAAO,CAAC;QAChD,MAAM,MAAM,GAAW,EAAE;AAEzB,QAAA,QAAQ,CAAC,gBAAgB,CAAC,eAAe,EAAE,KAAK,IAAG;AACjD,YAAA,IAAI,KAAK,CAAC,IAAI,CAAC,IAAI,GAAG,CAAC;AAAE,gBAAA,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC;AAClD,QAAA,CAAC,CAAC;QAEF,OAAO,IAAI,OAAO,CAAQ,CAAC,OAAO,EAAE,MAAM,KAAI;AAC5C,YAAA,QAAQ,CAAC,gBAAgB,CAAC,MAAM,EAAE,MAAK;gBACrC,KAAK,CAAC,YAA0B;AAC9B,oBAAA,IAAI;AACF,wBAAA,MAAM,IAAI,GAAG,IAAI,IAAI,CAAC,MAAM,EAAE,EAAE,IAAI,EAAE,QAAQ,CAAC,QAAQ,IAAI,YAAY,EAAE,CAAC;wBAC1E,MAAM,MAAM,GAAG,MAAM,eAAe,CAAC,MAAM,IAAI,CAAC,WAAW,EAAE,CAAC;AAC9D,wBAAA,OAAO,CAAC,IAAI,KAAK,CAAC,MAAM,CAAC,CAAC;oBAC5B;oBAAE,OAAO,KAAK,EAAE;wBACd,MAAM,CAAC,KAAK,YAAY,KAAK,GAAG,KAAK,GAAG,IAAI,KAAK,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC;oBACnE;gBACF,CAAC,GAAG;AACN,YAAA,CAAC,CAAC;AACF,YAAA,QAAQ,CAAC,gBAAgB,CAAC,OAAO,EAAE,MAAM,MAAM,CAAC,IAAI,KAAK,CAAC,mBAAmB,CAAC,CAAC,CAAC;YAEhF,QAAQ,CAAC,KAAK,EAAE;YAChB,UAAU,CACR,MAAK;AACH,gBAAA,IAAI,QAAQ,CAAC,KAAK,KAAK,UAAU;oBAAE,QAAQ,CAAC,IAAI,EAAE;YACpD,CAAC,EACD,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,UAAU,CAAC,CACxB;AACH,QAAA,CAAC,CAAC;IACJ;AAEmB,IAAA,mBAAmB,CAAC,MAAkB,EAAA;AACvD,QAAA,IAAI,CAAC,WAAW,CAAC,UAAU,EAAE;AAC7B,QAAA,IAAI,CAAC,WAAW,CAAC,OAAO,CAAC,MAAM,CAAC;AAChC,QAAA,MAAM,CAAC,OAAO,CAAC,IAAI,CAAC,OAAO,CAAC;IAC9B;IAEmB,eAAe,GAAA;AAChC,QAAA,IAAI,CAAC,WAAW,CAAC,UAAU,EAAE;IAC/B;AACD;;;;"}

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

@@ -0,0 +1,29 @@
+import { Signal } from '#core/Signal';
+import type { AudioBus } from './AudioBus';
+import type { AudioEffect } from './AudioEffect';
+import type { Voice } from './Playable';
+/**
+ * An already-ended {@link Voice} returned for degenerate play calls — a seek
+ * offset past the asset's duration, or a generator played before the
+ * `AudioContext` is unlocked. All controls are inert; `ended` is `true` from
+ * the start and {@link NoopVoice.onEnd} never fires.
+ *
+ * @internal
+ */
+export declare class NoopVoice implements Voice {
+    readonly onEnd: Signal<[]>;
+    private readonly _bus;
+    private _output;
+    constructor(bus: AudioBus);
+    get ended(): boolean;
+    get output(): AudioNode;
+    get volume(): number;
+    set volume(_value: number);
+    get bus(): AudioBus;
+    set bus(_bus: AudioBus);
+    fade(_to: number, _ms: number): void;
+    stop(_fadeMs?: number): void;
+    addEffect(_effect: AudioEffect): this;
+    removeEffect(_effect: AudioEffect): this;
+}
+//# sourceMappingURL=NoopVoice.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"NoopVoice.d.ts","sourceRoot":"","sources":["../../../src/audio/NoopVoice.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,EAAE,MAAM,cAAc,CAAC;AAGtC,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AAC3C,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,eAAe,CAAC;AACjD,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,YAAY,CAAC;AAExC;;;;;;;GAOG;AACH,qBAAa,SAAU,YAAW,KAAK;IACrC,SAAgB,KAAK,aAAgB;IACrC,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAW;IAChC,OAAO,CAAC,OAAO,CAA0B;gBAEtB,GAAG,EAAE,QAAQ;IAIhC,IAAW,KAAK,IAAI,OAAO,CAE1B;IAED,IAAW,MAAM,IAAI,SAAS,CAE7B;IAED,IAAW,MAAM,IAAI,MAAM,CAE1B;IAED,IAAW,MAAM,CAAC,MAAM,EAAE,MAAM,EAE/B;IAED,IAAW,GAAG,IAAI,QAAQ,CAEzB;IAED,IAAW,GAAG,CAAC,IAAI,EAAE,QAAQ,EAE5B;IAEM,IAAI,CAAC,GAAG,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,IAAI;IAIpC,IAAI,CAAC,OAAO,CAAC,EAAE,MAAM,GAAG,IAAI;IAI5B,SAAS,CAAC,OAAO,EAAE,WAAW,GAAG,IAAI;IAIrC,YAAY,CAAC,OAAO,EAAE,WAAW,GAAG,IAAI;CAGhD"}

package/dist/esm/audio/NoopVoice.js

@@ -0,0 +1,52 @@
+import { Signal } from '../core/Signal.js';
+import { getAudioContext } from './audio-context.js';
+
+/**
+ * An already-ended {@link Voice} returned for degenerate play calls — a seek
+ * offset past the asset's duration, or a generator played before the
+ * `AudioContext` is unlocked. All controls are inert; `ended` is `true` from
+ * the start and {@link NoopVoice.onEnd} never fires.
+ *
+ * @internal
+ */
+class NoopVoice {
+    onEnd = new Signal();
+    _bus;
+    _output = null;
+    constructor(bus) {
+        this._bus = bus;
+    }
+    get ended() {
+        return true;
+    }
+    get output() {
+        return (this._output ??= getAudioContext().createGain());
+    }
+    get volume() {
+        return 0;
+    }
+    set volume(_value) {
+        // inert — the voice already ended
+    }
+    get bus() {
+        return this._bus;
+    }
+    set bus(_bus) {
+        // inert — the voice already ended
+    }
+    fade(_to, _ms) {
+        // inert — the voice already ended
+    }
+    stop(_fadeMs) {
+        // inert — the voice already ended
+    }
+    addEffect(_effect) {
+        return this;
+    }
+    removeEffect(_effect) {
+        return this;
+    }
+}
+
+export { NoopVoice };
+//# sourceMappingURL=NoopVoice.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"NoopVoice.js","sources":["../../../../src/audio/NoopVoice.ts"],"sourcesContent":[null],"names":[],"mappings":";;;AAOA;;;;;;;AAOG;MACU,SAAS,CAAA;AACJ,IAAA,KAAK,GAAG,IAAI,MAAM,EAAE;AACnB,IAAA,IAAI;IACb,OAAO,GAAqB,IAAI;AAExC,IAAA,WAAA,CAAmB,GAAa,EAAA;AAC9B,QAAA,IAAI,CAAC,IAAI,GAAG,GAAG;IACjB;AAEA,IAAA,IAAW,KAAK,GAAA;AACd,QAAA,OAAO,IAAI;IACb;AAEA,IAAA,IAAW,MAAM,GAAA;QACf,QAAQ,IAAI,CAAC,OAAO,KAAK,eAAe,EAAE,CAAC,UAAU,EAAE;IACzD;AAEA,IAAA,IAAW,MAAM,GAAA;AACf,QAAA,OAAO,CAAC;IACV;IAEA,IAAW,MAAM,CAAC,MAAc,EAAA;;IAEhC;AAEA,IAAA,IAAW,GAAG,GAAA;QACZ,OAAO,IAAI,CAAC,IAAI;IAClB;IAEA,IAAW,GAAG,CAAC,IAAc,EAAA;;IAE7B;IAEO,IAAI,CAAC,GAAW,EAAE,GAAW,EAAA;;IAEpC;AAEO,IAAA,IAAI,CAAC,OAAgB,EAAA;;IAE5B;AAEO,IAAA,SAAS,CAAC,OAAoB,EAAA;AACnC,QAAA,OAAO,IAAI;IACb;AAEO,IAAA,YAAY,CAAC,OAAoB,EAAA;AACtC,QAAA,OAAO,IAAI;IACb;AACD;;;;"}

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

@@ -0,0 +1,135 @@
+import type { SceneNode } from '#core/SceneNode';
+import type { Signal } from '#core/Signal';
+import type { Vector } from '#math/Vector';
+import type { AudioBus } from './AudioBus';
+import type { AudioEffect } from './AudioEffect';
+import type { AudioManager } from './AudioManager';
+/**
+ * A live playback instance in the audio graph with a control surface.
+ *
+ * A Voice is created by playing a {@link Playable} via {@link AudioManager.play}
+ * (and, later, by opening an `AudioInput`). Each `play()` returns an independent
+ * Voice, so overlapping concurrent playback of the same asset is just multiple
+ * Voices.
+ *
+ * Concrete voices mix in the capability interfaces ({@link Seekable},
+ * {@link Pausable}, {@link Loopable}, {@link RatePitched}, {@link Spatializable})
+ * for whatever their backing Web Audio node actually supports — narrow with a
+ * capability check (`'seek' in voice`) before using one.
+ */
+export interface Voice {
+    /**
+     * Stop playback and release this voice's resources. Pass `fadeMs` to ramp
+     * the volume to zero over that many milliseconds before stopping; omit (or
+     * pass `0`) to stop immediately. Idempotent — calling again is a no-op.
+     */
+    stop(fadeMs?: number): void;
+    /** Playback volume in the range [0, 1]. Bus volume (0..2) can amplify beyond this. */
+    volume: number;
+    /**
+     * Ramp the volume to `to` (clamped to [0, 1]) over `ms` milliseconds without
+     * stopping. Use {@link Voice.stop} with a fade argument to fade out and stop.
+     */
+    fade(to: number, ms: number): void;
+    /** `true` once playback has ended naturally or been stopped. */
+    readonly ended: boolean;
+    /** Fires once when this voice ends (natural end or {@link Voice.stop}). */
+    readonly onEnd: Signal;
+    /**
+     * The voice's output node — the last node before the {@link AudioBus}. Use it
+     * as a parallel tap for an analyser, or (later) as the insertion point for
+     * per-voice effects.
+     */
+    readonly output: AudioNode;
+    /** The {@link AudioBus} this voice routes into. Reassign to reroute live. */
+    bus: AudioBus;
+    /**
+     * Insert a per-voice {@link AudioEffect} into this voice's output chain
+     * (after the volume gain, before the bus). Effects are applied in insertion
+     * order.
+     */
+    addEffect(effect: AudioEffect): this;
+    /** Remove a previously added per-voice effect. The caller still owns it and must `destroy()` it. */
+    removeEffect(effect: AudioEffect): this;
+}
+/** A voice whose playhead can be read and moved. */
+export interface Seekable {
+    /** Current playback position in seconds. */
+    time: number;
+    /** Total duration in seconds (`Infinity` for open-ended sources). */
+    readonly duration: number;
+    /** Move the playhead to `t` seconds. */
+    seek(t: number): void;
+}
+/** A voice that can be paused and resumed in place. */
+export interface Pausable {
+    pause(): void;
+    resume(): void;
+    readonly paused: boolean;
+}
+/** A voice whose source can loop. */
+export interface Loopable {
+    loop: boolean;
+}
+/** A voice with rate / pitch controls. */
+export interface RatePitched {
+    /** Playback rate multiplier (1 = normal). */
+    playbackRate: number;
+    /** Fine pitch offset in cents. */
+    detune: number;
+}
+/** A voice that can be positioned in 2D space and optionally track a node. */
+export interface Spatializable {
+    /** World-space position of the source, or `null` when not spatialized. */
+    position: Vector | null;
+    /**
+     * Track a {@link SceneNode}: the voice reads the node's global translation
+     * each frame. Pass `null` to stop following and fall back to
+     * {@link Spatializable.position}.
+     */
+    follow(node: SceneNode | null): void;
+}
+/**
+ * Per-play overrides passed to {@link AudioManager.play}.
+ */
+export interface PlayOptions {
+    /** Route this play through a specific {@link AudioBus}. */
+    bus?: AudioBus;
+    /** Override volume for this play instance. Range [0, 1]. */
+    volume?: number;
+    /** Override looping for this play instance. */
+    loop?: boolean;
+    /** Override playback rate for this play instance. */
+    playbackRate?: number;
+    /** Override pitch detune (cents) for this play instance. */
+    detune?: number;
+    /** Seek offset in seconds before starting playback. */
+    time?: number;
+    /** Start muted (volume 0). */
+    muted?: boolean;
+}
+/**
+ * Implemented by audio assets ({@link Sound}, {@link AudioStream},
+ * {@link AudioGenerator}) to support manager-driven playback via
+ * {@link AudioManager.play}.
+ *
+ * Assets are **data descriptors** — they hold the audio data and default
+ * playback parameters. The playback machinery lives in the {@link Voice}
+ * returned by `_createVoice`; the manager is injected at play time, so assets
+ * never reach for a global.
+ *
+ * @internal - `_createVoice` is a low-level hook; consumers should call
+ * `audioManager.play(asset)` instead of calling `_createVoice` directly.
+ */
+export interface Playable {
+    /**
+     * Create and start a new playback instance. Called by
+     * {@link AudioManager.play}; do not call directly.
+     *
+     * @param manager - The owning {@link AudioManager} (provides bus hierarchy).
+     * @param options - Per-play overrides.
+     * @returns A {@link Voice} handle for the new instance.
+     */
+    _createVoice(manager: AudioManager, options: PlayOptions): Voice;
+}
+//# sourceMappingURL=Playable.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"Playable.d.ts","sourceRoot":"","sources":["../../../src/audio/Playable.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAC;AACjD,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,cAAc,CAAC;AAC3C,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,cAAc,CAAC;AAE3C,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AAC3C,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,eAAe,CAAC;AACjD,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,gBAAgB,CAAC;AAEnD;;;;;;;;;;;;GAYG;AACH,MAAM,WAAW,KAAK;IACpB;;;;OAIG;IACH,IAAI,CAAC,MAAM,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAC5B,sFAAsF;IACtF,MAAM,EAAE,MAAM,CAAC;IACf;;;OAGG;IACH,IAAI,CAAC,EAAE,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,GAAG,IAAI,CAAC;IACnC,gEAAgE;IAChE,QAAQ,CAAC,KAAK,EAAE,OAAO,CAAC;IACxB,2EAA2E;IAC3E,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB;;;;OAIG;IACH,QAAQ,CAAC,MAAM,EAAE,SAAS,CAAC;IAC3B,6EAA6E;IAC7E,GAAG,EAAE,QAAQ,CAAC;IACd;;;;OAIG;IACH,SAAS,CAAC,MAAM,EAAE,WAAW,GAAG,IAAI,CAAC;IACrC,oGAAoG;IACpG,YAAY,CAAC,MAAM,EAAE,WAAW,GAAG,IAAI,CAAC;CACzC;AAED,oDAAoD;AACpD,MAAM,WAAW,QAAQ;IACvB,4CAA4C;IAC5C,IAAI,EAAE,MAAM,CAAC;IACb,qEAAqE;IACrE,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,wCAAwC;IACxC,IAAI,CAAC,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;CACvB;AAED,uDAAuD;AACvD,MAAM,WAAW,QAAQ;IACvB,KAAK,IAAI,IAAI,CAAC;IACd,MAAM,IAAI,IAAI,CAAC;IACf,QAAQ,CAAC,MAAM,EAAE,OAAO,CAAC;CAC1B;AAED,qCAAqC;AACrC,MAAM,WAAW,QAAQ;IACvB,IAAI,EAAE,OAAO,CAAC;CACf;AAED,0CAA0C;AAC1C,MAAM,WAAW,WAAW;IAC1B,6CAA6C;IAC7C,YAAY,EAAE,MAAM,CAAC;IACrB,kCAAkC;IAClC,MAAM,EAAE,MAAM,CAAC;CAChB;AAED,8EAA8E;AAC9E,MAAM,WAAW,aAAa;IAC5B,0EAA0E;IAC1E,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;IACxB;;;;OAIG;IACH,MAAM,CAAC,IAAI,EAAE,SAAS,GAAG,IAAI,GAAG,IAAI,CAAC;CACtC;AAED;;GAEG;AACH,MAAM,WAAW,WAAW;IAC1B,2DAA2D;IAC3D,GAAG,CAAC,EAAE,QAAQ,CAAC;IACf,4DAA4D;IAC5D,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,+CAA+C;IAC/C,IAAI,CAAC,EAAE,OAAO,CAAC;IACf,qDAAqD;IACrD,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,4DAA4D;IAC5D,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,uDAAuD;IACvD,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,8BAA8B;IAC9B,KAAK,CAAC,EAAE,OAAO,CAAC;CACjB;AAED;;;;;;;;;;;;GAYG;AACH,MAAM,WAAW,QAAQ;IACvB;;;;;;;OAOG;IACH,YAAY,CAAC,OAAO,EAAE,YAAY,EAAE,OAAO,EAAE,WAAW,GAAG,KAAK,CAAC;CAClE"}