@woosh/meep-engine 2.154.0 → 2.156.0

package/src/engine/sound/ecs/emitter/SoundTrack.js

@@ -6,18 +6,11 @@ import { number_compare_ascending } from "../../../../core/primitives/numbers/nu
 import { compareStrings } from "../../../../core/primitives/strings/compareStrings.js";
 import { computeStringHash } from "../../../../core/primitives/strings/computeStringHash.js";
 import { SoundTrackFlags } from "./SoundTrackFlags.js";
-import { SoundTrackNodes } from "./SoundTrackNodes.js";
 
 const DEFAULT_FLAGS = SoundTrackFlags.StartWhenReady;
 
 export class SoundTrack {
 
-    /**
-     *
-     * @type {AudioBuffer|null}
-     */
-    #buffer = null;
-
     /**
      *
      * @type {String|null}
@@ -25,10 +18,24 @@ export class SoundTrack {
     url = null;
 
     /**
-     *
+     * Playback cursor in seconds. Backed by the bound sopra instance when linked.
      * @type {number}
      */
-    time = 0;
+    #time = 0;
+
+    /**
+     * Bound sopra EventInstance (set by SoundEmitterComponentContext while this track is linked), or
+     * null. Lets time reads/seeks plumb into sopra.
+     * @type {EventInstance|null}
+     */
+    __instance = null;
+
+    /**
+     * Owning translation record while this track is linked, or null. Lets a live `volume` set plumb
+     * into the bound sopra instance gain.
+     * @type {SoundEmitterComponentContext|null}
+     */
+    __soundRuntime = null;
 
     /**
      * @deprecated Not used
@@ -42,13 +49,6 @@ export class SoundTrack {
      */
     __volume = 1;
 
-    /**
-     * In seconds
-     * Obtained once clip is loaded
-     * @type {number}
-     */
-    duration = -1;
-
 
     /**
      *
@@ -64,115 +64,31 @@ export class SoundTrack {
     };
 
     /**
-     * @private
-     * @type {SoundTrackNodes}
-     */
-    #nodes = null;
-
-    /**
-     *
-     * @return {SoundTrackNodes}
+     * @deprecated sopra owns the audio graph — the track no longer holds WebAudio nodes.
      */
     get nodes() {
-        return this.#nodes;
+        throw new Error("SoundTrack.nodes is deprecated — sopra owns the audio graph");
     }
 
     /**
-     *
-     * @param {AudioContext} context
+     * Playback cursor in seconds. Reads the bound sopra instance's playhead when linked, else the
+     * last value set.
+     * @returns {number}
      */
-    initializeNodes(context) {
-        this.#nodes = new SoundTrackNodes(context);
+    get time() {
+        return this.__instance !== null ? this.__instance.playhead : this.#time;
     }
 
     /**
-     *
-     * @param {AudioBuffer} v
-     */
-    set buffer(v) {
-        this.#buffer = v;
-
-        this.duration = v.duration;
-
-        this.setFlag(SoundTrackFlags.Ready);
-    }
-
-    get buffer() {
-        return this.#buffer;
-    }
-
-    /**
-     *
-     * @returns {BaseAudioContext}
+     * Setting the cursor seeks the bound sopra instance (e.g. resetSoundEmitterTracks sets 0).
+     * @param {number} v
      */
-    get #context() {
-        return this.nodes.volume.context;
-    }
-
-    start(startTime = 0) {
-        //TODO: figure out a way to use AudioBuffer.playbackRate.value to control speed of playback
-        const nodes = this.nodes;
-
-        if (nodes.source !== null) {
-
-            /*
-             source is already used up, need to create a new one
-             NOTE: AudioBufferSourceNode can only be used once, if we want to start playback again - we have to create a new one
-             see https://stackoverflow.com/questions/59815825/how-to-skip-ahead-n-seconds-while-playing-track-using-web-audio-api
-             */
-            this.suspend();
-
-        }
-
-        nodes.source = this.#context.createBufferSource();
-
-        //connect source to output
-        nodes.source.connect(nodes.volume);
-
-        const looping = this.getFlag(SoundTrackFlags.Loop);
-
-        nodes.source.loop = looping;
-
-        // Make the sound source use the buffer and start playing it.
-        nodes.source.buffer = this.#buffer;
-
-        nodes.source.onended = () => {
-            if (!looping) {
-                this.clearFlag(SoundTrackFlags.Playing);
-                this.on.ended.send1(this);
-            }
-        }
-
-        let when = startTime;
-
-        if (this.time < 0) {
-            // playback will start in the future
-            when = -this.time;
-
-            nodes.source.start(when, 0);
-        } else {
-            // playback will start from within the track's duration (already playing)
-
-            nodes.source.start(when, this.time);
-        }
-
-        this.setFlag(SoundTrackFlags.Playing);
-        this.clearFlag(SoundTrackFlags.Suspended);
-    }
-
-    suspend() {
-        const nodes = this.#nodes;
-
-        if (nodes.source !== null) {
-
-            nodes.source.stop();
-            nodes.source.disconnect();
-
-            nodes.source = null;
+    set time(v) {
+        this.#time = v;
 
+        if (this.__instance !== null) {
+            this.__instance.seek(v);
         }
-
-        this.setFlag(SoundTrackFlags.Suspended);
     }
 
     /**
@@ -264,43 +180,8 @@ export class SoundTrack {
      * @param {number} duration How long the transition should take, in seconds
      * @param {number} [startAfter] when fading should start, see WebAudio docs on {@link AudioContext#currentTime}
      */
-    setVolumeOverTime(target, duration, startAfter = 0) {
-        // instantly update volume for consistency purposes wrt serialization
-        this.__volume = target;
-
-        const nodes = this.nodes;
-        if (nodes !== null) {
-
-            /**
-             *
-             * @type {GainNode}
-             */
-            const volume_node = nodes.volume;
-
-            /**
-             *
-             * @type {AudioParam}
-             */
-            const gain = volume_node.gain;
-
-            const current_value = gain.value;
-
-            let start_time = startAfter;
-
-            /**
-             * @type {AudioContext}
-             */
-            const audioContext = volume_node.context;
-
-            if (audioContext !== undefined) {
-                start_time += audioContext.currentTime;
-            }
-
-            // cancel any scheduled values
-            gain.cancelScheduledValues(0);
-
-            gain.setValueCurveAtTime([current_value, target], start_time, duration);
-        }
+    setVolumeOverTime() {
+        throw new Error("SoundTrack.setVolumeOverTime is deprecated — fades are owned by the sopra instance");
     }
 
     /**
@@ -310,8 +191,9 @@ export class SoundTrack {
     set volume(v) {
         this.__volume = v;
 
-        if (this.nodes !== null) {
-            this.nodes.volume.gain.setValueAtTime(v, 0);
+        // when linked, a live volume change is heard immediately (emitter.volume × track.volume)
+        if (this.__soundRuntime !== null) {
+            this.__soundRuntime.refreshTrackVolume(this);
         }
     }