@woosh/meep-engine 2.155.0 → 2.156.0

package/src/engine/sound/sopra/runtime/BusGraph.js

@@ -0,0 +1,227 @@
+import { dB2Volume } from "../../dB2Volume.js";
+import { volume2dB } from "../../volume2dB.js";
+import { rampGain } from "../util/fadeOutAndStop.js";
+
+/**
+ * A {@link BusDefinition.parentId} equal to this means "no parent" — the bus is a root and routes
+ * straight to the engine destination.
+ * @type {string}
+ */
+export const BUS_ROOT_PARENT = "";
+
+/**
+ * Runtime mixer: instantiates a set of {@link BusDefinition}s into chained WebAudio nodes.
+ *
+ * Each bus is wired `input → effect[0] → … → effect[n] → gain(output)`; the output then connects to
+ * its parent bus's input, or to the engine destination for a root bus (parentId === "").
+ */
+export class BusGraph {
+
+    /**
+     * id -> { definition, input, output }
+     * @type {Map<string, {definition: BusDefinition, input: AudioNode, output: GainNode}>}
+     */
+    buses = new Map();
+
+    /**
+     * @type {BaseAudioContext}
+     */
+    #ctx;
+
+    /**
+     * @type {AudioNode}
+     */
+    #destination;
+
+    /**
+     * @param {BaseAudioContext} ctx
+     * @param {AudioNode} destination engine master destination node
+     */
+    constructor(ctx, destination) {
+        this.#ctx = ctx;
+        this.#destination = destination;
+    }
+
+    /**
+     * Build the graph from a flat list of bus definitions. Order-independent: all nodes are created
+     * first, then wired to their parents.
+     * @param {BusDefinition[]} definitions
+     */
+    build(definitions) {
+        const ctx = this.#ctx;
+
+        // pass 1: create the per-bus node chain (input → effects → gain)
+        for (let i = 0; i < definitions.length; i++) {
+            const def = definitions[i];
+
+            const gain = ctx.createGain();
+            const nominal = dB2Volume(def.gainDb);
+            gain.gain.setValueAtTime(nominal, 0);
+
+            let input = gain;
+
+            const effects = def.effects;
+
+            if (effects.length > 0) {
+                let previousOutput = null;
+
+                for (let e = 0; e < effects.length; e++) {
+                    const built = effects[e].build(ctx);
+
+                    if (previousOutput === null) {
+                        // first effect is the chain head
+                        input = built.input;
+                    } else {
+                        previousOutput.connect(built.input);
+                    }
+
+                    previousOutput = built.output;
+                }
+
+                // last effect feeds the bus gain (output)
+                previousOutput.connect(gain);
+            }
+
+            // `nominal` is the authoritative logical fader gain (linear), tracked separately from the
+            // node's instantaneous `.value` — which WebAudio does NOT update under ramps/setTargetAtTime.
+            // get/setVolume read/write `nominal`; ducking (approachVolume) is a transient modulation that
+            // deliberately does NOT touch it, so the duck can capture + restore the true nominal.
+            this.buses.set(def.id, { definition: def, input, output: gain, nominal });
+        }
+
+        // pass 2: route each bus output to its parent's input (or the engine destination)
+        for (let i = 0; i < definitions.length; i++) {
+            const def = definitions[i];
+
+            const bus = this.buses.get(def.id);
+
+            if (def.parentId === BUS_ROOT_PARENT) {
+                bus.output.connect(this.#destination);
+            } else {
+                const parent = this.buses.get(def.parentId);
+
+                if (parent === undefined) {
+                    throw new Error(`sopra: bus '${def.id}' references unknown parent '${def.parentId}'`);
+                }
+
+                bus.output.connect(parent.input);
+            }
+
+            // aux sends: route a post-fader copy of this bus into each target bus, at the send level
+            // (e.g. a dry bus sending to a shared reverb bus)
+            const sends = def.sends;
+            for (let s = 0; s < sends.length; s++) {
+                const send = sends[s];
+
+                const target = this.buses.get(send.targetBusId);
+                if (target === undefined) {
+                    throw new Error(`sopra: bus '${def.id}' sends to unknown bus '${send.targetBusId}'`);
+                }
+
+                const sendGain = ctx.createGain();
+                sendGain.gain.setValueAtTime(dB2Volume(send.levelDb), 0);
+
+                bus.output.connect(sendGain);
+                sendGain.connect(target.input);
+            }
+        }
+    }
+
+    /**
+     * @param {string} id
+     * @returns {boolean}
+     */
+    has(id) {
+        return this.buses.has(id);
+    }
+
+    /**
+     * Node that voices/children should connect into for a given bus.
+     * @param {string} id
+     * @returns {AudioNode}
+     */
+    getInput(id) {
+        const bus = this.buses.get(id);
+
+        if (bus === undefined) {
+            throw new Error(`sopra: no bus '${id}'`);
+        }
+
+        return bus.input;
+    }
+
+    /**
+     * @param {string} id
+     * @returns {number} linear gain
+     */
+    getVolume(id) {
+        const bus = this.buses.get(id);
+
+        if (bus === undefined) {
+            throw new Error(`sopra: no bus '${id}'`);
+        }
+
+        return bus.nominal;
+    }
+
+    /**
+     * @param {string} id
+     * @param {number} linear linear gain
+     */
+    setVolume(id, linear) {
+        const bus = this.buses.get(id);
+
+        if (bus === undefined) {
+            throw new Error(`sopra: no bus '${id}'`);
+        }
+
+        bus.nominal = linear;
+        bus.output.gain.setValueAtTime(linear, 0);
+    }
+
+    /**
+     * @param {string} id
+     * @returns {number} gain in decibels
+     */
+    getVolumeDb(id) {
+        return volume2dB(this.getVolume(id));
+    }
+
+    /**
+     * Click-safely ramp a bus's linear volume to `linear` over `duration` seconds (used by mixer
+     * snapshot blends). For an instant change use {@link setVolume}.
+     * @param {string} id
+     * @param {number} linear target linear gain
+     * @param {number} duration seconds
+     * @param {number} [startAfter=0] seconds
+     */
+    rampVolume(id, linear, duration, startAfter = 0) {
+        const bus = this.buses.get(id);
+
+        if (bus === undefined) {
+            throw new Error(`sopra: no bus '${id}'`);
+        }
+
+        bus.nominal = linear; // a ramp is a nominal fader move; record where it's heading
+        rampGain(bus.output.gain, linear, duration, this.#ctx, startAfter);
+    }
+
+    /**
+     * Exponentially approach a target linear volume with a time constant (used by ducking attack/
+     * release). Unlike {@link rampVolume} this does not anchor — it's a smooth setTargetAtTime glide.
+     * @param {string} id
+     * @param {number} linear target linear gain
+     * @param {number} timeConstant seconds
+     */
+    approachVolume(id, linear, timeConstant) {
+        const bus = this.buses.get(id);
+
+        if (bus === undefined) {
+            throw new Error(`sopra: no bus '${id}'`);
+        }
+
+        // NB: a transient modulation (ducking) — deliberately does NOT update `nominal`, so the duck can
+        // capture the true fader position at engage and restore to it on release.
+        bus.output.gain.setTargetAtTime(linear, this.#ctx.currentTime, timeConstant);
+    }
+}

package/src/engine/sound/sopra/runtime/EventInstance.d.ts

@@ -0,0 +1,144 @@
+/**
+ * Lifecycle state of an {@link EventInstance }.
+ */
+export type EventInstanceState = number;
+export namespace EventInstanceState {
+    let Initial: number;
+    let Playing: number;
+    let Stopped: number;
+}
+/**
+ * One triggered playing of an {@link EventDescription}. Transient — never serialized.
+ *
+ * Playback is **cursor-based**: each frame {@link update} compares the logical playhead
+ * (`now - startedAt`) against the resolved timeline and, for each leaf whose window is current,
+ * spawns a voice — but only while the instance is audible. Out-of-range/below-threshold instances go
+ * **virtual** (their voices stop while the cursor keeps advancing) and revive at the correct child +
+ * buffer-offset when audible again (D3). 3D instances own a shared `attenuationGain → panner → bus`
+ * chain (D4); the attenuation gain is driven by distance through the event's attenuation curve.
+ */
+export class EventInstance {
+    /**
+     * @param {SopraEngine} engine
+     * @param {EventDescription} description
+     * @param {{busId?:string, position?:Vector3, oneShot?:boolean, maxLifetime?:number, playbackContext?:SopraPlaybackContext, startTime?:number}} [options]
+     */
+    constructor(engine: SopraEngine, description: EventDescription, { busId, position, oneShot, maxLifetime, playbackContext, startTime }?: {
+        busId?: string;
+        position?: Vector3;
+        oneShot?: boolean;
+        maxLifetime?: number;
+        playbackContext?: SopraPlaybackContext;
+        startTime?: number;
+    });
+    /**
+     * @type {number}
+     */
+    startedAt: number;
+    /**
+     * @type {EventInstanceState|number}
+     */
+    state: EventInstanceState | number;
+    /**
+     * Current post-attenuation linear gain (1 for non-3D). Read by the VoiceManager for steal-quietest.
+     * @type {number}
+     */
+    currentGain: number;
+    /**
+     * Fires `this` when the instance has fully stopped (ended, stopped, timed out, or failed to load).
+     * @type {Signal<EventInstance>}
+     */
+    onEnded: Signal<EventInstance>;
+    /**
+     * @type {SopraEngine}
+     */
+    engine: SopraEngine;
+    /**
+     * @type {EventDescription}
+     */
+    description: EventDescription;
+    /**
+     * @type {string}
+     */
+    busId: string;
+    /**
+     * World position for spatialization. Null = non-positional.
+     * @type {Vector3|null}
+     */
+    position: Vector3 | null;
+    /**
+     * @type {boolean}
+     */
+    oneShot: boolean;
+    /**
+     * @type {number}
+     */
+    maxLifetimeSeconds: number;
+    /**
+     * @type {SopraPlaybackContext}
+     */
+    playbackContext: SopraPlaybackContext;
+    /**
+     * Current playback position in seconds (now - startedAt, clamped at 0).
+     * @returns {number}
+     */
+    get playhead(): number;
+    /**
+     * Live voices currently sounding (timeline order).
+     * @returns {Voice[]}
+     */
+    get voices(): Voice[];
+    /**
+     * Begin playback at context time `now`.
+     * @param {number} now
+     */
+    start(now: number): void;
+    /**
+     * Live instance gain in decibels (composes with 3D attenuation).
+     * @returns {number}
+     */
+    get gainDb(): number;
+    /**
+     * Set the instance gain immediately.
+     * @param {number} db
+     */
+    setGainDb(db: number): void;
+    /**
+     * Ramp the instance gain to a target over `duration` (click-safe). Does not stop the instance.
+     * @param {number} targetDb
+     * @param {number} duration seconds
+     * @param {number} [startAfter=0] seconds
+     */
+    fadeToGainDb(targetDb: number, duration: number, startAfter?: number): void;
+    /**
+     * Fade the instance out to silence over `duration`, then stop it (audio-clock deadline checked in
+     * {@link update}; no setTimeout).
+     * @param {number} duration seconds
+     * @param {number} [startAfter=0] seconds
+     */
+    fadeOutAndStop(duration: number, startAfter?: number): void;
+    /**
+     * Re-base the playhead to `seconds` and respawn voices at the new offset. Preserves the resolved
+     * timeline + playback RNG state (no re-pick / no reseed) — only the cursor moves.
+     * @param {number} seconds
+     */
+    seek(seconds: number): void;
+    /**
+     * Restart from the beginning (seek to 0).
+     */
+    restart(): void;
+    /**
+     * Advance the instance one frame: update spatialization, then evaluate the timeline against the
+     * playhead (spawning / virtualizing voices).
+     * @param {number} now context time
+     * @param {Vector3|null} listenerPosition
+     */
+    update(now: number, listenerPosition: Vector3 | null): void;
+    /**
+     * Stop all voices, tear down the output chain, and finish the instance.
+     */
+    stop(): void;
+    #private;
+}
+import Signal from "../../../../core/events/signal/Signal.js";
+//# sourceMappingURL=EventInstance.d.ts.map

package/src/engine/sound/sopra/runtime/EventInstance.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"EventInstance.d.ts","sourceRoot":"","sources":["../../../../../../src/engine/sound/sopra/runtime/EventInstance.js"],"names":[],"mappings":";;;iCAQU,MAAM;;;;;;AAiBhB;;;;;;;;;GASG;AACH;IAyFI;;;;OAIG;IACH,wIAFW;QAAC,KAAK,CAAC,EAAC,MAAM,CAAC;QAAC,QAAQ,CAAC,UAAS;QAAC,OAAO,CAAC,EAAC,OAAO,CAAC;QAAC,WAAW,CAAC,EAAC,MAAM,CAAC;QAAC,eAAe,CAAC,uBAAsB;QAAC,SAAS,CAAC,EAAC,MAAM,CAAA;KAAC,EA+C7I;IAzID;;OAEG;IACH,WAFU,MAAM,CAEF;IAEd;;OAEG;IACH,OAFU,kBAAkB,GAAC,MAAM,CAEA;IAEnC;;;OAGG;IACH,aAFU,MAAM,CAEA;IAEhB;;;OAGG;IACH,SAFU,OAAO,aAAa,CAAC,CAER;IAgFnB;;OAEG;IACH,oBAAoB;IAEpB;;OAEG;IACH,8BAA8B;IAE9B;;OAEG;IACH,OAFU,MAAM,CAEE;IAElB;;;OAGG;IACH,UAFU,UAAQ,IAAI,CAEE;IAExB;;OAEG;IACH,SAFU,OAAO,CAEK;IAEtB;;OAEG;IACH,oBAFU,MAAM,CAEqB;IAErC;;OAEG;IACH,sCAAsC;IAK1C;;;OAGG;IACH,uBAEC;IAED;;;OAGG;IACH,sBAeC;IAED;;;OAGG;IACH,WAFW,MAAM,QAyChB;IA0ED;;;OAGG;IACH,qBAEC;IAED;;;OAGG;IACH,cAFW,MAAM,QAQhB;IAED;;;;;OAKG;IACH,uBAJW,MAAM,YACN,MAAM,eACN,MAAM,QAQhB;IAED;;;;;OAKG;IACH,yBAHW,MAAM,eACN,MAAM,QAYhB;IAED;;;;OAIG;IACH,cAFW,MAAM,QAehB;IAED;;OAEG;IACH,gBAEC;IAED;;;;;OAKG;IACH,YAHW,MAAM,oBACN,UAAQ,IAAI,QAyCtB;IAmGD;;OAEG;IACH,aA6BC;;CACJ;mBAlkBkB,0CAA0C"}