@woosh/meep-engine 3.46.0 → 3.47.0

package/src/engine/sound/sopra/definition/effect/CompressorEffect.js

@@ -1,122 +1,137 @@
-import { hash_mix3 } from "../../../../../core/math/hash/hash_mix3.js";
-import { computeHashFloat } from "../../../../../core/primitives/numbers/computeHashFloat.js";
-import { AbstractAudioEffect } from "./AbstractAudioEffect.js";
-
-/**
- * Dynamics compressor bus insert, backed by a {@link DynamicsCompressorNode}.
- * NOTE: this is a per-bus insert; the engine's master compressor (in SoundEngine) is separate
- * master-glue and is not duplicated here.
- */
-export class CompressorEffect extends AbstractAudioEffect {
-
-    /**
-     * dB.
-     * @type {number}
-     */
-    threshold = -24;
-
-    /**
-     * dB.
-     * @type {number}
-     */
-    knee = 30;
-
-    /**
-     * @type {number}
-     */
-    ratio = 12;
-
-    /**
-     * Seconds.
-     * @type {number}
-     */
-    attack = 0.003;
-
-    /**
-     * Seconds.
-     * @type {number}
-     */
-    release = 0.25;
-
-    /**
-     *
-     * @param {{threshold?:number, knee?:number, ratio?:number, attack?:number, release?:number}} [options]
-     * @returns {CompressorEffect}
-     */
-    static from({ threshold = -24, knee = 30, ratio = 12, attack = 0.003, release = 0.25 } = {}) {
-        const r = new CompressorEffect();
-
-        r.threshold = threshold;
-        r.knee = knee;
-        r.ratio = ratio;
-        r.attack = attack;
-        r.release = release;
-
-        return r;
-    }
-
-    /**
-     * @param {BaseAudioContext} ctx
-     * @returns {{input: AudioNode, output: AudioNode}}
-     */
-    build(ctx) {
-        const node = ctx.createDynamicsCompressor();
-
-        node.threshold.value = this.threshold;
-        node.knee.value = this.knee;
-        node.ratio.value = this.ratio;
-        node.attack.value = this.attack;
-        node.release.value = this.release;
-
-        return { input: node, output: node };
-    }
-
-    /**
-     *
-     * @param {CompressorEffect} other
-     * @returns {boolean}
-     */
-    equals(other) {
-        return this.threshold === other.threshold
-            && this.knee === other.knee
-            && this.ratio === other.ratio
-            && this.attack === other.attack
-            && this.release === other.release;
-    }
-
-    hash() {
-        return hash_mix3(
-            hash_mix3(
-                computeHashFloat(this.threshold),
-                computeHashFloat(this.knee),
-                computeHashFloat(this.ratio)
-            ),
-            computeHashFloat(this.attack),
-            computeHashFloat(this.release)
-        );
-    }
-
-    clone() {
-        return CompressorEffect.from(this);
-    }
-
-    toJSON() {
-        return {
-            threshold: this.threshold,
-            knee: this.knee,
-            ratio: this.ratio,
-            attack: this.attack,
-            release: this.release
-        };
-    }
-
-    fromJSON({ threshold = -24, knee = 30, ratio = 12, attack = 0.003, release = 0.25 }) {
-        this.threshold = threshold;
-        this.knee = knee;
-        this.ratio = ratio;
-        this.attack = attack;
-        this.release = release;
-    }
-}
-
-CompressorEffect.typeName = "SopraCompressorEffect";
+import { hash_mix3 } from "../../../../../core/math/hash/hash_mix3.js";
+import { computeHashFloat } from "../../../../../core/primitives/numbers/computeHashFloat.js";
+import { AbstractAudioEffect } from "./AbstractAudioEffect.js";
+
+/**
+ * @typedef {import("./AbstractAudioEffect.js").BuiltAudioEffect} BuiltAudioEffect
+ */
+
+/**
+ * Dynamics compressor insert (on a bus or an event), backed by a {@link DynamicsCompressorNode}.
+ * NOTE: this is a per-bus or per-instance insert; the engine's master compressor (in SoundEngine) is separate
+ * master-glue and is not duplicated here.
+ */
+export class CompressorEffect extends AbstractAudioEffect {
+
+    /**
+     * dB.
+     * @type {number}
+     */
+    threshold = -24;
+
+    /**
+     * dB.
+     * @type {number}
+     */
+    knee = 30;
+
+    /**
+     * @type {number}
+     */
+    ratio = 12;
+
+    /**
+     * Seconds.
+     * @type {number}
+     */
+    attack = 0.003;
+
+    /**
+     * Seconds.
+     * @type {number}
+     */
+    release = 0.25;
+
+    /**
+     *
+     * @param {{threshold?:number, knee?:number, ratio?:number, attack?:number, release?:number}} [options]
+     * @returns {CompressorEffect}
+     */
+    static from({ threshold = -24, knee = 30, ratio = 12, attack = 0.003, release = 0.25 } = {}) {
+        const r = new CompressorEffect();
+
+        r.threshold = threshold;
+        r.knee = knee;
+        r.ratio = ratio;
+        r.attack = attack;
+        r.release = release;
+
+        return r;
+    }
+
+    /**
+     * @param {BaseAudioContext} ctx
+     * @returns {BuiltAudioEffect}
+     */
+    build(ctx) {
+        const node = ctx.createDynamicsCompressor();
+
+        node.threshold.value = this.threshold;
+        node.knee.value = this.knee;
+        node.ratio.value = this.ratio;
+        node.attack.value = this.attack;
+        node.release.value = this.release;
+
+        return {
+            input: node,
+            output: node,
+            params: [node.threshold, node.knee, node.ratio, node.attack, node.release]
+        };
+    }
+
+    /**
+     *
+     * @param {CompressorEffect} other
+     * @returns {boolean}
+     */
+    equals(other) {
+        return this.threshold === other.threshold
+            && this.knee === other.knee
+            && this.ratio === other.ratio
+            && this.attack === other.attack
+            && this.release === other.release;
+    }
+
+    hash() {
+        return hash_mix3(
+            hash_mix3(
+                computeHashFloat(this.threshold),
+                computeHashFloat(this.knee),
+                computeHashFloat(this.ratio)
+            ),
+            computeHashFloat(this.attack),
+            computeHashFloat(this.release)
+        );
+    }
+
+    clone() {
+        return CompressorEffect.from(this);
+    }
+
+    toJSON() {
+        return {
+            threshold: this.threshold,
+            knee: this.knee,
+            ratio: this.ratio,
+            attack: this.attack,
+            release: this.release
+        };
+    }
+
+    fromJSON({ threshold = -24, knee = 30, ratio = 12, attack = 0.003, release = 0.25 }) {
+        this.threshold = threshold;
+        this.knee = knee;
+        this.ratio = ratio;
+        this.attack = attack;
+        this.release = release;
+    }
+}
+
+CompressorEffect.typeName = "SopraCompressorEffect";
+
+/**
+ * What a built compressor can move while it plays.
+ * @readonly
+ * @type {string[]}
+ */
+CompressorEffect.parameters = ['threshold', 'knee', 'ratio', 'attack', 'release'];

package/src/engine/sound/sopra/definition/effect/EqEffect.d.ts

@@ -13,7 +13,7 @@ export namespace EqFilterType {
     let Allpass: number;
 }
 /**
- * Equalizer / filter bus insert, backed by a {@link BiquadFilterNode}.
+ * Equalizer / filter insert (on a bus or an event), backed by a {@link BiquadFilterNode}.
  */
 export class EqEffect extends AbstractAudioEffect {
     /**
@@ -69,6 +69,8 @@ export class EqEffect extends AbstractAudioEffect {
 }
 export namespace EqEffect {
     let typeName: string;
+    let parameters: string[];
 }
+export type BuiltAudioEffect = import("./AbstractAudioEffect.js").BuiltAudioEffect;
 import { AbstractAudioEffect } from "./AbstractAudioEffect.js";
 //# sourceMappingURL=EqEffect.d.ts.map

package/src/engine/sound/sopra/definition/effect/EqEffect.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"EqEffect.d.ts","sourceRoot":"","sources":["../../../../../../../src/engine/sound/sopra/definition/effect/EqEffect.js"],"names":[],"mappings":";;;2BAOU,MAAM;;;;;;;;;;;AAoBhB;;GAEG;AACH;IAyBI;;;;OAIG;IACH,mDAHW;QAAC,UAAU,CAAC,EAAC,YAAY,GAAC,MAAM,CAAC;QAAC,SAAS,CAAC,EAAC,MAAM,CAAC;QAAC,CAAC,CAAC,EAAC,MAAM,CAAC;QAAC,MAAM,CAAC,EAAC,MAAM,CAAA;KAAC,GAC7E,QAAQ,CAWpB;IArCD;;OAEG;IACH,YAFU,YAAY,GAAC,MAAM,CAEK;IAElC;;;OAGG;IACH,WAFU,MAAM,CAEA;IAEhB;;;OAGG;IACH,GAFU,MAAM,CAEV;IAEN;;;OAGG;IACH,QAFU,MAAM,CAEL;IAiCX;;;;OAIG;IACH,cAHW,QAAQ,GACN,OAAO,CAOnB;IAED,eASC;IAED,kBAEC;IAED;;;;;MAOC;IAED;;;;;aAKC;CACJ;;;;oCA7HmC,0BAA0B"}
+{"version":3,"file":"EqEffect.d.ts","sourceRoot":"","sources":["../../../../../../../src/engine/sound/sopra/definition/effect/EqEffect.js"],"names":[],"mappings":";;;2BAWU,MAAM;;;;;;;;;;;AAoBhB;;GAEG;AACH;IAyBI;;;;OAIG;IACH,mDAHW;QAAC,UAAU,CAAC,EAAC,YAAY,GAAC,MAAM,CAAC;QAAC,SAAS,CAAC,EAAC,MAAM,CAAC;QAAC,CAAC,CAAC,EAAC,MAAM,CAAC;QAAC,MAAM,CAAC,EAAC,MAAM,CAAA;KAAC,GAC7E,QAAQ,CAWpB;IArCD;;OAEG;IACH,YAFU,YAAY,GAAC,MAAM,CAEK;IAElC;;;OAGG;IACH,WAFU,MAAM,CAEA;IAEhB;;;OAGG;IACH,GAFU,MAAM,CAEV;IAEN;;;OAGG;IACH,QAFU,MAAM,CAEL;IAqCX;;;;OAIG;IACH,cAHW,QAAQ,GACN,OAAO,CAOnB;IAED,eASC;IAED,kBAEC;IAED;;;;;MAOC;IAED;;;;;aAKC;CACJ;;;oBAOS,MAAM,EAAE;;+BAzIL,OAAO,0BAA0B,EAAE,gBAAgB;oCAH5B,0BAA0B"}

package/src/engine/sound/sopra/definition/effect/EqEffect.js

@@ -1,131 +1,146 @@
-import { hash_mix2 } from "../../../../../core/math/hash/hash_mix2.js";
-import { hash_mix3 } from "../../../../../core/math/hash/hash_mix3.js";
-import { computeHashFloat } from "../../../../../core/primitives/numbers/computeHashFloat.js";
-import { AbstractAudioEffect } from "./AbstractAudioEffect.js";
-
-/**
- * Filter type, mapped to a WebAudio {@link BiquadFilterType}.
- * @enum {number}
- */
-export const EqFilterType = {
-    Lowpass: 0,
-    Highpass: 1,
-    Bandpass: 2,
-    Lowshelf: 3,
-    Highshelf: 4,
-    Peaking: 5,
-    Notch: 6,
-    Allpass: 7
-};
-
-/**
- * @type {string[]}
- */
-const EQ_FILTER_TYPE_TO_BIQUAD = [
-    'lowpass', 'highpass', 'bandpass', 'lowshelf', 'highshelf', 'peaking', 'notch', 'allpass'
-];
-
-/**
- * Equalizer / filter bus insert, backed by a {@link BiquadFilterNode}.
- */
-export class EqEffect extends AbstractAudioEffect {
-
-    /**
-     * @type {EqFilterType|number}
-     */
-    filterType = EqFilterType.Peaking;
-
-    /**
-     * Cutoff/center frequency in Hz.
-     * @type {number}
-     */
-    frequency = 350;
-
-    /**
-     * Quality factor.
-     * @type {number}
-     */
-    Q = 1;
-
-    /**
-     * Boost/cut in decibels (only used by peaking / shelf filters).
-     * @type {number}
-     */
-    gainDb = 0;
-
-    /**
-     *
-     * @param {{filterType?:EqFilterType|number, frequency?:number, Q?:number, gainDb?:number}} [options]
-     * @returns {EqEffect}
-     */
-    static from({ filterType = EqFilterType.Peaking, frequency = 350, Q = 1, gainDb = 0 } = {}) {
-        const r = new EqEffect();
-
-        r.filterType = filterType;
-        r.frequency = frequency;
-        r.Q = Q;
-        r.gainDb = gainDb;
-
-        return r;
-    }
-
-    /**
-     * @param {BaseAudioContext} ctx
-     * @returns {{input: AudioNode, output: AudioNode}}
-     */
-    build(ctx) {
-        const node = ctx.createBiquadFilter();
-
-        node.type = EQ_FILTER_TYPE_TO_BIQUAD[this.filterType] ?? 'peaking';
-        node.frequency.value = this.frequency;
-        node.Q.value = this.Q;
-        node.gain.value = this.gainDb;
-
-        return { input: node, output: node };
-    }
-
-    /**
-     *
-     * @param {EqEffect} other
-     * @returns {boolean}
-     */
-    equals(other) {
-        return this.filterType === other.filterType
-            && this.frequency === other.frequency
-            && this.Q === other.Q
-            && this.gainDb === other.gainDb;
-    }
-
-    hash() {
-        return hash_mix2(
-            hash_mix3(
-                this.filterType,
-                computeHashFloat(this.frequency),
-                computeHashFloat(this.Q)
-            ),
-            computeHashFloat(this.gainDb)
-        );
-    }
-
-    clone() {
-        return EqEffect.from(this);
-    }
-
-    toJSON() {
-        return {
-            filterType: this.filterType,
-            frequency: this.frequency,
-            Q: this.Q,
-            gainDb: this.gainDb
-        };
-    }
-
-    fromJSON({ filterType = EqFilterType.Peaking, frequency = 350, Q = 1, gainDb = 0 }) {
-        this.filterType = filterType;
-        this.frequency = frequency;
-        this.Q = Q;
-        this.gainDb = gainDb;
-    }
-}
-
-EqEffect.typeName = "SopraEqEffect";
+import { hash_mix2 } from "../../../../../core/math/hash/hash_mix2.js";
+import { hash_mix3 } from "../../../../../core/math/hash/hash_mix3.js";
+import { computeHashFloat } from "../../../../../core/primitives/numbers/computeHashFloat.js";
+import { AbstractAudioEffect } from "./AbstractAudioEffect.js";
+
+/**
+ * @typedef {import("./AbstractAudioEffect.js").BuiltAudioEffect} BuiltAudioEffect
+ */
+
+/**
+ * Filter type, mapped to a WebAudio {@link BiquadFilterType}.
+ * @enum {number}
+ */
+export const EqFilterType = {
+    Lowpass: 0,
+    Highpass: 1,
+    Bandpass: 2,
+    Lowshelf: 3,
+    Highshelf: 4,
+    Peaking: 5,
+    Notch: 6,
+    Allpass: 7
+};
+
+/**
+ * @type {string[]}
+ */
+const EQ_FILTER_TYPE_TO_BIQUAD = [
+    'lowpass', 'highpass', 'bandpass', 'lowshelf', 'highshelf', 'peaking', 'notch', 'allpass'
+];
+
+/**
+ * Equalizer / filter insert (on a bus or an event), backed by a {@link BiquadFilterNode}.
+ */
+export class EqEffect extends AbstractAudioEffect {
+
+    /**
+     * @type {EqFilterType|number}
+     */
+    filterType = EqFilterType.Peaking;
+
+    /**
+     * Cutoff/center frequency in Hz.
+     * @type {number}
+     */
+    frequency = 350;
+
+    /**
+     * Quality factor.
+     * @type {number}
+     */
+    Q = 1;
+
+    /**
+     * Boost/cut in decibels (only used by peaking / shelf filters).
+     * @type {number}
+     */
+    gainDb = 0;
+
+    /**
+     *
+     * @param {{filterType?:EqFilterType|number, frequency?:number, Q?:number, gainDb?:number}} [options]
+     * @returns {EqEffect}
+     */
+    static from({ filterType = EqFilterType.Peaking, frequency = 350, Q = 1, gainDb = 0 } = {}) {
+        const r = new EqEffect();
+
+        r.filterType = filterType;
+        r.frequency = frequency;
+        r.Q = Q;
+        r.gainDb = gainDb;
+
+        return r;
+    }
+
+    /**
+     * @param {BaseAudioContext} ctx
+     * @returns {BuiltAudioEffect}
+     */
+    build(ctx) {
+        const node = ctx.createBiquadFilter();
+
+        node.type = EQ_FILTER_TYPE_TO_BIQUAD[this.filterType] ?? 'peaking';
+        node.frequency.value = this.frequency;
+        node.Q.value = this.Q;
+        node.gain.value = this.gainDb;
+
+        return {
+            input: node,
+            output: node,
+            params: [node.frequency, node.Q, node.gain]
+        };
+    }
+
+    /**
+     *
+     * @param {EqEffect} other
+     * @returns {boolean}
+     */
+    equals(other) {
+        return this.filterType === other.filterType
+            && this.frequency === other.frequency
+            && this.Q === other.Q
+            && this.gainDb === other.gainDb;
+    }
+
+    hash() {
+        return hash_mix2(
+            hash_mix3(
+                this.filterType,
+                computeHashFloat(this.frequency),
+                computeHashFloat(this.Q)
+            ),
+            computeHashFloat(this.gainDb)
+        );
+    }
+
+    clone() {
+        return EqEffect.from(this);
+    }
+
+    toJSON() {
+        return {
+            filterType: this.filterType,
+            frequency: this.frequency,
+            Q: this.Q,
+            gainDb: this.gainDb
+        };
+    }
+
+    fromJSON({ filterType = EqFilterType.Peaking, frequency = 350, Q = 1, gainDb = 0 }) {
+        this.filterType = filterType;
+        this.frequency = frequency;
+        this.Q = Q;
+        this.gainDb = gainDb;
+    }
+}
+
+EqEffect.typeName = "SopraEqEffect";
+
+/**
+ * What a built EQ can move while it plays. The filter TYPE is structure, not a parameter.
+ * @readonly
+ * @type {string[]}
+ */
+EqEffect.parameters = ['frequency', 'Q', 'gainDb'];

package/src/engine/sound/sopra/definition/effect/ReverbEffect.d.ts

@@ -48,5 +48,6 @@ export class ReverbEffect extends AbstractAudioEffect {
 export namespace ReverbEffect {
     let typeName: string;
 }
+export type BuiltAudioEffect = import("./AbstractAudioEffect.js").BuiltAudioEffect;
 import { AbstractAudioEffect } from "./AbstractAudioEffect.js";
 //# sourceMappingURL=ReverbEffect.d.ts.map

package/src/engine/sound/sopra/definition/effect/ReverbEffect.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"ReverbEffect.d.ts","sourceRoot":"","sources":["../../../../../../../src/engine/sound/sopra/definition/effect/ReverbEffect.js"],"names":[],"mappings":"AAmBA;;;;;;;;;;;GAWG;AACH;IAcI;;;OAGG;IACH,2CAHW;QAAC,YAAY,CAAC,EAAC,MAAM,CAAC;QAAC,UAAU,CAAC,EAAC,MAAM,CAAA;KAAC,GACxC,YAAY,CASxB;IAvBD;;;OAGG;IACH,cAFU,MAAM,CAEG;IAEnB;;;OAGG;IACH,YAFU,MAAM,CAED;IAoCf;;;OAGG;IACH,cAHW,YAAY,GACV,OAAO,CAKnB;IAED,eAKC;IAED,sBAEC;IAED;;;MAKC;IAED;;;aAGC;CACJ;;;;oCA1GmC,0BAA0B"}
+{"version":3,"file":"ReverbEffect.d.ts","sourceRoot":"","sources":["../../../../../../../src/engine/sound/sopra/definition/effect/ReverbEffect.js"],"names":[],"mappings":"AAuBA;;;;;;;;;;;GAWG;AACH;IAcI;;;OAGG;IACH,2CAHW;QAAC,YAAY,CAAC,EAAC,MAAM,CAAC;QAAC,UAAU,CAAC,EAAC,MAAM,CAAA;KAAC,GACxC,YAAY,CASxB;IAvBD;;;OAGG;IACH,cAFU,MAAM,CAEG;IAEnB;;;OAGG;IACH,YAFU,MAAM,CAED;IAqCf;;;OAGG;IACH,cAHW,YAAY,GACV,OAAO,CAKnB;IAED,eAKC;IAED,sBAEC;IAED;;;MAKC;IAED;;;aAGC;CACJ;;;;+BA5GY,OAAO,0BAA0B,EAAE,gBAAgB;oCAH5B,0BAA0B"}

package/src/engine/sound/sopra/definition/effect/ReverbEffect.js

@@ -4,6 +4,10 @@ import { computeHashFloat } from "../../../../../core/primitives/numbers/compute
 import { reverbImpulseResponse } from "../../../simulation/render/reverbImpulseResponse.js";
 import { AbstractAudioEffect } from "./AbstractAudioEffect.js";
 
+/**
+ * @typedef {import("./AbstractAudioEffect.js").BuiltAudioEffect} BuiltAudioEffect
+ */
+
 /**
  * Seed for the procedural impulse response. Fixed (not authorable): the IR is a decaying noise tail whose
  * audible character comes entirely from `decaySeconds`/`decayPower`, so the noise realisation carries no
@@ -58,7 +62,8 @@ export class ReverbEffect extends AbstractAudioEffect {
 
     /**
      * @param {BaseAudioContext} ctx
-     * @returns {{input: AudioNode, output: AudioNode}}
+     * @returns {BuiltAudioEffect} no params: the tail is baked into the impulse response at build, so
+     *          {@link ReverbEffect.parameters} is empty (inherited)
      */
     build(ctx) {
         const convolver = ctx.createConvolver();