@woosh/meep-engine 3.46.0 → 3.49.0

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

@@ -12,6 +12,10 @@ export const BUS_ROOT_PARENT: string;
  *
  * Each bus is wired `input → effect[0] → … → effect[n] → gain(output)`; the output then connects to
  * its parent bus's input, or to the engine destination for a root bus (parentId === "").
+ *
+ * A bus's inserts are an {@link EffectChain}, and their parameters move through {@link setEffectParam} /
+ * {@link approachEffectParam} — the same two verbs as the fader's {@link setVolume} / {@link approachVolume}.
+ * The graph's nodes stay its own.
  */
 export class BusGraph {
     /**
@@ -20,13 +24,16 @@ export class BusGraph {
      */
     constructor(ctx: BaseAudioContext, destination: AudioNode);
     /**
-     * id -> { definition, input, output }
-     * @type {Map<string, {definition: BusDefinition, input: AudioNode, output: GainNode}>}
+     * id -> the bus's live record
+     * @type {Map<string, {definition: BusDefinition, input: AudioNode, output: GainNode, nominal: number, effects: EffectChain|null, sends: GainNode[]}>}
      */
     buses: Map<string, {
         definition: BusDefinition;
         input: AudioNode;
         output: GainNode;
+        nominal: number;
+        effects: EffectChain | null;
+        sends: GainNode[];
     }>;
     /**
      * Build the graph from a flat list of bus definitions. Order-independent: all nodes are created
@@ -69,6 +76,40 @@ export class BusGraph {
      * @returns {AudioNode}
      */
     getOutput(id: string): AudioNode;
+    /**
+     * Move a parameter of one of a bus's insert effects, now. See {@link EffectChain#setParam}.
+     * @param {string} id bus
+     * @param {number} effectIndex position in the bus definition's `effects`
+     * @param {string} name one of that effect class's `parameters` (`'frequency'` on an `EqEffect`)
+     * @param {number} value in the parameter's own units
+     */
+    setEffectParam(id: string, effectIndex: number, name: string, value: number): void;
+    /**
+     * Glide a parameter of one of a bus's insert effects toward `value`. See {@link EffectChain#approachParam}.
+     * @param {string} id bus
+     * @param {number} effectIndex
+     * @param {string} name
+     * @param {number} value
+     * @param {number} timeConstant seconds, above 0
+     */
+    approachEffectParam(id: string, effectIndex: number, name: string, value: number, timeConstant: number): void;
+    /**
+     * Where a bus effect's parameter was last sent (a glide's target, not where it has got to).
+     * @param {string} id bus
+     * @param {number} effectIndex
+     * @param {string} name
+     * @returns {number}
+     */
+    getEffectParam(id: string, effectIndex: number, name: string): number;
+    /**
+     * Whether this graph has bus `id`, with an insert at `effectIndex` exposing a parameter `name` — an
+     * address {@link setEffectParam} would take. Asks; never throws.
+     * @param {string} id bus
+     * @param {number} effectIndex
+     * @param {string} name
+     * @returns {boolean}
+     */
+    hasEffectParam(id: string, effectIndex: number, name: string): boolean;
     /**
      * @param {string} id
      * @returns {number} linear gain
@@ -116,4 +157,5 @@ export class BusGraph {
     #private;
 }
 export type BusDefinition = import("../definition/BusDefinition.js").BusDefinition;
+import { EffectChain } from "./EffectChain.js";
 //# sourceMappingURL=BusGraph.d.ts.map

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;;GAEG;AAEH;;;;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,EAAE,aAAa,CAAC;QAAC,KAAK,EAAE,SAAS,CAAC;QAAC,MAAM,EAAE,QAAQ,CAAA;KAAC,CAAC,CAEpE;IAqBlB;;;;OAIG;IACH,mBAFW,aAAa,EAAE,QA4FzB;IAED;;;;;;;;;;;;;;;OAeG;IACH,gBAcC;IAED;;;OAGG;IACH,QAHW,MAAM,GACJ,OAAO,CAInB;IAoBD;;;;OAIG;IACH,aAHW,MAAM,GACJ,SAAS,CAIrB;IAED;;;;;OAKG;IACH,cAHW,MAAM,GACJ,SAAS,CAIrB;IAED;;;OAGG;IACH,cAHW,MAAM,GACJ,MAAM,CAIlB;IAED;;;;;;;;;;;;;;;OAeG;IACH,cAHW,MAAM,UACN,MAAM,QAkBhB;IAED;;;OAGG;IACH,gBAHW,MAAM,GACJ,MAAM,CAIlB;IAED;;;;;;;OAOG;IACH,eALW,MAAM,UACN,MAAM,YACN,MAAM,eACN,MAAM,QAOhB;IAED;;;;;;OAMG;IACH,mBAJW,MAAM,UACN,MAAM,gBACN,MAAM,QAQhB;;CACJ;4BAxSY,OAAO,gCAAgC,EAAE,aAAa"}
+{"version":3,"file":"BusGraph.d.ts","sourceRoot":"","sources":["../../../../../../src/engine/sound/sopra/runtime/BusGraph.js"],"names":[],"mappings":"AAKA;;GAEG;AAEH;;;;GAIG;AACH,8BAFU,MAAM,CAEkB;AAElC;;;;;;;;;GASG;AACH;IAkBI;;;OAGG;IACH,iBAHW,gBAAgB,eAChB,SAAS,EAKnB;IAvBD;;;OAGG;IACH,OAFU,IAAI,MAAM,EAAE;QAAC,UAAU,EAAE,aAAa,CAAC;QAAC,KAAK,EAAE,SAAS,CAAC;QAAC,MAAM,EAAE,QAAQ,CAAC;QAAC,OAAO,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,WAAW,GAAC,IAAI,CAAC;QAAC,KAAK,EAAE,QAAQ,EAAE,CAAA;KAAC,CAAC,CAEnI;IAqBlB;;;;OAIG;IACH,mBAFW,aAAa,EAAE,QAqEzB;IAED;;;;;;;;;;;;;;;OAeG;IACH,gBAcC;IAED;;;OAGG;IACH,QAHW,MAAM,GACJ,OAAO,CAInB;IAoBD;;;;OAIG;IACH,aAHW,MAAM,GACJ,SAAS,CAIrB;IAED;;;;;OAKG;IACH,cAHW,MAAM,GACJ,SAAS,CAIrB;IAkBD;;;;;;OAMG;IACH,mBALW,MAAM,eACN,MAAM,QACN,MAAM,SACN,MAAM,QAIhB;IAED;;;;;;;OAOG;IACH,wBANW,MAAM,eACN,MAAM,QACN,MAAM,SACN,MAAM,gBACN,MAAM,QAIhB;IAED;;;;;;OAMG;IACH,mBALW,MAAM,eACN,MAAM,QACN,MAAM,GACJ,MAAM,CAIlB;IAED;;;;;;;OAOG;IACH,mBALW,MAAM,eACN,MAAM,QACN,MAAM,GACJ,OAAO,CAMnB;IAED;;;OAGG;IACH,cAHW,MAAM,GACJ,MAAM,CAIlB;IAED;;;;;;;;;;;;;;;OAeG;IACH,cAHW,MAAM,UACN,MAAM,QAYhB;IAED;;;OAGG;IACH,gBAHW,MAAM,GACJ,MAAM,CAIlB;IAED;;;;;;;OAOG;IACH,eALW,MAAM,UACN,MAAM,YACN,MAAM,eACN,MAAM,QAOhB;IAED;;;;;;OAMG;IACH,mBAJW,MAAM,UACN,MAAM,gBACN,MAAM,QAQhB;;CACJ;4BA/UY,OAAO,gCAAgC,EAAE,aAAa;4BAHvC,kBAAkB"}

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

@@ -1,6 +1,7 @@
 import { dB2Volume } from "../../dB2Volume.js";
 import { volume2dB } from "../../volume2dB.js";
-import { rampGain } from "../util/fadeOutAndStop.js";
+import { cancelAndHold, rampGain } from "../util/fadeOutAndStop.js";
+import { EffectChain } from "./EffectChain.js";
 
 /**
  * @typedef {import("../definition/BusDefinition.js").BusDefinition} BusDefinition
@@ -18,12 +19,16 @@ export const BUS_ROOT_PARENT = "";
  *
  * Each bus is wired `input → effect[0] → … → effect[n] → gain(output)`; the output then connects to
  * its parent bus's input, or to the engine destination for a root bus (parentId === "").
+ *
+ * A bus's inserts are an {@link EffectChain}, and their parameters move through {@link setEffectParam} /
+ * {@link approachEffectParam} — the same two verbs as the fader's {@link setVolume} / {@link approachVolume}.
+ * The graph's nodes stay its own.
  */
 export class BusGraph {
 
     /**
-     * id -> { definition, input, output }
-     * @type {Map<string, {definition: BusDefinition, input: AudioNode, output: GainNode}>}
+     * id -> the bus's live record
+     * @type {Map<string, {definition: BusDefinition, input: AudioNode, output: GainNode, nominal: number, effects: EffectChain|null, sends: GainNode[]}>}
      */
     buses = new Map();
 
@@ -63,44 +68,21 @@ export class BusGraph {
             gain.gain.setValueAtTime(nominal, 0);
 
             let input = gain;
+            let effects = null;
 
-            // every node this bus owns, so {@link dispose} can unwire the lot rather than only the
-            // ends of the chain
-            const chain = [];
-
-            const effects = def.effects;
-
-            if (effects.length > 0) {
-                let previousOutput = null;
-
-                for (let e = 0; e < effects.length; e++) {
-                    const built = effects[e].build(ctx);
-
-                    chain.push(built.input);
+            if (def.effects.length > 0) {
+                effects = new EffectChain(ctx, def.effects);
 
-                    if (built.output !== built.input) {
-                        chain.push(built.output);
-                    }
-
-                    if (previousOutput === null) {
-                        // first effect is the chain head
-                        input = built.input;
-                    } else {
-                        previousOutput.connect(built.input);
-                    }
-
-                    previousOutput = built.output;
-                }
-
-                // last effect feeds the bus gain (output)
-                previousOutput.connect(gain);
+                // the inserts' tail feeds the bus gain (output); their head is the bus input
+                effects.output.connect(gain);
+                input = effects.input;
             }
 
             // `nominal` is the authoritative logical fader gain (linear), tracked separately from the
             // node's instantaneous `.value` — which WebAudio does NOT update under ramps/setTargetAtTime.
             // get/setVolume read/write `nominal`; ducking (approachVolume) is a transient modulation that
             // deliberately does NOT touch it, so the duck can capture + restore the true nominal.
-            this.buses.set(def.id, { definition: def, input, output: gain, nominal, chain, sends: [] });
+            this.buses.set(def.id, { definition: def, input, output: gain, nominal, effects, sends: [] });
         }
 
         // pass 2: route each bus output to its parent's input (or the engine destination)
@@ -163,8 +145,8 @@ export class BusGraph {
         for (const bus of this.buses.values()) {
             bus.output.disconnect();
 
-            for (let i = 0; i < bus.chain.length; i++) {
-                bus.chain[i].disconnect();
+            if (bus.effects !== null) {
+                bus.effects.disconnect();
             }
 
             for (let i = 0; i < bus.sends.length; i++) {
@@ -189,7 +171,7 @@ export class BusGraph {
      * factored here instead of being repeated verbatim in each accessor — one place owns the message and
      * the "unknown bus is fatal" policy.
      * @param {string} id
-     * @returns {{definition: BusDefinition, input: AudioNode, output: GainNode}}
+     * @returns {{definition: BusDefinition, input: AudioNode, output: GainNode, nominal: number, effects: EffectChain|null, sends: GainNode[]}}
      */
     #bus(id) {
         const bus = this.buses.get(id);
@@ -220,6 +202,70 @@ export class BusGraph {
         return this.#bus(id).output;
     }
 
+    /**
+     * The bus's inserts — throws if it has none, since addressing an effect on a bus that defines no
+     * effects is the same programming error as addressing a bus that does not exist.
+     * @param {string} id
+     * @returns {EffectChain}
+     */
+    #effects(id) {
+        const effects = this.#bus(id).effects;
+
+        if (effects === null) {
+            throw new Error(`sopra: bus '${id}' has no effects`);
+        }
+
+        return effects;
+    }
+
+    /**
+     * Move a parameter of one of a bus's insert effects, now. See {@link EffectChain#setParam}.
+     * @param {string} id bus
+     * @param {number} effectIndex position in the bus definition's `effects`
+     * @param {string} name one of that effect class's `parameters` (`'frequency'` on an `EqEffect`)
+     * @param {number} value in the parameter's own units
+     */
+    setEffectParam(id, effectIndex, name, value) {
+        this.#effects(id).setParam(effectIndex, name, value);
+    }
+
+    /**
+     * Glide a parameter of one of a bus's insert effects toward `value`. See {@link EffectChain#approachParam}.
+     * @param {string} id bus
+     * @param {number} effectIndex
+     * @param {string} name
+     * @param {number} value
+     * @param {number} timeConstant seconds, above 0
+     */
+    approachEffectParam(id, effectIndex, name, value, timeConstant) {
+        this.#effects(id).approachParam(effectIndex, name, value, timeConstant);
+    }
+
+    /**
+     * Where a bus effect's parameter was last sent (a glide's target, not where it has got to).
+     * @param {string} id bus
+     * @param {number} effectIndex
+     * @param {string} name
+     * @returns {number}
+     */
+    getEffectParam(id, effectIndex, name) {
+        return this.#effects(id).getParam(effectIndex, name);
+    }
+
+    /**
+     * Whether this graph has bus `id`, with an insert at `effectIndex` exposing a parameter `name` — an
+     * address {@link setEffectParam} would take. Asks; never throws.
+     * @param {string} id bus
+     * @param {number} effectIndex
+     * @param {string} name
+     * @returns {boolean}
+     */
+    hasEffectParam(id, effectIndex, name) {
+        const bus = this.buses.get(id);
+
+        return bus !== undefined && bus.effects !== null && bus.effects.hasParam(effectIndex, name);
+    }
+
     /**
      * @param {string} id
      * @returns {number} linear gain
@@ -252,13 +298,7 @@ export class BusGraph {
         const param = bus.output.gain;
         const now = this.#ctx.currentTime;
 
-        if (typeof param.cancelAndHoldAtTime === "function") {
-            param.cancelAndHoldAtTime(now);
-        } else {
-            // portable fallback (Firefox), as in `rampGain`
-            param.cancelScheduledValues(now);
-        }
-
+        cancelAndHold(param, now);
         param.setValueAtTime(linear, now);
     }
 

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

@@ -0,0 +1,96 @@
+/**
+ * Resolve an effect-parameter address against a list of effect definitions: the position of `name` among
+ * the class `parameters` of the effect at `index`, or throw naming what the list does have. The one
+ * place an `(effect index, parameter name)` address is checked — a chain resolves through it, and so does
+ * anything that holds addresses for a chain not yet built (`EffectParamOverrides`).
+ * @param {AbstractAudioEffect[]} effects
+ * @param {number} index
+ * @param {string} name
+ * @returns {number}
+ */
+export function effectParamIndex(effects: AbstractAudioEffect[], index: number, name: string): number;
+/**
+ * @typedef {import("../definition/effect/AbstractAudioEffect.js").AbstractAudioEffect} AbstractAudioEffect
+ */
+/**
+ * The live nodes of an ordered list of insert effects, wired `effect[0] → … → effect[n]`, and the one place
+ * their parameters are moved at runtime.
+ *
+ * Shared by a bus's inserts ({@link BusGraph}) and a single play's inserts ({@link EventInstance}), so both
+ * address a parameter the same way: by the effect's index in the list it was built from and the parameter's
+ * name, one of the effect class's {@link AbstractAudioEffect.parameters} — the name of the definition field
+ * it starts from (`EqEffect.frequency` → `'frequency'`).
+ *
+ * Each parameter's NOMINAL value — where it was last sent — is tracked here rather than read back from the
+ * node, because WebAudio does not move `AudioParam.value` under scheduled automation: a glide's target is
+ * only visible in the automation list.
+ *
+ * Built once per bus and once per playing instance, so it is kept small: the parameter names are the
+ * effect classes' own static lists (read through the definitions, never copied), and the per-chain state is
+ * three flat arrays.
+ */
+export class EffectChain {
+    /**
+     * @param {BaseAudioContext} ctx
+     * @param {AbstractAudioEffect[]} effects at least one
+     */
+    constructor(ctx: BaseAudioContext, effects: AbstractAudioEffect[]);
+    /**
+     * Head of the chain: what feeds it connects here.
+     * @type {AudioNode}
+     */
+    input: AudioNode;
+    /**
+     * Tail of the chain: connect this onward.
+     * @type {AudioNode}
+     */
+    output: AudioNode;
+    /**
+     * @returns {number} how many effects the chain holds
+     */
+    get length(): number;
+    /**
+     * Whether the chain has an effect at `index` exposing a parameter called `name` — an address
+     * {@link setParam} would take. Asks; never throws.
+     * @param {number} index
+     * @param {string} name
+     * @returns {boolean}
+     */
+    hasParam(index: number, name: string): boolean;
+    /**
+     * Move an effect's parameter to `value`, now. Whatever automation was in flight on it is cancelled.
+     *
+     * @param {number} index effect's position in the list the chain was built from
+     * @param {string} name one of the effect class's `parameters`
+     * @param {number} value in the parameter's own units (Hz, dB, ...)
+     */
+    setParam(index: number, name: string, value: number): void;
+    /**
+     * Glide an effect's parameter toward `value` exponentially, covering ~63% of the way per
+     * `timeConstant` — the WebAudio `setTargetAtTime` glide, and the counterpart of
+     * {@link BusGraph#approachVolume}. Whatever was in flight is cancelled and held first, so a value sent
+     * every frame (a filter tracking a game value) retargets from wherever the last glide had got to, and
+     * the automation list never grows.
+     *
+     * @param {number} index
+     * @param {string} name
+     * @param {number} value
+     * @param {number} timeConstant seconds, above 0
+     */
+    approachParam(index: number, name: string, value: number, timeConstant: number): void;
+    /**
+     * Where an effect's parameter was last sent — the target of a glide still in flight, not the value it
+     * has reached — or its defined value if it has not been moved.
+     * @param {number} index
+     * @param {string} name
+     * @returns {number}
+     */
+    getParam(index: number, name: string): number;
+    /**
+     * Unwire every node the chain owns. Idempotent.
+     */
+    disconnect(): void;
+    #private;
+}
+export type AbstractAudioEffect = import("../definition/effect/AbstractAudioEffect.js").AbstractAudioEffect;
+//# sourceMappingURL=EffectChain.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"EffectChain.d.ts","sourceRoot":"","sources":["../../../../../../src/engine/sound/sopra/runtime/EffectChain.js"],"names":[],"mappings":"AAoQA;;;;;;;;;GASG;AACH,0CALW,mBAAmB,EAAE,SACrB,MAAM,QACN,MAAM,GACJ,MAAM,CAiBlB;AA1RD;;GAEG;AAEH;;;;;;;;;;;;;;;;GAgBG;AACH;IA4CI;;;OAGG;IACH,iBAHW,gBAAgB,WAChB,mBAAmB,EAAE,EA6D/B;IAzGD;;;OAGG;IACH,OAFU,SAAS,CAEb;IAEN;;;OAGG;IACH,QAFU,SAAS,CAEZ;IAiGP;;OAEG;IACH,qBAEC;IAED;;;;;;OAMG;IACH,gBAJW,MAAM,QACN,MAAM,GACJ,OAAO,CAMnB;IAoBD;;;;;;OAMG;IACH,gBAJW,MAAM,QACN,MAAM,SACN,MAAM,QAchB;IAED;;;;;;;;;;;OAWG;IACH,qBALW,MAAM,QACN,MAAM,SACN,MAAM,gBACN,MAAM,QAehB;IAED;;;;;;OAMG;IACH,gBAJW,MAAM,QACN,MAAM,GACJ,MAAM,CAIlB;IAED;;OAEG;IACH,mBAMC;;CACJ;kCA5OY,OAAO,6CAA6C,EAAE,mBAAmB"}

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

@@ -0,0 +1,286 @@
+import { assert } from "../../../../core/assert.js";
+import { cancelAndHold } from "../util/fadeOutAndStop.js";
+
+/**
+ * @typedef {import("../definition/effect/AbstractAudioEffect.js").AbstractAudioEffect} AbstractAudioEffect
+ */
+
+/**
+ * The live nodes of an ordered list of insert effects, wired `effect[0] → … → effect[n]`, and the one place
+ * their parameters are moved at runtime.
+ *
+ * Shared by a bus's inserts ({@link BusGraph}) and a single play's inserts ({@link EventInstance}), so both
+ * address a parameter the same way: by the effect's index in the list it was built from and the parameter's
+ * name, one of the effect class's {@link AbstractAudioEffect.parameters} — the name of the definition field
+ * it starts from (`EqEffect.frequency` → `'frequency'`).
+ *
+ * Each parameter's NOMINAL value — where it was last sent — is tracked here rather than read back from the
+ * node, because WebAudio does not move `AudioParam.value` under scheduled automation: a glide's target is
+ * only visible in the automation list.
+ *
+ * Built once per bus and once per playing instance, so it is kept small: the parameter names are the
+ * effect classes' own static lists (read through the definitions, never copied), and the per-chain state is
+ * three flat arrays.
+ */
+export class EffectChain {
+
+    /**
+     * Head of the chain: what feeds it connects here.
+     * @type {AudioNode}
+     */
+    input;
+
+    /**
+     * Tail of the chain: connect this onward.
+     * @type {AudioNode}
+     */
+    output;
+
+    /**
+     * @type {BaseAudioContext}
+     */
+    #ctx;
+
+    /**
+     * The definitions the chain was built from — the source of each effect's parameter names. Shared with
+     * the owner (a bus or event definition); never written.
+     * @type {AbstractAudioEffect[]}
+     */
+    #effects;
+
+    /**
+     * Each effect's input and output node, in chain order: `[in0, out0, in1, out1, …]`. For {@link disconnect}.
+     * @type {AudioNode[]}
+     */
+    #nodes;
+
+    /**
+     * Every effect's live params, effect by effect, each effect's in its class's `parameters` order.
+     * @type {AudioParam[]}
+     */
+    #params;
+
+    /**
+     * Where each param of {@link #params} was last sent, same layout.
+     * @type {Float64Array}
+     */
+    #nominal;
+
+    /**
+     * @param {BaseAudioContext} ctx
+     * @param {AbstractAudioEffect[]} effects at least one
+     */
+    constructor(ctx, effects) {
+        assert.defined(ctx, 'ctx');
+        assert.isArray(effects, 'effects');
+        assert.greaterThan(effects.length, 0, 'effects.length');
+
+        this.#ctx = ctx;
+        this.#effects = effects;
+
+        const effectCount = effects.length;
+
+        let paramCount = 0;
+        for (let i = 0; i < effectCount; i++) {
+            paramCount += parametersOf(effects[i]).length;
+        }
+
+        const nodes = new Array(effectCount * 2);
+        const params = new Array(paramCount);
+        const nominal = new Float64Array(paramCount);
+
+        let slot = 0;
+        let previousOutput = null;
+
+        for (let i = 0; i < effectCount; i++) {
+            const effect = effects[i];
+            const built = effect.build(ctx);
+            const names = parametersOf(effect);
+
+            nodes[i * 2] = built.input;
+            nodes[i * 2 + 1] = built.output;
+
+            if (previousOutput === null) {
+                this.input = built.input;
+            } else {
+                previousOutput.connect(built.input);
+            }
+
+            previousOutput = built.output;
+
+            if (names.length > 0) {
+                const exposed = built.params;
+
+                // the class's list is the contract `build` answers to; a mismatch would silently move
+                // the wrong param, so it is refused here, where the effect that broke it is known
+                if (exposed === undefined || exposed.length !== names.length) {
+                    throw new Error(`sopra: ${effect.constructor.name}.build returned ${exposed === undefined ? 'no' : exposed.length} params, its class declares ${names.length} (${names.join(', ')})`);
+                }
+
+                for (let p = 0; p < names.length; p++) {
+                    params[slot] = exposed[p];
+                    nominal[slot] = exposed[p].value;
+                    slot++;
+                }
+            }
+        }
+
+        this.output = previousOutput;
+        this.#nodes = nodes;
+        this.#params = params;
+        this.#nominal = nominal;
+    }
+
+    /**
+     * @returns {number} how many effects the chain holds
+     */
+    get length() {
+        return this.#effects.length;
+    }
+
+    /**
+     * Whether the chain has an effect at `index` exposing a parameter called `name` — an address
+     * {@link setParam} would take. Asks; never throws.
+     * @param {number} index
+     * @param {string} name
+     * @returns {boolean}
+     */
+    hasParam(index, name) {
+        const effect = effectAt(this.#effects, index);
+
+        return effect !== undefined && parametersOf(effect).indexOf(name) !== -1;
+    }
+
+    /**
+     * The flat slot of an effect's parameter, or throw naming what does exist.
+     * @param {number} index
+     * @param {string} name
+     * @returns {number}
+     */
+    #slot(index, name) {
+        const effects = this.#effects;
+        const p = effectParamIndex(effects, index, name);
+
+        let slot = 0;
+        for (let i = 0; i < index; i++) {
+            slot += parametersOf(effects[i]).length;
+        }
+
+        return slot + p;
+    }
+
+    /**
+     * Move an effect's parameter to `value`, now. Whatever automation was in flight on it is cancelled.
+     *
+     * @param {number} index effect's position in the list the chain was built from
+     * @param {string} name one of the effect class's `parameters`
+     * @param {number} value in the parameter's own units (Hz, dB, ...)
+     */
+    setParam(index, name, value) {
+        // an AudioParam throws on a non-finite value, so say which call sent it
+        assert.isFinite(value, 'value');
+
+        const slot = this.#slot(index, name);
+        const param = this.#params[slot];
+        const now = this.#ctx.currentTime;
+
+        this.#nominal[slot] = value;
+
+        cancelAndHold(param, now);
+        param.setValueAtTime(value, now);
+    }
+
+    /**
+     * Glide an effect's parameter toward `value` exponentially, covering ~63% of the way per
+     * `timeConstant` — the WebAudio `setTargetAtTime` glide, and the counterpart of
+     * {@link BusGraph#approachVolume}. Whatever was in flight is cancelled and held first, so a value sent
+     * every frame (a filter tracking a game value) retargets from wherever the last glide had got to, and
+     * the automation list never grows.
+     *
+     * @param {number} index
+     * @param {string} name
+     * @param {number} value
+     * @param {number} timeConstant seconds, above 0
+     */
+    approachParam(index, name, value, timeConstant) {
+        assert.isFinite(value, 'value');
+        assert.isFinite(timeConstant, 'timeConstant');
+        assert.greaterThan(timeConstant, 0, 'timeConstant');
+
+        const slot = this.#slot(index, name);
+        const param = this.#params[slot];
+        const now = this.#ctx.currentTime;
+
+        this.#nominal[slot] = value;
+
+        cancelAndHold(param, now);
+        param.setTargetAtTime(value, now, timeConstant);
+    }
+
+    /**
+     * Where an effect's parameter was last sent — the target of a glide still in flight, not the value it
+     * has reached — or its defined value if it has not been moved.
+     * @param {number} index
+     * @param {string} name
+     * @returns {number}
+     */
+    getParam(index, name) {
+        return this.#nominal[this.#slot(index, name)];
+    }
+
+    /**
+     * Unwire every node the chain owns. Idempotent.
+     */
+    disconnect() {
+        const nodes = this.#nodes;
+
+        for (let i = 0; i < nodes.length; i++) {
+            nodes[i].disconnect();
+        }
+    }
+}
+
+/**
+ * @param {AbstractAudioEffect} effect
+ * @returns {string[]}
+ */
+function parametersOf(effect) {
+    return effect.constructor.parameters;
+}
+
+/**
+ * @param {AbstractAudioEffect[]} effects
+ * @param {number} index
+ * @returns {AbstractAudioEffect|undefined} undefined for an index that is no position in the list
+ *          (negative, fractional, past the end)
+ */
+function effectAt(effects, index) {
+    return Number.isInteger(index) ? effects[index] : undefined;
+}
+
+/**
+ * Resolve an effect-parameter address against a list of effect definitions: the position of `name` among
+ * the class `parameters` of the effect at `index`, or throw naming what the list does have. The one
+ * place an `(effect index, parameter name)` address is checked — a chain resolves through it, and so does
+ * anything that holds addresses for a chain not yet built (`EffectParamOverrides`).
+ * @param {AbstractAudioEffect[]} effects
+ * @param {number} index
+ * @param {string} name
+ * @returns {number}
+ */
+export function effectParamIndex(effects, index, name) {
+    const effect = effectAt(effects, index);
+
+    if (effect === undefined) {
+        throw new Error(`sopra: no effect at index ${index} (there are ${effects.length})`);
+    }
+
+    const names = parametersOf(effect);
+    const p = names.indexOf(name);
+
+    if (p === -1) {
+        throw new Error(`sopra: effect ${index} has no parameter '${name}' (it exposes: ${names.join(', ') || 'none'})`);
+    }
+
+    return p;
+}