@woosh/meep-engine 2.154.0 → 2.156.0

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

@@ -0,0 +1,191 @@
+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 { AbstractAudioClip } from "./AbstractAudioClip.js";
+
+/**
+ * The only buffer-referencing clip — a leaf that plays a single audio asset.
+ * Replaces the "definition" half of the legacy {@link SoundTrack} (which conflated definition,
+ * live node and playback state).
+ */
+export class SampleAudioClip extends AbstractAudioClip {
+
+    /**
+     * Asset path, or asset alias if {@link usingAlias} is set.
+     * @type {string}
+     */
+    url = "";
+
+    /**
+     * When true, {@link url} is an asset alias to be resolved via the AssetManager rather than a path.
+     * @type {boolean}
+     */
+    usingAlias = false;
+
+    /**
+     * @type {boolean}
+     */
+    loop = false;
+
+    /**
+     * Loop region start, in seconds. Only meaningful when {@link loop} is set. 0 = start of buffer.
+     * @type {number}
+     */
+    loopStart = 0;
+
+    /**
+     * Loop region end, in seconds. Only meaningful when {@link loop} is set. 0 = end of buffer.
+     * @type {number}
+     */
+    loopEnd = 0;
+
+    /**
+     * Per-trigger pitch randomization, applied as a symmetric +/- offset in cents.
+     * @type {number}
+     */
+    pitchRandom = 0;
+
+    /**
+     * Per-trigger gain randomization, applied as a symmetric +/- offset in decibels.
+     * @type {number}
+     */
+    gainRandom = 0;
+
+    /**
+     *
+     * @param {string} url
+     * @param {{usingAlias?:boolean, loop?:boolean, gain?:number, pitch?:number, loopStart?:number, loopEnd?:number, pitchRandom?:number, gainRandom?:number}} [options]
+     * @returns {SampleAudioClip}
+     */
+    static from(url, {
+        usingAlias = false,
+        loop = false,
+        gain = 0,
+        pitch = 0,
+        loopStart = 0,
+        loopEnd = 0,
+        pitchRandom = 0,
+        gainRandom = 0
+    } = {}) {
+        const r = new SampleAudioClip();
+
+        r.url = url;
+        r.usingAlias = usingAlias;
+        r.loop = loop;
+        r.gain = gain;
+        r.pitch = pitch;
+        r.loopStart = loopStart;
+        r.loopEnd = loopEnd;
+        r.pitchRandom = pitchRandom;
+        r.gainRandom = gainRandom;
+
+        return r;
+    }
+
+    /**
+     *
+     * @param {SampleAudioClip} other
+     * @returns {boolean}
+     */
+    equals(other) {
+        return super.equals(other)
+            && this.url === other.url
+            && this.usingAlias === other.usingAlias
+            && this.loop === other.loop
+            && this.loopStart === other.loopStart
+            && this.loopEnd === other.loopEnd
+            && this.pitchRandom === other.pitchRandom
+            && this.gainRandom === other.gainRandom;
+    }
+
+    /**
+     * @returns {number}
+     */
+    hash() {
+        return combine_hash(
+            super.hash(),
+            computeStringHash(this.url),
+            this.usingAlias ? 1 : 0,
+            this.loop ? 1 : 0,
+            computeHashFloat(this.loopStart),
+            computeHashFloat(this.loopEnd),
+            computeHashFloat(this.pitchRandom),
+            computeHashFloat(this.gainRandom)
+        );
+    }
+
+    /**
+     * @returns {SampleAudioClip}
+     */
+    clone() {
+        const r = new SampleAudioClip();
+
+        r.copyBaseFrom(this);
+        r.url = this.url;
+        r.usingAlias = this.usingAlias;
+        r.loop = this.loop;
+        r.loopStart = this.loopStart;
+        r.loopEnd = this.loopEnd;
+        r.pitchRandom = this.pitchRandom;
+        r.gainRandom = this.gainRandom;
+
+        return r;
+    }
+
+    toJSON() {
+        return {
+            gain: this.gain,
+            pitch: this.pitch,
+            url: this.url,
+            usingAlias: this.usingAlias,
+            loop: this.loop,
+            loopStart: this.loopStart,
+            loopEnd: this.loopEnd,
+            pitchRandom: this.pitchRandom,
+            gainRandom: this.gainRandom
+        };
+    }
+
+    fromJSON({ gain = 0, pitch = 0, url = "", usingAlias = false, loop = false, loopStart = 0, loopEnd = 0, pitchRandom = 0, gainRandom = 0 }) {
+        this.gain = gain;
+        this.pitch = pitch;
+        this.url = url;
+        this.usingAlias = usingAlias;
+        this.loop = loop;
+        this.loopStart = loopStart;
+        this.loopEnd = loopEnd;
+        this.pitchRandom = pitchRandom;
+        this.gainRandom = gainRandom;
+    }
+
+    planTimeline(env, gainDb = 0, pitchCents = 0, offset = 0) {
+        let g = gainDb + this.gain;
+        let p = pitchCents + this.pitch;
+
+        // per-trigger randomization: symmetric +/- range, deterministic via the playback RNG
+        if (this.gainRandom !== 0) {
+            g += (env.playback.random() * 2 - 1) * this.gainRandom;
+        }
+        if (this.pitchRandom !== 0) {
+            p += (env.playback.random() * 2 - 1) * this.pitchRandom;
+        }
+
+        const duration = this.loop ? Infinity : env.durationOf(this);
+
+        return {
+            plays: [{ clip: this, offset, gainDb: g, pitchCents: p }],
+            duration
+        };
+    }
+
+    collectSampleClips(out = []) {
+        out.push(this);
+        return out;
+    }
+
+    loops() {
+        return this.loop;
+    }
+}
+
+SampleAudioClip.typeName = "SopraSampleAudioClip";

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

@@ -0,0 +1,18 @@
+export class SampleAudioClipSerializationAdapter extends BinaryClassSerializationAdapter<any> {
+    constructor();
+    klass: typeof SampleAudioClip;
+    version: number;
+    /**
+     * @param {BinaryBuffer} buffer
+     * @param {SampleAudioClip} value
+     */
+    serialize(buffer: BinaryBuffer, value: SampleAudioClip): void;
+    /**
+     * @param {BinaryBuffer} buffer
+     * @param {SampleAudioClip} value
+     */
+    deserialize(buffer: BinaryBuffer, value: SampleAudioClip): void;
+}
+import { BinaryClassSerializationAdapter } from "../../../../ecs/storage/binary/BinaryClassSerializationAdapter.js";
+import { SampleAudioClip } from "./SampleAudioClip.js";
+//# sourceMappingURL=SampleAudioClipSerializationAdapter.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"SampleAudioClipSerializationAdapter.d.ts","sourceRoot":"","sources":["../../../../../../../src/engine/sound/sopra/definition/clip/SampleAudioClipSerializationAdapter.js"],"names":[],"mappings":"AAGA;;IACI,8BAAwB;IACxB,gBAAY;IAEZ;;;OAGG;IACH,uCAFW,eAAe,QAYzB;IAED;;;OAGG;IACH,yCAFW,eAAe,QAYzB;CACJ;gDAtC+C,mEAAmE;gCACnF,sBAAsB"}

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

@@ -0,0 +1,39 @@
+import { BinaryClassSerializationAdapter } from "../../../../ecs/storage/binary/BinaryClassSerializationAdapter.js";
+import { SampleAudioClip } from "./SampleAudioClip.js";
+
+export class SampleAudioClipSerializationAdapter extends BinaryClassSerializationAdapter {
+    klass = SampleAudioClip;
+    version = 0;
+
+    /**
+     * @param {BinaryBuffer} buffer
+     * @param {SampleAudioClip} value
+     */
+    serialize(buffer, value) {
+        buffer.writeFloat32(value.gain);
+        buffer.writeFloat32(value.pitch);
+        buffer.writeUTF8String(value.url);
+        buffer.writeUint8(value.usingAlias ? 1 : 0);
+        buffer.writeUint8(value.loop ? 1 : 0);
+        buffer.writeFloat32(value.loopStart);
+        buffer.writeFloat32(value.loopEnd);
+        buffer.writeFloat32(value.pitchRandom);
+        buffer.writeFloat32(value.gainRandom);
+    }
+
+    /**
+     * @param {BinaryBuffer} buffer
+     * @param {SampleAudioClip} value
+     */
+    deserialize(buffer, value) {
+        value.gain = buffer.readFloat32();
+        value.pitch = buffer.readFloat32();
+        value.url = buffer.readUTF8String();
+        value.usingAlias = buffer.readUint8() !== 0;
+        value.loop = buffer.readUint8() !== 0;
+        value.loopStart = buffer.readFloat32();
+        value.loopEnd = buffer.readFloat32();
+        value.pitchRandom = buffer.readFloat32();
+        value.gainRandom = buffer.readFloat32();
+    }
+}

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

@@ -0,0 +1,40 @@
+/**
+ * Plays all children in order. Per-playback cursor state lives on the runtime instance (P1
+ * scheduler), never on this definition.
+ */
+export class SequenceContainerAudioClip extends ContainerAudioClip {
+    /**
+     *
+     * @param {AbstractAudioClip[]} [children]
+     * @returns {SequenceContainerAudioClip}
+     */
+    static from(children?: AbstractAudioClip[]): SequenceContainerAudioClip;
+    clone(): SequenceContainerAudioClip;
+    toJSON(): {
+        gain: number;
+        pitch: number;
+        children: {
+            type: string;
+            data: any;
+        }[];
+    };
+    fromJSON({ gain, pitch, children }: {
+        gain?: number;
+        pitch?: number;
+        children?: any[];
+    }): void;
+    planTimeline(env: any, gainDb?: number, pitchCents?: number, offset?: number): {
+        plays: {
+            clip: SampleAudioClip;
+            offset: number;
+            gainDb: number;
+            pitchCents: number;
+        }[];
+        duration: number;
+    };
+}
+export namespace SequenceContainerAudioClip {
+    let typeName: string;
+}
+import { ContainerAudioClip } from "./ContainerAudioClip.js";
+//# sourceMappingURL=SequenceContainerAudioClip.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"SequenceContainerAudioClip.d.ts","sourceRoot":"","sources":["../../../../../../../src/engine/sound/sopra/definition/clip/SequenceContainerAudioClip.js"],"names":[],"mappings":"AAIA;;;GAGG;AACH;IAEI;;;;OAIG;IACH,uBAHW,mBAAmB,GACjB,0BAA0B,CAQtC;IAeD,oCAUC;IAED;;;;;;;MAMC;IAED;;;;aAIC;IAED;;;;;;;;MAyBC;CACJ;;;;mCAvFkC,yBAAyB"}

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

@@ -0,0 +1,91 @@
+import { combine_hash } from "../../../../../core/collection/array/combine_hash.js";
+import { ContainerAudioClip } from "./ContainerAudioClip.js";
+import { deserializeAudioClipFromJSON, serializeAudioClipToJSON } from "../../serialization/sopraJSON.js";
+
+/**
+ * Plays all children in order. Per-playback cursor state lives on the runtime instance (P1
+ * scheduler), never on this definition.
+ */
+export class SequenceContainerAudioClip extends ContainerAudioClip {
+
+    /**
+     *
+     * @param {AbstractAudioClip[]} [children]
+     * @returns {SequenceContainerAudioClip}
+     */
+    static from(children = []) {
+        const r = new SequenceContainerAudioClip();
+
+        r.addChildren(children);
+
+        return r;
+    }
+
+    // equals is inherited from ContainerAudioClip (gain/pitch + children) — a Sequence adds no fields.
+
+    hash() {
+        let h = super.hash();
+
+        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 SequenceContainerAudioClip();
+
+        r.copyBaseFrom(this);
+
+        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,
+            children: this.children.map(serializeAudioClipToJSON)
+        };
+    }
+
+    fromJSON({ gain = 0, pitch = 0, children = [] }) {
+        this.gain = gain;
+        this.pitch = pitch;
+        this.children = children.map(deserializeAudioClipFromJSON);
+    }
+
+    planTimeline(env, gainDb = 0, pitchCents = 0, offset = 0) {
+        const childGain = gainDb + this.gain;
+        const childPitch = pitchCents + this.pitch;
+
+        const plays = [];
+        let cursor = offset;
+
+        const children = this.children;
+        for (let i = 0; i < children.length; i++) {
+            const sub = children[i].planTimeline(env, childGain, childPitch, cursor);
+
+            for (let j = 0; j < sub.plays.length; j++) {
+                plays.push(sub.plays[j]);
+            }
+
+            if (sub.duration === Infinity) {
+                // an infinite (looping) child is terminal — the sequence cannot advance past it
+                cursor = Infinity;
+                break;
+            }
+
+            cursor += sub.duration;
+        }
+
+        return { plays, duration: cursor === Infinity ? Infinity : cursor - offset };
+    }
+}
+
+SequenceContainerAudioClip.typeName = "SopraSequenceContainerAudioClip";

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

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

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

@@ -0,0 +1 @@
+{"version":3,"file":"SequenceContainerAudioClipSerializationAdapter.d.ts","sourceRoot":"","sources":["../../../../../../../src/engine/sound/sopra/definition/clip/SequenceContainerAudioClipSerializationAdapter.js"],"names":[],"mappings":"AAGA;IACI,yCAAmC;IACnC,gBAAY;IAEZ;;;OAGG;IACH,uCAFW,0BAA0B,QAcpC;IAED;;;OAGG;IACH,yCAFW,0BAA0B,QAapC;CACJ;qDAzCoD,+EAA+E;2CACzF,iCAAiC"}

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

@@ -0,0 +1,42 @@
+import { ObjectBasedClassSerializationAdapter } from "../../../../ecs/storage/binary/object/ObjectBasedClassSerializationAdapter.js";
+import { SequenceContainerAudioClip } from "./SequenceContainerAudioClip.js";
+
+export class SequenceContainerAudioClipSerializationAdapter extends ObjectBasedClassSerializationAdapter {
+    klass = SequenceContainerAudioClip;
+    version = 0;
+
+    /**
+     * @param {BinaryBuffer} buffer
+     * @param {SequenceContainerAudioClip} value
+     */
+    serialize(buffer, value) {
+        buffer.writeFloat32(value.gain);
+        buffer.writeFloat32(value.pitch);
+
+        const children = value.children;
+        const n = children.length;
+
+        buffer.writeUintVar(n);
+
+        for (let i = 0; i < n; i++) {
+            this.objectAdapter.serialize(buffer, children[i]);
+        }
+    }
+
+    /**
+     * @param {BinaryBuffer} buffer
+     * @param {SequenceContainerAudioClip} value
+     */
+    deserialize(buffer, value) {
+        value.gain = buffer.readFloat32();
+        value.pitch = buffer.readFloat32();
+
+        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/SilenceAudioClip.d.ts

@@ -0,0 +1,44 @@
+/**
+ * Represents dead air.
+ * @example useful for introducing pauses inside a {@link SequenceContainerAudioClip}; the scheduler
+ * advances its cursor by {@link duration} and emits no source.
+ */
+export class SilenceAudioClip extends AbstractAudioClip {
+    /**
+     *
+     * @param {number} duration seconds
+     * @returns {SilenceAudioClip}
+     */
+    static from(duration: number): SilenceAudioClip;
+    /**
+     * Duration of the silence, in seconds.
+     * @type {number}
+     */
+    duration: number;
+    /**
+     *
+     * @param {SilenceAudioClip} other
+     * @returns {boolean}
+     */
+    equals(other: SilenceAudioClip): boolean;
+    clone(): SilenceAudioClip;
+    toJSON(): {
+        gain: number;
+        pitch: number;
+        duration: number;
+    };
+    fromJSON({ gain, pitch, duration }: {
+        gain?: number;
+        pitch?: number;
+        duration?: number;
+    }): void;
+    planTimeline(env: any, gainDb?: number, pitchCents?: number, offset?: number): {
+        plays: any[];
+        duration: number;
+    };
+}
+export namespace SilenceAudioClip {
+    let typeName: string;
+}
+import { AbstractAudioClip } from "./AbstractAudioClip.js";
+//# sourceMappingURL=SilenceAudioClip.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"SilenceAudioClip.d.ts","sourceRoot":"","sources":["../../../../../../../src/engine/sound/sopra/definition/clip/SilenceAudioClip.js"],"names":[],"mappings":"AAIA;;;;GAIG;AACH;IAQI;;;;OAIG;IACH,sBAHW,MAAM,GACJ,gBAAgB,CAQ5B;IAjBD;;;OAGG;IACH,UAFU,MAAM,CAEH;IAeb;;;;OAIG;IACH,cAHW,gBAAgB,GACd,OAAO,CAKnB;IASD,0BAOC;IAED;;;;MAMC;IAED;;;;aAIC;IAED;;;MAGC;CACJ;;;;kCAxEiC,wBAAwB"}

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

@@ -0,0 +1,77 @@
+import { combine_hash } from "../../../../../core/collection/array/combine_hash.js";
+import { computeHashFloat } from "../../../../../core/primitives/numbers/computeHashFloat.js";
+import { AbstractAudioClip } from "./AbstractAudioClip.js";
+
+/**
+ * Represents dead air.
+ * @example useful for introducing pauses inside a {@link SequenceContainerAudioClip}; the scheduler
+ * advances its cursor by {@link duration} and emits no source.
+ */
+export class SilenceAudioClip extends AbstractAudioClip {
+
+    /**
+     * Duration of the silence, in seconds.
+     * @type {number}
+     */
+    duration = 0;
+
+    /**
+     *
+     * @param {number} duration seconds
+     * @returns {SilenceAudioClip}
+     */
+    static from(duration) {
+        const r = new SilenceAudioClip();
+
+        r.duration = duration;
+
+        return r;
+    }
+
+    /**
+     *
+     * @param {SilenceAudioClip} other
+     * @returns {boolean}
+     */
+    equals(other) {
+        return super.equals(other)
+            && this.duration === other.duration;
+    }
+
+    hash() {
+        return combine_hash(
+            super.hash(),
+            computeHashFloat(this.duration)
+        );
+    }
+
+    clone() {
+        const r = new SilenceAudioClip();
+
+        r.copyBaseFrom(this);
+        r.duration = this.duration;
+
+        return r;
+    }
+
+    toJSON() {
+        return {
+            gain: this.gain,
+            pitch: this.pitch,
+            duration: this.duration
+        };
+    }
+
+    fromJSON({ gain = 0, pitch = 0, duration = 0 }) {
+        this.gain = gain;
+        this.pitch = pitch;
+        this.duration = duration;
+    }
+
+    planTimeline(env, gainDb = 0, pitchCents = 0, offset = 0) {
+        // dead air — contributes no voice, only advances the schedule cursor by its duration
+        return { plays: [], duration: this.duration };
+    }
+}
+
+SilenceAudioClip.typeName = "SopraSilenceAudioClip";

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

@@ -0,0 +1,18 @@
+export class SilenceAudioClipSerializationAdapter extends BinaryClassSerializationAdapter<any> {
+    constructor();
+    klass: typeof SilenceAudioClip;
+    version: number;
+    /**
+     * @param {BinaryBuffer} buffer
+     * @param {SilenceAudioClip} value
+     */
+    serialize(buffer: BinaryBuffer, value: SilenceAudioClip): void;
+    /**
+     * @param {BinaryBuffer} buffer
+     * @param {SilenceAudioClip} value
+     */
+    deserialize(buffer: BinaryBuffer, value: SilenceAudioClip): void;
+}
+import { BinaryClassSerializationAdapter } from "../../../../ecs/storage/binary/BinaryClassSerializationAdapter.js";
+import { SilenceAudioClip } from "./SilenceAudioClip.js";
+//# sourceMappingURL=SilenceAudioClipSerializationAdapter.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"SilenceAudioClipSerializationAdapter.d.ts","sourceRoot":"","sources":["../../../../../../../src/engine/sound/sopra/definition/clip/SilenceAudioClipSerializationAdapter.js"],"names":[],"mappings":"AAGA;;IACI,+BAAyB;IACzB,gBAAY;IAEZ;;;OAGG;IACH,uCAFW,gBAAgB,QAM1B;IAED;;;OAGG;IACH,yCAFW,gBAAgB,QAM1B;CACJ;gDA1B+C,mEAAmE;iCAClF,uBAAuB"}

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

@@ -0,0 +1,27 @@
+import { BinaryClassSerializationAdapter } from "../../../../ecs/storage/binary/BinaryClassSerializationAdapter.js";
+import { SilenceAudioClip } from "./SilenceAudioClip.js";
+
+export class SilenceAudioClipSerializationAdapter extends BinaryClassSerializationAdapter {
+    klass = SilenceAudioClip;
+    version = 0;
+
+    /**
+     * @param {BinaryBuffer} buffer
+     * @param {SilenceAudioClip} value
+     */
+    serialize(buffer, value) {
+        buffer.writeFloat32(value.gain);
+        buffer.writeFloat32(value.pitch);
+        buffer.writeFloat32(value.duration);
+    }
+
+    /**
+     * @param {BinaryBuffer} buffer
+     * @param {SilenceAudioClip} value
+     */
+    deserialize(buffer, value) {
+        value.gain = buffer.readFloat32();
+        value.pitch = buffer.readFloat32();
+        value.duration = buffer.readFloat32();
+    }
+}