@woosh/meep-engine 3.3.0 → 3.4.0

package/src/engine/sound/sopra/SopraEngine.js

@@ -1,432 +1,432 @@
-import { assert } from "../../../core/assert.js";
-import { dB2Volume } from "../dB2Volume.js";
-import { volume2dB } from "../volume2dB.js";
-import { BUS_ROOT_PARENT, BusGraph } from "./runtime/BusGraph.js";
-import { BusDefinition } from "./definition/BusDefinition.js";
-import { MixerSnapshot } from "./definition/MixerSnapshot.js";
-import { EventInstance } from "./runtime/EventInstance.js";
-import { ParameterStore } from "./runtime/ParameterStore.js";
-import { SopraPlaybackContext } from "./runtime/SopraPlaybackContext.js";
-import { VoiceManager } from "./runtime/VoiceManager.js";
-
-/**
- * Default top-level bus ids, kept identical to the legacy {@link SoundEmitterChannels} for back-compat
- * with the settings UI and `SoundEmitter.channel` strings.
- * @enum {string}
- */
-export const SopraDefaultBus = {
-    Master: "master",
-    Effects: "effects",
-    Music: "music",
-    Ambient: "ambient"
-};
-
-// legacy default mix (verified SoundEmitterSystem constructor): Effects 1.2, Music 0.1, Ambient 1
-const LEGACY_EFFECTS_VOLUME = 1.2;
-const LEGACY_MUSIC_VOLUME = 0.1;
-
-/**
- * The ECS-AGNOSTIC sopra audio engine. It owns the mixer bus graph, parameter store and the set of
- * active {@link EventInstance}s, and is driven by a single clock (the injected AudioContext's
- * `currentTime`). It never creates an AudioContext — the meep `SoundEngine` owns that. Voices are
- * recycled through the shared {@link VOICE_POOL}.
- *
- * The entire public surface is unit-testable with a mock AudioContext + a stub {@link BufferProvider}.
- */
-export class SopraEngine {
-
-    /**
-     * @type {ParameterStore}
-     */
-    parameters = new ParameterStore();
-
-    /**
-     * Shared playback context (seeded RNG + random-container history) used by instances that don't
-     * supply their own. In P3 each emitter supplies its own seeded context (entity id + tick).
-     * @type {SopraPlaybackContext}
-     */
-    defaultPlaybackContext = new SopraPlaybackContext();
-
-    /**
-     * Per-event instance limits + voice stealing.
-     * @type {VoiceManager}
-     */
-    voiceManager = new VoiceManager();
-
-    /**
-     * Listener world position for spatialization/attenuation. Null = no listener set yet (events play
-     * unattenuated). In P3 this is driven from the ECS SoundListener.
-     * @type {Vector3|null}
-     */
-    listenerPosition = null;
-
-    /**
-     * @type {Set<EventInstance>}
-     */
-    #activeInstances = new Set();
-
-    /**
-     * Active ducking rules + their runtime state.
-     * @type {{rule: DuckingRule, engaged: boolean, nominalDb: number}[]}
-     */
-    #duckers = [];
-
-    /**
-     * @param {BaseAudioContext} audioContext
-     * @param {AudioNode} destinationNode master destination the bus root routes into
-     * @param {BufferProvider} bufferProvider
-     */
-    constructor(audioContext, destinationNode, bufferProvider) {
-        assert.defined(audioContext, 'audioContext');
-        assert.defined(destinationNode, 'destinationNode');
-        assert.defined(bufferProvider, 'bufferProvider');
-
-        /**
-         * @type {BaseAudioContext}
-         */
-        this.audioContext = audioContext;
-
-        /**
-         * @type {AudioNode}
-         */
-        this.destination = destinationNode;
-
-        /**
-         * @type {BufferProvider}
-         */
-        this.bufferProvider = bufferProvider;
-
-        /**
-         * @type {BusGraph}
-         */
-        this.busGraph = new BusGraph(audioContext, destinationNode);
-        this.busGraph.build(SopraEngine.defaultBuses());
-    }
-
-    /**
-     * @returns {number} current context time (the engine's authoritative clock)
-     */
-    get currentTime() {
-        return this.audioContext.currentTime;
-    }
-
-    /**
-     * The master bus's OUTPUT node — a post-mix tap for a GLOBAL send (e.g. a probe-reverb send). Connecting a
-     * node to it fans a COPY of the whole mix off without affecting the dry path to the destination.
-     * @returns {AudioNode}
-     */
-    get masterBusOutput() {
-        return this.busGraph.getOutput(SopraDefaultBus.Master);
-    }
-
-    /**
-     * The default bus tree: a master root with the three legacy channels at the legacy mix.
-     * @returns {BusDefinition[]}
-     */
-    static defaultBuses() {
-        return [
-            BusDefinition.from(SopraDefaultBus.Master, { parentId: BUS_ROOT_PARENT, gainDb: 0 }),
-            BusDefinition.from(SopraDefaultBus.Effects, { parentId: SopraDefaultBus.Master, gainDb: volume2dB(LEGACY_EFFECTS_VOLUME) }),
-            BusDefinition.from(SopraDefaultBus.Music, { parentId: SopraDefaultBus.Master, gainDb: volume2dB(LEGACY_MUSIC_VOLUME) }),
-            BusDefinition.from(SopraDefaultBus.Ambient, { parentId: SopraDefaultBus.Master, gainDb: 0 })
-        ];
-    }
-
-    /**
-     * Replace the mixer with a new bus tree (rebuilds the WebAudio graph).
-     * @param {BusDefinition[]} busDefinitions
-     */
-    setBuses(busDefinitions) {
-        this.busGraph = new BusGraph(this.audioContext, this.destination);
-        this.busGraph.build(busDefinitions);
-    }
-
-    /**
-     * Create (but do not start) an instance of an event.
-     * @param {EventDescription} description
-     * @param {{busId?:string, position?:Vector3, oneShot?:boolean, maxLifetime?:number, seed?:number, playbackContext?:SopraPlaybackContext}} [options]
-     * @returns {EventInstance}
-     */
-    createInstance(description, options = {}) {
-        const playbackContext = options.playbackContext
-            ?? (options.seed !== undefined ? new SopraPlaybackContext(options.seed) : this.defaultPlaybackContext);
-
-        return new EventInstance(this, description, { ...options, playbackContext });
-    }
-
-    /**
-     * Create, start and track an instance.
-     * @param {EventDescription} description
-     * @param {{busId?:string, position?:Vector3, oneShot?:boolean, maxLifetime?:number, seed?:number, playbackContext?:SopraPlaybackContext}} [options]
-     * @returns {EventInstance}
-     */
-    playEvent(description, options = {}) {
-        if (!this.voiceManager.makeRoom(description)) {
-            // event instance limit reached and steal mode is None — drop this play
-            return null;
-        }
-
-        const instance = this.createInstance(description, options);
-
-        this.voiceManager.register(instance);
-        this.#activeInstances.add(instance);
-
-        try {
-            instance.start(this.currentTime);
-        } catch (e) {
-            // clean up registries before propagating (rethrows — not a silent catch)
-            this.voiceManager.unregister(instance);
-            this.#activeInstances.delete(instance);
-            throw e;
-        }
-
-        return instance;
-    }
-
-    /**
-     * Fire-and-forget: a one-shot that auto-releases when its content finishes (or on the
-     * lifetime/asset-failure fallback).
-     * @param {EventDescription} description
-     * @param {{busId?:string, position?:Vector3, maxLifetime?:number}} [options]
-     * @returns {EventInstance}
-     */
-    playOneShot(description, options = {}) {
-        return this.playEvent(description, { ...options, oneShot: true });
-    }
-
-    /**
-     * @param {EventInstance} instance
-     */
-    stop(instance) {
-        instance.stop();
-    }
-
-    /**
-     * Crossfade from a playing instance to a new event: start the new one at silence and fade it up to
-     * its nominal gain while fading the old one out and stopping it, over `duration`.
-     * @param {EventInstance|null} oldInstance instance to fade out (may be null)
-     * @param {EventDescription} description event to fade in
-     * @param {{busId?:string, position?:Vector3, duration?:number}} [options]
-     * @returns {EventInstance|null} the new instance (or null if the play was denied by limits)
-     */
-    crossfade(oldInstance, description, options = {}) {
-        const duration = options.duration ?? 1;
-
-        const newInstance = this.playEvent(description, options);
-
-        if (newInstance !== null) {
-            const nominalDb = newInstance.gainDb;
-
-            newInstance.setGainDb(nominalDb - 60); // start ~silent
-            newInstance.fadeToGainDb(nominalDb, duration);
-        }
-
-        if (oldInstance !== null && oldInstance !== newInstance) {
-            oldInstance.fadeOutAndStop(duration);
-        }
-
-        return newInstance;
-    }
-
-    /**
-     * @param {string} name
-     * @param {number} value
-     */
-    setParameter(name, value) {
-        this.parameters.set(name, value);
-    }
-
-    /**
-     * @param {string} name
-     * @returns {number|undefined}
-     */
-    getParameter(name) {
-        return this.parameters.get(name);
-    }
-
-    /**
-     * Set the listener world position used for 3D attenuation/culling.
-     * @param {Vector3} position
-     */
-    setListener(position) {
-        this.listenerPosition = position;
-    }
-
-    /**
-     * Register a parameter with a default value.
-     * @param {string} name
-     * @param {number} [defaultValue]
-     */
-    defineParameter(name, defaultValue = 0) {
-        this.parameters.define(name, defaultValue);
-    }
-
-    /**
-     * Bind an arbitrary apply callback to a parameter (runs on change, and once now if already set).
-     * @param {string} name
-     * @param {function(number)} applyFn
-     */
-    bindParameter(name, applyFn) {
-        this.parameters.bind(name, applyFn);
-    }
-
-    /**
-     * Drive a bus's linear volume from a parameter through an {@link AnimationCurve}.
-     * @param {string} name
-     * @param {string} busId
-     * @param {AnimationCurve} curve maps parameter value -> linear bus gain
-     */
-    bindParameterToBusVolume(name, busId, curve) {
-        this.parameters.bind(name, (value) => this.setBusVolume(busId, curve.evaluate(value)));
-    }
-
-    /**
-     * @param {string} busId
-     * @returns {number} linear gain
-     */
-    getBusVolume(busId) {
-        return this.busGraph.getVolume(busId);
-    }
-
-    /**
-     * @param {string} busId
-     * @param {number} linear linear gain
-     */
-    setBusVolume(busId, linear) {
-        this.busGraph.setVolume(busId, linear);
-    }
-
-    /**
-     * Apply a {@link MixerSnapshot}: move each listed bus to its target gain. `duration` 0 snaps
-     * instantly; > 0 click-safely ramps (a mix-state blend).
-     * @param {MixerSnapshot} snapshot
-     * @param {{duration?:number}} [options]
-     */
-    applySnapshot(snapshot, { duration = 0 } = {}) {
-        const buses = snapshot.buses;
-
-        for (let i = 0; i < buses.length; i++) {
-            const entry = buses[i];
-            const linear = dB2Volume(entry.gainDb);
-
-            if (duration <= 0) {
-                this.busGraph.setVolume(entry.busId, linear);
-            } else {
-                this.busGraph.rampVolume(entry.busId, linear, duration);
-            }
-        }
-    }
-
-    /**
-     * Capture the current gain of each given bus into a snapshot (e.g. to restore a mix later).
-     * @param {string} id
-     * @param {string[]} busIds
-     * @returns {MixerSnapshot}
-     */
-    captureSnapshot(id, busIds) {
-        const buses = [];
-
-        for (let i = 0; i < busIds.length; i++) {
-            buses.push({ busId: busIds[i], gainDb: this.busGraph.getVolumeDb(busIds[i]) });
-        }
-
-        return MixerSnapshot.from(id, buses);
-    }
-
-    /**
-     * Advance the engine. Drives per-instance lifetime bookkeeping (and, from P1, the scheduler).
-     * @param {number} [now] context time; defaults to the live clock
-     */
-    update(now = this.currentTime) {
-        const listenerPosition = this.listenerPosition;
-
-        // snapshot — an instance may finish (and remove itself) during its own update
-        const instances = [...this.#activeInstances];
-
-        for (let i = 0; i < instances.length; i++) {
-            instances[i].update(now, listenerPosition);
-        }
-
-        this.#updateDuckers();
-    }
-
-    /**
-     * Register a ducking rule (e.g. duck `music` while anything plays on `dialogue`). Evaluated each
-     * {@link update}.
-     * @param {DuckingRule} rule
-     */
-    addDucker(rule) {
-        this.#duckers.push({ rule, engaged: false, nominalDb: 0 });
-    }
-
-    /**
-     * Remove all ducking rules (restoring any currently-ducked target to its captured nominal).
-     */
-    clearDuckers() {
-        const duckers = this.#duckers;
-
-        for (let i = 0; i < duckers.length; i++) {
-            const d = duckers[i];
-            if (d.engaged) {
-                this.busGraph.approachVolume(d.rule.targetBusId, dB2Volume(d.nominalDb), d.rule.release);
-            }
-        }
-
-        this.#duckers = [];
-    }
-
-    /**
-     * Edge-triggered duck engage/release: a target ducks while its trigger bus has any live instance,
-     * and restores to the gain captured at engage time when the trigger goes quiet.
-     */
-    #updateDuckers() {
-        const duckers = this.#duckers;
-
-        for (let i = 0; i < duckers.length; i++) {
-            const d = duckers[i];
-            const active = this.#busActiveCount(d.rule.triggerBusId) > 0;
-
-            if (active && !d.engaged) {
-                d.engaged = true;
-                d.nominalDb = this.busGraph.getVolumeDb(d.rule.targetBusId);
-                this.busGraph.approachVolume(d.rule.targetBusId, dB2Volume(d.nominalDb + d.rule.duckDb), d.rule.attack);
-            } else if (!active && d.engaged) {
-                d.engaged = false;
-                this.busGraph.approachVolume(d.rule.targetBusId, dB2Volume(d.nominalDb), d.rule.release);
-            }
-        }
-    }
-
-    /**
-     * @param {string} busId
-     * @returns {number} count of live instances routed to that bus
-     */
-    #busActiveCount(busId) {
-        let n = 0;
-
-        this.#activeInstances.forEach(instance => {
-            if (instance.busId === busId) {
-                n++;
-            }
-        });
-
-        return n;
-    }
-
-    /**
-     * @returns {number} count of live instances (for tests/diagnostics)
-     */
-    get activeInstanceCount() {
-        return this.#activeInstances.size;
-    }
-
-    /**
-     * Internal: invoked by an {@link EventInstance} when it finishes. Uses the `__` prefix because it
-     * is a cross-class internal call, not part of the public API.
-     * @param {EventInstance} instance
-     */
-    __onInstanceFinished(instance) {
-        this.#activeInstances.delete(instance);
-        this.voiceManager.unregister(instance);
-    }
-}
+import { assert } from "../../../core/assert.js";
+import { dB2Volume } from "../dB2Volume.js";
+import { volume2dB } from "../volume2dB.js";
+import { BUS_ROOT_PARENT, BusGraph } from "./runtime/BusGraph.js";
+import { BusDefinition } from "./definition/BusDefinition.js";
+import { MixerSnapshot } from "./definition/MixerSnapshot.js";
+import { EventInstance } from "./runtime/EventInstance.js";
+import { ParameterStore } from "./runtime/ParameterStore.js";
+import { SopraPlaybackContext } from "./runtime/SopraPlaybackContext.js";
+import { VoiceManager } from "./runtime/VoiceManager.js";
+
+/**
+ * Default top-level bus ids, kept identical to the channel names the legacy sound components used, so
+ * the settings UI and any converted `channel` string keep resolving.
+ * @enum {string}
+ */
+export const SopraDefaultBus = {
+    Master: "master",
+    Effects: "effects",
+    Music: "music",
+    Ambient: "ambient"
+};
+
+// the mix inherited from the pre-sopra engine: Effects 1.2, Music 0.1, Ambient 1
+const LEGACY_EFFECTS_VOLUME = 1.2;
+const LEGACY_MUSIC_VOLUME = 0.1;
+
+/**
+ * The ECS-AGNOSTIC sopra audio engine. It owns the mixer bus graph, parameter store and the set of
+ * active {@link EventInstance}s, and is driven by a single clock (the injected AudioContext's
+ * `currentTime`). It never creates an AudioContext — the meep `SoundEngine` owns that. Voices are
+ * recycled through the shared {@link VOICE_POOL}.
+ *
+ * The entire public surface is unit-testable with a mock AudioContext + a stub {@link BufferProvider}.
+ */
+export class SopraEngine {
+
+    /**
+     * @type {ParameterStore}
+     */
+    parameters = new ParameterStore();
+
+    /**
+     * Shared playback context (seeded RNG + random-container history) used by instances that don't
+     * supply their own. In P3 each emitter supplies its own seeded context (entity id + tick).
+     * @type {SopraPlaybackContext}
+     */
+    defaultPlaybackContext = new SopraPlaybackContext();
+
+    /**
+     * Per-event instance limits + voice stealing.
+     * @type {VoiceManager}
+     */
+    voiceManager = new VoiceManager();
+
+    /**
+     * Listener world position for spatialization/attenuation. Null = no listener set yet (events play
+     * unattenuated). In P3 this is driven from the ECS SoundListener.
+     * @type {Vector3|null}
+     */
+    listenerPosition = null;
+
+    /**
+     * @type {Set<EventInstance>}
+     */
+    #activeInstances = new Set();
+
+    /**
+     * Active ducking rules + their runtime state.
+     * @type {{rule: DuckingRule, engaged: boolean, nominalDb: number}[]}
+     */
+    #duckers = [];
+
+    /**
+     * @param {BaseAudioContext} audioContext
+     * @param {AudioNode} destinationNode master destination the bus root routes into
+     * @param {BufferProvider} bufferProvider
+     */
+    constructor(audioContext, destinationNode, bufferProvider) {
+        assert.defined(audioContext, 'audioContext');
+        assert.defined(destinationNode, 'destinationNode');
+        assert.defined(bufferProvider, 'bufferProvider');
+
+        /**
+         * @type {BaseAudioContext}
+         */
+        this.audioContext = audioContext;
+
+        /**
+         * @type {AudioNode}
+         */
+        this.destination = destinationNode;
+
+        /**
+         * @type {BufferProvider}
+         */
+        this.bufferProvider = bufferProvider;
+
+        /**
+         * @type {BusGraph}
+         */
+        this.busGraph = new BusGraph(audioContext, destinationNode);
+        this.busGraph.build(SopraEngine.defaultBuses());
+    }
+
+    /**
+     * @returns {number} current context time (the engine's authoritative clock)
+     */
+    get currentTime() {
+        return this.audioContext.currentTime;
+    }
+
+    /**
+     * The master bus's OUTPUT node — a post-mix tap for a GLOBAL send (e.g. a probe-reverb send). Connecting a
+     * node to it fans a COPY of the whole mix off without affecting the dry path to the destination.
+     * @returns {AudioNode}
+     */
+    get masterBusOutput() {
+        return this.busGraph.getOutput(SopraDefaultBus.Master);
+    }
+
+    /**
+     * The default bus tree: a master root with the three legacy channels at the legacy mix.
+     * @returns {BusDefinition[]}
+     */
+    static defaultBuses() {
+        return [
+            BusDefinition.from(SopraDefaultBus.Master, { parentId: BUS_ROOT_PARENT, gainDb: 0 }),
+            BusDefinition.from(SopraDefaultBus.Effects, { parentId: SopraDefaultBus.Master, gainDb: volume2dB(LEGACY_EFFECTS_VOLUME) }),
+            BusDefinition.from(SopraDefaultBus.Music, { parentId: SopraDefaultBus.Master, gainDb: volume2dB(LEGACY_MUSIC_VOLUME) }),
+            BusDefinition.from(SopraDefaultBus.Ambient, { parentId: SopraDefaultBus.Master, gainDb: 0 })
+        ];
+    }
+
+    /**
+     * Replace the mixer with a new bus tree (rebuilds the WebAudio graph).
+     * @param {BusDefinition[]} busDefinitions
+     */
+    setBuses(busDefinitions) {
+        this.busGraph = new BusGraph(this.audioContext, this.destination);
+        this.busGraph.build(busDefinitions);
+    }
+
+    /**
+     * Create (but do not start) an instance of an event.
+     * @param {EventDescription} description
+     * @param {{busId?:string, position?:Vector3, oneShot?:boolean, maxLifetime?:number, seed?:number, playbackContext?:SopraPlaybackContext}} [options]
+     * @returns {EventInstance}
+     */
+    createInstance(description, options = {}) {
+        const playbackContext = options.playbackContext
+            ?? (options.seed !== undefined ? new SopraPlaybackContext(options.seed) : this.defaultPlaybackContext);
+
+        return new EventInstance(this, description, { ...options, playbackContext });
+    }
+
+    /**
+     * Create, start and track an instance.
+     * @param {EventDescription} description
+     * @param {{busId?:string, position?:Vector3, oneShot?:boolean, maxLifetime?:number, seed?:number, playbackContext?:SopraPlaybackContext}} [options]
+     * @returns {EventInstance}
+     */
+    playEvent(description, options = {}) {
+        if (!this.voiceManager.makeRoom(description)) {
+            // event instance limit reached and steal mode is None — drop this play
+            return null;
+        }
+
+        const instance = this.createInstance(description, options);
+
+        this.voiceManager.register(instance);
+        this.#activeInstances.add(instance);
+
+        try {
+            instance.start(this.currentTime);
+        } catch (e) {
+            // clean up registries before propagating (rethrows — not a silent catch)
+            this.voiceManager.unregister(instance);
+            this.#activeInstances.delete(instance);
+            throw e;
+        }
+
+        return instance;
+    }
+
+    /**
+     * Fire-and-forget: a one-shot that auto-releases when its content finishes (or on the
+     * lifetime/asset-failure fallback).
+     * @param {EventDescription} description
+     * @param {{busId?:string, position?:Vector3, maxLifetime?:number}} [options]
+     * @returns {EventInstance}
+     */
+    playOneShot(description, options = {}) {
+        return this.playEvent(description, { ...options, oneShot: true });
+    }
+
+    /**
+     * @param {EventInstance} instance
+     */
+    stop(instance) {
+        instance.stop();
+    }
+
+    /**
+     * Crossfade from a playing instance to a new event: start the new one at silence and fade it up to
+     * its nominal gain while fading the old one out and stopping it, over `duration`.
+     * @param {EventInstance|null} oldInstance instance to fade out (may be null)
+     * @param {EventDescription} description event to fade in
+     * @param {{busId?:string, position?:Vector3, duration?:number}} [options]
+     * @returns {EventInstance|null} the new instance (or null if the play was denied by limits)
+     */
+    crossfade(oldInstance, description, options = {}) {
+        const duration = options.duration ?? 1;
+
+        const newInstance = this.playEvent(description, options);
+
+        if (newInstance !== null) {
+            const nominalDb = newInstance.gainDb;
+
+            newInstance.setGainDb(nominalDb - 60); // start ~silent
+            newInstance.fadeToGainDb(nominalDb, duration);
+        }
+
+        if (oldInstance !== null && oldInstance !== newInstance) {
+            oldInstance.fadeOutAndStop(duration);
+        }
+
+        return newInstance;
+    }
+
+    /**
+     * @param {string} name
+     * @param {number} value
+     */
+    setParameter(name, value) {
+        this.parameters.set(name, value);
+    }
+
+    /**
+     * @param {string} name
+     * @returns {number|undefined}
+     */
+    getParameter(name) {
+        return this.parameters.get(name);
+    }
+
+    /**
+     * Set the listener world position used for 3D attenuation/culling.
+     * @param {Vector3} position
+     */
+    setListener(position) {
+        this.listenerPosition = position;
+    }
+
+    /**
+     * Register a parameter with a default value.
+     * @param {string} name
+     * @param {number} [defaultValue]
+     */
+    defineParameter(name, defaultValue = 0) {
+        this.parameters.define(name, defaultValue);
+    }
+
+    /**
+     * Bind an arbitrary apply callback to a parameter (runs on change, and once now if already set).
+     * @param {string} name
+     * @param {function(number)} applyFn
+     */
+    bindParameter(name, applyFn) {
+        this.parameters.bind(name, applyFn);
+    }
+
+    /**
+     * Drive a bus's linear volume from a parameter through an {@link AnimationCurve}.
+     * @param {string} name
+     * @param {string} busId
+     * @param {AnimationCurve} curve maps parameter value -> linear bus gain
+     */
+    bindParameterToBusVolume(name, busId, curve) {
+        this.parameters.bind(name, (value) => this.setBusVolume(busId, curve.evaluate(value)));
+    }
+
+    /**
+     * @param {string} busId
+     * @returns {number} linear gain
+     */
+    getBusVolume(busId) {
+        return this.busGraph.getVolume(busId);
+    }
+
+    /**
+     * @param {string} busId
+     * @param {number} linear linear gain
+     */
+    setBusVolume(busId, linear) {
+        this.busGraph.setVolume(busId, linear);
+    }
+
+    /**
+     * Apply a {@link MixerSnapshot}: move each listed bus to its target gain. `duration` 0 snaps
+     * instantly; > 0 click-safely ramps (a mix-state blend).
+     * @param {MixerSnapshot} snapshot
+     * @param {{duration?:number}} [options]
+     */
+    applySnapshot(snapshot, { duration = 0 } = {}) {
+        const buses = snapshot.buses;
+
+        for (let i = 0; i < buses.length; i++) {
+            const entry = buses[i];
+            const linear = dB2Volume(entry.gainDb);
+
+            if (duration <= 0) {
+                this.busGraph.setVolume(entry.busId, linear);
+            } else {
+                this.busGraph.rampVolume(entry.busId, linear, duration);
+            }
+        }
+    }
+
+    /**
+     * Capture the current gain of each given bus into a snapshot (e.g. to restore a mix later).
+     * @param {string} id
+     * @param {string[]} busIds
+     * @returns {MixerSnapshot}
+     */
+    captureSnapshot(id, busIds) {
+        const buses = [];
+
+        for (let i = 0; i < busIds.length; i++) {
+            buses.push({ busId: busIds[i], gainDb: this.busGraph.getVolumeDb(busIds[i]) });
+        }
+
+        return MixerSnapshot.from(id, buses);
+    }
+
+    /**
+     * Advance the engine. Drives per-instance lifetime bookkeeping (and, from P1, the scheduler).
+     * @param {number} [now] context time; defaults to the live clock
+     */
+    update(now = this.currentTime) {
+        const listenerPosition = this.listenerPosition;
+
+        // snapshot — an instance may finish (and remove itself) during its own update
+        const instances = [...this.#activeInstances];
+
+        for (let i = 0; i < instances.length; i++) {
+            instances[i].update(now, listenerPosition);
+        }
+
+        this.#updateDuckers();
+    }
+
+    /**
+     * Register a ducking rule (e.g. duck `music` while anything plays on `dialogue`). Evaluated each
+     * {@link update}.
+     * @param {DuckingRule} rule
+     */
+    addDucker(rule) {
+        this.#duckers.push({ rule, engaged: false, nominalDb: 0 });
+    }
+
+    /**
+     * Remove all ducking rules (restoring any currently-ducked target to its captured nominal).
+     */
+    clearDuckers() {
+        const duckers = this.#duckers;
+
+        for (let i = 0; i < duckers.length; i++) {
+            const d = duckers[i];
+            if (d.engaged) {
+                this.busGraph.approachVolume(d.rule.targetBusId, dB2Volume(d.nominalDb), d.rule.release);
+            }
+        }
+
+        this.#duckers = [];
+    }
+
+    /**
+     * Edge-triggered duck engage/release: a target ducks while its trigger bus has any live instance,
+     * and restores to the gain captured at engage time when the trigger goes quiet.
+     */
+    #updateDuckers() {
+        const duckers = this.#duckers;
+
+        for (let i = 0; i < duckers.length; i++) {
+            const d = duckers[i];
+            const active = this.#busActiveCount(d.rule.triggerBusId) > 0;
+
+            if (active && !d.engaged) {
+                d.engaged = true;
+                d.nominalDb = this.busGraph.getVolumeDb(d.rule.targetBusId);
+                this.busGraph.approachVolume(d.rule.targetBusId, dB2Volume(d.nominalDb + d.rule.duckDb), d.rule.attack);
+            } else if (!active && d.engaged) {
+                d.engaged = false;
+                this.busGraph.approachVolume(d.rule.targetBusId, dB2Volume(d.nominalDb), d.rule.release);
+            }
+        }
+    }
+
+    /**
+     * @param {string} busId
+     * @returns {number} count of live instances routed to that bus
+     */
+    #busActiveCount(busId) {
+        let n = 0;
+
+        this.#activeInstances.forEach(instance => {
+            if (instance.busId === busId) {
+                n++;
+            }
+        });
+
+        return n;
+    }
+
+    /**
+     * @returns {number} count of live instances (for tests/diagnostics)
+     */
+    get activeInstanceCount() {
+        return this.#activeInstances.size;
+    }
+
+    /**
+     * Internal: invoked by an {@link EventInstance} when it finishes. Uses the `__` prefix because it
+     * is a cross-class internal call, not part of the public API.
+     * @param {EventInstance} instance
+     */
+    __onInstanceFinished(instance) {
+        this.#activeInstances.delete(instance);
+        this.voiceManager.unregister(instance);
+    }
+}