@woosh/meep-engine 2.163.10 → 2.164.0

package/src/engine/sound/simulation/render/ProbeReverbRenderer.js

@@ -0,0 +1,231 @@
+import { seededRandom } from "../../../../core/math/random/seededRandom.js";
+import { FADE_EPSILON, rampGain } from "../../sopra/util/fadeOutAndStop.js";
+import { reverbImpulseResponse } from "./reverbImpulseResponse.js";
+
+/**
+ * An acoustic-owned reverb send bus, separate from sopra's static `ReverbEffect` (which is left
+ * untouched). Renders the probe-baked reverb: each frame {@link update} reads the nearest probe's decay
+ * at the listener and, when it changes meaningfully, re-bakes the IR into the INACTIVE of a
+ * double-buffered `ConvolverNode` pair and equal-power crossfades to it — so crossing probe cells does
+ * not click.
+ *
+ * Graph: `input → [convolverA → wetA, convolverB → wetB] → output → destination`. Sources / a sopra bus
+ * send a post-fader copy into {@link input}; {@link output} mixes into the destination. WebAudio-touching
+ * but ECS-agnostic.
+ *
+ * Tunables are plain settable fields (no opaque config bag).
+ */
+export class ProbeReverbRenderer {
+    /**
+     * IR envelope exponent (higher = faster fade).
+     * @type {number}
+     */
+    decayPower = 2;
+
+    /**
+     * Crossfade duration (seconds) when the reverb changes — long enough to be click-free.
+     * @type {number}
+     */
+    crossfadeSeconds = 0.5;
+
+    /**
+     * Minimum change in decay (seconds) that triggers a re-bake + crossfade — avoids churning the
+     * convolver on tiny listener moves.
+     * @type {number}
+     */
+    changeThreshold = 0.1;
+
+    /**
+     * Decay below this (seconds) is treated as "no reverb": the wet level crossfades to 0.
+     * @type {number}
+     */
+    minDecay = 0.05;
+
+    /**
+     * @type {BaseAudioContext}
+     */
+    #ctx;
+
+    /**
+     * @type {GainNode}
+     */
+    #input;
+
+    /**
+     * @type {GainNode}
+     */
+    #output;
+
+    /**
+     * @type {ConvolverNode[]}
+     */
+    #convolvers;
+
+    /**
+     * @type {GainNode[]} per-convolver wet gains (the crossfade)
+     */
+    #wets;
+
+    /**
+     * Index (0/1) of the currently-audible convolver.
+     * @type {number}
+     */
+    #active = 0;
+
+    /**
+     * Current wet target (1 = audible, 0 = silent) — tracked so an audible/silent flip across `minDecay`
+     * is never swallowed by the band re-bake hysteresis. Starts 0 (the wets are built silent).
+     * @type {number}
+     */
+    #currentWet = 0;
+
+    /**
+     * Per-band RT60 (seconds) of the currently-rendered IR; `[-1,-1,-1]` until the first bake.
+     * @type {Float32Array}
+     */
+    #currentBands = new Float32Array([-1, -1, -1]);
+
+    /**
+     * Reused scratch for the per-frame band fetch from the probe field (allocation-free `update`).
+     * @type {Float32Array}
+     */
+    #scratchBands = new Float32Array(3);
+
+    /**
+     * @type {function():number}
+     */
+    #random = seededRandom(1);
+
+    /**
+     * @type {AcousticProbeField|null}
+     */
+    #probeField = null;
+
+    /**
+     * @param {BaseAudioContext} audioContext
+     * @param {AudioNode} destination where the wet output mixes (e.g. the master / engine destination)
+     */
+    constructor(audioContext, destination) {
+        this.#ctx = audioContext;
+
+        const ctx = audioContext;
+
+        this.#input = ctx.createGain();
+        this.#output = ctx.createGain();
+
+        const convolverA = ctx.createConvolver();
+        const convolverB = ctx.createConvolver();
+        convolverA.normalize = true;
+        convolverB.normalize = true;
+
+        const wetA = ctx.createGain();
+        const wetB = ctx.createGain();
+        wetA.gain.setValueAtTime(0, 0);
+        wetB.gain.setValueAtTime(0, 0);
+
+        this.#input.connect(convolverA);
+        this.#input.connect(convolverB);
+        convolverA.connect(wetA);
+        convolverB.connect(wetB);
+        wetA.connect(this.#output);
+        wetB.connect(this.#output);
+        this.#output.connect(destination);
+
+        this.#convolvers = [convolverA, convolverB];
+        this.#wets = [wetA, wetB];
+    }
+
+    /**
+     * The node sources / a sopra bus send their post-fader copy into.
+     * @returns {AudioNode}
+     */
+    get input() {
+        return this.#input;
+    }
+
+    /**
+     * The wet output (already connected to the destination).
+     * @returns {AudioNode}
+     */
+    get output() {
+        return this.#output;
+    }
+
+    /**
+     * @param {AcousticProbeField} probeField the baked probe volume the reverb reads from
+     */
+    setProbeField(probeField) {
+        this.#probeField = probeField;
+    }
+
+    /**
+     * Drive the reverb from the listener position via the bound probe field. No-op if no field is set.
+     * @param {number} x
+     * @param {number} y
+     * @param {number} z
+     */
+    update(x, y, z) {
+        if (this.#probeField === null) {
+            return;
+        }
+
+        this.#probeField.reverbBandsAt(x, y, z, this.#scratchBands);
+        this.setBands(this.#scratchBands);
+    }
+
+    /**
+     * Set the reverb decay as a single broadband RT60 (broadcast to all three bands).
+     * @param {number} decaySeconds
+     */
+    setDecay(decaySeconds) {
+        this.#scratchBands[0] = decaySeconds;
+        this.#scratchBands[1] = decaySeconds;
+        this.#scratchBands[2] = decaySeconds;
+        this.setBands(this.#scratchBands);
+    }
+
+    /**
+     * Set the per-band reverb RT60 `[low, mid, high]`, crossfading the convolver pair if it changed
+     * meaningfully. Below `minDecay` (loudest band) the reverb fades toward silence.
+     * @param {Float32Array|number[]} bands per-band RT60 seconds
+     */
+    setBands(bands) {
+        const current = this.#currentBands;
+
+        const maxDecay = Math.max(bands[0], bands[1], bands[2]);
+        const targetWet = maxDecay >= this.minDecay ? 1 : 0;
+
+        const bandsClose = Math.abs(bands[0] - current[0]) < this.changeThreshold
+            && Math.abs(bands[1] - current[1]) < this.changeThreshold
+            && Math.abs(bands[2] - current[2]) < this.changeThreshold;
+
+        // Re-bake/crossfade unless BOTH the IR is unchanged (sub-threshold band move) AND the audible/
+        // silent state is unchanged. Gating only on `bandsClose` would swallow a `minDecay` crossing
+        // smaller than `changeThreshold` (changeThreshold 0.1 > minDecay 0.05) — leaving the reverb stuck
+        // on or off across that boundary.
+        if (bandsClose && targetWet === this.#currentWet) {
+            return;
+        }
+
+        current[0] = bands[0];
+        current[1] = bands[1];
+        current[2] = bands[2];
+        this.#currentWet = targetWet;
+
+        const inactive = 1 - this.#active;
+
+        if (targetWet > 0) {
+            this.#convolvers[inactive].buffer = reverbImpulseResponse(
+                this.#ctx, bands, this.decayPower, this.#random
+            );
+        }
+
+        // crossfade via the shared click-safe ramp (anchors the in-progress fade with cancelAndHoldAtTime
+        // where available, so crossing a probe cell mid-fade doesn't snap). Fade to FADE_EPSILON, never 0.
+        const cf = this.crossfadeSeconds;
+        rampGain(this.#wets[this.#active].gain, FADE_EPSILON, cf, this.#ctx);
+        rampGain(this.#wets[inactive].gain, targetWet > 0 ? 1 : FADE_EPSILON, cf, this.#ctx);
+
+        this.#active = inactive;
+    }
+}

package/src/engine/sound/simulation/render/foaReverbImpulseResponse.d.ts

@@ -0,0 +1,37 @@
+/**
+ * Build a first-order ambisonic (FOA / B-format) reverb impulse response — four MONO `AudioBuffer`s
+ * `{w, x, y, z}` — from a probe's per-band RT60 `[low, mid, high]` and per-band arrival direction
+ * (`directions`, band-major xyz, the 0…1 anisotropy vectors {@link bakeReverbBands} produces). Driven by a
+ * SEEDED rng (reproducible).
+ *
+ * The synthesis mirrors {@link reverbImpulseResponse}: one white-noise stream is split into three bands
+ * (one-pole filters) and each band is given its own exponential decay envelope (a band rings for its RT60).
+ * `w` is the omni sum of the enveloped bands — identical to the scalar mono tail. The directional channels
+ * are the SAME enveloped bands weighted by each band's arrival-direction component:
+ *
+ *   `x[i] = Σ_band bandTail[band][i] · directionX[band]`   (likewise `y`, `z`)
+ *
+ * so the B-format channels are CORRELATED with `w` and scaled by the per-band anisotropy. A first-order
+ * decode (`0.5·W + 0.5·(look · XYZ)`) then renders the tail louder toward each band's arrival direction and
+ * nulled away from it; a diffuse band (zero direction) contributes only to `w` and images centred. Energy
+ * is conserved — `x/y/z` carry no extra tail, only a re-weighting of `w`'s.
+ *
+ * The four buffers must drive convolvers with `normalize = false`: per-channel normalisation would erase the
+ * `w`-vs-`xyz` magnitude relationship that encodes the direction. Instead all four channels are scaled by a
+ * SINGLE factor (to unit `w` energy) so reverb loudness is RT60-independent — the `ConvolverNode`
+ * `normalize` behaviour the scalar path gets — without disturbing the directional ratio.
+ *
+ * @param {BaseAudioContext} ctx
+ * @param {Float32Array|number[]} decayBands per-band RT60 seconds `[low, mid, high]`
+ * @param {Float32Array|number[]} directions per-band arrival direction, band-major xyz (length 9)
+ * @param {number} decayPower envelope exponent (higher = faster fade)
+ * @param {function():number} random seeded RNG in [0, 1)
+ * @returns {{w:AudioBuffer, x:AudioBuffer, y:AudioBuffer, z:AudioBuffer}}
+ */
+export function foaReverbImpulseResponse(ctx: BaseAudioContext, decayBands: Float32Array | number[], directions: Float32Array | number[], decayPower: number, random: () => number): {
+    w: AudioBuffer;
+    x: AudioBuffer;
+    y: AudioBuffer;
+    z: AudioBuffer;
+};
+//# sourceMappingURL=foaReverbImpulseResponse.d.ts.map

package/src/engine/sound/simulation/render/foaReverbImpulseResponse.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"foaReverbImpulseResponse.d.ts","sourceRoot":"","sources":["../../../../../../src/engine/sound/simulation/render/foaReverbImpulseResponse.js"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH,8CAPW,gBAAgB,cAChB,YAAY,GAAC,MAAM,EAAE,cACrB,YAAY,GAAC,MAAM,EAAE,cACrB,MAAM,gBACK,MAAM;OACZ,WAAW;OAAI,WAAW;OAAI,WAAW;OAAI,WAAW;EAkFvE"}

package/src/engine/sound/simulation/render/foaReverbImpulseResponse.js

@@ -0,0 +1,113 @@
+import { LOW_MID_HZ, MID_HIGH_HZ } from "./reverbImpulseResponse.js";
+
+/**
+ * Build a first-order ambisonic (FOA / B-format) reverb impulse response — four MONO `AudioBuffer`s
+ * `{w, x, y, z}` — from a probe's per-band RT60 `[low, mid, high]` and per-band arrival direction
+ * (`directions`, band-major xyz, the 0…1 anisotropy vectors {@link bakeReverbBands} produces). Driven by a
+ * SEEDED rng (reproducible).
+ *
+ * The synthesis mirrors {@link reverbImpulseResponse}: one white-noise stream is split into three bands
+ * (one-pole filters) and each band is given its own exponential decay envelope (a band rings for its RT60).
+ * `w` is the omni sum of the enveloped bands — identical to the scalar mono tail. The directional channels
+ * are the SAME enveloped bands weighted by each band's arrival-direction component:
+ *
+ *   `x[i] = Σ_band bandTail[band][i] · directionX[band]`   (likewise `y`, `z`)
+ *
+ * so the B-format channels are CORRELATED with `w` and scaled by the per-band anisotropy. A first-order
+ * decode (`0.5·W + 0.5·(look · XYZ)`) then renders the tail louder toward each band's arrival direction and
+ * nulled away from it; a diffuse band (zero direction) contributes only to `w` and images centred. Energy
+ * is conserved — `x/y/z` carry no extra tail, only a re-weighting of `w`'s.
+ *
+ * The four buffers must drive convolvers with `normalize = false`: per-channel normalisation would erase the
+ * `w`-vs-`xyz` magnitude relationship that encodes the direction. Instead all four channels are scaled by a
+ * SINGLE factor (to unit `w` energy) so reverb loudness is RT60-independent — the `ConvolverNode`
+ * `normalize` behaviour the scalar path gets — without disturbing the directional ratio.
+ *
+ * @param {BaseAudioContext} ctx
+ * @param {Float32Array|number[]} decayBands per-band RT60 seconds `[low, mid, high]`
+ * @param {Float32Array|number[]} directions per-band arrival direction, band-major xyz (length 9)
+ * @param {number} decayPower envelope exponent (higher = faster fade)
+ * @param {function():number} random seeded RNG in [0, 1)
+ * @returns {{w:AudioBuffer, x:AudioBuffer, y:AudioBuffer, z:AudioBuffer}}
+ */
+export function foaReverbImpulseResponse(
+    ctx,
+    decayBands,
+    directions,
+    decayPower,
+    random
+) {
+
+    const sampleRate = ctx.sampleRate;
+
+    const lenLow = Math.max(1, Math.floor(decayBands[0] * sampleRate));
+    const lenMid = Math.max(1, Math.floor(decayBands[1] * sampleRate));
+    const lenHigh = Math.max(1, Math.floor(decayBands[2] * sampleRate));
+    const length = Math.max(lenLow, lenMid, lenHigh);
+
+    const w = ctx.createBuffer(1, length, sampleRate);
+    const x = ctx.createBuffer(1, length, sampleRate);
+    const y = ctx.createBuffer(1, length, sampleRate);
+    const z = ctx.createBuffer(1, length, sampleRate);
+
+    const wData = w.getChannelData(0);
+    const xData = x.getChannelData(0);
+    const yData = y.getChannelData(0);
+    const zData = z.getChannelData(0);
+
+    // per-band X/Y/Z arrival-direction components (band-major xyz)
+    const dxLow = directions[0], dyLow = directions[1], dzLow = directions[2];
+    const dxMid = directions[3], dyMid = directions[4], dzMid = directions[5];
+    const dxHigh = directions[6], dyHigh = directions[7], dzHigh = directions[8];
+
+    // one-pole smoothing coefficients for the band split: a = 1 − e^(−2π f / fs)
+    const aLow = 1 - Math.exp((-2 * Math.PI * LOW_MID_HZ) / sampleRate);
+    const aHigh = 1 - Math.exp((-2 * Math.PI * MID_HIGH_HZ) / sampleRate);
+
+    let lpLow = 0;
+    let lpHigh = 0;
+    let sumSqW = 0;
+
+    for (let i = 0; i < length; i++) {
+
+        const noise = random() * 2 - 1;
+
+        lpLow += aLow * (noise - lpLow);
+        lpHigh += aHigh * (noise - lpHigh);
+
+        // energy-preserving 3-way split: low + mid + high == noise
+        const low = lpLow;
+        const mid = lpHigh - lpLow;
+        const high = noise - lpHigh;
+
+        const envLow = i < lenLow ? Math.pow(1 - i / lenLow, decayPower) : 0;
+        const envMid = i < lenMid ? Math.pow(1 - i / lenMid, decayPower) : 0;
+        const envHigh = i < lenHigh ? Math.pow(1 - i / lenHigh, decayPower) : 0;
+
+        // each band's enveloped sample, shared by the omni and directional channels
+        const bLow = low * envLow;
+        const bMid = mid * envMid;
+        const bHigh = high * envHigh;
+
+        const wSample = bLow + bMid + bHigh;
+        wData[i] = wSample;
+        xData[i] = bLow * dxLow + bMid * dxMid + bHigh * dxHigh;
+        yData[i] = bLow * dyLow + bMid * dyMid + bHigh * dyHigh;
+        zData[i] = bLow * dzLow + bMid * dzMid + bHigh * dzHigh;
+
+        sumSqW += wSample * wSample;
+    }
+
+    // scale all four channels by one factor → unit-energy W (RT60-independent loudness), directional ratio kept
+    if (sumSqW > 0) {
+        const norm = 1 / Math.sqrt(sumSqW);
+        for (let i = 0; i < length; i++) {
+            wData[i] *= norm;
+            xData[i] *= norm;
+            yData[i] *= norm;
+            zData[i] *= norm;
+        }
+    }
+
+    return { w, x, y, z };
+}

package/src/engine/sound/simulation/render/reverbImpulseResponse.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Generate a stereo reverb impulse response from a PER-BAND decay time `[low, mid, high]` (the probe-baked
+ * RT60s). White noise is split into three bands (one-pole filters), each given its OWN exponential decay
+ * envelope (a band rings for its band's RT60, then falls silent), and the bands are summed — so a room
+ * whose highs die quickly produces a tail that darkens over time (room timbre), not a flat decaying hiss.
+ * Driven by a SEEDED rng (never `Math.random`, so a bake is reproducible). Returned as an `AudioBuffer`
+ * ready to assign to a `ConvolverNode.buffer`.
+ *
+ * With three equal bands this reduces to the plain scalar tail (the band split reconstructs the noise).
+ *
+ * @param {BaseAudioContext} ctx
+ * @param {Float32Array|number[]} decayBands per-band RT60 seconds `[low, mid, high]`
+ * @param {number} decayPower envelope exponent (higher = faster fade)
+ * @param {function():number} random seeded RNG in [0, 1)
+ * @returns {AudioBuffer}
+ */
+export function reverbImpulseResponse(ctx: BaseAudioContext, decayBands: Float32Array | number[], decayPower: number, random: () => number): AudioBuffer;
+/**
+ * Band split frequencies (Hz): low | mid below this, mid | high below the second. Crude one-pole splits —
+ * enough to give the reverb tail per-band timbre (a bright vs. dead room), it is decaying noise, not a
+ * precise crossover. Exported so the directional ({@link foaReverbImpulseResponse}) path splits identically.
+ * @type {number}
+ */
+export const LOW_MID_HZ: number;
+export const MID_HIGH_HZ: 2500;
+//# sourceMappingURL=reverbImpulseResponse.d.ts.map

package/src/engine/sound/simulation/render/reverbImpulseResponse.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"reverbImpulseResponse.d.ts","sourceRoot":"","sources":["../../../../../../src/engine/sound/simulation/render/reverbImpulseResponse.js"],"names":[],"mappings":"AASA;;;;;;;;;;;;;;;GAeG;AACH,2CANW,gBAAgB,cAChB,YAAY,GAAC,MAAM,EAAE,cACrB,MAAM,gBACK,MAAM,GACf,WAAW,CAoDvB;AA3ED;;;;;GAKG;AACH,yBAFU,MAAM,CAEc;AAC9B,+BAAgC"}

package/src/engine/sound/simulation/render/reverbImpulseResponse.js

@@ -0,0 +1,76 @@
+/**
+ * Band split frequencies (Hz): low | mid below this, mid | high below the second. Crude one-pole splits —
+ * enough to give the reverb tail per-band timbre (a bright vs. dead room), it is decaying noise, not a
+ * precise crossover. Exported so the directional ({@link foaReverbImpulseResponse}) path splits identically.
+ * @type {number}
+ */
+export const LOW_MID_HZ = 250;
+export const MID_HIGH_HZ = 2500;
+
+/**
+ * Generate a stereo reverb impulse response from a PER-BAND decay time `[low, mid, high]` (the probe-baked
+ * RT60s). White noise is split into three bands (one-pole filters), each given its OWN exponential decay
+ * envelope (a band rings for its band's RT60, then falls silent), and the bands are summed — so a room
+ * whose highs die quickly produces a tail that darkens over time (room timbre), not a flat decaying hiss.
+ * Driven by a SEEDED rng (never `Math.random`, so a bake is reproducible). Returned as an `AudioBuffer`
+ * ready to assign to a `ConvolverNode.buffer`.
+ *
+ * With three equal bands this reduces to the plain scalar tail (the band split reconstructs the noise).
+ *
+ * @param {BaseAudioContext} ctx
+ * @param {Float32Array|number[]} decayBands per-band RT60 seconds `[low, mid, high]`
+ * @param {number} decayPower envelope exponent (higher = faster fade)
+ * @param {function():number} random seeded RNG in [0, 1)
+ * @returns {AudioBuffer}
+ */
+export function reverbImpulseResponse(
+    ctx,
+    decayBands,
+    decayPower,
+    random
+) {
+
+    const sampleRate = ctx.sampleRate;
+
+    const lenLow = Math.max(1, Math.floor(decayBands[0] * sampleRate));
+    const lenMid = Math.max(1, Math.floor(decayBands[1] * sampleRate));
+    const lenHigh = Math.max(1, Math.floor(decayBands[2] * sampleRate));
+    const length = Math.max(lenLow, lenMid, lenHigh);
+
+    const ir = ctx.createBuffer(2, length, sampleRate);
+
+    // one-pole smoothing coefficients for the band split: a = 1 − e^(−2π f / fs)
+    const aLow = 1 - Math.exp((-2 * Math.PI * LOW_MID_HZ) / sampleRate);
+    const aHigh = 1 - Math.exp((-2 * Math.PI * MID_HIGH_HZ) / sampleRate);
+
+    const channel_count = ir.numberOfChannels;
+
+    for (let channel = 0; channel < channel_count; channel++) {
+        const data = ir.getChannelData(channel);
+
+        let lpLow = 0;
+        let lpHigh = 0;
+
+        for (let i = 0; i < length; i++) {
+
+            const noise = random() * 2 - 1;
+
+            lpLow += aLow * (noise - lpLow);
+            lpHigh += aHigh * (noise - lpHigh);
+
+            // energy-preserving 3-way split: low + mid + high == noise
+            const low = lpLow;
+            const mid = lpHigh - lpLow;
+            const high = noise - lpHigh;
+
+            const envLow = i < lenLow ? Math.pow(1 - i / lenLow, decayPower) : 0;
+            const envMid = i < lenMid ? Math.pow(1 - i / lenMid, decayPower) : 0;
+            const envHigh = i < lenHigh ? Math.pow(1 - i / lenHigh, decayPower) : 0;
+
+            data[i] = low * envLow + mid * envMid + high * envHigh;
+
+        }
+    }
+
+    return ir;
+}

package/src/engine/sound/simulation/serialization/populateAcousticSerializationRegistry.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Register every acoustic-simulation binary serialization adapter into `registry` — the value types
+ * ({@link AcousticMaterial}, {@link AcousticMedium}, {@link AcousticDirectivity}) and the components
+ * ({@link AcousticBody}, {@link AcousticVolume}, {@link AcousticProbeField}). Call this when wiring save/load
+ * for a config that uses the acoustic simulation (mirrors `populateSopraSerializationRegistry`).
+ *
+ * @param {BinarySerializationRegistry} registry
+ */
+export function populateAcousticSerializationRegistry(registry: BinarySerializationRegistry): void;
+//# sourceMappingURL=populateAcousticSerializationRegistry.d.ts.map

package/src/engine/sound/simulation/serialization/populateAcousticSerializationRegistry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"populateAcousticSerializationRegistry.d.ts","sourceRoot":"","sources":["../../../../../../src/engine/sound/simulation/serialization/populateAcousticSerializationRegistry.js"],"names":[],"mappings":"AAOA;;;;;;;GAOG;AACH,mGASC"}

package/src/engine/sound/simulation/serialization/populateAcousticSerializationRegistry.js

@@ -0,0 +1,25 @@
+import { AcousticMediumSerializationAdapter } from "../core/AcousticMediumSerializationAdapter.js";
+import { AcousticDirectivitySerializationAdapter } from "../definition/AcousticDirectivitySerializationAdapter.js";
+import { AcousticMaterialSerializationAdapter } from "../definition/AcousticMaterialSerializationAdapter.js";
+import { AcousticBodySerializationAdapter } from "../ecs/AcousticBodySerializationAdapter.js";
+import { AcousticVolumeSerializationAdapter } from "../ecs/AcousticVolumeSerializationAdapter.js";
+import { AcousticProbeFieldSerializationAdapter } from "../probe/AcousticProbeFieldSerializationAdapter.js";
+
+/**
+ * Register every acoustic-simulation binary serialization adapter into `registry` — the value types
+ * ({@link AcousticMaterial}, {@link AcousticMedium}, {@link AcousticDirectivity}) and the components
+ * ({@link AcousticBody}, {@link AcousticVolume}, {@link AcousticProbeField}). Call this when wiring save/load
+ * for a config that uses the acoustic simulation (mirrors `populateSopraSerializationRegistry`).
+ *
+ * @param {BinarySerializationRegistry} registry
+ */
+export function populateAcousticSerializationRegistry(registry) {
+    registry.registerAdapters([
+        new AcousticMaterialSerializationAdapter(),
+        new AcousticMediumSerializationAdapter(),
+        new AcousticDirectivitySerializationAdapter(),
+        new AcousticBodySerializationAdapter(),
+        new AcousticVolumeSerializationAdapter(),
+        new AcousticProbeFieldSerializationAdapter()
+    ]);
+}

package/src/engine/sound/sopra/SopraEngine.d.ts

@@ -70,6 +70,12 @@ export class SopraEngine {
      * @returns {number} current context time (the engine's authoritative clock)
      */
     get currentTime(): number;
+    /**
+     * 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(): AudioNode;
     /**
      * Replace the mixer with a new bus tree (rebuilds the WebAudio graph).
      * @param {BusDefinition[]} busDefinitions

package/src/engine/sound/sopra/SopraEngine.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"SopraEngine.d.ts","sourceRoot":"","sources":["../../../../../src/engine/sound/sopra/SopraEngine.js"],"names":[],"mappings":";;;;8BAcU,MAAM;;;;;;;AAahB;;;;;;;GAOG;AACH;IA6EI;;;OAGG;IACH,uBAFa,aAAa,EAAE,CAS3B;IAlDD;;;;OAIG;IACH,0BAJW,gBAAgB,mBAChB,SAAS,kCA4BnB;IAlED;;OAEG;IACH,YAFU,cAAc,CAEU;IAElC;;;;OAIG;IACH,wBAFU,oBAAoB,CAEsB;IAEpD;;;OAGG;IACH,cAFU,YAAY,CAEY;IAElC;;;;OAIG;IACH,kBAFU,UAAQ,IAAI,CAEE;IAuBpB;;OAEG;IACH,cAFU,gBAAgB,CAEM;IAEhC;;OAEG;IACH,aAFU,SAAS,CAEe;IAElC;;OAEG;IACH,+BAAoC;IAEpC;;OAEG;IACH,UAFU,QAAQ,CAEyC;IAI/D;;OAEG;IACH,0BAEC;IAeD;;;OAGG;IACH,yBAFW,aAAa,EAAE,QAKzB;IAED;;;;;OAKG;IACH;gBAHmB,MAAM;;kBAA8B,OAAO;sBAAe,MAAM;eAAQ,MAAM;0BAAmB,oBAAoB;QAC3H,aAAa,CAOzB;IAED;;;;;OAKG;IACH,mDAHW;QAAC,KAAK,CAAC,EAAC,MAAM,CAAC;QAAC,QAAQ,CAAC,UAAS;QAAC,OAAO,CAAC,EAAC,OAAO,CAAC;QAAC,WAAW,CAAC,EAAC,MAAM,CAAC;QAAC,IAAI,CAAC,EAAC,MAAM,CAAC;QAAC,eAAe,CAAC,EAAC,oBAAoB,CAAA;KAAC,GAC5H,aAAa,CAuBzB;IAED;;;;;;OAMG;IACH,qDAHW;QAAC,KAAK,CAAC,EAAC,MAAM,CAAC;QAAC,QAAQ,CAAC,UAAS;QAAC,WAAW,CAAC,EAAC,MAAM,CAAA;KAAC,GACrD,aAAa,CAIzB;IAED;;OAEG;IACH,eAFW,aAAa,QAIvB;IAED;;;;;;;OAOG;IACH,uBALW,aAAa,GAAC,IAAI;gBAEV,MAAM;;mBAA+B,MAAM;QACjD,aAAa,GAAC,IAAI,CAmB9B;IAED;;;OAGG;IACH,mBAHW,MAAM,SACN,MAAM,QAIhB;IAED;;;OAGG;IACH,mBAHW,MAAM,GACJ,MAAM,GAAC,SAAS,CAI5B;IAED;;;OAGG;IACH,qCAEC;IAED;;;;OAIG;IACH,sBAHW,MAAM,iBACN,MAAM,QAIhB;IAED;;;;OAIG;IACH,oBAHW,MAAM,kBACG,MAAM,gBAIzB;IAED;;;;;OAKG;IACH,+BAJW,MAAM,SACN,MAAM,+BAKhB;IAED;;;OAGG;IACH,oBAHW,MAAM,GACJ,MAAM,CAIlB;IAED;;;OAGG;IACH,oBAHW,MAAM,UACN,MAAM,QAIhB;IAED;;;;;OAKG;IACH,wBAHW,aAAa,iBACb;QAAC,QAAQ,CAAC,EAAC,MAAM,CAAA;KAAC,QAe5B;IAED;;;;;OAKG;IACH,oBAJW,MAAM,UACN,MAAM,EAAE,GACN,aAAa,CAUzB;IAED;;;OAGG;IACH,aAFW,MAAM,QAahB;IAED;;;;OAIG;IACH,mCAEC;IAED;;OAEG;IACH,qBAWC;IAwCD;;OAEG;IACH,kCAEC;IAED;;;;OAIG;IACH,+BAFW,aAAa,QAKvB;;CACJ;+BA/Z8B,6BAA6B;qCACvB,mCAAmC;6BAC3C,2BAA2B;yBANd,uBAAuB;8BACnC,+BAA+B;8BAE/B,4BAA4B;8BAD5B,+BAA+B"}
+{"version":3,"file":"SopraEngine.d.ts","sourceRoot":"","sources":["../../../../../src/engine/sound/sopra/SopraEngine.js"],"names":[],"mappings":";;;;8BAcU,MAAM;;;;;;;AAahB;;;;;;;GAOG;AACH;IAsFI;;;OAGG;IACH,uBAFa,aAAa,EAAE,CAS3B;IA3DD;;;;OAIG;IACH,0BAJW,gBAAgB,mBAChB,SAAS,kCA4BnB;IAlED;;OAEG;IACH,YAFU,cAAc,CAEU;IAElC;;;;OAIG;IACH,wBAFU,oBAAoB,CAEsB;IAEpD;;;OAGG;IACH,cAFU,YAAY,CAEY;IAElC;;;;OAIG;IACH,kBAFU,UAAQ,IAAI,CAEE;IAuBpB;;OAEG;IACH,cAFU,gBAAgB,CAEM;IAEhC;;OAEG;IACH,aAFU,SAAS,CAEe;IAElC;;OAEG;IACH,+BAAoC;IAEpC;;OAEG;IACH,UAFU,QAAQ,CAEyC;IAI/D;;OAEG;IACH,0BAEC;IAED;;;;OAIG;IACH,iCAEC;IAeD;;;OAGG;IACH,yBAFW,aAAa,EAAE,QAKzB;IAED;;;;;OAKG;IACH;gBAHmB,MAAM;;kBAA8B,OAAO;sBAAe,MAAM;eAAQ,MAAM;0BAAmB,oBAAoB;QAC3H,aAAa,CAOzB;IAED;;;;;OAKG;IACH,mDAHW;QAAC,KAAK,CAAC,EAAC,MAAM,CAAC;QAAC,QAAQ,CAAC,UAAS;QAAC,OAAO,CAAC,EAAC,OAAO,CAAC;QAAC,WAAW,CAAC,EAAC,MAAM,CAAC;QAAC,IAAI,CAAC,EAAC,MAAM,CAAC;QAAC,eAAe,CAAC,EAAC,oBAAoB,CAAA;KAAC,GAC5H,aAAa,CAuBzB;IAED;;;;;;OAMG;IACH,qDAHW;QAAC,KAAK,CAAC,EAAC,MAAM,CAAC;QAAC,QAAQ,CAAC,UAAS;QAAC,WAAW,CAAC,EAAC,MAAM,CAAA;KAAC,GACrD,aAAa,CAIzB;IAED;;OAEG;IACH,eAFW,aAAa,QAIvB;IAED;;;;;;;OAOG;IACH,uBALW,aAAa,GAAC,IAAI;gBAEV,MAAM;;mBAA+B,MAAM;QACjD,aAAa,GAAC,IAAI,CAmB9B;IAED;;;OAGG;IACH,mBAHW,MAAM,SACN,MAAM,QAIhB;IAED;;;OAGG;IACH,mBAHW,MAAM,GACJ,MAAM,GAAC,SAAS,CAI5B;IAED;;;OAGG;IACH,qCAEC;IAED;;;;OAIG;IACH,sBAHW,MAAM,iBACN,MAAM,QAIhB;IAED;;;;OAIG;IACH,oBAHW,MAAM,kBACG,MAAM,gBAIzB;IAED;;;;;OAKG;IACH,+BAJW,MAAM,SACN,MAAM,+BAKhB;IAED;;;OAGG;IACH,oBAHW,MAAM,GACJ,MAAM,CAIlB;IAED;;;OAGG;IACH,oBAHW,MAAM,UACN,MAAM,QAIhB;IAED;;;;;OAKG;IACH,wBAHW,aAAa,iBACb;QAAC,QAAQ,CAAC,EAAC,MAAM,CAAA;KAAC,QAe5B;IAED;;;;;OAKG;IACH,oBAJW,MAAM,UACN,MAAM,EAAE,GACN,aAAa,CAUzB;IAED;;;OAGG;IACH,aAFW,MAAM,QAahB;IAED;;;;OAIG;IACH,mCAEC;IAED;;OAEG;IACH,qBAWC;IAwCD;;OAEG;IACH,kCAEC;IAED;;;;OAIG;IACH,+BAFW,aAAa,QAKvB;;CACJ;+BAxa8B,6BAA6B;qCACvB,mCAAmC;6BAC3C,2BAA2B;yBANd,uBAAuB;8BACnC,+BAA+B;8BAE/B,4BAA4B;8BAD5B,+BAA+B"}

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

@@ -110,6 +110,15 @@ export class SopraEngine {
         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[]}

package/src/engine/sound/sopra/definition/EventDescription.d.ts

@@ -33,6 +33,7 @@ export class EventDescription {
      */
     gainDb: number;
     /**
+     * Should the sound be spatialized?
      * @type {boolean}
      */
     is3D: boolean;
@@ -46,6 +47,7 @@ export class EventDescription {
      */
     distanceMin: number;
     /**
+     * Maximum distance from the listener at which the sound is audible.
      * @type {number}
      */
     distanceMax: number;
@@ -65,6 +67,7 @@ export class EventDescription {
      */
     priority: number;
     /**
+     * When stealing, which voice to replace.
      * @type {VoiceStealMode|number}
      */
     stealMode: VoiceStealMode | number;

package/src/engine/sound/sopra/definition/EventDescription.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"EventDescription.d.ts","sourceRoot":"","sources":["../../../../../../src/engine/sound/sopra/definition/EventDescription.js"],"names":[],"mappings":"AAiBA;;;;GAIG;AACH;IA4EI;;;;;;OAMG;IACH,mBALW,MAAM,qKAEN,QAAQ,gBAAgB,CAAC,GACvB,gBAAgB,CAgC5B;IA/GD;;;OAGG;IACH,OAFU,MAAM,CAEL;IAEX;;;OAGG;IACH,4BAAkC;IAElC;;;OAGG;IACH,OAFU,MAAM,CAEE;IAElB;;;OAGG;IACH,QAFU,MAAM,CAEL;IAEX;;OAEG;IACH,MAFU,OAAO,CAEJ;IAEb;;;OAGG;IACH,cAFU,iBAAiB,GAAC,MAAM,CAEI;IAEtC;;OAEG;IACH,aAFU,MAAM,CAEA;IAEhB;;OAEG;IACH,aAFU,MAAM,CAEI;IAEpB;;;OAGG;IACH,aAFU,cAAc,CAEW;IAEnC;;;OAGG;IACH,cAFU,MAAM,CAEE;IAElB;;;OAGG;IACH,UAFU,MAAM,CAEH;IAEb;;OAEG;IACH,WAFU,cAAc,GAAC,MAAM,CAEG;IAElC;;;OAGG;IACH,oBAFU,MAAM,CAES;IAyCzB;;;;OAIG;IACH,cAHW,gBAAgB,GACd,OAAO,CAgBnB;IAED;;;;;OAKG;IACH,QAFa,MAAM,CAkBlB;IAED,0BAkBC;IAED;;;;;;;;;;;;;;;;;;;MAgBC;IAED;;;;;;;;;;;;;;aAmCC;CACJ;;;;kCA3PiC,wBAAwB;+BAF3B,4CAA4C;+BAI5C,qBAAqB"}
+{"version":3,"file":"EventDescription.d.ts","sourceRoot":"","sources":["../../../../../../src/engine/sound/sopra/definition/EventDescription.js"],"names":[],"mappings":"AAiBA;;;;GAIG;AACH;IA+EI;;;;;;OAMG;IACH,mBALW,MAAM,qKAEN,QAAQ,gBAAgB,CAAC,GACvB,gBAAgB,CAgC5B;IAlHD;;;OAGG;IACH,OAFU,MAAM,CAEL;IAEX;;;OAGG;IACH,4BAAkC;IAElC;;;OAGG;IACH,OAFU,MAAM,CAEE;IAElB;;;OAGG;IACH,QAFU,MAAM,CAEL;IAEX;;;OAGG;IACH,MAFU,OAAO,CAEJ;IAEb;;;OAGG;IACH,cAFU,iBAAiB,GAAC,MAAM,CAEI;IAEtC;;OAEG;IACH,aAFU,MAAM,CAEA;IAEhB;;;OAGG;IACH,aAFU,MAAM,CAEI;IAEpB;;;OAGG;IACH,aAFU,cAAc,CAEW;IAEnC;;;OAGG;IACH,cAFU,MAAM,CAEE;IAElB;;;OAGG;IACH,UAFU,MAAM,CAEH;IAEb;;;OAGG;IACH,WAFU,cAAc,GAAC,MAAM,CAEG;IAElC;;;OAGG;IACH,oBAFU,MAAM,CAES;IAyCzB;;;;OAIG;IACH,cAHW,gBAAgB,GACd,OAAO,CAgBnB;IAED;;;;;OAKG;IACH,QAFa,MAAM,CAkBlB;IAED,0BAkBC;IAED;;;;;;;;;;;;;;;;;;;MAgBC;IAED;;;;;;;;;;;;;;aAmCC;CACJ;;;;kCA7PiC,wBAAwB;+BAH3B,4CAA4C;+BAI5C,qBAAqB"}

package/src/engine/sound/sopra/definition/EventDescription.js

@@ -2,9 +2,9 @@ import { combine_hash } from "../../../../core/collection/array/combine_hash.js"
 import { computeHashFloat } from "../../../../core/primitives/numbers/computeHashFloat.js";
 import { computeStringHash } from "../../../../core/primitives/strings/computeStringHash.js";
 import { AnimationCurve } from "../../../animation/curve/AnimationCurve.js";
+import { deserializeAudioClipFromJSON, serializeAudioClipToJSON } from "../serialization/sopraJSON.js";
 import { SilenceAudioClip } from "./clip/SilenceAudioClip.js";
 import { SopraPanningModel } from "./SopraPanningModel.js";
-import { deserializeAudioClipFromJSON, serializeAudioClipToJSON } from "../serialization/sopraJSON.js";
 import { VoiceStealMode } from "./VoiceStealMode.js";
 
 /**
@@ -47,6 +47,7 @@ export class EventDescription {
     gainDb = 0;
 
     /**
+     * Should the sound be spatialized?
      * @type {boolean}
      */
     is3D = false;
@@ -63,6 +64,7 @@ export class EventDescription {
     distanceMin = 1;
 
     /**
+     * Maximum distance from the listener at which the sound is audible.
      * @type {number}
      */
     distanceMax = 10000;
@@ -86,6 +88,7 @@ export class EventDescription {
     priority = 0;
 
     /**
+     * When stealing, which voice to replace.
      * @type {VoiceStealMode|number}
      */
     stealMode = VoiceStealMode.Oldest;

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

@@ -42,6 +42,13 @@ export class BusGraph {
      * @returns {AudioNode}
      */
     getInput(id: string): AudioNode;
+    /**
+     * The bus's OUTPUT node (post-effects, post-gain) — the signal it routes to its parent / the destination.
+     * Tap it to fan a COPY of the bus's mix elsewhere (e.g. a probe-reverb send off the master bus).
+     * @param {string} id
+     * @returns {AudioNode}
+     */
+    getOutput(id: string): AudioNode;
     /**
      * @param {string} id
      * @returns {number} linear gain

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

@@ -1 +1 @@
-{"version":3,"file":"BusGraph.d.ts","sourceRoot":"","sources":["../../../../../../src/engine/sound/sopra/runtime/BusGraph.js"],"names":[],"mappings":"AAIA;;;;GAIG;AACH,8BAFU,MAAM,CAEkB;AAElC;;;;;GAKG;AACH;IAkBI;;;OAGG;IACH,iBAHW,gBAAgB,eAChB,SAAS,EAKnB;IAvBD;;;OAGG;IACH,OAFU,IAAI,MAAM,EAAE;QAAC,UAAU,gBAAgB;QAAC,KAAK,EAAE,SAAS,CAAC;QAAC,MAAM,EAAE,QAAQ,CAAA;KAAC,CAAC,CAEpE;IAqBlB;;;;OAIG;IACH,mBAFW,eAAe,QAgFzB;IAED;;;OAGG;IACH,QAHW,MAAM,GACJ,OAAO,CAInB;IAED;;;;OAIG;IACH,aAHW,MAAM,GACJ,SAAS,CAUrB;IAED;;;OAGG;IACH,cAHW,MAAM,GACJ,MAAM,CAUlB;IAED;;;OAGG;IACH,cAHW,MAAM,UACN,MAAM,QAWhB;IAED;;;OAGG;IACH,gBAHW,MAAM,GACJ,MAAM,CAIlB;IAED;;;;;;;OAOG;IACH,eALW,MAAM,UACN,MAAM,YACN,MAAM,eACN,MAAM,QAWhB;IAED;;;;;;OAMG;IACH,mBAJW,MAAM,UACN,MAAM,gBACN,MAAM,QAYhB;;CACJ"}
+{"version":3,"file":"BusGraph.d.ts","sourceRoot":"","sources":["../../../../../../src/engine/sound/sopra/runtime/BusGraph.js"],"names":[],"mappings":"AAIA;;;;GAIG;AACH,8BAFU,MAAM,CAEkB;AAElC;;;;;GAKG;AACH;IAkBI;;;OAGG;IACH,iBAHW,gBAAgB,eAChB,SAAS,EAKnB;IAvBD;;;OAGG;IACH,OAFU,IAAI,MAAM,EAAE;QAAC,UAAU,gBAAgB;QAAC,KAAK,EAAE,SAAS,CAAC;QAAC,MAAM,EAAE,QAAQ,CAAA;KAAC,CAAC,CAEpE;IAqBlB;;;;OAIG;IACH,mBAFW,eAAe,QAgFzB;IAED;;;OAGG;IACH,QAHW,MAAM,GACJ,OAAO,CAInB;IAED;;;;OAIG;IACH,aAHW,MAAM,GACJ,SAAS,CAUrB;IAED;;;;;OAKG;IACH,cAHW,MAAM,GACJ,SAAS,CAUrB;IAED;;;OAGG;IACH,cAHW,MAAM,GACJ,MAAM,CAUlB;IAED;;;OAGG;IACH,cAHW,MAAM,UACN,MAAM,QAWhB;IAED;;;OAGG;IACH,gBAHW,MAAM,GACJ,MAAM,CAIlB;IAED;;;;;;;OAOG;IACH,eALW,MAAM,UACN,MAAM,YACN,MAAM,eACN,MAAM,QAWhB;IAED;;;;;;OAMG;IACH,mBAJW,MAAM,UACN,MAAM,gBACN,MAAM,QAYhB;;CACJ"}