@aura3d/audio 3.0.1 → 4.0.0

package/dist/game-sound/LoopHandle.js

@@ -0,0 +1,78 @@
+/**
+ * game-sound/LoopHandle.ts — live loop control (§6.8).
+ *
+ * `setRate`/`setGain` use `AudioParam.setTargetAtTime` (τ = rampMs/3 per
+ * AudioSource.setPlaybackRate convention). The handle fronts a running
+ * `VoiceRecord` (or several, for engine layers — see EngineLoop.ts).
+ */
+import { dbToGain } from "./types.js";
+export class LoopHandleImpl {
+    ctx;
+    voice;
+    spatial;
+    stopVoice;
+    stopped = false;
+    constructor(ctx, voice, spatial, stopVoice) {
+        this.ctx = ctx;
+        this.voice = voice;
+        this.spatial = spatial;
+        this.stopVoice = stopVoice;
+    }
+    get id() {
+        return this.voice.id;
+    }
+    get ended() {
+        return this.stopped || this.voice.ended;
+    }
+    stop(fadeMs = 0) {
+        if (this.stopped)
+            return;
+        this.stopped = true;
+        const gain = this.voice.gain;
+        if (fadeMs > 0 && gain.gain?.setTargetAtTime) {
+            gain.gain.setTargetAtTime(0, this.ctx.currentTime, fadeMs / 3000);
+            const voice = this.voice;
+            const release = () => this.stopVoice(voice);
+            setTimeout(release, fadeMs + 30).unref?.();
+        }
+        else {
+            this.stopVoice(this.voice);
+        }
+    }
+    setPosition(p) {
+        this.spatial?.setPosition(p);
+    }
+    setPositionVelocity(p, v) {
+        this.spatial?.setPosition(p);
+        if (v)
+            this.spatial?.setVelocity(v);
+    }
+    setOcclusion(amount01) {
+        this.spatial?.setOcclusion(amount01);
+    }
+    setRate(rate, rampMs = 0) {
+        const param = this.voice.source.playbackRate;
+        if (!param)
+            return;
+        const next = Math.max(0.0625, rate);
+        if (rampMs > 0 && param.setTargetAtTime) {
+            param.setTargetAtTime(next, this.ctx.currentTime, rampMs / 3000);
+        }
+        else {
+            param.value = next;
+        }
+    }
+    setGain(gainDb, rampMs = 0) {
+        const linear = dbToGain(gainDb);
+        const gain = this.voice.gain;
+        if (!gain.gain)
+            return;
+        if (rampMs > 0 && gain.gain.setTargetAtTime) {
+            gain.gain.setTargetAtTime(Math.min(4, Math.max(0, linear)), this.ctx.currentTime, rampMs / 3000);
+        }
+        else {
+            gain.gain.value = Math.min(4, Math.max(0, linear));
+        }
+    }
+}
+//# sourceMappingURL=LoopHandle.js.map

package/dist/game-sound/LoopHandle.js.map

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

package/dist/game-sound/MasterChain.d.ts

@@ -0,0 +1,57 @@
+/**
+ * game-sound/MasterChain.ts — §6.8 master bus chain.
+ *
+ *   master gain (headroom) → [glue, opt-in] → limiter → makeup trim → safety clipper → destination
+ *
+ * Chrome's DynamicsCompressorNode always applies automatic makeup gain
+ * (≈ 0.6 × the full-scale gain reduction). The old default chain (glue −18 dB
+ * 3:1 + limiter −6 dB 12:1) therefore lifted quiet material by +8.3 dB and
+ * pushed −12 dBFS by +6.1 dB (L4 OfflineAudioContext sweep): beds, hums and
+ * tails came up to meet the hits — a squashed, loud, buzzing mix. The default
+ * is now a hard-knee −1 dBFS 20:1 limiter followed by a trim that cancels its
+ * makeup exactly, so the chain is level-transparent below the ceiling.
+ *
+ * The two `DynamicsCompressorNode`s are NOT brick-wall limiting (max ratio
+ * 20, finite attack): 32 simultaneous 0 dBFS hits still overshoot ~1.5 dB.
+ * The `WaveShaperNode` safety clip (1,024-point curve, linear below −6 dBFS,
+ * tanh knee to ±0.966 ≈ −0.3 dBFS) is the guaranteed ceiling — inaudible at
+ * normal levels.
+ */
+import type { SoundGraphContext, SoundNodeLike } from "./types.js";
+export interface MasterChainOptions {
+    /** Glue compressor stage (−18 dB, 3:1). Off by default: its makeup gain lifts quiet material. */
+    readonly glue?: boolean;
+    /** Limiter threshold, default −1 dBFS. */
+    readonly limiterCeilingDb?: number;
+    /**
+     * Fixed headroom gain in front of the dynamics stages (default
+     * MASTER_HEADROOM). Game sample libraries are normalised to ~−1 dBFS peaks;
+     * at unity, a few overlapping hits drive the limiter into audible pumping and
+     * the safety clipper into distortion. The master volume slider scales on top.
+     */
+    readonly headroom?: number;
+}
+/** Default master headroom: −4.4 dB (0.6 linear). */
+export declare const MASTER_HEADROOM = 0.6;
+export declare const LIMITER_CEILING_DB = -1;
+export declare const LIMITER_RATIO = 20;
+/**
+ * Makeup gain (dB) Chrome/WebKit's DynamicsCompressor adds for a hard-knee
+ * curve: 0.6 × the reduction a 0 dBFS input gets, i.e. 0.6·|T|·(1 − 1/R).
+ * L4 sweep: T −1, R 20 → measured +0.57 dB, formula 0.57.
+ */
+export declare function limiterMakeupDb(thresholdDb: number, ratio: number): number;
+export interface MasterChain {
+    readonly input: AudioNode;
+    readonly output: SoundNodeLike;
+    readonly limiterEngaged: boolean;
+    /** Human-readable stage list for `proof()`. */
+    readonly stages: readonly string[];
+    /** Master volume 0..1 (scaled by the fixed headroom). */
+    setMasterGain(volume01: number): void;
+    dispose(): void;
+}
+/** Safety-clip curve: linear to −6 dBFS, tanh knee, endpoints ±0.966. */
+export declare function safetyClipCurve(size?: number): Float32Array;
+export declare function createMasterChain(ctx: SoundGraphContext, destination: AudioNode, options?: MasterChainOptions): MasterChain;
+//# sourceMappingURL=MasterChain.d.ts.map

package/dist/game-sound/MasterChain.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"MasterChain.d.ts","sourceRoot":"","sources":["../../../../../packages/audio/src/game-sound/MasterChain.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAEH,OAAO,KAAK,EAAE,iBAAiB,EAAE,aAAa,EAAE,MAAM,SAAS,CAAC;AAEhE,MAAM,WAAW,kBAAkB;IACjC,iGAAiG;IACjG,QAAQ,CAAC,IAAI,CAAC,EAAE,OAAO,CAAC;IACxB,0CAA0C;IAC1C,QAAQ,CAAC,gBAAgB,CAAC,EAAE,MAAM,CAAC;IACnC;;;;;OAKG;IACH,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;CAC5B;AAED,qDAAqD;AACrD,eAAO,MAAM,eAAe,MAAM,CAAC;AACnC,eAAO,MAAM,kBAAkB,KAAK,CAAC;AACrC,eAAO,MAAM,aAAa,KAAK,CAAC;AAEhC;;;;GAIG;AACH,wBAAgB,eAAe,CAAC,WAAW,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,MAAM,CAE1E;AAED,MAAM,WAAW,WAAW;IAC1B,QAAQ,CAAC,KAAK,EAAE,SAAS,CAAC;IAC1B,QAAQ,CAAC,MAAM,EAAE,aAAa,CAAC;IAC/B,QAAQ,CAAC,cAAc,EAAE,OAAO,CAAC;IACjC,+CAA+C;IAC/C,QAAQ,CAAC,MAAM,EAAE,SAAS,MAAM,EAAE,CAAC;IACnC,yDAAyD;IACzD,aAAa,CAAC,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;IACtC,OAAO,IAAI,IAAI,CAAC;CACjB;AAED,yEAAyE;AACzE,wBAAgB,eAAe,CAAC,IAAI,SAAO,GAAG,YAAY,CAczD;AAeD,wBAAgB,iBAAiB,CAC/B,GAAG,EAAE,iBAAiB,EACtB,WAAW,EAAE,SAAS,EACtB,OAAO,GAAE,kBAAuB,GAC/B,WAAW,CAoGb"}

package/dist/game-sound/MasterChain.js

@@ -0,0 +1,144 @@
+/**
+ * game-sound/MasterChain.ts — §6.8 master bus chain.
+ *
+ *   master gain (headroom) → [glue, opt-in] → limiter → makeup trim → safety clipper → destination
+ *
+ * Chrome's DynamicsCompressorNode always applies automatic makeup gain
+ * (≈ 0.6 × the full-scale gain reduction). The old default chain (glue −18 dB
+ * 3:1 + limiter −6 dB 12:1) therefore lifted quiet material by +8.3 dB and
+ * pushed −12 dBFS by +6.1 dB (L4 OfflineAudioContext sweep): beds, hums and
+ * tails came up to meet the hits — a squashed, loud, buzzing mix. The default
+ * is now a hard-knee −1 dBFS 20:1 limiter followed by a trim that cancels its
+ * makeup exactly, so the chain is level-transparent below the ceiling.
+ *
+ * The two `DynamicsCompressorNode`s are NOT brick-wall limiting (max ratio
+ * 20, finite attack): 32 simultaneous 0 dBFS hits still overshoot ~1.5 dB.
+ * The `WaveShaperNode` safety clip (1,024-point curve, linear below −6 dBFS,
+ * tanh knee to ±0.966 ≈ −0.3 dBFS) is the guaranteed ceiling — inaudible at
+ * normal levels.
+ */
+/** Default master headroom: −4.4 dB (0.6 linear). */
+export const MASTER_HEADROOM = 0.6;
+export const LIMITER_CEILING_DB = -1;
+export const LIMITER_RATIO = 20;
+/**
+ * Makeup gain (dB) Chrome/WebKit's DynamicsCompressor adds for a hard-knee
+ * curve: 0.6 × the reduction a 0 dBFS input gets, i.e. 0.6·|T|·(1 − 1/R).
+ * L4 sweep: T −1, R 20 → measured +0.57 dB, formula 0.57.
+ */
+export function limiterMakeupDb(thresholdDb, ratio) {
+    return 0.6 * Math.abs(thresholdDb) * (1 - 1 / ratio);
+}
+/** Safety-clip curve: linear to −6 dBFS, tanh knee, endpoints ±0.966. */
+export function safetyClipCurve(size = 1024) {
+    const curve = new Float32Array(size);
+    const knee = 0.5; // −6 dBFS
+    const peak = 0.966;
+    const tanhKnee = Math.tanh((1 - knee) * 2);
+    for (let i = 0; i < size; i++) {
+        const x = (i / (size - 1)) * 2 - 1;
+        const ax = Math.abs(x);
+        curve[i] =
+            ax <= knee
+                ? x
+                : Math.sign(x) * (knee + ((ax - knee) / (1 - knee)) * tanhKnee * (peak - knee) / tanhKnee);
+    }
+    return curve;
+}
+export function createMasterChain(ctx, destination, options = {}) {
+    const ceiling = options.limiterCeilingDb ?? LIMITER_CEILING_DB;
+    const glueOn = options.glue ?? false;
+    const headroom = Math.max(0, Math.min(1, options.headroom ?? MASTER_HEADROOM));
+    const input = ctx.createGain();
+    input.gain.value = headroom;
+    const stages = ["masterGain"];
+    const chain = [];
+    let limiter;
+    let shaper;
+    if (ctx.createDynamicsCompressor && glueOn) {
+        const glue = ctx.createDynamicsCompressor();
+        glue.threshold.value = -18;
+        glue.knee.value = 6;
+        glue.ratio.value = 3;
+        glue.attack.value = 0.005;
+        glue.release.value = 0.25;
+        chain.push(glue);
+        stages.push("glue(-18dB)");
+    }
+    if (ctx.createDynamicsCompressor) {
+        limiter = ctx.createDynamicsCompressor();
+        // Hard-knee peak limiter; the safety clip below is the guaranteed ceiling.
+        limiter.threshold.value = ceiling;
+        limiter.knee.value = 0;
+        limiter.ratio.value = LIMITER_RATIO;
+        limiter.attack.value = 0.001;
+        limiter.release.value = 0.1;
+        chain.push(limiter);
+        stages.push(`limiter(${ceiling}dB)`);
+        // Cancel the compressor's automatic makeup gain (exact for knee 0).
+        const trim = ctx.createGain();
+        trim.gain.value = Math.pow(10, -limiterMakeupDb(ceiling, LIMITER_RATIO) / 20);
+        chain.push(trim);
+        stages.push("makeupTrim");
+    }
+    if (ctx.createWaveShaper) {
+        shaper = ctx.createWaveShaper();
+        shaper.curve = safetyClipCurve();
+        shaper.oversample = "none";
+        chain.push(shaper);
+        stages.push("safetyClip(±0.966)");
+    }
+    // Wire input → chain → destination.
+    let head = input;
+    for (const node of chain) {
+        head.connect(node);
+        head = node;
+    }
+    head.connect(destination);
+    let limiterEngaged = false;
+    // `reduction` is read off live compressor state in proof paths; fakes may
+    // not expose it, so engagement is computed from the signal instead.
+    const reductionProbe = limiter;
+    const limiterActive = () => reductionProbe?.reduction !== undefined && reductionProbe.reduction < 0;
+    // Engaged flag is sticky within a proof read — set when the limiter reports
+    // negative gain reduction at least once.
+    const pollLimiter = () => {
+        if (limiterActive())
+            limiterEngaged = true;
+    };
+    if (typeof setInterval === "function" && reductionProbe?.reduction !== undefined) {
+        const timer = setInterval(pollLimiter, 500);
+        if (typeof timer === "object" && timer !== null && "unref" in timer) {
+            timer.unref();
+        }
+    }
+    return {
+        input,
+        output: head,
+        stages,
+        get limiterEngaged() {
+            pollLimiter();
+            return limiterEngaged || limiterActive();
+        },
+        setMasterGain(volume01) {
+            input.gain.value = Math.max(0, Math.min(1, volume01)) * headroom;
+        },
+        dispose() {
+            for (const node of chain) {
+                try {
+                    node.disconnect();
+                }
+                catch {
+                    /* already disconnected */
+                }
+            }
+            try {
+                input.disconnect();
+            }
+            catch {
+                /* noop */
+            }
+        }
+    };
+}
+//# sourceMappingURL=MasterChain.js.map

package/dist/game-sound/MasterChain.js.map

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

package/dist/game-sound/MusicController.d.ts

@@ -0,0 +1,59 @@
+/**
+ * game-sound/MusicController.ts — §6.8 music.
+ *
+ * Single-stem tracks stream through one `MediaElementAudioSourceNode` (no
+ * decode). Multi-stem tracks are decoded buffers started on ONE shared
+ * `start(when)` timestamp — separate media elements cannot stay sample-
+ * aligned. Crossfade default 1.5 s; `setIntensity` drives stem gains;
+ * `stinger` quantizes to beat/bar from `bpm` + the track's start time;
+ * pause duck −9 dB + lowpass 1.2 kHz.
+ */
+import type { SoundGraphContext, SoundNodeLike } from "./types.js";
+export interface MusicTrackSpec {
+    readonly stems: readonly {
+        readonly url: string;
+        readonly id?: string;
+    }[];
+    readonly bpm?: number;
+    readonly loop?: boolean;
+}
+export interface MusicControllerOptions {
+    readonly ctx: SoundGraphContext;
+    readonly output: SoundNodeLike;
+    readonly tracks: Readonly<Record<string, MusicTrackSpec>>;
+    readonly bufferFor: (url: string) => AudioBuffer | undefined;
+    /** Media-element factory (injectable for tests). */
+    readonly createMediaElement?: (url: string) => HTMLMediaElement;
+    /** Cue player injected by the engine so `stinger` can schedule cues. */
+    readonly playCue?: (cue: string) => void;
+}
+export declare class MusicControllerImpl {
+    private readonly o;
+    private active?;
+    private intensity;
+    private ducked;
+    private duckFilter?;
+    private disposed;
+    constructor(o: MusicControllerOptions);
+    play(track: string, options?: {
+        crossfadeMs?: number;
+    }): void;
+    setIntensity(level01: number): void;
+    /** Beat/bar-quantized stinger scheduling from the playing track's start. */
+    quantizeDelay(quantize: "beat" | "bar" | "none" | undefined): number;
+    stingerDelay(quantize?: "beat" | "bar" | "none"): number;
+    /** C-25: schedule a cue stinger quantized to the playing track's beat/bar. */
+    stinger(cue: string, o?: {
+        quantize?: "beat" | "bar" | "none";
+    }): void;
+    /** Pause duck: −9 dB + lowpass 1.2 kHz until cleared. */
+    setDucked(ducked: boolean): void;
+    stop(fadeMs?: number): void;
+    get playing(): string | undefined;
+    dispose(): void;
+    private startTrack;
+    private stemLevel;
+    private applyStemGains;
+    private stopTrack;
+}
+//# sourceMappingURL=MusicController.d.ts.map

package/dist/game-sound/MusicController.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"MusicController.d.ts","sourceRoot":"","sources":["../../../../../packages/audio/src/game-sound/MusicController.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAGH,OAAO,KAAK,EAAmB,iBAAiB,EAAE,aAAa,EAAmB,MAAM,SAAS,CAAC;AAElG,MAAM,WAAW,cAAc;IAC7B,QAAQ,CAAC,KAAK,EAAE,SAAS;QAAE,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,EAAE,CAAC,EAAE,MAAM,CAAA;KAAE,EAAE,CAAC;IAC1E,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,IAAI,CAAC,EAAE,OAAO,CAAC;CACzB;AAED,MAAM,WAAW,sBAAsB;IACrC,QAAQ,CAAC,GAAG,EAAE,iBAAiB,CAAC;IAChC,QAAQ,CAAC,MAAM,EAAE,aAAa,CAAC;IAC/B,QAAQ,CAAC,MAAM,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,cAAc,CAAC,CAAC,CAAC;IAC1D,QAAQ,CAAC,SAAS,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,WAAW,GAAG,SAAS,CAAC;IAC7D,oDAAoD;IACpD,QAAQ,CAAC,kBAAkB,CAAC,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,gBAAgB,CAAC;IAChE,wEAAwE;IACxE,QAAQ,CAAC,OAAO,CAAC,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,IAAI,CAAC;CAC1C;AAaD,qBAAa,mBAAmB;IAOlB,OAAO,CAAC,QAAQ,CAAC,CAAC;IAN9B,OAAO,CAAC,MAAM,CAAC,CAAc;IAC7B,OAAO,CAAC,SAAS,CAAK;IACtB,OAAO,CAAC,MAAM,CAAS;IACvB,OAAO,CAAC,UAAU,CAAC,CAAkB;IACrC,OAAO,CAAC,QAAQ,CAAS;gBAEI,CAAC,EAAE,sBAAsB;IAEtD,IAAI,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,GAAE;QAAE,WAAW,CAAC,EAAE,MAAM,CAAA;KAAO,GAAG,IAAI;IAajE,YAAY,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI;IAKnC,4EAA4E;IAC5E,aAAa,CAAC,QAAQ,EAAE,MAAM,GAAG,KAAK,GAAG,MAAM,GAAG,SAAS,GAAG,MAAM;IAUpE,YAAY,CAAC,QAAQ,CAAC,EAAE,MAAM,GAAG,KAAK,GAAG,MAAM,GAAG,MAAM;IAIxD,8EAA8E;IAC9E,OAAO,CAAC,GAAG,EAAE,MAAM,EAAE,CAAC,GAAE;QAAE,QAAQ,CAAC,EAAE,MAAM,GAAG,KAAK,GAAG,MAAM,CAAA;KAAO,GAAG,IAAI;IAW1E,yDAAyD;IACzD,SAAS,CAAC,MAAM,EAAE,OAAO,GAAG,IAAI;IAShC,IAAI,CAAC,MAAM,SAAM,GAAG,IAAI;IASxB,IAAI,OAAO,IAAI,MAAM,GAAG,SAAS,CAEhC;IAED,OAAO,IAAI,IAAI;IAMf,OAAO,CAAC,UAAU;IA0DlB,OAAO,CAAC,SAAS;IAKjB,OAAO,CAAC,cAAc;IAQtB,OAAO,CAAC,SAAS;CA0BlB"}

package/dist/game-sound/MusicController.js

@@ -0,0 +1,210 @@
+/**
+ * game-sound/MusicController.ts — §6.8 music.
+ *
+ * Single-stem tracks stream through one `MediaElementAudioSourceNode` (no
+ * decode). Multi-stem tracks are decoded buffers started on ONE shared
+ * `start(when)` timestamp — separate media elements cannot stay sample-
+ * aligned. Crossfade default 1.5 s; `setIntensity` drives stem gains;
+ * `stinger` quantizes to beat/bar from `bpm` + the track's start time;
+ * pause duck −9 dB + lowpass 1.2 kHz.
+ */
+import { clamp, dbToGain } from "./types.js";
+export class MusicControllerImpl {
+    o;
+    active;
+    intensity = 1;
+    ducked = false;
+    duckFilter;
+    disposed = false;
+    constructor(o) {
+        this.o = o;
+    }
+    play(track, options = {}) {
+        if (this.disposed)
+            return;
+        const spec = this.o.tracks[track];
+        if (!spec)
+            throw new Error(`Unknown music track "${track}"`);
+        const fade = options.crossfadeMs ?? 1500;
+        const prev = this.active;
+        if (prev) {
+            rampGain(prev.gain, this.o.ctx.currentTime, 0, fade);
+            setTimeout(() => this.stopTrack(prev), fade + 60).unref?.();
+        }
+        this.active = this.startTrack(track, spec, fade);
+    }
+    setIntensity(level01) {
+        this.intensity = clamp(level01, 0, 1);
+        this.applyStemGains();
+    }
+    /** Beat/bar-quantized stinger scheduling from the playing track's start. */
+    quantizeDelay(quantize) {
+        const track = this.active;
+        if (!track?.bpm || quantize === "none" || quantize === undefined)
+            return 0;
+        const beat = 60 / track.bpm;
+        const bar = beat * 4;
+        const elapsed = this.o.ctx.currentTime - track.startedAt;
+        const unit = quantize === "bar" ? bar : beat;
+        return (Math.ceil(elapsed / unit) * unit - elapsed) || unit;
+    }
+    stingerDelay(quantize) {
+        return this.quantizeDelay(quantize);
+    }
+    /** C-25: schedule a cue stinger quantized to the playing track's beat/bar. */
+    stinger(cue, o = {}) {
+        const play = this.o.playCue;
+        if (!play)
+            return;
+        const delayS = this.quantizeDelay(o.quantize);
+        if (delayS <= 0) {
+            play(cue);
+            return;
+        }
+        setTimeout(() => play(cue), delayS * 1000).unref?.();
+    }
+    /** Pause duck: −9 dB + lowpass 1.2 kHz until cleared. */
+    setDucked(ducked) {
+        this.ducked = ducked;
+        if (!this.active)
+            return;
+        const target = ducked ? dbToGain(-9) : 1;
+        rampGain(this.active.gain, this.o.ctx.currentTime, target, 120);
+        const f = this.duckFilter?.frequency;
+        if (f)
+            f.value = ducked ? 1200 : 20_000;
+    }
+    stop(fadeMs = 500) {
+        if (this.active) {
+            const prev = this.active;
+            rampGain(prev.gain, this.o.ctx.currentTime, 0, fadeMs);
+            setTimeout(() => this.stopTrack(prev), fadeMs + 60).unref?.();
+            this.active = undefined;
+        }
+    }
+    get playing() {
+        return this.active?.name;
+    }
+    dispose() {
+        this.disposed = true;
+        if (this.active)
+            this.stopTrack(this.active);
+        this.active = undefined;
+    }
+    startTrack(name, spec, fadeInMs) {
+        const ctx = this.o.ctx;
+        const gain = ctx.createGain();
+        const g = gain;
+        g.gain.value = fadeInMs > 0 ? 0.0001 : 1;
+        if (this.ducked)
+            g.gain.value = dbToGain(-9) * g.gain.value;
+        let duckFilter;
+        if (typeof ctx.createBiquadFilter === "function") {
+            duckFilter = ctx.createBiquadFilter();
+            duckFilter.type = "lowpass";
+            if (duckFilter.frequency)
+                duckFilter.frequency.value = this.ducked ? 1200 : 20_000;
+            gain.connect(duckFilter);
+            duckFilter.connect(this.o.output);
+        }
+        else {
+            gain.connect(this.o.output);
+        }
+        this.duckFilter = duckFilter;
+        if (fadeInMs > 0)
+            rampGain(gain, ctx.currentTime, this.ducked ? dbToGain(-9) : 1, fadeInMs);
+        const track = { name, gain, stems: [], mediaElement: undefined, startedAt: ctx.currentTime, bpm: spec.bpm, stopped: false };
+        if (spec.stems.length === 1 && typeof ctx.createMediaElementSource === "function" && this.o.createMediaElement) {
+            // Single stem → streamed media element.
+            const element = this.o.createMediaElement(spec.stems[0].url);
+            element.loop = spec.loop ?? true;
+            const source = ctx.createMediaElementSource(element);
+            source.connect(gain);
+            track.mediaElement = element;
+            track.stems = [source];
+            void element.play?.();
+        }
+        else {
+            // Multi-stem → decoded buffers started on one shared `when`.
+            const when = ctx.currentTime + 0.05;
+            const stemGains = [];
+            const stems = spec.stems.map((stem, i) => {
+                const source = ctx.createBufferSource();
+                source.buffer = this.o.bufferFor(stem.url) ?? null;
+                source.loop = spec.loop ?? true;
+                const stemGain = ctx.createGain();
+                const param = stemGain.gain;
+                // Base stem (index 0) is always full; intensity layers fade in by
+                // setIntensity — start at their intensity-scaled level.
+                param.value = i === 0 ? 1 : this.stemLevel(i, spec.stems.length);
+                if (i > 0)
+                    stemGains[i - 1] = param;
+                source.connect(stemGain);
+                stemGain.connect(gain);
+                source.start(when);
+                return source;
+            });
+            track.stems = stems;
+            track.stemGains = stemGains;
+            // Beat quantization anchors at the shared start timestamp, not mount time.
+            track.startedAt = when;
+        }
+        return track;
+    }
+    stemLevel(stemIndex, stemCount) {
+        // Later stems represent higher intensity layers.
+        return this.intensity * Math.min(1, (stemIndex + 1) / stemCount);
+    }
+    applyStemGains() {
+        const track = this.active;
+        if (!track || track.stems.length <= 1)
+            return;
+        track.stemGains?.forEach((param, i) => {
+            param.value = this.stemLevel(i + 1, track.stems.length);
+        });
+    }
+    stopTrack(track) {
+        if (track.stopped)
+            return;
+        track.stopped = true;
+        for (const stem of track.stems) {
+            try {
+                stem.stop?.();
+            }
+            catch {
+                /* noop */
+            }
+            try {
+                stem.disconnect();
+            }
+            catch {
+                /* noop */
+            }
+        }
+        try {
+            track.mediaElement?.pause?.();
+        }
+        catch {
+            /* noop */
+        }
+        try {
+            track.gain.disconnect();
+        }
+        catch {
+            /* noop */
+        }
+    }
+}
+const rampGain = (gain, now, target, ms) => {
+    const param = gain.gain;
+    if (!param)
+        return;
+    if (ms <= 0 || !param.linearRampToValueAtTime) {
+        param.value = target;
+        return;
+    }
+    param.cancelScheduledValues?.(now);
+    param.setValueAtTime?.(Math.max(0.0001, param.value), now);
+    param.linearRampToValueAtTime(Math.max(0.0001, target), now + ms / 1000);
+};
+//# sourceMappingURL=MusicController.js.map

package/dist/game-sound/MusicController.js.map

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

package/dist/game-sound/ReverbSend.d.ts

@@ -0,0 +1,30 @@
+/**
+ * game-sound/ReverbSend.ts — §6.8 reverb send.
+ *
+ * One convolver send off the bus mix, tier-gated (off on `low`; IR length ≤
+ * the §17 budget: medium 0.8 s, high 1.5 s, ultra 2.5 s). Presets pick a
+ * bundled mono 24 kHz IR via the format probe. `underwater` adds a 1.8 kHz
+ * lowpass on the send path.
+ */
+import type { SoundGraphContext, SoundNodeLike } from "./types.js";
+export type ReverbPreset = "none" | "small-room" | "hall" | "street" | "hangar" | "underwater";
+export type QualityTier = "low" | "medium" | "high" | "ultra";
+export declare const IR_BUDGET_SECONDS: Record<QualityTier, number>;
+/** IR lengths shipped per preset (seconds, mono 24 kHz — from the pack manifest). */
+export declare const PRESET_IR_SECONDS: Record<Exclude<ReverbPreset, "none">, number>;
+export declare const presetIrUrl: (preset: ReverbPreset, extension: string) => string | undefined;
+export interface ReverbSendOptions {
+    readonly ctx: SoundGraphContext;
+    readonly preset: ReverbPreset;
+    readonly tier: QualityTier;
+    /** Resolve an IR url → decoded AudioBuffer (async loading upstream). */
+    readonly bufferFor: (url: string) => AudioBuffer | undefined;
+}
+export interface ReverbSend {
+    readonly enabled: boolean;
+    readonly sendInput?: SoundNodeLike;
+    readonly irSeconds: number;
+    dispose(): void;
+}
+export declare function createReverbSend(options: ReverbSendOptions): ReverbSend;
+//# sourceMappingURL=ReverbSend.d.ts.map

package/dist/game-sound/ReverbSend.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ReverbSend.d.ts","sourceRoot":"","sources":["../../../../../packages/audio/src/game-sound/ReverbSend.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,KAAK,EAAmB,iBAAiB,EAAE,aAAa,EAAE,MAAM,SAAS,CAAC;AAEjF,MAAM,MAAM,YAAY,GAAG,MAAM,GAAG,YAAY,GAAG,MAAM,GAAG,QAAQ,GAAG,QAAQ,GAAG,YAAY,CAAC;AAC/F,MAAM,MAAM,WAAW,GAAG,KAAK,GAAG,QAAQ,GAAG,MAAM,GAAG,OAAO,CAAC;AAE9D,eAAO,MAAM,iBAAiB,EAAE,MAAM,CAAC,WAAW,EAAE,MAAM,CAKzD,CAAC;AAEF,qFAAqF;AACrF,eAAO,MAAM,iBAAiB,EAAE,MAAM,CAAC,OAAO,CAAC,YAAY,EAAE,MAAM,CAAC,EAAE,MAAM,CAM3E,CAAC;AAEF,eAAO,MAAM,WAAW,GAAI,QAAQ,YAAY,EAAE,WAAW,MAAM,KAAG,MAAM,GAAG,SACX,CAAC;AAErE,MAAM,WAAW,iBAAiB;IAChC,QAAQ,CAAC,GAAG,EAAE,iBAAiB,CAAC;IAChC,QAAQ,CAAC,MAAM,EAAE,YAAY,CAAC;IAC9B,QAAQ,CAAC,IAAI,EAAE,WAAW,CAAC;IAC3B,wEAAwE;IACxE,QAAQ,CAAC,SAAS,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,WAAW,GAAG,SAAS,CAAC;CAC9D;AAED,MAAM,WAAW,UAAU;IACzB,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC;IAC1B,QAAQ,CAAC,SAAS,CAAC,EAAE,aAAa,CAAC;IACnC,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,OAAO,IAAI,IAAI,CAAC;CACjB;AAED,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,iBAAiB,GAAG,UAAU,CA4CvE"}