@codexo/exojs 0.6.12 → 0.7.12

package/dist/esm/audio/AudioAnalyser.js

@@ -1,88 +1,308 @@
 import { isAudioContextReady, getAudioContext, onAudioContextReady } from './audio-context.js';
 
+/**
+ * Lightweight visualisation analyser backed by a Web Audio AnalyserNode.
+ *
+ * Accepts any of: AudioBus, Sound, Music, MediaStream, AudioNode, or null.
+ * The tap is a parallel branch — it does not affect the source's main routing.
+ *
+ * Migration from 0.7.1: the old constructor was `new AudioAnalyser(media, options)`.
+ * The new API is `new AudioAnalyser(options?); analyser.source = media`.
+ */
 class AudioAnalyser {
-    _media;
-    _fftSize;
-    _minDecibels;
-    _maxDecibels;
-    _smoothingTimeConstant;
-    _frequencyBinCount;
-    _timeDomainData;
-    _frequencyData;
-    _preciseTimeDomainData;
-    _preciseFrequencyData;
     _analyser = null;
-    _analyserTarget = null;
-    constructor(media, options = {}) {
-        const { fftSize, minDecibels, maxDecibels, smoothingTimeConstant } = options;
-        this._media = media;
-        this._fftSize = fftSize ?? 2048;
-        this._minDecibels = minDecibels ?? -100;
-        this._maxDecibels = maxDecibels ?? -30;
-        this._smoothingTimeConstant = smoothingTimeConstant ?? 0.8;
-        this._frequencyBinCount = this._fftSize / 2;
-        this._timeDomainData = new Uint8Array(this._frequencyBinCount);
-        this._frequencyData = new Uint8Array(this._frequencyBinCount);
-        this._preciseTimeDomainData = new Float32Array(this._frequencyBinCount);
-        this._preciseFrequencyData = new Float32Array(this._frequencyBinCount);
+    _options;
+    _source = null;
+    _tapSource = null;
+    _streamSource = null;
+    // Pre-allocated buffers
+    _byteSpectrum;
+    _floatSpectrum;
+    _byteWaveform;
+    _floatWaveform;
+    /**
+     * Create an `AudioAnalyser` with the given options. The underlying
+     * `AnalyserNode` is created immediately if the `AudioContext` is already
+     * running, or deferred until {@link onAudioContextReady} fires.
+     */
+    constructor(options) {
+        this._options = {
+            fftSize: options?.fftSize ?? 2048,
+            smoothingTimeConstant: options?.smoothingTimeConstant ?? 0.8,
+            minDecibels: options?.minDecibels ?? -100,
+            maxDecibels: options?.maxDecibels ?? -30,
+        };
+        const binCount = this._options.fftSize >> 1;
+        this._byteSpectrum = new Uint8Array(binCount);
+        this._floatSpectrum = new Float32Array(binCount);
+        this._byteWaveform = new Uint8Array(binCount);
+        this._floatWaveform = new Float32Array(binCount);
         if (isAudioContextReady()) {
-            this.setupWithAudioContext(getAudioContext());
+            this._setupAnalyser(getAudioContext());
         }
         else {
-            onAudioContextReady.once(this.setupWithAudioContext, this);
+            onAudioContextReady.once(this._setupAnalyser, this);
         }
     }
-    connect() {
-        if (!this._analyser || this._analyserTarget !== null) {
-            return this;
+    // -----------------------------------------------------------------------
+    // Source setter
+    // -----------------------------------------------------------------------
+    /**
+     * The currently tapped audio source, or `null` if none is set.
+     * Assigning a new value disconnects the previous tap and connects the new
+     * source as a parallel branch without affecting the source's main routing.
+     */
+    get source() {
+        return this._source;
+    }
+    set source(value) {
+        if (value === this._source)
+            return;
+        // 1. Disconnect current tap
+        this._disconnectTap();
+        this._source = value;
+        if (value === null)
+            return;
+        // 2. Resolve and connect new tap
+        if (isAudioContextReady()) {
+            this._connectSource(value, getAudioContext());
         }
-        const analyserTarget = this._media.analyserTarget;
-        if (!analyserTarget) {
-            throw new Error('No AudioNode on property analyserTarget.');
+        else {
+            onAudioContextReady.once((ctx) => {
+                if (this._source === value) {
+                    this._connectSource(value, ctx);
+                }
+            }, this);
         }
-        this._analyserTarget = analyserTarget;
-        analyserTarget.connect(this._analyser);
-        return this;
     }
-    get timeDomainData() {
+    // -----------------------------------------------------------------------
+    // AnalyserNode property pass-throughs
+    // -----------------------------------------------------------------------
+    get fftSize() {
+        return this._options.fftSize;
+    }
+    /** Number of frequency bins available — half of `fftSize`. */
+    get frequencyBinCount() {
+        return this._options.fftSize >> 1;
+    }
+    get smoothingTimeConstant() {
+        return this._analyser?.smoothingTimeConstant ?? this._options.smoothingTimeConstant;
+    }
+    set smoothingTimeConstant(v) {
+        this._options.smoothingTimeConstant = v;
+        if (this._analyser)
+            this._analyser.smoothingTimeConstant = v;
+    }
+    get minDecibels() {
+        return this._analyser?.minDecibels ?? this._options.minDecibels;
+    }
+    set minDecibels(v) {
+        this._options.minDecibels = v;
+        if (this._analyser)
+            this._analyser.minDecibels = v;
+    }
+    get maxDecibels() {
+        return this._analyser?.maxDecibels ?? this._options.maxDecibels;
+    }
+    set maxDecibels(v) {
+        this._options.maxDecibels = v;
+        if (this._analyser)
+            this._analyser.maxDecibels = v;
+    }
+    // -----------------------------------------------------------------------
+    // Raw data
+    // -----------------------------------------------------------------------
+    /** Fill and return the byte frequency spectrum (0..255 per bin). */
+    getSpectrum(into) {
+        const buf = into ?? this._byteSpectrum;
         if (this._analyser) {
-            this.connect();
-            this._analyser.getByteTimeDomainData(this._timeDomainData);
+            this._analyser.getByteFrequencyData(buf);
         }
-        return this._timeDomainData;
+        else {
+            buf.fill(0);
+        }
+        return buf;
     }
-    get frequencyData() {
+    /** Fill and return the float frequency spectrum (dB per bin). */
+    getSpectrumFloat(into) {
+        const buf = into ?? this._floatSpectrum;
         if (this._analyser) {
-            this.connect();
-            this._analyser.getByteFrequencyData(this._frequencyData);
+            this._analyser.getFloatFrequencyData(buf);
         }
-        return this._frequencyData;
+        else {
+            buf.fill(0);
+        }
+        return buf;
     }
-    get preciseTimeDomainData() {
+    /** Fill and return the byte time-domain waveform (0..255 per sample). */
+    getWaveform(into) {
+        const buf = into ?? this._byteWaveform;
         if (this._analyser) {
-            this.connect();
-            this._analyser.getFloatTimeDomainData(this._preciseTimeDomainData);
+            this._analyser.getByteTimeDomainData(buf);
+        }
+        else {
+            buf.fill(0);
         }
-        return this._preciseTimeDomainData;
+        return buf;
     }
-    get preciseFrequencyData() {
+    /** Fill and return the float time-domain waveform (-1..1 per sample). */
+    getWaveformFloat(into) {
+        const buf = into ?? this._floatWaveform;
         if (this._analyser) {
-            this.connect();
-            this._analyser.getFloatFrequencyData(this._preciseFrequencyData);
+            this._analyser.getFloatTimeDomainData(buf);
+        }
+        else {
+            buf.fill(0);
+        }
+        return buf;
+    }
+    // -----------------------------------------------------------------------
+    // Convenience helpers
+    // -----------------------------------------------------------------------
+    /**
+     * Return the mean energy of frequency bins in the given Hz range, normalised 0..1.
+     * Uses the byte spectrum (0..255), normalised by dividing by 255.
+     */
+    getBandEnergy(fromHz, toHz) {
+        if (!this._analyser)
+            return 0;
+        const ctx = getAudioContext();
+        const nyquist = ctx.sampleRate / 2;
+        const binCount = this.frequencyBinCount;
+        const fromBin = Math.max(0, Math.min(binCount - 1, Math.round(fromHz / nyquist * binCount)));
+        const toBin = Math.max(0, Math.min(binCount - 1, Math.round(toHz / nyquist * binCount)));
+        const lo = Math.min(fromBin, toBin);
+        const hi = Math.max(fromBin, toBin);
+        const spectrum = this.getSpectrum();
+        let sum = 0;
+        const count = hi - lo + 1;
+        for (let i = lo; i <= hi; i++) {
+            sum += spectrum[i];
         }
-        return this._preciseFrequencyData;
+        return sum / (count * 255);
+    }
+    /** Return low (0-250 Hz), mid (250-2 kHz), and high (2 k-20 kHz) band energies (0..1 each). */
+    getLowMidHigh() {
+        return {
+            low: this.getBandEnergy(0, 250),
+            mid: this.getBandEnergy(250, 2000),
+            high: this.getBandEnergy(2000, 20000),
+        };
+    }
+    /** Return overall RMS energy across all bins, normalised 0..1. */
+    getRms() {
+        if (!this._analyser)
+            return 0;
+        const ctx = getAudioContext();
+        const nyquist = ctx.sampleRate / 2;
+        return this.getBandEnergy(0, nyquist);
     }
+    // -----------------------------------------------------------------------
+    // Lifecycle
+    // -----------------------------------------------------------------------
+    /**
+     * Disconnect the analyser tap, release the internal `AnalyserNode`, and
+     * cancel any pending setup callbacks. Call when the analyser is no longer
+     * needed to avoid memory leaks.
+     */
     destroy() {
         onAudioContextReady.clearByContext(this);
-        this._analyserTarget?.disconnect();
+        this._disconnectTap();
         this._analyser?.disconnect();
+        this._analyser = null;
+        this._source = null;
+    }
+    // -----------------------------------------------------------------------
+    // Private helpers
+    // -----------------------------------------------------------------------
+    _setupAnalyser(audioContext) {
+        const node = audioContext.createAnalyser();
+        node.fftSize = this._options.fftSize;
+        node.minDecibels = this._options.minDecibels;
+        node.maxDecibels = this._options.maxDecibels;
+        node.smoothingTimeConstant = this._options.smoothingTimeConstant;
+        this._analyser = node;
+        // If a source was set before the context was ready, connect it now.
+        if (this._source !== null) {
+            this._connectSource(this._source, audioContext);
+        }
+    }
+    _connectSource(source, audioContext) {
+        if (!this._analyser)
+            return;
+        const tap = this._resolveToAudioNode(source, audioContext);
+        if (!tap) {
+            // AudioBus/Sound/Music not ready — defer via their own onceSetup
+            this._deferConnectionViaBus(source);
+            return;
+        }
+        this._tapSource = tap;
+        tap.connect(this._analyser);
     }
-    setupWithAudioContext(audioContext) {
-        this._analyser = audioContext.createAnalyser();
-        this._analyser.fftSize = this._fftSize;
-        this._analyser.minDecibels = this._minDecibels;
-        this._analyser.maxDecibels = this._maxDecibels;
-        this._analyser.smoothingTimeConstant = this._smoothingTimeConstant;
+    _resolveToAudioNode(source, audioContext) {
+        if (source === null)
+            return null;
+        // MediaStream — detect by getTracks (duck-type, since AudioNode also doesn't exist in jsdom)
+        const asStream = source;
+        if (typeof asStream.getTracks === 'function') {
+            if (this._streamSource) {
+                this._streamSource.disconnect();
+                this._streamSource = null;
+            }
+            const msNode = audioContext.createMediaStreamSource(source);
+            this._streamSource = msNode;
+            return msNode;
+        }
+        // AudioBus — has _getOutputNode (checked first since bus nodes also have connect/disconnect)
+        const asBus = source;
+        if (typeof asBus._getOutputNode === 'function') {
+            return asBus._getOutputNode();
+        }
+        // Sound / Music — tap analyserTarget
+        const asMedia = source;
+        if ('analyserTarget' in asMedia) {
+            return asMedia.analyserTarget ?? null;
+        }
+        // Raw AudioNode — duck-type: has connect & disconnect
+        const asNode = source;
+        if (typeof asNode.connect === 'function' && typeof asNode.disconnect === 'function') {
+            return source;
+        }
+        return null;
+    }
+    _deferConnectionViaBus(source) {
+        // AudioBus exposes onceSetup
+        const asBus = source;
+        if (typeof asBus.onceSetup === 'function') {
+            asBus.onceSetup(() => {
+                if (this._source === source && this._analyser && isAudioContextReady()) {
+                    this._connectSource(source, getAudioContext());
+                }
+            });
+            return;
+        }
+        // Sound/Music — they set up when audioContext is ready (same signal)
+        onAudioContextReady.once(() => {
+            if (this._source === source && this._analyser && isAudioContextReady()) {
+                this._connectSource(source, getAudioContext());
+            }
+        }, this);
+    }
+    _disconnectTap() {
+        if (this._tapSource && this._analyser) {
+            try {
+                this._tapSource.disconnect(this._analyser);
+            }
+            catch {
+                // Ignore if already disconnected
+            }
+        }
+        this._tapSource = null;
+        // Clean up cached stream source
+        if (this._streamSource) {
+            this._streamSource.disconnect();
+            this._streamSource = null;
+        }
     }
 }
 

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

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

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

@@ -0,0 +1,82 @@
+import type { AudioFilter } from './AudioFilter';
+/** Construction options for {@link AudioBus}. */
+export interface AudioBusOptions {
+    parent?: AudioBus | null;
+    volume?: number;
+    muted?: boolean;
+    pan?: number;
+    filters?: ReadonlyArray<AudioFilter>;
+}
+/**
+ * Hierarchical mixer node in the engine's audio routing graph. Each bus
+ * owns three Web Audio nodes (input gain, optional filter chain, stereo
+ * pan, output gain) and routes its output into its parent's input — the
+ * root bus connects to the destination.
+ *
+ * The three engine-built-in busses are constructed by {@link AudioManager}:
+ * `master` (root), `music` (child of master), `sound` (child of master).
+ * User code creates additional busses via `new AudioBus(name, { parent })`
+ * and registers them via {@link AudioManager.registerBus}.
+ *
+ * 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.
+ *
+ * Setup is deferred until the global `AudioContext` is unlocked
+ * (browser autoplay policy); operations that need live nodes are no-ops
+ * until that happens.
+ */
+export declare class AudioBus {
+    readonly name: string;
+    private _parent;
+    private _volume;
+    private _muted;
+    private _pan;
+    private readonly _filters;
+    private _setup;
+    private _scheduledStopId;
+    constructor(name: string, options?: AudioBusOptions);
+    get parent(): AudioBus | null;
+    get volume(): number;
+    set volume(value: number);
+    get muted(): boolean;
+    set muted(value: boolean);
+    get pan(): number;
+    set pan(value: number);
+    get inputNode(): GainNode | null;
+    /**
+     * Append a filter 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.
+     */
+    addFilter(filter: AudioFilter): this;
+    /** Remove `filter` from the chain. No-op if not present. Caller still owns + must `destroy()` it. */
+    removeFilter(filter: AudioFilter): this;
+    /**
+     * Linearly ramp the output gain from 0 to the current volume over
+     * `durationMs`. Cancels any in-flight ramps on the same gain node.
+     */
+    fadeIn(durationMs: number): this;
+    /**
+     * Linearly ramp the output gain to 0 over `durationMs`. By default
+     * mutes the bus once the ramp completes (`stopAfter: true`); pass
+     * `stopAfter: false` to let the ramp finish silently while leaving
+     * `muted` unchanged.
+     */
+    fadeOut(durationMs: number, options?: {
+        stopAfter?: boolean;
+    }): this;
+    destroy(): void;
+    /** Internal: returns the input GainNode where children should connect. */
+    _getInputNode(): GainNode | null;
+    /** Internal: returns the output GainNode that connects upstream. */
+    _getOutputNode(): GainNode | null;
+    private _setupAudio;
+    private _connectUpstream;
+    /** Subscribe to the moment this bus's audio nodes are ready. Internal use. */
+    onceSetup(callback: () => void): void;
+    private _rebuildFilterChain;
+    private _applyVolume;
+    private _clearScheduledStop;
+}