@woosh/meep-engine 2.155.0 → 2.156.0

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

@@ -0,0 +1,579 @@
+import Signal from "../../../../core/events/signal/Signal.js";
+import { dB2Volume } from "../../dB2Volume.js";
+import { FADE_EPSILON, rampGain } from "../util/fadeOutAndStop.js";
+import { SOPRA_PANNING_MODEL_TO_WEBAUDIO } from "../definition/SopraPanningModel.js";
+import { VOICE_POOL } from "./VoicePool.js";
+
+/**
+ * Lifecycle state of an {@link EventInstance}.
+ * @enum {number}
+ */
+export const EventInstanceState = {
+    Initial: 0,
+    Playing: 1,
+    Stopped: 2
+};
+
+/**
+ * How far ahead (seconds) leaves are spawned before their scheduled start, so `source.start(when)`
+ * stays sample-accurate even when the driving frame is slightly late ("Tale of Two Clocks").
+ * @type {number}
+ */
+const LOOKAHEAD_SECONDS = 0.2;
+
+const DEFAULT_MAX_LIFETIME_SECONDS = 60;
+
+/**
+ * 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 {
+
+    /**
+     * @type {number}
+     */
+    startedAt = 0;
+
+    /**
+     * @type {EventInstanceState|number}
+     */
+    state = EventInstanceState.Initial;
+
+    /**
+     * Current post-attenuation linear gain (1 for non-3D). Read by the VoiceManager for steal-quietest.
+     * @type {number}
+     */
+    currentGain = 1;
+
+    /**
+     * Fires `this` when the instance has fully stopped (ended, stopped, timed out, or failed to load).
+     * @type {Signal<EventInstance>}
+     */
+    onEnded = new Signal();
+
+    /**
+     * Resolved timeline: one entry per leaf play. Null until buffers are loaded and the timeline is
+     * resolved. Each entry: { clip, offset, gainDb, pitchCents, duration, voice }.
+     * @type {{clip: SampleAudioClip, offset: number, gainDb: number, pitchCents: number, duration: number, voice: Voice|null}[]|null}
+     */
+    #timeline = null;
+
+    /**
+     * @type {Map<SampleAudioClip, AudioBuffer>|null}
+     */
+    #bufferMap = null;
+
+    /**
+     * @type {number}
+     */
+    #totalDuration = 0;
+
+    /**
+     * Node that voices route into: the instance's attenuation gain (3D) or the bus input (2D).
+     * @type {AudioNode|null}
+     */
+    #chainHead = null;
+
+    /**
+     * @type {GainNode|null}
+     */
+    #attenuationGain = null;
+
+    /**
+     * @type {PannerNode|null}
+     */
+    #panner = null;
+
+    /**
+     * Always-on per-instance trim gain — the chain head ALL voices route through (2D and 3D). Carries
+     * the live instance volume (setGainDb / fades); composes (multiplies) with #attenuationGain in 3D.
+     * @type {GainNode|null}
+     */
+    #instanceGain = null;
+
+    /**
+     * Live instance gain in decibels (0 dB = unity). Applied to #instanceGain.
+     * @type {number}
+     */
+    #gainDb = 0;
+
+    /**
+     * Audio-clock time at which a scheduled fade-out stops the instance; Infinity = none.
+     * @type {number}
+     */
+    #stopDeadline = Infinity;
+
+    /**
+     * @type {boolean}
+     */
+    #audible = true;
+
+    /**
+     * Logical start timestamp (audio clock). When set, the playhead is `now - startTime` from the
+     * outset, so a promoted emitter resumes at the phase it "should" be at given elapsed real time
+     * (continuous-clock semantics); null = start now (playhead 0).
+     * @type {number|null}
+     */
+    #startTime = null;
+
+    /**
+     * @param {SopraEngine} engine
+     * @param {EventDescription} description
+     * @param {{busId?:string, position?:Vector3, oneShot?:boolean, maxLifetime?:number, playbackContext?:SopraPlaybackContext, startTime?:number}} [options]
+     */
+    constructor(engine, description, {
+        busId = description.busId,
+        position = null,
+        oneShot = false,
+        maxLifetime = DEFAULT_MAX_LIFETIME_SECONDS,
+        playbackContext = engine.defaultPlaybackContext,
+        startTime = null
+    } = {}) {
+        /**
+         * @type {SopraEngine}
+         */
+        this.engine = engine;
+
+        /**
+         * @type {EventDescription}
+         */
+        this.description = description;
+
+        /**
+         * @type {string}
+         */
+        this.busId = busId;
+
+        /**
+         * World position for spatialization. Null = non-positional.
+         * @type {Vector3|null}
+         */
+        this.position = position;
+
+        /**
+         * @type {boolean}
+         */
+        this.oneShot = oneShot;
+
+        /**
+         * @type {number}
+         */
+        this.maxLifetimeSeconds = maxLifetime;
+
+        /**
+         * @type {SopraPlaybackContext}
+         */
+        this.playbackContext = playbackContext;
+
+        this.#startTime = startTime;
+    }
+
+    /**
+     * Current playback position in seconds (now - startedAt, clamped at 0).
+     * @returns {number}
+     */
+    get playhead() {
+        return Math.max(0, this.engine.currentTime - this.startedAt);
+    }
+
+    /**
+     * Live voices currently sounding (timeline order).
+     * @returns {Voice[]}
+     */
+    get voices() {
+        const timeline = this.#timeline;
+
+        if (timeline === null) {
+            return [];
+        }
+
+        const result = [];
+        for (let i = 0; i < timeline.length; i++) {
+            if (timeline[i].voice !== null) {
+                result.push(timeline[i].voice);
+            }
+        }
+
+        return result;
+    }
+
+    /**
+     * Begin playback at context time `now`.
+     * @param {number} now
+     */
+    start(now) {
+        this.startedAt = this.#startTime !== null ? this.#startTime : now;
+        this.state = EventInstanceState.Playing;
+
+        const samples = this.description.rootClip.collectSampleClips();
+        const provider = this.engine.bufferProvider;
+
+        // synchronous fast path: all candidate buffers already decoded
+        const bufferMap = new Map();
+        let allReady = true;
+
+        for (let i = 0; i < samples.length; i++) {
+            const clip = samples[i];
+            const buffer = provider.tryGet(clip.url, clip.usingAlias);
+
+            if (buffer === null) {
+                allReady = false;
+                break;
+            }
+
+            bufferMap.set(clip, buffer);
+        }
+
+        if (allReady) {
+            this.#resolve(now, bufferMap);
+            return;
+        }
+
+        // deferred: load every candidate buffer, then resolve once they arrive
+        Promise.all(
+            samples.map(clip => provider.get(clip.url, clip.usingAlias).then(buffer => [clip, buffer]))
+        ).then(
+            entries => {
+                if (this.state === EventInstanceState.Playing) {
+                    this.#resolve(this.engine.currentTime, new Map(entries));
+                }
+            },
+            error => this.#failLoad(error)
+        );
+    }
+
+    /**
+     * @param {number} now
+     * @param {Map<SampleAudioClip, AudioBuffer>} bufferMap
+     */
+    #resolve(now, bufferMap) {
+        this.#bufferMap = bufferMap;
+
+        const env = {
+            durationOf: (clip) => bufferMap.get(clip).duration,
+            playback: this.playbackContext,
+            getParameter: (name) => this.engine.getParameter(name)
+        };
+
+        const { plays, duration } = this.description.rootClip.planTimeline(env, this.description.gainDb, 0, 0);
+
+        const timeline = [];
+        for (let i = 0; i < plays.length; i++) {
+            const p = plays[i];
+
+            timeline.push({
+                clip: p.clip,
+                offset: p.offset,
+                gainDb: p.gainDb,
+                pitchCents: p.pitchCents,
+                duration: p.clip.loop ? Infinity : bufferMap.get(p.clip).duration,
+                voice: null
+            });
+        }
+
+        this.#timeline = timeline;
+        this.#totalDuration = duration;
+
+        this.#buildOutputChain();
+
+        // initial evaluation at the start time (spawns leaves due immediately, if audible)
+        this.update(now, this.engine.listenerPosition);
+    }
+
+    #buildOutputChain() {
+        const engine = this.engine;
+        const ctx = engine.audioContext;
+        const busInput = engine.busGraph.getInput(this.busId);
+        const description = this.description;
+
+        // the instance gain is the uniform chain head (2D and 3D), so live volume/fades have one home
+        this.#instanceGain = ctx.createGain();
+        this.#instanceGain.gain.setValueAtTime(dB2Volume(this.#gainDb), 0);
+
+        if (description.is3D) {
+            this.#attenuationGain = ctx.createGain();
+
+            const panner = ctx.createPanner();
+            panner.panningModel = SOPRA_PANNING_MODEL_TO_WEBAUDIO[description.panningModel] ?? 'HRTF';
+            // the panner does DIRECTION only; distance attenuation is the custom gain node (rolloff=0)
+            panner.distanceModel = 'linear';
+            panner.rolloffFactor = 0;
+            panner.refDistance = description.distanceMin;
+            panner.maxDistance = description.distanceMax;
+            this.#panner = panner;
+
+            // voices -> instanceGain -> attenuationGain -> panner -> bus
+            this.#instanceGain.connect(this.#attenuationGain);
+            this.#attenuationGain.connect(panner);
+            panner.connect(busInput);
+        } else {
+            // voices -> instanceGain -> bus
+            this.#instanceGain.connect(busInput);
+        }
+
+        this.#chainHead = this.#instanceGain;
+    }
+
+    /**
+     * Live instance gain in decibels (composes with 3D attenuation).
+     * @returns {number}
+     */
+    get gainDb() {
+        return this.#gainDb;
+    }
+
+    /**
+     * Set the instance gain immediately.
+     * @param {number} db
+     */
+    setGainDb(db) {
+        this.#gainDb = db;
+
+        if (this.#instanceGain !== null) {
+            this.#instanceGain.gain.setValueAtTime(dB2Volume(db), this.engine.currentTime);
+        }
+    }
+
+    /**
+     * 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, duration, startAfter = 0) {
+        this.#gainDb = targetDb;
+
+        if (this.#instanceGain !== null) {
+            rampGain(this.#instanceGain.gain, dB2Volume(targetDb), duration, this.engine.audioContext, startAfter);
+        }
+    }
+
+    /**
+     * 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, startAfter = 0) {
+        if (this.state !== EventInstanceState.Playing) {
+            return;
+        }
+
+        if (this.#instanceGain !== null) {
+            rampGain(this.#instanceGain.gain, FADE_EPSILON, duration, this.engine.audioContext, startAfter);
+        }
+
+        this.#stopDeadline = this.engine.currentTime + startAfter + duration;
+    }
+
+    /**
+     * 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) {
+        if (this.state !== EventInstanceState.Playing || this.#timeline === null) {
+            return;
+        }
+
+        this.startedAt = this.engine.currentTime - Math.max(0, seconds);
+
+        const timeline = this.#timeline;
+        for (let i = 0; i < timeline.length; i++) {
+            this.#retire(timeline[i]);
+        }
+
+        this.update(this.engine.currentTime, this.engine.listenerPosition);
+    }
+
+    /**
+     * Restart from the beginning (seek to 0).
+     */
+    restart() {
+        this.seek(0);
+    }
+
+    /**
+     * 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, listenerPosition) {
+        if (this.state !== EventInstanceState.Playing) {
+            return;
+        }
+
+        if (this.#timeline === null) {
+            // still loading — only the lifetime backstop applies
+            if (this.oneShot && (now - this.startedAt) > this.maxLifetimeSeconds) {
+                this.stop();
+            }
+            return;
+        }
+
+        const description = this.description;
+
+        if (description.is3D && this.position !== null && listenerPosition !== null) {
+            const distance = this.position.distanceTo(listenerPosition);
+            const gain = Math.max(0, description.attenuation.evaluate(distance));
+
+            this.#attenuationGain.gain.setValueAtTime(gain, 0);
+            this.#panner.setPosition(this.position.x, this.position.y, this.position.z);
+
+            this.currentGain = gain;
+            this.#audible = distance <= description.distanceMax && gain > dB2Volume(description.virtualThresholdDb);
+        } else {
+            this.currentGain = 1;
+            this.#audible = true;
+        }
+
+        this.#evaluate(now);
+
+        // scheduled fade-out deadline (audio-clock based, not setTimeout)
+        if (this.state === EventInstanceState.Playing && now >= this.#stopDeadline) {
+            this.stop();
+        }
+
+        if (this.state === EventInstanceState.Playing && this.oneShot && (now - this.startedAt) > this.maxLifetimeSeconds) {
+            this.stop();
+        }
+    }
+
+    /**
+     * @param {number} now
+     */
+    #evaluate(now) {
+        const playhead = now - this.startedAt;
+        const timeline = this.#timeline;
+        const audible = this.#audible;
+
+        for (let i = 0; i < timeline.length; i++) {
+            const entry = timeline[i];
+
+            const start = entry.offset;
+            const end = entry.duration === Infinity ? Infinity : entry.offset + entry.duration;
+
+            const withinWindow = (playhead + LOOKAHEAD_SECONDS >= start) && (playhead < end);
+
+            if (withinWindow && audible) {
+                if (entry.voice === null) {
+                    const when = Math.max(now, this.startedAt + start);
+                    const bufferOffset = Math.max(0, playhead - start);
+
+                    entry.voice = this.#spawnVoice(entry, when, bufferOffset);
+                }
+            } else if (entry.voice !== null) {
+                // out of range (virtualize) or past the leaf's window — stop, keep the cursor
+                this.#retire(entry);
+            }
+        }
+
+        if (this.oneShot && this.#totalDuration !== Infinity && playhead >= this.#totalDuration) {
+            this.stop();
+        }
+    }
+
+    /**
+     * @param {{clip: SampleAudioClip, gainDb: number, pitchCents: number}} entry
+     * @param {number} when
+     * @param {number} bufferOffset
+     * @returns {Voice}
+     */
+    #spawnVoice(entry, when, bufferOffset) {
+        const clip = entry.clip;
+        const buffer = this.#bufferMap.get(clip);
+
+        let offset = bufferOffset;
+
+        // A resumed/long-running loop can have an offset beyond the buffer — phase reconstruction on
+        // promote (playhead = now - startTime) or revival after a long virtual period. Wrap it into the
+        // loop region so the source starts at a valid in-buffer position. (Offsets within the first pass,
+        // i.e. ≤ loopEnd, are left as-is so a one-time intro region still plays.)
+        if (clip.loop) {
+            const loopEnd = clip.loopEnd > 0 ? clip.loopEnd : buffer.duration;
+            const loopStart = clip.loopStart;
+            const loopLength = loopEnd - loopStart;
+
+            if (loopLength > 0 && offset > loopEnd) {
+                offset = loopStart + ((offset - loopStart) % loopLength);
+            }
+        }
+
+        const voice = VOICE_POOL.get();
+
+        voice.play(this.engine.audioContext, this.#chainHead, buffer, {
+            gainLinear: dB2Volume(entry.gainDb),
+            detuneCents: entry.pitchCents,
+            loop: clip.loop,
+            loopStart: clip.loopStart,
+            loopEnd: clip.loopEnd,
+            when,
+            offset
+        });
+
+        return voice;
+    }
+
+    /**
+     * @param {{voice: Voice|null}} entry
+     */
+    #retire(entry) {
+        if (entry.voice !== null) {
+            entry.voice.stop();
+            VOICE_POOL.release(entry.voice);
+            entry.voice = null;
+        }
+    }
+
+    /**
+     * @param {Error} error
+     */
+    #failLoad(error) {
+        // expected-failure path (missing/failed asset): surface it (log) and release — do NOT hang
+        // and do NOT silently swallow.
+        console.error(`sopra: event '${this.description.label}' could not load its buffer`, error);
+
+        this.stop();
+    }
+
+    /**
+     * Stop all voices, tear down the output chain, and finish the instance.
+     */
+    stop() {
+        if (this.state === EventInstanceState.Stopped) {
+            return;
+        }
+
+        this.state = EventInstanceState.Stopped;
+
+        const timeline = this.#timeline;
+        if (timeline !== null) {
+            for (let i = 0; i < timeline.length; i++) {
+                this.#retire(timeline[i]);
+            }
+        }
+
+        if (this.#panner !== null) {
+            this.#panner.disconnect();
+        }
+        if (this.#attenuationGain !== null) {
+            this.#attenuationGain.disconnect();
+        }
+        if (this.#instanceGain !== null) {
+            this.#instanceGain.disconnect();
+        }
+
+        if (this.onEnded.hasHandlers()) {
+            this.onEnded.send1(this);
+        }
+
+        this.engine.__onInstanceFinished(this);
+    }
+}

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

@@ -0,0 +1,42 @@
+/**
+ * Holds live values for named parameters (RTPC). P0 is the minimal store (define/get/set + a change
+ * signal); automation curves binding parameter values to gains/pitch/sends are layered on in P1.
+ */
+export class ParameterStore {
+    /**
+     * Fires (name, value) whenever a parameter changes.
+     * @type {Signal<string, number>}
+     */
+    onChanged: Signal<string, number>;
+    /**
+     * Register a parameter with its default value (no-op if already defined).
+     * @param {string} name
+     * @param {number} defaultValue
+     */
+    define(name: string, defaultValue: number): void;
+    /**
+     * @param {string} name
+     * @returns {boolean}
+     */
+    has(name: string): boolean;
+    /**
+     * @param {string} name
+     * @returns {number|undefined}
+     */
+    get(name: string): number | undefined;
+    /**
+     * @param {string} name
+     * @param {number} value
+     */
+    set(name: string, value: number): void;
+    /**
+     * Bind a callback to a parameter; it runs on every change (and once now if the parameter already
+     * has a value). Used to drive bus gains / voice params from an automation curve.
+     * @param {string} name
+     * @param {function(number)} applyFn
+     */
+    bind(name: string, applyFn: (arg0: number) => any): void;
+    #private;
+}
+import Signal from "../../../../core/events/signal/Signal.js";
+//# sourceMappingURL=ParameterStore.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"ParameterStore.d.ts","sourceRoot":"","sources":["../../../../../../src/engine/sound/sopra/runtime/ParameterStore.js"],"names":[],"mappings":"AAEA;;;GAGG;AACH;IAaI;;;OAGG;IACH,WAFU,OAAO,MAAM,EAAE,MAAM,CAAC,CAEP;IAEzB;;;;OAIG;IACH,aAHW,MAAM,gBACN,MAAM,QAMhB;IAED;;;OAGG;IACH,UAHW,MAAM,GACJ,OAAO,CAInB;IAED;;;OAGG;IACH,UAHW,MAAM,GACJ,MAAM,GAAC,SAAS,CAI5B;IAED;;;OAGG;IACH,UAHW,MAAM,SACN,MAAM,QAqBhB;IAED;;;;;OAKG;IACH,WAHW,MAAM,kBACG,MAAM,gBAezB;;CACJ;mBAjGkB,0CAA0C"}