@woosh/meep-engine 2.155.0 → 2.156.0

package/src/engine/sound/sopra/definition/clip/AbstractAudioClip.js

@@ -0,0 +1,109 @@
+import { combine_hash } from "../../../../../core/collection/array/combine_hash.js";
+import { computeHashFloat } from "../../../../../core/primitives/numbers/computeHashFloat.js";
+
+/**
+ * Base class for all audio clips.
+ *
+ * A clip is a pure, serializable DEFINITION node — it holds no WebAudio objects and no playback
+ * state. Playback state lives in a transient {@link EventInstance}/{@link Voice}; see the
+ * definition/instance split in `sopra/IMPLEMENTATION_PLAN.md`.
+ *
+ * NOTE: unlike the original stub, there is no `parent` pointer and no `channel` field. Inheritance
+ * of gain/pitch is resolved ONCE, top-down, at voice instantiation (uniform control flow — no
+ * null=inherit sentinels reach the runtime). Routing is decided by {@link EventDescription.busId}.
+ */
+export class AbstractAudioClip {
+
+    /**
+     * Gain offset in decibel, accumulated additively down the clip tree at voice-instantiation time.
+     * @type {number}
+     */
+    gain = 0;
+
+    /**
+     * Pitch offset in cents, accumulated additively down the clip tree at voice-instantiation time.
+     * @type {number}
+     */
+    pitch = 0;
+
+    /**
+     * @protected
+     * @param {AbstractAudioClip} other
+     */
+    copyBaseFrom(other) {
+        this.gain = other.gain;
+        this.pitch = other.pitch;
+    }
+
+    /**
+     * Base equality: the gain/pitch every clip carries. Subclasses override and extend it via
+     * `super.equals(other)`.
+     * @param {AbstractAudioClip} other
+     * @returns {boolean}
+     */
+    equals(other) {
+        return this.gain === other.gain
+            && this.pitch === other.pitch;
+    }
+
+    /**
+     * Base hash: folds in the gain/pitch every clip carries. Subclasses override and extend it via
+     * `super.hash()`.
+     * @returns {number}
+     */
+    hash() {
+        return combine_hash(
+            computeHashFloat(this.gain),
+            computeHashFloat(this.pitch)
+        );
+    }
+
+    /**
+     * Resolve this clip (and its subtree) into a flat list of timed leaf plays. Overridden by every
+     * concrete clip; children are reached via polymorphic dispatch (no type switching). Gain/pitch
+     * inheritance is accumulated top-down and resolved here ONCE, so the runtime never sees an
+     * inherit sentinel.
+     *
+     * @param {{durationOf: function(SampleAudioClip):number, playback: SopraPlaybackContext, getParameter: function(string):(number|undefined)}} env
+     *        `durationOf` returns a sample's buffer duration; `playback` supplies the seeded RNG and
+     *        random-container history; `getParameter` reads a live RTPC value (used by Switch/Blend
+     *        containers, read once at plan time), returning `undefined` if unset.
+     * @param {number} [gainDb] accumulated gain offset (dB); start with the event's master gain
+     * @param {number} [pitchCents] accumulated pitch offset (cents)
+     * @param {number} [offset] start time of this clip relative to the timeline origin (seconds)
+     * @returns {{plays: {clip: SampleAudioClip, offset: number, gainDb: number, pitchCents: number}[], duration: number}}
+     */
+    planTimeline(env, gainDb = 0, pitchCents = 0, offset = 0) {
+        throw new Error('Implementation must override planTimeline()');
+    }
+
+    /**
+     * Append every {@link SampleAudioClip} leaf reachable from this clip (across ALL branches) into
+     * `out`. Used to ensure candidate buffers are loaded before the timeline is resolved, so random
+     * selection consumes the RNG exactly once. Default: contributes nothing (overridden by sample
+     * leaves and containers).
+     *
+     * @param {SampleAudioClip[]} [out]
+     * @returns {SampleAudioClip[]}
+     */
+    collectSampleClips(out = []) {
+        return out;
+    }
+
+    /**
+     * Whether this clip (or its subtree) can produce unbounded playback — i.e. an emitter holding it is
+     * a persistent source, not a one-shot. Used to decide auto-release/lifetime behaviour. Default
+     * false; overridden by looping leaves and containers. Conservative: a container reports looping if
+     * ANY reachable child can loop.
+     * @returns {boolean}
+     */
+    loops() {
+        return false;
+    }
+}
+
+/**
+ * @readonly
+ * @type {boolean}
+ */
+AbstractAudioClip.prototype.isAudioClip = true;

package/src/engine/sound/sopra/definition/clip/BlendContainerAudioClip.d.ts

@@ -0,0 +1,80 @@
+/**
+ * Plays EVERY child whose blend gain is > 0 simultaneously, each scaled by a per-child
+ * parameter→linear-gain {@link AnimationCurve} — e.g. weather-layered ambience crossfaded by an
+ * "intensity" parameter. Supersedes the dormant `material/` composition concept.
+ *
+ * v1: the parameter is read ONCE at trigger time (a snapshot mix), not re-blended live as the
+ * parameter later sweeps — live per-voice re-blend is a documented follow-up (see IMPLEMENTATION_PLAN
+ * §9; it needs per-voice parameter binding). A child with no blend curve is always fully on (gain 1).
+ */
+export class BlendContainerAudioClip extends ContainerAudioClip {
+    /**
+     * @param {AbstractAudioClip[]} [children]
+     * @param {{parameter?:string, defaultValue?:number, blends?:AnimationCurve[]}} [options]
+     * @returns {BlendContainerAudioClip}
+     */
+    static from(children?: AbstractAudioClip[], { parameter, defaultValue, blends }?: {
+        parameter?: string;
+        defaultValue?: number;
+        blends?: AnimationCurve[];
+    }): BlendContainerAudioClip;
+    /**
+     * RTPC name whose value drives the per-child blend gains.
+     * @type {string}
+     */
+    parameter: string;
+    /**
+     * Parameter value used when the parameter is unset.
+     * @type {number}
+     */
+    defaultValue: number;
+    /**
+     * Per-child blend curves (parameter value → linear gain), parallel to {@link children}. A missing
+     * entry means "always fully on".
+     * @type {AnimationCurve[]}
+     */
+    blends: AnimationCurve[];
+    planTimeline(env: any, gainDb?: number, pitchCents?: number, offset?: number): {
+        plays: {
+            clip: SampleAudioClip;
+            offset: number;
+            gainDb: number;
+            pitchCents: number;
+        }[];
+        duration: number;
+    };
+    /**
+     * @param {BlendContainerAudioClip} other
+     * @returns {boolean}
+     */
+    equals(other: BlendContainerAudioClip): boolean;
+    clone(): BlendContainerAudioClip;
+    toJSON(): {
+        gain: number;
+        pitch: number;
+        parameter: string;
+        defaultValue: number;
+        blends: {
+            keys: any[];
+        }[];
+        children: {
+            type: string;
+            data: any;
+        }[];
+    };
+    fromJSON({ gain, pitch, parameter, defaultValue, blends, children }: {
+        gain?: number;
+        pitch?: number;
+        parameter?: string;
+        defaultValue?: number;
+        blends?: any[];
+        children?: any[];
+    }): void;
+    #private;
+}
+export namespace BlendContainerAudioClip {
+    let typeName: string;
+}
+import { ContainerAudioClip } from "./ContainerAudioClip.js";
+import { AnimationCurve } from "../../../../animation/curve/AnimationCurve.js";
+//# sourceMappingURL=BlendContainerAudioClip.d.ts.map

package/src/engine/sound/sopra/definition/clip/BlendContainerAudioClip.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"BlendContainerAudioClip.d.ts","sourceRoot":"","sources":["../../../../../../../src/engine/sound/sopra/definition/clip/BlendContainerAudioClip.js"],"names":[],"mappings":"AAQA;;;;;;;;GAQG;AACH;IAqBI;;;;OAIG;IACH,uBAJW,mBAAmB,wCACnB;QAAC,SAAS,CAAC,EAAC,MAAM,CAAC;QAAC,YAAY,CAAC,EAAC,MAAM,CAAC;QAAC,MAAM,CAAC,EAAC,cAAc,EAAE,CAAA;KAAC,GACjE,uBAAuB,CAWnC;IAjCD;;;OAGG;IACH,WAFU,MAAM,CAED;IAEf;;;OAGG;IACH,cAFU,MAAM,CAEC;IAEjB;;;;OAIG;IACH,QAFU,cAAc,EAAE,CAEd;IAkCZ;;;;;;;;MA+BC;IAED;;;OAGG;IACH,cAHW,uBAAuB,GACrB,OAAO,CAkBnB;IAiBD,iCAaC;IAED;;;;;;;;;;;;MASC;IAED;;;;;;;aAWC;;CACJ;;;;mCA7KkC,yBAAyB;+BAF7B,+CAA+C"}

package/src/engine/sound/sopra/definition/clip/BlendContainerAudioClip.js

@@ -0,0 +1,181 @@
+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 { volume2dB } from "../../../volume2dB.js";
+import { ContainerAudioClip } from "./ContainerAudioClip.js";
+import { deserializeAudioClipFromJSON, serializeAudioClipToJSON } from "../../serialization/sopraJSON.js";
+
+/**
+ * Plays EVERY child whose blend gain is > 0 simultaneously, each scaled by a per-child
+ * parameter→linear-gain {@link AnimationCurve} — e.g. weather-layered ambience crossfaded by an
+ * "intensity" parameter. Supersedes the dormant `material/` composition concept.
+ *
+ * v1: the parameter is read ONCE at trigger time (a snapshot mix), not re-blended live as the
+ * parameter later sweeps — live per-voice re-blend is a documented follow-up (see IMPLEMENTATION_PLAN
+ * §9; it needs per-voice parameter binding). A child with no blend curve is always fully on (gain 1).
+ */
+export class BlendContainerAudioClip extends ContainerAudioClip {
+
+    /**
+     * RTPC name whose value drives the per-child blend gains.
+     * @type {string}
+     */
+    parameter = "";
+
+    /**
+     * Parameter value used when the parameter is unset.
+     * @type {number}
+     */
+    defaultValue = 0;
+
+    /**
+     * Per-child blend curves (parameter value → linear gain), parallel to {@link children}. A missing
+     * entry means "always fully on".
+     * @type {AnimationCurve[]}
+     */
+    blends = [];
+
+    /**
+     * @param {AbstractAudioClip[]} [children]
+     * @param {{parameter?:string, defaultValue?:number, blends?:AnimationCurve[]}} [options]
+     * @returns {BlendContainerAudioClip}
+     */
+    static from(children = [], { parameter = "", defaultValue = 0, blends = [] } = {}) {
+        const r = new BlendContainerAudioClip();
+
+        r.addChildren(children);
+        r.parameter = parameter;
+        r.defaultValue = defaultValue;
+        r.blends = blends;
+
+        return r;
+    }
+
+    /**
+     * Linear blend gain for a child at a parameter value (never negative).
+     * @param {number} childIndex
+     * @param {number} value
+     * @returns {number}
+     */
+    #blendGain(childIndex, value) {
+        const curve = this.blends[childIndex];
+
+        if (curve === undefined) {
+            return 1; // no curve -> always fully on
+        }
+
+        return Math.max(0, curve.evaluate(value));
+    }
+
+    planTimeline(env, gainDb = 0, pitchCents = 0, offset = 0) {
+        const children = this.children;
+        const value = env.getParameter(this.parameter) ?? this.defaultValue;
+
+        const plays = [];
+        let duration = 0;
+
+        for (let i = 0; i < children.length; i++) {
+            const blend = this.#blendGain(i, value);
+
+            if (blend <= 0) {
+                continue; // inaudible at this parameter value
+            }
+
+            const sub = children[i].planTimeline(
+                env,
+                gainDb + this.gain + volume2dB(blend),
+                pitchCents + this.pitch,
+                offset
+            );
+
+            for (let j = 0; j < sub.plays.length; j++) {
+                plays.push(sub.plays[j]);
+            }
+
+            if (sub.duration > duration) {
+                duration = sub.duration;
+            }
+        }
+
+        return { plays, duration };
+    }
+
+    /**
+     * @param {BlendContainerAudioClip} other
+     * @returns {boolean}
+     */
+    equals(other) {
+        if (!super.equals(other) // gain/pitch + children
+            || this.parameter !== other.parameter
+            || this.defaultValue !== other.defaultValue
+            || this.blends.length !== other.blends.length
+        ) {
+            return false;
+        }
+
+        for (let i = 0; i < this.blends.length; i++) {
+            if (!this.blends[i].equals(other.blends[i])) {
+                return false;
+            }
+        }
+
+        return true;
+    }
+
+    hash() {
+        let h = combine_hash(
+            super.hash(),
+            computeStringHash(this.parameter),
+            computeHashFloat(this.defaultValue)
+        );
+
+        const children = this.children;
+        for (let i = 0; i < children.length; i++) {
+            h = combine_hash(h, children[i].hash());
+        }
+
+        return h;
+    }
+
+    clone() {
+        const r = new BlendContainerAudioClip();
+
+        r.copyBaseFrom(this);
+        r.parameter = this.parameter;
+        r.defaultValue = this.defaultValue;
+        r.blends = this.blends.map(c => c.clone());
+
+        for (let i = 0; i < this.children.length; i++) {
+            r.addChild(this.children[i].clone());
+        }
+
+        return r;
+    }
+
+    toJSON() {
+        return {
+            gain: this.gain,
+            pitch: this.pitch,
+            parameter: this.parameter,
+            defaultValue: this.defaultValue,
+            blends: this.blends.map(c => c.toJSON()),
+            children: this.children.map(serializeAudioClipToJSON)
+        };
+    }
+
+    fromJSON({ gain = 0, pitch = 0, parameter = "", defaultValue = 0, blends = [], children = [] }) {
+        this.gain = gain;
+        this.pitch = pitch;
+        this.parameter = parameter;
+        this.defaultValue = defaultValue;
+        this.blends = blends.map(json => {
+            const curve = new AnimationCurve();
+            curve.fromJSON(json);
+            return curve;
+        });
+        this.children = children.map(deserializeAudioClipFromJSON);
+    }
+}
+
+BlendContainerAudioClip.typeName = "SopraBlendContainerAudioClip";

package/src/engine/sound/sopra/definition/clip/BlendContainerAudioClipSerializationAdapter.d.ts

@@ -0,0 +1,17 @@
+export class BlendContainerAudioClipSerializationAdapter extends ObjectBasedClassSerializationAdapter {
+    klass: typeof BlendContainerAudioClip;
+    version: number;
+    /**
+     * @param {BinaryBuffer} buffer
+     * @param {BlendContainerAudioClip} value
+     */
+    serialize(buffer: BinaryBuffer, value: BlendContainerAudioClip): void;
+    /**
+     * @param {BinaryBuffer} buffer
+     * @param {BlendContainerAudioClip} value
+     */
+    deserialize(buffer: BinaryBuffer, value: BlendContainerAudioClip): void;
+}
+import { ObjectBasedClassSerializationAdapter } from "../../../../ecs/storage/binary/object/ObjectBasedClassSerializationAdapter.js";
+import { BlendContainerAudioClip } from "./BlendContainerAudioClip.js";
+//# sourceMappingURL=BlendContainerAudioClipSerializationAdapter.d.ts.map

package/src/engine/sound/sopra/definition/clip/BlendContainerAudioClipSerializationAdapter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"BlendContainerAudioClipSerializationAdapter.d.ts","sourceRoot":"","sources":["../../../../../../../src/engine/sound/sopra/definition/clip/BlendContainerAudioClipSerializationAdapter.js"],"names":[],"mappings":"AAKA;IACI,sCAAgC;IAChC,gBAAY;IAEZ;;;OAGG;IACH,uCAFW,uBAAuB,QA4BjC;IAED;;;OAGG;IACH,yCAFW,uBAAuB,QA6BjC;CACJ;qDAvEoD,+EAA+E;wCAC5F,8BAA8B"}

package/src/engine/sound/sopra/definition/clip/BlendContainerAudioClipSerializationAdapter.js

@@ -0,0 +1,74 @@
+import { AnimationCurve } from "../../../../animation/curve/AnimationCurve.js";
+import { Keyframe } from "../../../../animation/curve/Keyframe.js";
+import { ObjectBasedClassSerializationAdapter } from "../../../../ecs/storage/binary/object/ObjectBasedClassSerializationAdapter.js";
+import { BlendContainerAudioClip } from "./BlendContainerAudioClip.js";
+
+export class BlendContainerAudioClipSerializationAdapter extends ObjectBasedClassSerializationAdapter {
+    klass = BlendContainerAudioClip;
+    version = 0;
+
+    /**
+     * @param {BinaryBuffer} buffer
+     * @param {BlendContainerAudioClip} value
+     */
+    serialize(buffer, value) {
+        buffer.writeFloat32(value.gain);
+        buffer.writeFloat32(value.pitch);
+        buffer.writeUTF8String(value.parameter);
+        buffer.writeFloat32(value.defaultValue);
+
+        // blend curves (parallel to children) written as inline keyframes (AnimationCurve has no adapter)
+        const blends = value.blends;
+        buffer.writeUintVar(blends.length);
+        for (let i = 0; i < blends.length; i++) {
+            const keys = blends[i].keys;
+            buffer.writeUintVar(keys.length);
+            for (let k = 0; k < keys.length; k++) {
+                const kf = keys[k];
+                buffer.writeFloat32(kf.time);
+                buffer.writeFloat32(kf.value);
+                buffer.writeFloat32(kf.inTangent);
+                buffer.writeFloat32(kf.outTangent);
+            }
+        }
+
+        const children = value.children;
+        buffer.writeUintVar(children.length);
+        for (let i = 0; i < children.length; i++) {
+            this.objectAdapter.serialize(buffer, children[i]);
+        }
+    }
+
+    /**
+     * @param {BinaryBuffer} buffer
+     * @param {BlendContainerAudioClip} value
+     */
+    deserialize(buffer, value) {
+        value.gain = buffer.readFloat32();
+        value.pitch = buffer.readFloat32();
+        value.parameter = buffer.readUTF8String();
+        value.defaultValue = buffer.readFloat32();
+
+        const blendCount = buffer.readUintVar();
+        const blends = [];
+        for (let i = 0; i < blendCount; i++) {
+            const curve = new AnimationCurve();
+            const keyCount = buffer.readUintVar();
+            for (let k = 0; k < keyCount; k++) {
+                const time = buffer.readFloat32();
+                const v = buffer.readFloat32();
+                const inTangent = buffer.readFloat32();
+                const outTangent = buffer.readFloat32();
+                curve.add(Keyframe.from(time, v, inTangent, outTangent));
+            }
+            blends.push(curve);
+        }
+        value.blends = blends;
+
+        const n = buffer.readUintVar();
+        value.clearChildren();
+        for (let i = 0; i < n; i++) {
+            value.addChild(this.objectAdapter.deserialize(buffer));
+        }
+    }
+}

package/src/engine/sound/sopra/definition/clip/ContainerAudioClip.d.ts

@@ -0,0 +1,34 @@
+/**
+ * Abstract base for clips that hold an ordered set of child clips.
+ * Not directly serializable — concrete subclasses ({@link SequenceContainerAudioClip},
+ * {@link RandomContainerAudioClip}) define playback semantics.
+ */
+export class ContainerAudioClip extends AbstractAudioClip {
+    /**
+     * @type {AbstractAudioClip[]}
+     */
+    children: AbstractAudioClip[];
+    /**
+     *
+     * @param {AbstractAudioClip} clip
+     * @returns {this}
+     */
+    addChild(clip: AbstractAudioClip): this;
+    /**
+     *
+     * @param {AbstractAudioClip[]} clips
+     * @returns {this}
+     */
+    addChildren(clips: AbstractAudioClip[]): this;
+    clearChildren(): void;
+    /**
+     * Container equality: the inherited gain/pitch (via `super.equals`) plus a same-length,
+     * element-wise child comparison. Concrete subclasses override and extend this via
+     * `super.equals(other)`.
+     * @param {ContainerAudioClip} other
+     * @returns {boolean}
+     */
+    equals(other: ContainerAudioClip): boolean;
+}
+import { AbstractAudioClip } from "./AbstractAudioClip.js";
+//# sourceMappingURL=ContainerAudioClip.d.ts.map

package/src/engine/sound/sopra/definition/clip/ContainerAudioClip.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ContainerAudioClip.d.ts","sourceRoot":"","sources":["../../../../../../../src/engine/sound/sopra/definition/clip/ContainerAudioClip.js"],"names":[],"mappings":"AAGA;;;;GAIG;AACH;IAEI;;OAEG;IACH,UAFU,iBAAiB,EAAE,CAEf;IAEd;;;;OAIG;IACH,eAHW,iBAAiB,GACf,IAAI,CAQhB;IAED;;;;OAIG;IACH,mBAHW,iBAAiB,EAAE,GACjB,IAAI,CAQhB;IAED,sBAEC;IA6BD;;;;;;OAMG;IACH,cAHW,kBAAkB,GAChB,OAAO,CAqBnB;CACJ;kCAlGiC,wBAAwB"}

package/src/engine/sound/sopra/definition/clip/ContainerAudioClip.js

@@ -0,0 +1,100 @@
+import { assert } from "../../../../../core/assert.js";
+import { AbstractAudioClip } from "./AbstractAudioClip.js";
+
+/**
+ * Abstract base for clips that hold an ordered set of child clips.
+ * Not directly serializable — concrete subclasses ({@link SequenceContainerAudioClip},
+ * {@link RandomContainerAudioClip}) define playback semantics.
+ */
+export class ContainerAudioClip extends AbstractAudioClip {
+
+    /**
+     * @type {AbstractAudioClip[]}
+     */
+    children = [];
+
+    /**
+     *
+     * @param {AbstractAudioClip} clip
+     * @returns {this}
+     */
+    addChild(clip) {
+        assert.equal(clip.isAudioClip, true, 'clip.isAudioClip');
+
+        this.children.push(clip);
+
+        return this;
+    }
+
+    /**
+     *
+     * @param {AbstractAudioClip[]} clips
+     * @returns {this}
+     */
+    addChildren(clips) {
+        for (let i = 0; i < clips.length; i++) {
+            this.addChild(clips[i]);
+        }
+
+        return this;
+    }
+
+    clearChildren() {
+        this.children = [];
+    }
+
+    collectSampleClips(out = []) {
+        const children = this.children;
+
+        for (let i = 0; i < children.length; i++) {
+            children[i].collectSampleClips(out);
+        }
+
+        return out;
+    }
+
+    /**
+     * Conservative: the container can loop if ANY child can loop (a looping child makes a sequence
+     * terminal; a random/switch/blend may pick/play a looping child).
+     * @returns {boolean}
+     */
+    loops() {
+        const children = this.children;
+
+        for (let i = 0; i < children.length; i++) {
+            if (children[i].loops()) {
+                return true;
+            }
+        }
+
+        return false;
+    }
+
+    /**
+     * Container equality: the inherited gain/pitch (via `super.equals`) plus a same-length,
+     * element-wise child comparison. Concrete subclasses override and extend this via
+     * `super.equals(other)`.
+     * @param {ContainerAudioClip} other
+     * @returns {boolean}
+     */
+    equals(other) {
+        if (!super.equals(other)) {
+            return false;
+        }
+
+        const a = this.children;
+        const b = other.children;
+
+        if (a.length !== b.length) {
+            return false;
+        }
+
+        for (let i = 0; i < a.length; i++) {
+            if (!a[i].equals(b[i])) {
+                return false;
+            }
+        }
+
+        return true;
+    }
+}