@codexo/exojs 0.12.0 → 0.14.0

package/dist/esm/audio/AudioStream.js

@@ -0,0 +1,109 @@
+import { clamp } from '../math/utils.js';
+import { getAudioContext } from './audio-context.js';
+import { AudioStreamVoice } from './AudioStreamVoice.js';
+
+/**
+ * Streaming long-form audio backed by an `HTMLAudioElement` — background
+ * tracks, voice-over, **and internet radio** (same mechanism, low CPU/RAM).
+ * Decoded lazily via the browser's media pipeline, so memory cost scales with
+ * the decode buffer rather than total duration.
+ *
+ * `AudioStream` is a **data descriptor**: it holds the media element and default
+ * playback parameters but does not play itself. Playback is driven by
+ * `AudioManager.play(stream, options)`, which returns an {@link AudioStreamVoice}
+ * for fine-grained control (pause/resume, seek, loop, rate, volume, spatial).
+ *
+ * Because an `HTMLAudioElement` has a single playhead, a stream has **one active
+ * voice at a time** — playing again stops the previous voice. Routes through the
+ * manager's `music` bus by default (override via {@link PlayOptions.bus}).
+ *
+ * Use {@link Sound} for short, frequently-triggered clips that benefit from
+ * pre-decoded `AudioBuffer` storage and pooled overlapping playback.
+ */
+class AudioStream {
+    _audioElement;
+    /** Default volume applied to new voices. Range [0, 1]. */
+    volume;
+    /** Default loop flag applied to new voices. */
+    loop;
+    /** Default playback rate applied to new voices. */
+    playbackRate;
+    /** Default muted flag (starts a voice at volume 0). */
+    muted;
+    _sourceNode = null;
+    _activeVoice = null;
+    constructor(audioElement, options) {
+        this._audioElement = audioElement;
+        this.volume = clamp(options?.volume ?? 1, 0, 1);
+        this.loop = options?.loop ?? false;
+        this.playbackRate = clamp(options?.playbackRate ?? 1, 0.1, 20);
+        this.muted = options?.muted ?? false;
+        if (options?.time !== undefined) {
+            this._audioElement.currentTime = Math.max(0, options.time);
+        }
+    }
+    /** The backing `HTMLAudioElement`. */
+    get audioElement() {
+        return this._audioElement;
+    }
+    /** Total media duration in seconds (`NaN` until metadata has loaded). */
+    get duration() {
+        return this._audioElement.duration;
+    }
+    /**
+     * Implements {@link Playable}. Called by {@link AudioManager.play}.
+     *
+     * Stops any previously active voice (a stream has a single playhead), then
+     * starts a fresh {@link AudioStreamVoice}.
+     */
+    _createVoice(manager, options) {
+        const bus = options.bus ?? manager.music;
+        const audioContext = getAudioContext();
+        if (this._activeVoice !== null && !this._activeVoice.ended) {
+            this._activeVoice.stop();
+        }
+        // The MediaElementAudioSourceNode is 1:1 with the element — create it once.
+        if (this._sourceNode === null) {
+            this._sourceNode = audioContext.createMediaElementSource(this._audioElement);
+        }
+        else {
+            this._sourceNode.disconnect();
+        }
+        const output = audioContext.createGain();
+        const loop = options.loop ?? this.loop;
+        const playbackRate = clamp(options.playbackRate ?? this.playbackRate, 0.1, 20);
+        const volume = clamp(options.muted ? 0 : (options.volume ?? (this.muted ? 0 : this.volume)), 0, 1);
+        const voice = new AudioStreamVoice({
+            audioContext,
+            output,
+            bus,
+            manager,
+            volume,
+            element: this._audioElement,
+            sourceNode: this._sourceNode,
+            loop,
+            playbackRate,
+            ...(options.time !== undefined && { startTime: options.time }),
+        });
+        this._activeVoice = voice;
+        voice.onEnd.add(() => {
+            if (this._activeVoice === voice)
+                this._activeVoice = null;
+        });
+        return voice;
+    }
+    /** Stop the active voice and release the media graph. */
+    destroy() {
+        if (this._activeVoice !== null) {
+            this._activeVoice.stop();
+            this._activeVoice = null;
+        }
+        if (this._sourceNode !== null) {
+            this._sourceNode.disconnect();
+            this._sourceNode = null;
+        }
+    }
+}
+
+export { AudioStream };
+//# sourceMappingURL=AudioStream.js.map

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

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

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

@@ -0,0 +1,61 @@
+import { BaseVoice, type BaseVoiceInit } from './BaseVoice';
+import type { Loopable, Pausable, RatePitched, Seekable } from './Playable';
+/** Construction parameters for {@link AudioStreamVoice}. */
+export interface AudioStreamVoiceInit extends BaseVoiceInit {
+    element: HTMLMediaElement;
+    /** The element's `MediaElementAudioSourceNode` (owned by the {@link AudioStream}). */
+    sourceNode: MediaElementAudioSourceNode;
+    loop: boolean;
+    playbackRate: number;
+    /** Seek offset (seconds) to start at. */
+    startTime?: number;
+}
+/**
+ * Active playback handle for one {@link AudioStream} play call, backed by the
+ * stream's `HTMLMediaElement` + `MediaElementAudioSourceNode`. Because the
+ * element owns a single playhead, a stream has one active voice at a time —
+ * starting a new voice stops the previous one.
+ *
+ * Mixes in {@link Seekable}, {@link Pausable}, {@link Loopable},
+ * {@link RatePitched} (playback rate; `detune` is stored but inert — an
+ * `HTMLMediaElement` has no detune control), and (via {@link BaseVoice})
+ * {@link Spatializable}.
+ *
+ * @internal
+ */
+export declare class AudioStreamVoice extends BaseVoice implements Seekable, Pausable, Loopable, RatePitched {
+    private readonly _element;
+    private readonly _sourceNode;
+    private _detune;
+    private readonly _onEnded;
+    private _unlockHandler;
+    constructor(init: AudioStreamVoiceInit);
+    get duration(): number;
+    get time(): number;
+    set time(value: number);
+    seek(t: number): void;
+    pause(): void;
+    resume(): void;
+    get paused(): boolean;
+    get loop(): boolean;
+    set loop(value: boolean);
+    get playbackRate(): number;
+    set playbackRate(value: number);
+    /**
+     * Pitch detune in cents. An `HTMLMediaElement` exposes no detune control, so
+     * this value is stored but does not affect a stream — use {@link Sound} or
+     * {@link AudioGenerator} when you need real detune.
+     */
+    get detune(): number;
+    set detune(value: number);
+    protected _routeThroughPanner(panner: PannerNode): void;
+    protected _teardownSource(): void;
+    /**
+     * Start element playback. If the `AudioContext` is still locked by the
+     * browser's autoplay policy, defer the start until the first user gesture
+     * unlocks it.
+     */
+    private _startPlayback;
+    private _clearUnlockHandler;
+}
+//# sourceMappingURL=AudioStreamVoice.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"AudioStreamVoice.d.ts","sourceRoot":"","sources":["../../../src/audio/AudioStreamVoice.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,SAAS,EAAE,KAAK,aAAa,EAAE,MAAM,aAAa,CAAC;AAC5D,OAAO,KAAK,EAAE,QAAQ,EAAE,QAAQ,EAAE,WAAW,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AAE5E,4DAA4D;AAC5D,MAAM,WAAW,oBAAqB,SAAQ,aAAa;IACzD,OAAO,EAAE,gBAAgB,CAAC;IAC1B,sFAAsF;IACtF,UAAU,EAAE,2BAA2B,CAAC;IACxC,IAAI,EAAE,OAAO,CAAC;IACd,YAAY,EAAE,MAAM,CAAC;IACrB,yCAAyC;IACzC,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED;;;;;;;;;;;;GAYG;AACH,qBAAa,gBAAiB,SAAQ,SAAU,YAAW,QAAQ,EAAE,QAAQ,EAAE,QAAQ,EAAE,WAAW;IAClG,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAmB;IAC5C,OAAO,CAAC,QAAQ,CAAC,WAAW,CAA8B;IAC1D,OAAO,CAAC,OAAO,CAAK;IACpB,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAA8B;IACvD,OAAO,CAAC,cAAc,CAAuD;gBAE1D,IAAI,EAAE,oBAAoB;IAqB7C,IAAW,QAAQ,IAAI,MAAM,CAE5B;IAED,IAAW,IAAI,IAAI,MAAM,CAExB;IAED,IAAW,IAAI,CAAC,KAAK,EAAE,MAAM,EAE5B;IAEM,IAAI,CAAC,CAAC,EAAE,MAAM,GAAG,IAAI;IASrB,KAAK,IAAI,IAAI;IAIb,MAAM,IAAI,IAAI;IAIrB,IAAW,MAAM,IAAI,OAAO,CAE3B;IAMD,IAAW,IAAI,IAAI,OAAO,CAEzB;IAED,IAAW,IAAI,CAAC,KAAK,EAAE,OAAO,EAE7B;IAMD,IAAW,YAAY,IAAI,MAAM,CAEhC;IAED,IAAW,YAAY,CAAC,KAAK,EAAE,MAAM,EAEpC;IAED;;;;OAIG;IACH,IAAW,MAAM,IAAI,MAAM,CAE1B;IAED,IAAW,MAAM,CAAC,KAAK,EAAE,MAAM,EAE9B;cAMkB,mBAAmB,CAAC,MAAM,EAAE,UAAU,GAAG,IAAI;cAM7C,eAAe,IAAI,IAAI;IAO1C;;;;OAIG;IACH,OAAO,CAAC,cAAc;IAatB,OAAO,CAAC,mBAAmB;CAM5B"}

package/dist/esm/audio/AudioStreamVoice.js

@@ -0,0 +1,137 @@
+import { clamp } from '../math/utils.js';
+import { isAudioContextReady, onAudioContextReady } from './audio-context.js';
+import { BaseVoice } from './BaseVoice.js';
+
+/**
+ * Active playback handle for one {@link AudioStream} play call, backed by the
+ * stream's `HTMLMediaElement` + `MediaElementAudioSourceNode`. Because the
+ * element owns a single playhead, a stream has one active voice at a time —
+ * starting a new voice stops the previous one.
+ *
+ * Mixes in {@link Seekable}, {@link Pausable}, {@link Loopable},
+ * {@link RatePitched} (playback rate; `detune` is stored but inert — an
+ * `HTMLMediaElement` has no detune control), and (via {@link BaseVoice})
+ * {@link Spatializable}.
+ *
+ * @internal
+ */
+class AudioStreamVoice extends BaseVoice {
+    _element;
+    _sourceNode;
+    _detune = 0;
+    _onEnded = () => this._finish();
+    _unlockHandler = null;
+    constructor(init) {
+        super(init);
+        this._element = init.element;
+        this._sourceNode = init.sourceNode;
+        this._sourceNode.connect(this._output);
+        this._element.loop = init.loop;
+        this._element.playbackRate = init.playbackRate;
+        if (init.startTime !== undefined) {
+            this._element.currentTime = Math.max(0, init.startTime);
+        }
+        this._element.addEventListener('ended', this._onEnded);
+        this._startPlayback();
+    }
+    // -------------------------------------------------------------------------
+    // Seekable
+    // -------------------------------------------------------------------------
+    get duration() {
+        return this._element.duration;
+    }
+    get time() {
+        return this._element.currentTime;
+    }
+    set time(value) {
+        this.seek(value);
+    }
+    seek(t) {
+        if (this._ended)
+            return;
+        this._element.currentTime = Math.max(0, t);
+    }
+    // -------------------------------------------------------------------------
+    // Pausable
+    // -------------------------------------------------------------------------
+    pause() {
+        if (!this._ended)
+            this._element.pause();
+    }
+    resume() {
+        if (!this._ended)
+            void this._element.play();
+    }
+    get paused() {
+        return this._element.paused;
+    }
+    // -------------------------------------------------------------------------
+    // Loopable
+    // -------------------------------------------------------------------------
+    get loop() {
+        return this._element.loop;
+    }
+    set loop(value) {
+        this._element.loop = value;
+    }
+    // -------------------------------------------------------------------------
+    // RatePitched
+    // -------------------------------------------------------------------------
+    get playbackRate() {
+        return this._element.playbackRate;
+    }
+    set playbackRate(value) {
+        this._element.playbackRate = clamp(value, 0.1, 20);
+    }
+    /**
+     * Pitch detune in cents. An `HTMLMediaElement` exposes no detune control, so
+     * this value is stored but does not affect a stream — use {@link Sound} or
+     * {@link AudioGenerator} when you need real detune.
+     */
+    get detune() {
+        return this._detune;
+    }
+    set detune(value) {
+        this._detune = value;
+    }
+    // -------------------------------------------------------------------------
+    // BaseVoice hooks
+    // -------------------------------------------------------------------------
+    _routeThroughPanner(panner) {
+        this._sourceNode.disconnect();
+        this._sourceNode.connect(panner);
+        panner.connect(this._output);
+    }
+    _teardownSource() {
+        this._element.removeEventListener('ended', this._onEnded);
+        this._clearUnlockHandler();
+        this._element.pause();
+        this._sourceNode.disconnect();
+    }
+    /**
+     * Start element playback. If the `AudioContext` is still locked by the
+     * browser's autoplay policy, defer the start until the first user gesture
+     * unlocks it.
+     */
+    _startPlayback() {
+        if (isAudioContextReady()) {
+            void this._element.play();
+            return;
+        }
+        this._unlockHandler = () => {
+            this._clearUnlockHandler();
+            if (!this._ended)
+                void this._element.play();
+        };
+        onAudioContextReady.add(this._unlockHandler);
+    }
+    _clearUnlockHandler() {
+        if (this._unlockHandler !== null) {
+            onAudioContextReady.remove(this._unlockHandler);
+            this._unlockHandler = null;
+        }
+    }
+}
+
+export { AudioStreamVoice };
+//# sourceMappingURL=AudioStreamVoice.js.map

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

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

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

@@ -0,0 +1,111 @@
+import type { SceneNode } from '#core/SceneNode';
+import { Signal } from '#core/Signal';
+import { Vector } from '#math/Vector';
+import type { AudioBus } from './AudioBus';
+import type { AudioEffect } from './AudioEffect';
+import type { AudioManager } from './AudioManager';
+import type { Spatializable, Voice } from './Playable';
+/** Distance-attenuation configuration for a spatial voice. */
+export interface VoiceSpatialConfig {
+    distanceModel: DistanceModelType;
+    refDistance: number;
+    maxDistance: number;
+    rolloffFactor: number;
+}
+/** Construction parameters shared by every concrete voice. */
+export interface BaseVoiceInit {
+    audioContext: AudioContext;
+    /** The voice's output gain — the last node before the bus. */
+    output: GainNode;
+    bus: AudioBus;
+    manager: AudioManager;
+    /** Initial volume, range [0, 1]. */
+    volume: number;
+    /** Spatial parameters; defaults are used for any omitted field. */
+    spatial?: Partial<VoiceSpatialConfig>;
+    /**
+     * Connect the output to the bus on construction. Default `true`. Pass `false`
+     * for analysis-only voices (e.g. a live {@link InputVoice}) that should not be
+     * audible until explicitly routed.
+     */
+    autoConnect?: boolean;
+}
+/** A voice the {@link AudioManager} ticks each frame for spatial updates. */
+export interface SpatialVoice {
+    readonly ended: boolean;
+    _tickSpatial(): void;
+}
+/**
+ * Shared base for the concrete voices ({@link SoundVoice},
+ * {@link AudioStreamVoice}, {@link AudioGeneratorVoice}). Implements the common
+ * {@link Voice} control surface — volume, fade, stop, lifecycle Signal, bus
+ * routing — and the {@link Spatializable} capability via a lazily-inserted
+ * `PannerNode`.
+ *
+ * The voice graph is `<source> → [panner] → output(gain) → bus.input`. The
+ * `output` gain is always the last node (a stable tap point); the panner is
+ * inserted between the source and the gain only once the voice is actually
+ * spatialized. Concrete voices provide the two source-specific hooks
+ * {@link BaseVoice._routeThroughPanner} and {@link BaseVoice._teardownSource}.
+ *
+ * @internal
+ */
+export declare abstract class BaseVoice implements Voice, Spatializable, SpatialVoice {
+    protected readonly _audioContext: AudioContext;
+    protected readonly _output: GainNode;
+    protected readonly _manager: AudioManager;
+    protected _bus: AudioBus;
+    protected _volume: number;
+    protected _ended: boolean;
+    protected _stopTimer: ReturnType<typeof setTimeout> | null;
+    readonly onEnd: Signal<[]>;
+    private readonly _spatialConfig;
+    protected _panner: PannerNode | null;
+    private _position;
+    private _followNode;
+    private _spatialRegistered;
+    /** Per-voice effect chain, inserted between the output gain and the bus. */
+    private readonly _effects;
+    protected constructor(init: BaseVoiceInit);
+    get ended(): boolean;
+    get output(): AudioNode;
+    get volume(): number;
+    set volume(value: number);
+    get bus(): AudioBus;
+    set bus(bus: AudioBus);
+    addEffect(effect: AudioEffect): this;
+    removeEffect(effect: AudioEffect): this;
+    fade(to: number, ms: number): void;
+    stop(fadeMs?: number): void;
+    get position(): Vector | null;
+    set position(value: Vector | {
+        x: number;
+        y: number;
+    } | null);
+    follow(node: SceneNode | null): void;
+    /** @internal Called once per frame by {@link AudioManager.update} for spatial voices. */
+    _tickSpatial(): void;
+    /** The last node in the voice chain before the bus — the output gain, or the last effect. */
+    protected _tail(): AudioNode;
+    protected _connectOutput(): void;
+    /** Connect `tail` to the bus input, or to the destination with a deferred reroute while the bus is still locked. */
+    private _connectTail;
+    /** Rewire `output → [effects...] → bus` after the per-voice effect chain changes. */
+    private _rebuildEffectChain;
+    protected _clearStopTimer(): void;
+    private _ensurePanner;
+    /**
+     * Called once on natural end or explicit {@link BaseVoice.stop}. Idempotent —
+     * subsequent calls are no-ops once `_ended` is set.
+     */
+    protected _finish(): void;
+    /**
+     * Insert `panner` between the voice's source and its output gain. The source
+     * is currently connected directly to {@link BaseVoice._output}; rewire it as
+     * `source → panner → output`.
+     */
+    protected abstract _routeThroughPanner(panner: PannerNode): void;
+    /** Stop and disconnect the voice's source node(s). Called once from `_finish`. */
+    protected abstract _teardownSource(): void;
+}
+//# sourceMappingURL=BaseVoice.d.ts.map

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

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