@codexo/exojs 0.6.12 → 0.7.12

package/dist/esm/audio/audio-context.js

@@ -81,34 +81,77 @@ const onUserInteraction = () => {
         dispatchReadyIfRunning();
     });
 };
+/**
+ * Specialised {@link Signal} that fires once the global `AudioContext` reaches
+ * the `running` state. Subscribing via `add` or `once` automatically begins
+ * monitoring for user-interaction events that are required to resume a
+ * suspended context in browsers with autoplay policy.
+ *
+ * @internal
+ */
 class AudioContextReadySignal extends Signal {
+    /** Subscribe and immediately start interaction monitoring. */
     add(handler, context) {
         super.add(handler, context);
         ensureAudioContextReadyMonitoring();
         return this;
     }
+    /** Subscribe once and immediately start interaction monitoring. */
     once(handler, context) {
         super.once(handler, context);
         ensureAudioContextReadyMonitoring();
         return this;
     }
 }
+/**
+ * Signal that dispatches once the global `AudioContext` enters the `running`
+ * state. Handles browser autoplay-policy by listening for user-interaction
+ * events (`mousedown`, `touchstart`, `touchend`) and resuming a suspended
+ * context automatically.
+ *
+ * @example
+ * ```ts
+ * onAudioContextReady.once((ctx) => {
+ *   // safe to schedule audio nodes
+ * });
+ * ```
+ */
 const onAudioContextReady = new AudioContextReadySignal();
+/**
+ * Return the global singleton `AudioContext`, creating it if it does not yet
+ * exist. Also starts interaction-unlock monitoring so the context will resume
+ * on the first user gesture. Throws if `AudioContext` is not available in the
+ * current environment.
+ */
 const getAudioContext = () => {
     const audioContext = getOrCreateAudioContext();
     ensureAudioContextReadyMonitoring();
     return audioContext;
 };
+/**
+ * Return `true` if the global `AudioContext` has been created and is currently
+ * in the `running` state. Safe to call before `getAudioContext`; returns
+ * `false` if no context exists yet.
+ */
 const isAudioContextReady = () => {
     const audioContext = getExistingAudioContext();
     return audioContext !== null && audioContext.state === 'running';
 };
+/**
+ * Return the shared singleton `OfflineAudioContext` used for audio decoding.
+ * Its sample rate matches the live `AudioContext`. Creates the live context
+ * as a side effect if it does not exist yet.
+ */
 const getOfflineAudioContext = () => getOrCreateOfflineAudioContext();
-// Decodes audio data using a shared OfflineAudioContext whose sample rate is derived from
-// the live AudioContext. OfflineAudioContext.decodeAudioData is spec-compliant and works
-// in all major browsers. On some older mobile WebKit versions, decodeAudioData may only
-// succeed on a live (running) AudioContext — in those environments, sound loading may
-// fail with a browser-level error rather than an ExoJS-shaped error.
+/**
+ * Decode raw audio bytes into an `AudioBuffer` using the shared
+ * `OfflineAudioContext`. The context's sample rate is derived from the live
+ * `AudioContext`, ensuring decoded buffers are compatible with playback nodes.
+ *
+ * Note: on some older mobile WebKit versions `decodeAudioData` requires a
+ * running (live) context — decoding may fail with a browser-level error rather
+ * than an ExoJS-shaped error in those environments.
+ */
 const decodeAudioData = async (arrayBuffer) => getOrCreateOfflineAudioContext().decodeAudioData(arrayBuffer);
 
 export { decodeAudioData, getAudioContext, getOfflineAudioContext, isAudioContextReady, onAudioContextReady };

package/dist/esm/audio/audio-context.js.map

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

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

@@ -0,0 +1,19 @@
+import type { AbstractMedia } from './AbstractMedia';
+export interface CrossFadeOptions {
+    /** Stop the `from` media after fade completes. Default true. */
+    stopAfterFade?: boolean;
+    /** Auto-play `to` if currently paused. Default true. */
+    autoPlayTarget?: boolean;
+}
+/**
+ * Cross-fade from one media instance to another over `durationMs`.
+ *
+ * Calls `from.fadeOut(durationMs)` and `to.fadeIn(durationMs)` in parallel.
+ * If `to` is paused at call time and `autoPlayTarget !== false`, it will
+ * be played first (so the fade-in is audible).
+ *
+ * Returns a Promise that resolves after `durationMs` elapses (i.e., when
+ * the fade completes). Use `await crossFade(...)` for sequential music
+ * transitions, or fire-and-forget for non-blocking transitions.
+ */
+export declare function crossFade(from: AbstractMedia, to: AbstractMedia, durationMs: number, options?: CrossFadeOptions): Promise<void>;

package/dist/esm/audio/crossFade.js

@@ -0,0 +1,26 @@
+/**
+ * Cross-fade from one media instance to another over `durationMs`.
+ *
+ * Calls `from.fadeOut(durationMs)` and `to.fadeIn(durationMs)` in parallel.
+ * If `to` is paused at call time and `autoPlayTarget !== false`, it will
+ * be played first (so the fade-in is audible).
+ *
+ * Returns a Promise that resolves after `durationMs` elapses (i.e., when
+ * the fade completes). Use `await crossFade(...)` for sequential music
+ * transitions, or fire-and-forget for non-blocking transitions.
+ */
+async function crossFade(from, to, durationMs, options = {}) {
+    const stopAfterFade = options.stopAfterFade ?? true;
+    const autoPlayTarget = options.autoPlayTarget ?? true;
+    if (autoPlayTarget && to.paused) {
+        to.play();
+    }
+    from.fadeOut(durationMs, { stopAfter: stopAfterFade });
+    to.fadeIn(durationMs);
+    return new Promise((resolve) => {
+        setTimeout(resolve, Math.max(0, durationMs));
+    });
+}
+
+export { crossFade };
+//# sourceMappingURL=crossFade.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"crossFade.js","sources":["../../../../src/audio/crossFade.ts"],"sourcesContent":[null],"names":[],"mappings":"AASA;;;;;;;;;;AAUG;AACI,eAAe,SAAS,CAC3B,IAAmB,EACnB,EAAiB,EACjB,UAAkB,EAClB,OAAA,GAA4B,EAAE,EAAA;AAE9B,IAAA,MAAM,aAAa,GAAG,OAAO,CAAC,aAAa,IAAI,IAAI;AACnD,IAAA,MAAM,cAAc,GAAG,OAAO,CAAC,cAAc,IAAI,IAAI;AAErD,IAAA,IAAI,cAAc,IAAI,EAAE,CAAC,MAAM,EAAE;QAC7B,EAAE,CAAC,IAAI,EAAE;IACb;IAEA,IAAI,CAAC,OAAO,CAAC,UAAU,EAAE,EAAE,SAAS,EAAE,aAAa,EAAE,CAAC;AACtD,IAAA,EAAE,CAAC,MAAM,CAAC,UAAU,CAAC;AAErB,IAAA,OAAO,IAAI,OAAO,CAAO,CAAC,OAAO,KAAI;AACjC,QAAA,UAAU,CAAC,OAAO,EAAE,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,UAAU,CAAC,CAAC;AAChD,IAAA,CAAC,CAAC;AACN;;;;"}

package/dist/esm/audio/dsp/fft.d.ts

@@ -0,0 +1,22 @@
+/**
+ * In-place radix-2 Cooley-Tukey FFT.
+ *
+ * Operates on the supplied real/imag arrays (length must be a power of 2).
+ * After the call, real[i] and imag[i] hold the complex spectrum.
+ * A Hann window is applied to the input before the transform.
+ *
+ * These functions are duplicated (as plain JS) inside the beat-detector worklet
+ * source string because AudioWorklets cannot import modules.
+ */
+/** Apply a Hann window in-place to `real`. `imag` is zeroed. */
+export declare function hannWindow(real: Float32Array, imag: Float32Array): void;
+/**
+ * In-place FFT. `real` and `imag` must have the same length (power of 2).
+ * A Hann window is applied to `real` before the transform; `imag` is zeroed.
+ */
+export declare function fft(real: Float32Array, imag: Float32Array): void;
+/**
+ * Compute magnitude spectrum from complex FFT output.
+ * Returns a Float32Array of length `n/2` (positive frequencies only).
+ */
+export declare function magnitudeSpectrum(real: Float32Array, imag: Float32Array): Float32Array;

package/dist/esm/audio/dsp/mel.d.ts

@@ -0,0 +1,43 @@
+/**
+ * Mel-scale filterbank generator.
+ *
+ * Generates `numBands` triangular filters log-spaced from `fMin` to `fMax` Hz
+ * on the mel scale. Each filter is a typed array of weights for the FFT
+ * magnitude bins.
+ *
+ * These helpers are also inlined inside the beat-detector worklet source
+ * string (worklets cannot import modules).
+ */
+/** Convert Hz to mel. */
+export declare function hzToMel(hz: number): number;
+/** Convert mel to Hz. */
+export declare function melToHz(mel: number): number;
+export interface MelBand {
+    /** Index of the FFT bin where this filter starts (weight 0). */
+    readonly startBin: number;
+    /** Index of the peak FFT bin (weight 1). */
+    readonly peakBin: number;
+    /** Index of the FFT bin where this filter ends (weight 0). */
+    readonly endBin: number;
+    /** Pre-computed triangular weights, indexed from startBin..endBin (inclusive). */
+    readonly weights: Float32Array;
+}
+/**
+ * Build a mel filterbank.
+ *
+ * @param numBands   Number of mel bands (default 24).
+ * @param fMin       Lowest frequency in Hz (default 80).
+ * @param fMax       Highest frequency in Hz (default 8000).
+ * @param fftSize    Number of FFT points (e.g., 2048).
+ * @param sampleRate Audio sample rate in Hz (e.g., 48000).
+ */
+export declare function buildMelFilterbank(numBands: number, fMin: number, fMax: number, fftSize: number, sampleRate: number): Array<MelBand>;
+/**
+ * Compute mel band energies from a magnitude spectrum.
+ *
+ * @param mag     FFT magnitude spectrum (length = fftSize/2).
+ * @param bands   Filterbank from `buildMelFilterbank`.
+ * @param out     Optional pre-allocated output array of length `bands.length`.
+ * @returns       Log-compressed mel band energies.
+ */
+export declare function computeMelBands(mag: Float32Array, bands: Array<MelBand>, out?: Float32Array): Float32Array;

package/dist/esm/audio/dsp/tempogram.d.ts

@@ -0,0 +1,51 @@
+/**
+ * Autocorrelation-based tempogram.
+ *
+ * Given a novelty (onset-strength) curve sampled at rate `hopRate = sampleRate / hopSize`,
+ * this module computes the autocorrelation function (ACF) over a sliding window
+ * and returns the top tempo candidates.
+ *
+ * These helpers are also inlined inside the beat-detector worklet source string
+ * (worklets cannot import modules).
+ */
+export interface TempoCandidateResult {
+    /** BPM value. */
+    bpm: number;
+    /** Normalised peak score (0..1). */
+    score: number;
+    /** ACF lag in hops that produced this peak. */
+    lag: number;
+}
+/**
+ * Compute the normalised autocorrelation function over a novelty curve.
+ *
+ * @param flux       Recent novelty values (ring-buffer contents, oldest first).
+ * @param minLag     Minimum lag in samples (inclusive).
+ * @param maxLag     Maximum lag in samples (inclusive).
+ * @returns          ACF array indexed by lag (index 0 = lag minLag).
+ */
+export declare function computeAcf(flux: Float32Array, minLag: number, maxLag: number): Float32Array;
+/**
+ * Find the top-K peaks in the ACF and convert lags to BPM candidates.
+ *
+ * @param acf        Normalised ACF from `computeACF`.
+ * @param minLag     The lag (in hops) corresponding to acf[0].
+ * @param hopSize    Number of audio samples per hop.
+ * @param sampleRate Audio sample rate in Hz.
+ * @param topK       Number of peaks to return (default 3).
+ * @returns          Up to `topK` tempo candidates sorted by score descending.
+ */
+export declare function findTempoPeaks(acf: Float32Array, minLag: number, hopSize: number, sampleRate: number, topK?: number): Array<TempoCandidateResult>;
+/**
+ * Apply hysteresis to tempo candidate selection.
+ *
+ * Prevents rapid switching between tempo estimates:
+ * - Only switches to a new best if its score is > currentBestScore * 1.15.
+ * - Octave-related candidates (2x or 0.5x) require a score > 1.5x to switch.
+ *
+ * @param candidates   Sorted candidates from `findTempoPeaks`.
+ * @param currentBpm   Currently tracked BPM.
+ * @param currentScore Currently tracked best score.
+ * @returns            The selected best BPM.
+ */
+export declare function applyTempoHysteresis(candidates: Array<TempoCandidateResult>, currentBpm: number, currentScore: number): number;

package/dist/esm/audio/filters/ChorusFilter.d.ts

@@ -0,0 +1,52 @@
+import { AudioFilter } from '../AudioFilter';
+/** Construction options for {@link ChorusFilter}. */
+export interface ChorusFilterOptions {
+    /** Base delay in ms. Typical 15-30ms. Default 25. */
+    delayMs?: number;
+    /** Modulation depth in ms (peak deviation from base). Default 5. */
+    depthMs?: number;
+    /** LFO rate in Hz. Typical 0.1-5Hz for chorus, 5-15Hz for vibrato. Default 1.5. */
+    rateHz?: number;
+    /** Dry/wet mix, 0..1. Default 0.5 (equal mix). */
+    wet?: number;
+}
+/**
+ * Chorus effect using native WebAudio nodes (no worklet required).
+ *
+ * The signal splits into a dry path and a wet path. The wet path passes
+ * through a DelayNode whose delay time is modulated by a sine-wave LFO,
+ * producing the characteristic pitch-wobble / thickening of chorus.
+ *
+ * Node graph:
+ * ```
+ * inputGain ┬── dryGain ────────────────┐
+ *           │                            ├── outputGain
+ *           └── delayNode ── wetGain ────┘
+ *
+ * lfoOscillator ── lfoGain (depth) ── delayNode.delayTime
+ * ```
+ */
+export declare class ChorusFilter extends AudioFilter {
+    private _nodes;
+    private _delayMs;
+    private _depthMs;
+    private _rateHz;
+    private _wet;
+    constructor(options?: ChorusFilterOptions);
+    get inputNode(): AudioNode;
+    get outputNode(): AudioNode;
+    /** Base delay time in milliseconds. Default 25. */
+    get delayMs(): number;
+    set delayMs(value: number);
+    /** LFO modulation depth in milliseconds (peak deviation from base delay). Default 5. */
+    get depthMs(): number;
+    set depthMs(value: number);
+    /** LFO oscillation rate in Hz. Typical chorus range is 0.1–5 Hz; 5–15 Hz produces a vibrato effect. Default 1.5. */
+    get rateHz(): number;
+    set rateHz(value: number);
+    /** Wet (modulated) mix level, 0..1. The dry level is automatically `1 - wet`. Default 0.5. */
+    get wet(): number;
+    set wet(value: number);
+    destroy(): void;
+    private _setupNodes;
+}

package/dist/esm/audio/filters/ChorusFilter.js

@@ -0,0 +1,143 @@
+import { isAudioContextReady, getAudioContext, onAudioContextReady } from '../audio-context.js';
+import { AudioFilter } from '../AudioFilter.js';
+
+/**
+ * Chorus effect using native WebAudio nodes (no worklet required).
+ *
+ * The signal splits into a dry path and a wet path. The wet path passes
+ * through a DelayNode whose delay time is modulated by a sine-wave LFO,
+ * producing the characteristic pitch-wobble / thickening of chorus.
+ *
+ * Node graph:
+ * ```
+ * inputGain ┬── dryGain ────────────────┐
+ *           │                            ├── outputGain
+ *           └── delayNode ── wetGain ────┘
+ *
+ * lfoOscillator ── lfoGain (depth) ── delayNode.delayTime
+ * ```
+ */
+class ChorusFilter extends AudioFilter {
+    _nodes = null;
+    _delayMs;
+    _depthMs;
+    _rateHz;
+    _wet;
+    constructor(options = {}) {
+        super();
+        this._delayMs = Math.max(0, options.delayMs ?? 25);
+        this._depthMs = Math.max(0, options.depthMs ?? 5);
+        this._rateHz = Math.max(0, options.rateHz ?? 1.5);
+        this._wet = Math.max(0, Math.min(1, options.wet ?? 0.5));
+        if (isAudioContextReady()) {
+            this._setupNodes(getAudioContext());
+        }
+        else {
+            onAudioContextReady.once(this._setupNodes, this);
+        }
+    }
+    get inputNode() {
+        if (!this._nodes)
+            throw new Error('ChorusFilter not yet initialized.');
+        return this._nodes.inputGain;
+    }
+    get outputNode() {
+        if (!this._nodes)
+            throw new Error('ChorusFilter not yet initialized.');
+        return this._nodes.outputGain;
+    }
+    // -------------------------------------------------------------------------
+    // Getters / setters
+    // -------------------------------------------------------------------------
+    /** Base delay time in milliseconds. Default 25. */
+    get delayMs() { return this._delayMs; }
+    set delayMs(value) {
+        this._delayMs = Math.max(0, value);
+        if (this._nodes) {
+            this._nodes.delayNode.delayTime.setTargetAtTime(this._delayMs / 1000, this._nodes.delayNode.context.currentTime, 0.01);
+        }
+    }
+    /** LFO modulation depth in milliseconds (peak deviation from base delay). Default 5. */
+    get depthMs() { return this._depthMs; }
+    set depthMs(value) {
+        this._depthMs = Math.max(0, value);
+        if (this._nodes) {
+            this._nodes.lfoGain.gain.setTargetAtTime(this._depthMs / 1000, this._nodes.lfoGain.context.currentTime, 0.01);
+        }
+    }
+    /** LFO oscillation rate in Hz. Typical chorus range is 0.1–5 Hz; 5–15 Hz produces a vibrato effect. Default 1.5. */
+    get rateHz() { return this._rateHz; }
+    set rateHz(value) {
+        this._rateHz = Math.max(0, value);
+        if (this._nodes) {
+            this._nodes.lfoOscillator.frequency.setTargetAtTime(this._rateHz, this._nodes.inputGain.context.currentTime, 0.01);
+        }
+    }
+    /** Wet (modulated) mix level, 0..1. The dry level is automatically `1 - wet`. Default 0.5. */
+    get wet() { return this._wet; }
+    set wet(value) {
+        this._wet = Math.max(0, Math.min(1, value));
+        if (this._nodes) {
+            const ctx = this._nodes.wetGain.context;
+            this._nodes.wetGain.gain.setTargetAtTime(this._wet, ctx.currentTime, 0.01);
+            this._nodes.dryGain.gain.setTargetAtTime(1 - this._wet, ctx.currentTime, 0.01);
+        }
+    }
+    // -------------------------------------------------------------------------
+    // Lifecycle
+    // -------------------------------------------------------------------------
+    destroy() {
+        onAudioContextReady.clearByContext(this);
+        if (this._nodes) {
+            this._nodes.lfoOscillator.stop();
+            this._nodes.lfoOscillator.disconnect();
+            this._nodes.lfoGain.disconnect();
+            this._nodes.delayNode.disconnect();
+            this._nodes.dryGain.disconnect();
+            this._nodes.wetGain.disconnect();
+            this._nodes.inputGain.disconnect();
+            this._nodes.outputGain.disconnect();
+            this._nodes = null;
+        }
+    }
+    // -------------------------------------------------------------------------
+    // Private
+    // -------------------------------------------------------------------------
+    _setupNodes(ctx) {
+        const inputGain = ctx.createGain();
+        const outputGain = ctx.createGain();
+        const dryGain = ctx.createGain();
+        const wetGain = ctx.createGain();
+        // maxDelayTime must be larger than base + peak depth, with a small buffer.
+        const maxDelay = (this._delayMs + this._depthMs) / 1000 + 0.05;
+        const delayNode = ctx.createDelay(maxDelay);
+        const lfoGain = ctx.createGain();
+        // Initial values
+        inputGain.gain.setValueAtTime(1, ctx.currentTime);
+        outputGain.gain.setValueAtTime(1, ctx.currentTime);
+        dryGain.gain.setValueAtTime(1 - this._wet, ctx.currentTime);
+        wetGain.gain.setValueAtTime(this._wet, ctx.currentTime);
+        delayNode.delayTime.setValueAtTime(this._delayMs / 1000, ctx.currentTime);
+        lfoGain.gain.setValueAtTime(this._depthMs / 1000, ctx.currentTime);
+        // LFO
+        const lfoOscillator = ctx.createOscillator();
+        lfoOscillator.type = 'sine';
+        lfoOscillator.frequency.value = this._rateHz;
+        // Wiring
+        // LFO → lfoGain → delayNode.delayTime (AudioParam)
+        lfoOscillator.connect(lfoGain);
+        lfoGain.connect(delayNode.delayTime);
+        // Dry path: inputGain → dryGain → outputGain
+        inputGain.connect(dryGain);
+        dryGain.connect(outputGain);
+        // Wet path: inputGain → delayNode → wetGain → outputGain
+        inputGain.connect(delayNode);
+        delayNode.connect(wetGain);
+        wetGain.connect(outputGain);
+        lfoOscillator.start();
+        this._nodes = { inputGain, outputGain, dryGain, wetGain, delayNode, lfoOscillator, lfoGain };
+    }
+}
+
+export { ChorusFilter };
+//# sourceMappingURL=ChorusFilter.js.map

package/dist/esm/audio/filters/ChorusFilter.js.map

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

package/dist/esm/audio/filters/CompressorFilter.d.ts

@@ -0,0 +1,43 @@
+import { AudioFilter } from '../AudioFilter';
+/** Construction options for {@link CompressorFilter}. All values are clamped to their valid ranges on assignment. */
+export interface CompressorFilterOptions {
+    threshold?: number;
+    knee?: number;
+    ratio?: number;
+    attack?: number;
+    release?: number;
+}
+/**
+ * Dynamic-range compressor backed by a Web Audio `DynamicsCompressorNode`.
+ * Reduces the volume of loud signals above a threshold, evening out the
+ * perceived loudness of a mix. All parameter changes are applied with a short
+ * smoothing ramp so they are artifact-free during playback.
+ */
+export declare class CompressorFilter extends AudioFilter {
+    private _node;
+    private _threshold;
+    private _knee;
+    private _ratio;
+    private _attack;
+    private _release;
+    constructor(options?: CompressorFilterOptions);
+    get inputNode(): AudioNode;
+    get outputNode(): AudioNode;
+    /** Level above which compression begins, in dBFS. Range −100..0, default −24. */
+    get threshold(): number;
+    set threshold(value: number);
+    /** Width in dB of the transition region around the threshold (soft knee). Range 0..40, default 30. */
+    get knee(): number;
+    set knee(value: number);
+    /** Input-to-output dB ratio above the threshold. Range 1..20, default 12. */
+    get ratio(): number;
+    set ratio(value: number);
+    /** Time in seconds for the compressor to engage after the signal exceeds the threshold. Range 0..1, default 0.003. */
+    get attack(): number;
+    set attack(value: number);
+    /** Time in seconds for the compressor to disengage after the signal drops below the threshold. Range 0..1, default 0.25. */
+    get release(): number;
+    set release(value: number);
+    destroy(): void;
+    private _setup;
+}

package/dist/esm/audio/filters/CompressorFilter.js

@@ -0,0 +1,108 @@
+import { isAudioContextReady, getAudioContext, onAudioContextReady } from '../audio-context.js';
+import { AudioFilter } from '../AudioFilter.js';
+
+/**
+ * Dynamic-range compressor backed by a Web Audio `DynamicsCompressorNode`.
+ * Reduces the volume of loud signals above a threshold, evening out the
+ * perceived loudness of a mix. All parameter changes are applied with a short
+ * smoothing ramp so they are artifact-free during playback.
+ */
+class CompressorFilter extends AudioFilter {
+    _node = null;
+    _threshold;
+    _knee;
+    _ratio;
+    _attack;
+    _release;
+    constructor(options = {}) {
+        super();
+        this._threshold = Math.max(-100, Math.min(0, options.threshold ?? -24));
+        this._knee = Math.max(0, Math.min(40, options.knee ?? 30));
+        this._ratio = Math.max(1, Math.min(20, options.ratio ?? 12));
+        this._attack = Math.max(0, Math.min(1, options.attack ?? 0.003));
+        this._release = Math.max(0, Math.min(1, options.release ?? 0.25));
+        if (isAudioContextReady()) {
+            this._setup(getAudioContext());
+        }
+        else {
+            onAudioContextReady.once(this._setup, this);
+        }
+    }
+    get inputNode() {
+        if (!this._node)
+            throw new Error('CompressorFilter not yet initialized.');
+        return this._node;
+    }
+    get outputNode() {
+        if (!this._node)
+            throw new Error('CompressorFilter not yet initialized.');
+        return this._node;
+    }
+    /** Level above which compression begins, in dBFS. Range −100..0, default −24. */
+    get threshold() {
+        return this._threshold;
+    }
+    set threshold(value) {
+        this._threshold = Math.max(-100, Math.min(0, value));
+        if (this._node) {
+            this._node.threshold.setTargetAtTime(this._threshold, this._node.context.currentTime, 0.01);
+        }
+    }
+    /** Width in dB of the transition region around the threshold (soft knee). Range 0..40, default 30. */
+    get knee() {
+        return this._knee;
+    }
+    set knee(value) {
+        this._knee = Math.max(0, Math.min(40, value));
+        if (this._node) {
+            this._node.knee.setTargetAtTime(this._knee, this._node.context.currentTime, 0.01);
+        }
+    }
+    /** Input-to-output dB ratio above the threshold. Range 1..20, default 12. */
+    get ratio() {
+        return this._ratio;
+    }
+    set ratio(value) {
+        this._ratio = Math.max(1, Math.min(20, value));
+        if (this._node) {
+            this._node.ratio.setTargetAtTime(this._ratio, this._node.context.currentTime, 0.01);
+        }
+    }
+    /** Time in seconds for the compressor to engage after the signal exceeds the threshold. Range 0..1, default 0.003. */
+    get attack() {
+        return this._attack;
+    }
+    set attack(value) {
+        this._attack = Math.max(0, Math.min(1, value));
+        if (this._node) {
+            this._node.attack.setTargetAtTime(this._attack, this._node.context.currentTime, 0.01);
+        }
+    }
+    /** Time in seconds for the compressor to disengage after the signal drops below the threshold. Range 0..1, default 0.25. */
+    get release() {
+        return this._release;
+    }
+    set release(value) {
+        this._release = Math.max(0, Math.min(1, value));
+        if (this._node) {
+            this._node.release.setTargetAtTime(this._release, this._node.context.currentTime, 0.01);
+        }
+    }
+    destroy() {
+        onAudioContextReady.clearByContext(this);
+        this._node?.disconnect();
+        this._node = null;
+    }
+    _setup(ctx) {
+        const node = ctx.createDynamicsCompressor();
+        node.threshold.setValueAtTime(this._threshold, ctx.currentTime);
+        node.knee.setValueAtTime(this._knee, ctx.currentTime);
+        node.ratio.setValueAtTime(this._ratio, ctx.currentTime);
+        node.attack.setValueAtTime(this._attack, ctx.currentTime);
+        node.release.setValueAtTime(this._release, ctx.currentTime);
+        this._node = node;
+    }
+}
+
+export { CompressorFilter };
+//# sourceMappingURL=CompressorFilter.js.map

package/dist/esm/audio/filters/CompressorFilter.js.map

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