@woosh/meep-engine 3.45.0 → 3.47.0

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

@@ -2,6 +2,7 @@ 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, SopraPanningModel } from "../definition/SopraPanningModel.js";
+import { EffectChain } from "./EffectChain.js";
 import { VOICE_POOL } from "./VoicePool.js";
 import { LOW_MID_HZ, MID_HIGH_HZ } from "../../simulation/render/reverbImpulseResponse.js";
 import { v3_distance } from "../../../../core/geom/vec3/v3_distance.js";
@@ -185,11 +186,20 @@ export class EventInstance {
     #selfReleases = false;
 
     /**
-     * Node that voices route into: the instance's attenuation gain (3D) or the bus input (2D).
+     * Node that voices route into: the head of the event's inserts, or the instance gain when it has none.
      * @type {AudioNode|null}
      */
     #chainHead = null;
 
+    /**
+     * This instance's own copy of the event's insert effects ({@link EventDescription.effects}), ahead of
+     * its fader. Built with the instance — before its buffers arrive — so its parameters can be moved from
+     * the moment `playEvent` returns, by {@link setEffectParam} / {@link approachEffectParam}. Null when the
+     * event has no inserts.
+     * @type {EffectChain|null}
+     */
+    #effects = null;
+
     /**
      * @type {GainNode|null}
      */
@@ -201,7 +211,7 @@ export class EventInstance {
     #panner = null;
 
     /**
-     * Always-on per-instance trim gain — the chain head ALL voices route through (2D and 3D). Carries
+     * Always-on per-instance trim gain — the fader ALL voices route through (2D and 3D), after the inserts. Carries
      * the live instance volume (setGainDb / fades); composes (multiplies) with #attenuationGain in 3D.
      * @type {GainNode|null}
      */
@@ -247,6 +257,34 @@ export class EventInstance {
      */
     #audible = true;
 
+    /**
+     * Whether {@link position} was written since the panner last took it, as {@link moved} reports. True
+     * from the start, so the first update places the source.
+     * @type {boolean}
+     */
+    #source_moved = true;
+
+    /**
+     * The {@link SopraEngine#listenerVersion} this instance was last attenuated against; -1 = never.
+     * @type {number}
+     */
+    #listener_version = -1;
+
+    /**
+     * What the panner and the attenuation gain were last handed, NaN until they are. A transform
+     * announces any write — a rotation in place included — and a listener turning on the spot is a
+     * listener move too; neither changes what these hold, and a Web Audio write is not cheap, so each is
+     * compared before it is made.
+     * @type {number}
+     */
+    #written_x = NaN;
+    /** @type {number} */
+    #written_y = NaN;
+    /** @type {number} */
+    #written_z = NaN;
+    /** @type {number} */
+    #written_gain = NaN;
+
     /**
      * 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
@@ -325,8 +363,14 @@ export class EventInstance {
         this.busId = busId;
 
         /**
-         * World position for spatialization. Null = non-positional.
-         * @type {Vector3|null}
+         * World position for spatialization, read by index. Null = non-positional.
+         *
+         * Held by reference, not copied, and read when the instance starts, after {@link moved}, and
+         * whenever the listener moves ({@link SopraEngine#setListener}). So whoever writes it says so with
+         * {@link moved}; a source written without saying so keeps sounding where it last was. Give each
+         * instance an array of its own: every instance reads the one it holds, so instances sharing one
+         * are all wherever it was last written. (The acoustic simulation reads it afresh on each solve.)
+         * @type {ArrayLike<number>|null}
          */
         this.position = position;
 
@@ -368,6 +412,10 @@ export class EventInstance {
         this.#pathing = pathing;
 
         this.sourceRadius = sourceRadius;
+
+        if (description.effects.length > 0) {
+            this.#effects = new EffectChain(engine.audioContext, description.effects);
+        }
     }
 
     /**
@@ -483,7 +531,7 @@ export class EventInstance {
         this.#buildOutputChain();
 
         // initial evaluation at the start time (spawns leaves due immediately, if audible)
-        this.update(now, this.engine.listenerPosition);
+        this.update(now);
     }
 
     #buildOutputChain() {
@@ -492,7 +540,7 @@ export class EventInstance {
         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
+        // the instance gain is the uniform fader (2D and 3D), so live volume/fades have one home
         const pending = this.#pendingFade;
 
         this.#instanceGain = ctx.createGain();
@@ -591,7 +639,66 @@ export class EventInstance {
             this.#instanceGain.connect(busInput);
         }
 
-        this.#chainHead = this.#instanceGain;
+        // the event's inserts sit ahead of the fader (pre-fader, as on a bus), so a fade-out fades what
+        // they produce rather than feeding them a fading signal: voices -> effects -> instanceGain -> ...
+        if (this.#effects !== null) {
+            this.#effects.output.connect(this.#instanceGain);
+            this.#chainHead = this.#effects.input;
+        } else {
+            this.#chainHead = this.#instanceGain;
+        }
+    }
+
+    /**
+     * Move a parameter of this instance's copy of one of the event's insert effects, now — one play of a
+     * cue made duller, brighter or louder than the others. Other instances of the event, and the
+     * {@link EventDescription} itself, are untouched.
+     *
+     * Valid from the moment the instance exists, including while its buffers are still loading. The effect
+     * is addressed by its position in {@link EventDescription.effects}, the parameter by one of its class's
+     * `parameters` (`'frequency'` on an `EqEffect`).
+     *
+     * @param {number} effectIndex
+     * @param {string} name
+     * @param {number} value in the parameter's own units (Hz, dB, seconds, ...)
+     */
+    setEffectParam(effectIndex, name, value) {
+        this.#effectChain().setParam(effectIndex, name, value);
+    }
+
+    /**
+     * Glide a parameter of this instance's copy of one of the event's insert effects toward `value` —
+     * tracking a game value while the sound plays. See {@link EffectChain#approachParam}; addressed as
+     * {@link setEffectParam}.
+     *
+     * @param {number} effectIndex
+     * @param {string} name
+     * @param {number} value
+     * @param {number} timeConstant seconds, above 0
+     */
+    approachEffectParam(effectIndex, name, value, timeConstant) {
+        this.#effectChain().approachParam(effectIndex, name, value, timeConstant);
+    }
+
+    /**
+     * Where this instance's effect parameter was last sent (a glide's target), or its defined value.
+     * @param {number} effectIndex
+     * @param {string} name
+     * @returns {number}
+     */
+    getEffectParam(effectIndex, name) {
+        return this.#effectChain().getParam(effectIndex, name);
+    }
+
+    /**
+     * @returns {EffectChain}
+     */
+    #effectChain() {
+        if (this.#effects === null) {
+            throw new Error(`sopra: event '${this.description.label}' has no effects`);
+        }
+
+        return this.#effects;
     }
 
     /**
@@ -769,7 +876,7 @@ export class EventInstance {
             this.#retire(timeline[i]);
         }
 
-        this.update(this.engine.currentTime, this.engine.listenerPosition);
+        this.update(this.engine.currentTime);
     }
 
     /**
@@ -782,10 +889,13 @@ export class EventInstance {
     /**
      * Advance the instance one frame: update spatialization, then evaluate the timeline against the
      * playhead (spawning / virtualizing voices).
+     *
+     * The listener is the engine's ({@link SopraEngine#listenerPosition}), read here together with the
+     * version that says whether it moved, so a listener set during a tick is never paired with another's
+     * version.
      * @param {number} now context time
-     * @param {Vector3|null} listenerPosition
      */
-    update(now, listenerPosition) {
+    update(now) {
         if (this.state !== EventInstanceState.Playing) {
             return;
         }
@@ -811,25 +921,26 @@ export class EventInstance {
         }
 
         const description = this.description;
+        const engine = this.engine;
+        const listenerPosition = engine.listenerPosition;
 
         if (description.is3D && this.position !== null && listenerPosition !== null) {
-            // the position is a live view over the emitter transform, and the listener pose comes
-            // from one too, so both read by index
-            const distance = v3_distance(
-                this.position[0], this.position[1], this.position[2],
-                listenerPosition[0], listenerPosition[1], listenerPosition[2]
-            );
-            const gain = Math.max(0, description.attenuation.evaluate(distance));
-
-            this.#attenuationGain.gain.setValueAtTime(gain, 0);
-
-            if (this.#panner !== null) {
-                // absent for SopraPanningModel.None — positioned, but never rotated
-                this.#panner.setPosition(this.position[0], this.position[1], this.position[2]);
+            /*
+             Spatialized when something moved, not every frame: the source (its writer reports it with
+             moved()) or the listener (setListener). Until one does, the gain, the panner and the
+             audibility worked out last time all still hold. A crowd of one-shots standing where they
+             were played wrote a panner position and a gain each, every frame, and a Chrome profile put
+             the panner write at about 20 us.
+            */
+            const source_moved = this.#source_moved;
+            const listener_version = engine.listenerVersion;
+
+            if (source_moved || listener_version !== this.#listener_version) {
+                this.#source_moved = false;
+                this.#listener_version = listener_version;
+
+                this.#spatialize(listenerPosition, source_moved);
             }
-
-            this.currentGain = gain;
-            this.#audible = distance <= description.distanceMax && gain > dB2Volume(description.virtualThresholdDb);
         } else {
             this.currentGain = 1;
             this.#audible = true;
@@ -847,6 +958,67 @@ export class EventInstance {
         }
     }
 
+    /**
+     * Report that {@link position} was written, so the next {@link update} puts the source where it now
+     * is: its panner, its distance attenuation and whether it is audible at all. The instance reads the
+     * array only when something has moved, so a write nobody reports is not heard.
+     *
+     * Cheap and idempotent: it marks the instance, and the work happens once, in the next update,
+     * however many writes were reported before it. Harmless on a 2D instance, or on one that has stopped.
+     */
+    moved() {
+        this.#source_moved = true;
+    }
+
+    /**
+     * Attenuate against the listener and, when the source moved, put the panner on it. Writes only what
+     * changed.
+     *
+     * @param {ArrayLike<number>} listenerPosition
+     * @param {boolean} source_moved
+     */
+    #spatialize(listenerPosition, source_moved) {
+        const description = this.description;
+
+        // the position is a live view over the emitter transform, and the listener pose comes from one
+        // too, so both read by index
+        const position = this.position;
+
+        const x = position[0];
+        const y = position[1];
+        const z = position[2];
+
+        const distance = v3_distance(
+            x, y, z,
+            listenerPosition[0], listenerPosition[1], listenerPosition[2]
+        );
+
+        const gain = Math.max(0, description.attenuation.evaluate(distance));
+
+        if (gain !== this.#written_gain) {
+            this.#attenuationGain.gain.setValueAtTime(gain, 0);
+
+            this.#written_gain = gain;
+        }
+
+        // absent for SopraPanningModel.None — positioned, but never rotated
+        const panner = this.#panner;
+
+        if (
+            source_moved && panner !== null
+            && (x !== this.#written_x || y !== this.#written_y || z !== this.#written_z)
+        ) {
+            panner.setPosition(x, y, z);
+
+            this.#written_x = x;
+            this.#written_y = y;
+            this.#written_z = z;
+        }
+
+        this.currentGain = gain;
+        this.#audible = distance <= description.distanceMax && gain > dB2Volume(description.virtualThresholdDb);
+    }
+
     /**
      * @param {number} now
      */
@@ -983,6 +1155,9 @@ export class EventInstance {
         if (this.#instanceGain !== null) {
             this.#instanceGain.disconnect();
         }
+        if (this.#effects !== null) {
+            this.#effects.disconnect();
+        }
 
         if (this.onEnded.hasHandlers()) {
             this.onEnded.send1(this);

package/src/engine/sound/sopra/serialization/populateSopraSerializationRegistry.d.ts

@@ -1,5 +1,6 @@
 /**
- * Register every sopra definition adapter on a {@link BinarySerializationRegistry}.
+ * Register every sopra definition adapter, and the upgraders of their older formats, on a
+ * {@link BinarySerializationRegistry}.
  *
  * In production this is called from `GameBinarySerializationRegistry.initializeGameBinarySerializationRegistry`
  * (integration lands in P3); in P0 it backs the round-trip specs. Keeping the list here mirrors the

package/src/engine/sound/sopra/serialization/populateSopraSerializationRegistry.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"populateSopraSerializationRegistry.d.ts","sourceRoot":"","sources":["../../../../../../src/engine/sound/sopra/serialization/populateSopraSerializationRegistry.js"],"names":[],"mappings":"AAeA;;;;;;;;GAQG;AACH,gGAiBC"}
+{"version":3,"file":"populateSopraSerializationRegistry.d.ts","sourceRoot":"","sources":["../../../../../../src/engine/sound/sopra/serialization/populateSopraSerializationRegistry.js"],"names":[],"mappings":"AAiBA;;;;;;;;;GASG;AACH,gGAmBC"}

package/src/engine/sound/sopra/serialization/populateSopraSerializationRegistry.js

@@ -4,6 +4,8 @@ import { DuckingRuleSerializationAdapter } from "../definition/DuckingRuleSerial
 import { EqEffectSerializationAdapter } from "../definition/effect/EqEffectSerializationAdapter.js";
 import { ReverbEffectSerializationAdapter } from "../definition/effect/ReverbEffectSerializationAdapter.js";
 import { EventDescriptionSerializationAdapter } from "../definition/EventDescriptionSerializationAdapter.js";
+import { EventDescriptionSerializationUpgrader_0_1 } from "../definition/EventDescriptionSerializationUpgrader_0_1.js";
+import { EventDescription } from "../definition/EventDescription.js";
 import { MixerSnapshotSerializationAdapter } from "../definition/MixerSnapshotSerializationAdapter.js";
 import { ParameterDefinitionSerializationAdapter } from "../definition/ParameterDefinitionSerializationAdapter.js";
 import { BlendContainerAudioClipSerializationAdapter } from "../definition/clip/BlendContainerAudioClipSerializationAdapter.js";
@@ -14,7 +16,8 @@ import { SilenceAudioClipSerializationAdapter } from "../definition/clip/Silence
 import { SwitchContainerAudioClipSerializationAdapter } from "../definition/clip/SwitchContainerAudioClipSerializationAdapter.js";
 
 /**
- * Register every sopra definition adapter on a {@link BinarySerializationRegistry}.
+ * Register every sopra definition adapter, and the upgraders of their older formats, on a
+ * {@link BinarySerializationRegistry}.
  *
  * In production this is called from `GameBinarySerializationRegistry.initializeGameBinarySerializationRegistry`
  * (integration lands in P3); in P0 it backs the round-trip specs. Keeping the list here mirrors the
@@ -39,4 +42,6 @@ export function populateSopraSerializationRegistry(registry) {
         new MixerSnapshotSerializationAdapter(),
         new DuckingRuleSerializationAdapter()
     ]);
+
+    registry.registerUpgrader(EventDescription.typeName, new EventDescriptionSerializationUpgrader_0_1(registry));
 }

package/src/engine/sound/sopra/serialization/sopraSerializationHarness.d.ts

@@ -23,5 +23,20 @@ export function binaryRoundTrip<T>(objectAdapter: BinaryObjectSerializationAdapt
     restored: T;
     stable: boolean;
 };
+/**
+ * Write `description` in `EventDescription`'s binary format VERSION 0 — the layout before events carried
+ * insert effects — exactly as the adapter of that version wrote it (its `effects` are not written). Frozen
+ * here so the specs can author genuine version-0 data, for the upgraders to be tested against what was
+ * actually saved rather than against the current writer.
+ *
+ * Writes the record body only: no class-name/version header (the object adapter writes that) — which is
+ * also the form the `AudioEmitter` / `AudioEventTrigger` component formats embed it in.
+ *
+ * @param {BinaryBuffer} buffer
+ * @param {BinaryObjectSerializationAdapter} objectAdapter writes the nested root clip
+ * @param {import("../definition/EventDescription.js").EventDescription} description
+ */
+export function writeEventDescriptionVersion0(buffer: BinaryBuffer, objectAdapter: BinaryObjectSerializationAdapter, description: import("../definition/EventDescription.js").EventDescription): void;
 import { BinaryObjectSerializationAdapter } from "../../../ecs/storage/binary/object/BinaryObjectSerializationAdapter.js";
+import { BinaryBuffer } from "../../../../core/binary/BinaryBuffer.js";
 //# sourceMappingURL=sopraSerializationHarness.d.ts.map

package/src/engine/sound/sopra/serialization/sopraSerializationHarness.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"sopraSerializationHarness.d.ts","sourceRoot":"","sources":["../../../../../../src/engine/sound/sopra/serialization/sopraSerializationHarness.js"],"names":[],"mappings":"AAKA;;;;GAIG;AACH,0CAFa,gCAAgC,CAW5C;AAED;;;;;;;;;;;;;;GAcG;AACH,kDAJW,gCAAgC;;YAER,OAAO;EAczC;iDA/CgD,wEAAwE"}
+{"version":3,"file":"sopraSerializationHarness.d.ts","sourceRoot":"","sources":["../../../../../../src/engine/sound/sopra/serialization/sopraSerializationHarness.js"],"names":[],"mappings":"AAMA;;;;GAIG;AACH,0CAFa,gCAAgC,CAW5C;AAED;;;;;;;;;;;;;;GAcG;AACH,kDAJW,gCAAgC;;YAER,OAAO;EAczC;AAED;;;;;;;;;;;;GAYG;AACH,sDAJW,YAAY,iBACZ,gCAAgC,eAChC,OAAO,mCAAmC,EAAE,gBAAgB,QAkBtE;iDA9EgD,wEAAwE;6BAF5F,yCAAyC"}

package/src/engine/sound/sopra/serialization/sopraSerializationHarness.js

@@ -1,4 +1,5 @@
 import { BinaryBuffer } from "../../../../core/binary/BinaryBuffer.js";
+import { serialize_animation_curve } from "../../../animation/curve/animation_curve_binary_codec.js";
 import { BinaryObjectSerializationAdapter } from "../../../ecs/storage/binary/object/BinaryObjectSerializationAdapter.js";
 import { BinarySerializationRegistry } from "../../../ecs/storage/binary/BinarySerializationRegistry.js";
 import { populateSopraSerializationRegistry } from "./populateSopraSerializationRegistry.js";
@@ -47,3 +48,34 @@ export function binaryRoundTrip(objectAdapter, value) {
 
     return { restored, stable: second.toHexString() === firstHex };
 }
+
+/**
+ * Write `description` in `EventDescription`'s binary format VERSION 0 — the layout before events carried
+ * insert effects — exactly as the adapter of that version wrote it (its `effects` are not written). Frozen
+ * here so the specs can author genuine version-0 data, for the upgraders to be tested against what was
+ * actually saved rather than against the current writer.
+ *
+ * Writes the record body only: no class-name/version header (the object adapter writes that) — which is
+ * also the form the `AudioEmitter` / `AudioEventTrigger` component formats embed it in.
+ *
+ * @param {BinaryBuffer} buffer
+ * @param {BinaryObjectSerializationAdapter} objectAdapter writes the nested root clip
+ * @param {import("../definition/EventDescription.js").EventDescription} description
+ */
+export function writeEventDescriptionVersion0(buffer, objectAdapter, description) {
+    buffer.writeUTF8String(description.label);
+    objectAdapter.serialize(buffer, description.rootClip);
+    buffer.writeUTF8String(description.busId);
+    buffer.writeFloat32(description.gainDb);
+    buffer.writeUint8(description.is3D ? 1 : 0);
+    buffer.writeUint8(description.panningModel);
+    buffer.writeFloat32(description.distanceMin);
+    buffer.writeFloat32(description.distanceMax);
+
+    serialize_animation_curve(buffer, description.attenuation);
+
+    buffer.writeUintVar(description.maxInstances);
+    buffer.writeFloat32(description.priority);
+    buffer.writeUint8(description.stealMode);
+    buffer.writeFloat32(description.virtualThresholdDb);
+}

package/src/engine/sound/sopra/util/MockAudioContext.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"MockAudioContext.d.ts","sourceRoot":"","sources":["../../../../../../src/engine/sound/sopra/util/MockAudioContext.js"],"names":[],"mappings":"AAOA;IAOI;;;OAGG;IACH,oBAHW,MAAM,0BACN,OAAO,EAWjB;IAlBD;;OAEG;IACH,QAFU;QAAC,IAAI,EAAC,MAAM,CAAA;KAAC,EAAE,CAEb;IAOR,cAAkB;IAGd,yCAGC;IAIT,4CAIC;IAED,qDAMC;IAED,0DAQC;IAED,qEAGC;IAED,qEAGC;IAED,uCAGC;CACJ;AAoCD;IAMI;;OAEG;IACH,wCAFW;QAAC,qBAAqB,CAAC,EAAC,OAAO,CAAA;KAAC,EAM1C;IAXD,oBAAgB;IAEhB,mBAAmB;IAMf,+BAAkD;IAElD,2BAAyD;IAG7D;;OAEG;IACH,gBAEC;IAED,4BAIC;IAED,oCAsBC;IAED,oCAOC;IAED,0CAQC;IAED,8BAYC;IAED,iCAKC;IAED;;OAEG;IACH,qCAFW,MAAM,iBAMhB;IAED;;;;OAIG;IACH,+BAJW,MAAM,UACN,MAAM,cACN,MAAM;;;;;;MAehB;CACJ;AA1JD;IASI,qCAGC;IAVD;;OAEG;IACH,aAFU,aAAa,EAAE,CAER;IAEjB,sBAAqB;IAGjB,UAAgB;IAChB,aAAsB;IAG1B,0BAIC;IAED,mBAGC;IAED;;;OAGG;IACH,sBAHW,aAAa,GACX,OAAO,CAInB;CACJ"}
+{"version":3,"file":"MockAudioContext.d.ts","sourceRoot":"","sources":["../../../../../../src/engine/sound/sopra/util/MockAudioContext.js"],"names":[],"mappings":"AAOA;IAOI;;;OAGG;IACH,oBAHW,MAAM,0BACN,OAAO,EAWjB;IAlBD;;OAEG;IACH,QAFU;QAAC,IAAI,EAAC,MAAM,CAAA;KAAC,EAAE,CAEb;IAOR,cAAkB;IAGd,yCAGC;IAIT,4CAIC;IAED,qDAMC;IAED,0DAQC;IAED,qEAGC;IAED,qEAGC;IAED,uCAGC;CACJ;AAoCD;IAMI;;OAEG;IACH,wCAFW;QAAC,qBAAqB,CAAC,EAAC,OAAO,CAAA;KAAC,EAM1C;IAXD,oBAAgB;IAEhB,mBAAmB;IAMf,+BAAkD;IAElD,2BAAyD;IAG7D;;OAEG;IACH,gBAEC;IAED,4BAIC;IAED,oCAsBC;IAED,oCAOC;IAED,0CAQC;IAED,8BAeC;IAED,iCAKC;IAED;;OAEG;IACH,qCAFW,MAAM,iBAMhB;IAED;;;;OAIG;IACH,+BAJW,MAAM,UACN,MAAM,cACN,MAAM;;;;;;MAehB;CACJ;AA7JD;IASI,qCAGC;IAVD;;OAEG;IACH,aAFU,aAAa,EAAE,CAER;IAEjB,sBAAqB;IAGjB,UAAgB;IAChB,aAAsB;IAG1B,0BAIC;IAED,mBAGC;IAED;;;OAGG;IACH,sBAHW,aAAa,GACX,OAAO,CAInB;CACJ"}

package/src/engine/sound/sopra/util/MockAudioContext.js

@@ -180,8 +180,11 @@ export class MockAudioContext {
         node.refDistance = 1;
         node.maxDistance = 10000;
         node.lastPosition = null;
+        // every position the panner was handed, in order, as a param records its automation
+        node.positions = [];
         node.setPosition = (x, y, z) => {
             node.lastPosition = { x, y, z };
+            node.positions.push(node.lastPosition);
         };
         return node;
     }

package/src/engine/sound/sopra/util/fadeOutAndStop.d.ts

@@ -1,8 +1,18 @@
+/**
+ * Cancel every automation event on `param` from `time` on, holding the value the automation has at `time` —
+ * so whatever is scheduled next starts from where the param actually is, not from where an interrupted ramp
+ * or glide was heading. The one place the engine does this: `cancelAndHoldAtTime` where the browser has it
+ * (it is unimplemented in Firefox), else the portable `cancelScheduledValues` + anchor at the current
+ * value.
+ *
+ * @param {AudioParam} param
+ * @param {number} time context time
+ */
+export function cancelAndHold(param: AudioParam, time: number): void;
 /**
  * The ONE click-safe gain ramp. Anchor-then-ramp: pin the current value at the ramp start so the
- * origin is well-defined and re-trigger-safe (D1). Prefers `cancelAndHoldAtTime` but FEATURE-DETECTS
- * it (unimplemented in Firefox) and falls back to the portable `cancelScheduledValues` +
- * `setValueAtTime` idiom. Linear-ramps to `targetLinear` (use {@link FADE_EPSILON}, never 0, for fades
+ * origin is well-defined and re-trigger-safe (D1), through {@link cancelAndHold}. Linear-ramps to
+ * `targetLinear` (use {@link FADE_EPSILON}, never 0, for fades
  * to silence). Shared by every fade so no call site hand-rolls one.
  *
  * @param {AudioParam} param the gain param to ramp

package/src/engine/sound/sopra/util/fadeOutAndStop.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"fadeOutAndStop.d.ts","sourceRoot":"","sources":["../../../../../../src/engine/sound/sopra/util/fadeOutAndStop.js"],"names":[],"mappings":"AAQA;;;;;;;;;;;;;GAaG;AACH,gCAPW,UAAU,gBACV,MAAM,YACN,MAAM,OACN,gBAAgB,eAChB,MAAM,GACJ,MAAM,CAoBlB;AAED;;;;;;;;;GASG;AACH,yCANW,QAAQ,UACR,wBAAwB,GAAC,IAAI,OAC7B,gBAAgB,YAChB,MAAM,eACN,MAAM,QAShB;AA3DD;;;;;GAKG;AACH,2BAFU,MAAM,CAEmB"}
+{"version":3,"file":"fadeOutAndStop.d.ts","sourceRoot":"","sources":["../../../../../../src/engine/sound/sopra/util/fadeOutAndStop.js"],"names":[],"mappings":"AAQA;;;;;;;;;GASG;AACH,qCAHW,UAAU,QACV,MAAM,QAYhB;AAED;;;;;;;;;;;;GAYG;AACH,gCAPW,UAAU,gBACV,MAAM,YACN,MAAM,OACN,gBAAgB,eAChB,MAAM,GACJ,MAAM,CAWlB;AAED;;;;;;;;;GASG;AACH,yCANW,QAAQ,UACR,wBAAwB,GAAC,IAAI,OAC7B,gBAAgB,YAChB,MAAM,eACN,MAAM,QAShB;AAvED;;;;;GAKG;AACH,2BAFU,MAAM,CAEmB"}

package/src/engine/sound/sopra/util/fadeOutAndStop.js

@@ -6,11 +6,32 @@
  */
 export const FADE_EPSILON = 0.0001;
 
+/**
+ * Cancel every automation event on `param` from `time` on, holding the value the automation has at `time` —
+ * so whatever is scheduled next starts from where the param actually is, not from where an interrupted ramp
+ * or glide was heading. The one place the engine does this: `cancelAndHoldAtTime` where the browser has it
+ * (it is unimplemented in Firefox), else the portable `cancelScheduledValues` + anchor at the current
+ * value.
+ *
+ * @param {AudioParam} param
+ * @param {number} time context time
+ */
+export function cancelAndHold(param, time) {
+    if (typeof param.cancelAndHoldAtTime === "function") {
+        param.cancelAndHoldAtTime(time);
+    } else {
+        // read before cancelling: the anchor is the value the param holds now
+        const value = param.value;
+
+        param.cancelScheduledValues(time);
+        param.setValueAtTime(value, time);
+    }
+}
+
 /**
  * The ONE click-safe gain ramp. Anchor-then-ramp: pin the current value at the ramp start so the
- * origin is well-defined and re-trigger-safe (D1). Prefers `cancelAndHoldAtTime` but FEATURE-DETECTS
- * it (unimplemented in Firefox) and falls back to the portable `cancelScheduledValues` +
- * `setValueAtTime` idiom. Linear-ramps to `targetLinear` (use {@link FADE_EPSILON}, never 0, for fades
+ * origin is well-defined and re-trigger-safe (D1), through {@link cancelAndHold}. Linear-ramps to
+ * `targetLinear` (use {@link FADE_EPSILON}, never 0, for fades
  * to silence). Shared by every fade so no call site hand-rolls one.
  *
  * @param {AudioParam} param the gain param to ramp
@@ -24,16 +45,7 @@ export function rampGain(param, targetLinear, duration, ctx, startAfter = 0) {
     const startTime = ctx.currentTime + startAfter;
     const endTime = startTime + duration;
 
-    const currentValue = param.value;
-
-    if (typeof param.cancelAndHoldAtTime === "function") {
-        // holds the current automation value at startTime, discarding later scheduled events
-        param.cancelAndHoldAtTime(startTime);
-    } else {
-        // portable fallback (Firefox): clear future events then explicitly anchor the value
-        param.cancelScheduledValues(startTime);
-        param.setValueAtTime(currentValue, startTime);
-    }
+    cancelAndHold(param, startTime);
 
     param.linearRampToValueAtTime(targetLinear, endTime);