@driftengine/audio 3.61.0

package/dist/mix/bus.js

@@ -0,0 +1,293 @@
+import { clamp01 } from '../filters.js';
+/**
+ * One bus: everything that reaches it, through whatever it inserts, at whatever level it is set to.
+ *
+ * Three nodes rather than one, and each earns its place:
+ *
+ * ```
+ *   input ─ [inserts] ─ tap ─ [post-send inserts] ─ output ─→ parent.input
+ *                        └─ send gain ─→ a return bus
+ * ```
+ *
+ * **`input` is the fader**, and it is at the *top* of the chain rather than the bottom. That is not
+ * a preference: it is what makes a send post-fader, and it is what the mix this replaces already
+ * did — the level sat ahead of the lift, and the sends hung off the lift. A fader at the bottom
+ * would leave every insert and every send working on unattenuated signal, so turning a bus down
+ * would leave its reverb at full strength.
+ *
+ * **`tap` is where sends listen from**, and it exists as a real node so that rewiring the chain
+ * cannot silently move what the sends hear. Inserts added normally land above it and are heard by
+ * the sends; an insert added `postSend` lands below it and is not. The slam is the reason that flag
+ * exists: `graph.ts` says the sends hang off the stage before it "so the reverb tail never hears
+ * the slam", because a six-second convolution of a clipped bass hit is a mess still arriving three
+ * gates later.
+ *
+ * **`output` is a unity sum**, for the reason `AudioGraph.out` gives: what a parent hears has to be
+ * a node and not an implicit sum at somebody else's input, or nothing can ever be inserted between
+ * a bus and its parent.
+ *
+ * Cost: two multiplications by unity per bus that a hand-wired graph would not have. Both are exact
+ * in floating point, so they cannot move a mix — measured, by the gate in `scripts/audio-baseline.mjs`,
+ * which is bit-exact and passes across this change. What would make this wrong is a tree deep
+ * enough for the node count itself to matter, which at the depth a game mixes at — a master, a few
+ * groups, their children — it is not.
+ */
+/**
+ * Smoothing for parameter moves, seconds.
+ *
+ * The same 0.08 the mix has always used, and it lives here now because a bus is where every level
+ * move goes. Long enough to never click; short enough that a fader feels immediate.
+ */
+export const RAMP = 0.08;
+export class MixBus {
+    name;
+    context;
+    scheduleAt;
+    /** The fader. Sources and child buses connect here. */
+    input;
+    /** Where sends listen from. Unity, always. */
+    tap;
+    /** What the parent hears. Unity, always. */
+    output;
+    parent;
+    kids = [];
+    inserts = [];
+    /**
+     * Nodes fed from this bus's pre-insert signal, restored whenever the chain is rewired.
+     *
+     * For a stage that needs the bus as it arrives rather than as its own position in the chain would
+     * give it. The slam is the case: its wet path is tapped upstream of the lift's high-pass, because
+     * a low-cut ahead of the tap would make the effect vanish exactly when the player is in the air,
+     * which is where half of it is used. Registered rather than connected once, because `rebuild`
+     * disconnects `input` and would otherwise silently drop it the next time an insert is added.
+     */
+    inputTaps = [];
+    sends = new Map();
+    /**
+     * What each send was last asked for.
+     *
+     * Mirrored rather than read back off the parameter, for the reason `AudioGraph.mixLevels` gives:
+     * a send is ramped, and mid-ramp `gain.value` is somewhere between where it was and where it is
+     * going. A snapshot capturing sends would otherwise record whatever instant it happened to ask on.
+     */
+    sendAmounts = new Map();
+    levelValue;
+    mutedValue = false;
+    soloedValue = false;
+    /**
+     * What solo has decided about this bus, from the console that can see the whole tree.
+     *
+     * A separate factor rather than a second write to the level, because a bus silenced by somebody
+     * else's solo must come back to the level its own fader is at, and a single value cannot remember
+     * two decisions.
+     */
+    soloGateValue = 1;
+    /**
+     * A temporary move over the top of the fader, without disturbing it.
+     *
+     * The distinction `AudioGraph.fadeMusic` and `AudioGraph.levels` spent two paragraphs on: a fade
+     * is part of an *edit* and has to end by returning to whatever the player chose, so it cannot be
+     * allowed to overwrite that choice. Here the choice stays in `levelValue` and the edit is a
+     * factor beside it, which means the value to come back to is `1` rather than something the caller
+     * has to have remembered.
+     */
+    duckFactor = 1;
+    constructor(name, context, scheduleAt, options = {}) {
+        this.name = name;
+        this.context = context;
+        this.scheduleAt = scheduleAt;
+        this.levelValue = options.level === undefined ? 1 : clamp01(options.level);
+        this.parent = options.parent ?? null;
+        this.input = context.createGain();
+        this.input.gain.value = this.levelValue;
+        this.tap = context.createGain();
+        this.output = context.createGain();
+        this.rebuild();
+        if (this.parent !== null) {
+            this.output.connect(this.parent.input);
+            this.parent.kids.push(this);
+        }
+    }
+    get children() {
+        return this.kids;
+    }
+    get level() {
+        return this.levelValue;
+    }
+    get muted() {
+        return this.mutedValue;
+    }
+    get soloed() {
+        return this.soloedValue;
+    }
+    /** Feed a node from this bus's signal as it arrives, before any insert. See `inputTaps`. */
+    feedFromInput(node) {
+        this.inputTaps.push(node);
+        this.input.connect(node);
+    }
+    /** Append a stage to this bus's own signal path. See `InsertOptions.postSend`. */
+    insert(insert, options = {}) {
+        this.inserts.push({ insert, postSend: options.postSend === true });
+        this.rebuild();
+    }
+    /**
+     * Feed a return bus from this one, at `amount`.
+     *
+     * Idempotent per target: asking twice moves the existing send rather than building a second one,
+     * because this is called from per-frame code in every consumer that has ever used it and a send
+     * node per frame is a graph that grows until the page stops.
+     */
+    send(returnBus, amount) {
+        let gain = this.sends.get(returnBus);
+        if (gain === undefined) {
+            gain = this.context.createGain();
+            // At zero, then ramped: a send that springs into existence at full level is a click.
+            gain.gain.value = 0;
+            this.tap.connect(gain);
+            gain.connect(returnBus.input);
+            this.sends.set(returnBus, gain);
+        }
+        /*
+         * Floored at zero and not ceilinged at one. A send above unity is ordinary on a console — it is
+         * how a return is driven harder than the source feeding it — and the mix this replaces has
+         * always allowed it: `setReverbSend` floors at zero and stops there. Clamping to unity here
+         * would quietly change what every existing caller is allowed to ask for.
+         */
+        const floored = Number.isFinite(amount) ? Math.max(0, amount) : 0;
+        this.sendAmounts.set(returnBus, floored);
+        this.ramp(gain.gain, floored);
+    }
+    /** What this bus was last asked to send to that return, or 0 if it has never sent to it. */
+    sendAmount(returnBus) {
+        return this.sendAmounts.get(returnBus) ?? 0;
+    }
+    /** Every return this bus feeds, for a snapshot to capture. */
+    get sendTargets() {
+        return [...this.sends.keys()];
+    }
+    setLevel(level) {
+        this.levelValue = clamp01(level);
+        this.applyGain();
+    }
+    /**
+     * Move to a level over an explicit time, rather than at the fader's own smoothing.
+     *
+     * A fader is a control and wants to feel immediate; a snapshot recall is an edit and takes as
+     * long as it was asked to take. Both write the same mirrored level, so the mix knows where it is
+     * either way — which `AudioGraph.fadeMusic` deliberately does *not* do, because a fade there is
+     * part of an edit that has to return to the player's setting when it is over.
+     */
+    fadeLevel(level, seconds) {
+        this.levelValue = clamp01(level);
+        const at = this.scheduleAt();
+        const target = this.mutedValue ? 0 : this.levelValue * this.soloGateValue * this.duckFactor;
+        this.input.gain.cancelScheduledValues(at);
+        // A third of the span as the time constant: `setTargetAtTime` is asymptotic, and three time
+        // constants is where it is within five per cent of the target, which is where a listener
+        // stops hearing it move.
+        this.input.gain.setTargetAtTime(target, at, Math.max(seconds, 1e-3) / 3);
+    }
+    /**
+     * Move over the top of the fader and back, without moving the fader.
+     *
+     * `duck(0, 0.4)` takes this bus away over four tenths of a second; `duck(1, 0.4)` brings it back
+     * to exactly whatever the fader is set to, including a setting the player changed in between.
+     * Cost: this is a second thing multiplying into one parameter, so a caller that ducks and forgets
+     * to release leaves a bus quiet with a fader that says otherwise — which is why `duckedTo` is
+     * readable rather than private.
+     */
+    duck(factor, seconds) {
+        this.duckFactor = clamp01(factor);
+        const at = this.scheduleAt();
+        const target = this.mutedValue ? 0 : this.levelValue * this.soloGateValue * this.duckFactor;
+        this.input.gain.cancelScheduledValues(at);
+        if (seconds <= 0) {
+            this.input.gain.setTargetAtTime(target, at, RAMP);
+            return;
+        }
+        /*
+         * Linear, because a linear ramp actually *reaches* its target where `setTargetAtTime` only ever
+         * approaches it — and a score still faintly audible under the next scene is the bug this is
+         * for. From wherever the parameter actually is rather than from where it was last set, because
+         * cancelling a ramp mid-flight leaves the value between the two and a fade that starts by
+         * jumping back is an audible click.
+         */
+        this.input.gain.setValueAtTime(this.input.gain.value, at);
+        this.input.gain.linearRampToValueAtTime(target, at + Math.max(seconds, 0.001));
+    }
+    /** What this bus is ducked to, 1 when it is not. See `duck`. */
+    get duckedTo() {
+        return this.duckFactor;
+    }
+    setMute(muted) {
+        this.mutedValue = muted;
+        this.applyGain();
+    }
+    setSolo(soloed) {
+        this.soloedValue = soloed;
+        this.onSoloChanged?.();
+    }
+    /** Set by the console when it adopts this bus, so a solo anywhere re-resolves the whole tree. */
+    onSoloChanged = null;
+    /** Written by the console alone. 1 is audible, 0 is silenced by somebody else's solo. */
+    setSoloGate(gate) {
+        if (gate === this.soloGateValue)
+            return;
+        this.soloGateValue = gate;
+        this.applyGain();
+    }
+    /**
+     * Level, mute and the solo gate are one number, written once.
+     *
+     * Three writers to one parameter race, and the loser is whichever ran first — which is heard as a
+     * fader that sometimes does not take, and is nearly impossible to reproduce deliberately.
+     */
+    applyGain() {
+        this.ramp(this.input.gain, this.mutedValue ? 0 : this.levelValue * this.soloGateValue * this.duckFactor);
+    }
+    /**
+     * Rewire the series path.
+     *
+     * Only `input`, the insert outputs and `tap` are disconnected — never `output`, which carries this
+     * bus's connection to its parent and would take the whole subtree with it. The sends are
+     * reconnected here because `tap` was just disconnected, and a send silently dropped by a later
+     * insert is exactly the kind of fault that reads as "the reverb stopped working" days afterwards.
+     */
+    rebuild() {
+        this.input.disconnect();
+        for (const { insert } of this.inserts)
+            insert.output.disconnect();
+        this.tap.disconnect();
+        for (const node of this.inputTaps)
+            this.input.connect(node);
+        let node = this.input;
+        for (const { insert, postSend } of this.inserts) {
+            if (postSend)
+                continue;
+            node.connect(insert.input);
+            node = insert.output;
+        }
+        node.connect(this.tap);
+        node = this.tap;
+        for (const { insert, postSend } of this.inserts) {
+            if (!postSend)
+                continue;
+            node.connect(insert.input);
+            node = insert.output;
+        }
+        node.connect(this.output);
+        for (const gain of this.sends.values())
+            this.tap.connect(gain);
+    }
+    /**
+     * Every parameter move is ramped and every one lands on the console's instant.
+     *
+     * `scheduleAt`, never `currentTime`: offline there is no now, and a move left to the clock lands
+     * on instant zero along with every other move a render ever makes.
+     */
+    ramp(param, value) {
+        const at = this.scheduleAt();
+        param.cancelScheduledValues(at);
+        param.setTargetAtTime(value, at, RAMP);
+    }
+}

package/dist/mix/console.d.ts

@@ -0,0 +1,96 @@
+import type { ScheduleClock } from '../ambientLoop.ts';
+import { MixBus, type BusOptions } from './bus.ts';
+import { type MixSnapshot } from './snapshot.ts';
+export type { MixSnapshot };
+/**
+ * The mixer: a tree of buses, and the one place that can answer a question about all of them.
+ *
+ * A bus knows its own level and its own parent. Solo is the question no bus can answer alone —
+ * "is anything else soloed, and am I part of it" is a property of the whole tree — so the tree is
+ * held here and every bus asks this when its own solo changes.
+ *
+ * **Everything scheduled through one clock.** `at()` and `scheduleAt()` are the same pair
+ * `AudioGraph` has always had, and for the same reason: offline there is no "now", so a render
+ * describes its whole timeline against instants a caller supplies. Every bus is handed this clock
+ * at construction, so there is exactly one answer to "when" in a mix rather than one per node.
+ */
+export interface MixConsoleOptions {
+    /** Where "now" is. Defaults to the context's own clock, which is what a live mix wants. */
+    readonly scheduleAt?: ScheduleClock;
+    /**
+     * Where randomness comes from, for anything this console builds that needs it — today, the noise
+     * an impulse response is made of.
+     *
+     * Defaults to `Math.random`, and exists because a reverb built from an unseeded generator is a
+     * different reverb on every construction, so nothing carrying wet signal can be asserted exactly.
+     * The same rule `AGENTS.md` applies to storage and to clocks: take the capability as a parameter
+     * and ship the browser's as the default.
+     *
+     * Cost: a caller that seeds this gets a reproducible reverb and also a *worse-sounding* one if
+     * they seed it badly, because the tail's quality is the quality of its noise. What would make
+     * this wrong is a consumer using it to make the reverb deterministic in production, which is
+     * solving a problem nobody has at the price of one they will.
+     */
+    readonly random?: () => number;
+}
+export declare class MixConsole {
+    readonly context: BaseAudioContext;
+    /** Everything ends up here. Its insert chain is where a master filter belongs. */
+    readonly master: MixBus;
+    /**
+     * What reaches the speakers, summed in one place.
+     *
+     * The same node, for the same reason, as the `out` that `AudioGraph` grew after every exported
+     * clip turned out to be missing its send returns: "what the player hears" has to be a node, or
+     * the moment anything wants to listen to the mix there is nowhere to listen.
+     */
+    readonly out: GainNode;
+    private readonly buses;
+    private readonly snapshots;
+    private atSec;
+    private readonly randomSource;
+    constructor(context: BaseAudioContext, options?: MixConsoleOptions);
+    private readonly clock;
+    /**
+     * The bus called `name`, created under `master` if it does not exist yet.
+     *
+     * One verb rather than a create and a get, because a caller declaring a bus at startup and a
+     * caller reaching for one by name are asking the same question, and two verbs would mean choosing
+     * between them on every line. Cost: a typo makes a bus instead of an error. What would make this
+     * wrong is a console large enough to lose one in, which is when a caller should be holding the
+     * reference rather than the name.
+     */
+    bus(name: string, options?: BusOptions): MixBus;
+    find(name: string): MixBus | undefined;
+    get all(): readonly MixBus[];
+    private adopt;
+    /**
+     * Recompute every bus's solo gate.
+     *
+     * A bus is audible under solo if it *is* soloed, contains one, or is contained by one. Walked
+     * from scratch on every change rather than cached: the set of soloed buses is tiny, and a person
+     * pressing solo is not a per-frame path. Cost: O(buses × soloed) per toggle, which at the size a
+     * game mixes at is nothing. What would make this wrong is a console with thousands of buses,
+     * which is not what this is for.
+     */
+    private resolveSolo;
+    /**
+     * Schedule everything that follows at `seconds` on this context's timeline, or at "now" when null.
+     *
+     * An offline render sets it once per frame and gets a mix whose every move lands exactly where
+     * the picture is. Live callers never touch it.
+     *
+     * **Has no effect when a `scheduleAt` was supplied**, because then somebody else owns the answer
+     * and this console is a reader of it. That is the case whenever an `AudioGraph` built the
+     * console: the transport's own `at()` is the one to call.
+     */
+    at(seconds: number | null): void;
+    /** The instant scheduled work lands on. One reader, so "when" has one answer in a mix. */
+    scheduleAt(): number;
+    /** See `MixConsoleOptions.random`. */
+    random(): number;
+    /** Capture every level, mute and send, under a name. */
+    snapshot(name: string): MixSnapshot;
+    /** Crossfade back to a captured snapshot over `seconds`. */
+    recall(name: string, seconds?: number): void;
+}

package/dist/mix/console.js

@@ -0,0 +1,131 @@
+import { MixBus } from './bus.js';
+import { captureSnapshot, recallSnapshot } from './snapshot.js';
+export class MixConsole {
+    context;
+    /** Everything ends up here. Its insert chain is where a master filter belongs. */
+    master;
+    /**
+     * What reaches the speakers, summed in one place.
+     *
+     * The same node, for the same reason, as the `out` that `AudioGraph` grew after every exported
+     * clip turned out to be missing its send returns: "what the player hears" has to be a node, or
+     * the moment anything wants to listen to the mix there is nowhere to listen.
+     */
+    out;
+    buses = new Map();
+    snapshots = new Map();
+    atSec = null;
+    randomSource;
+    constructor(context, options = {}) {
+        this.context = context;
+        this.randomSource = options.random ?? Math.random;
+        /*
+         * One clock, and it may belong to somebody else. A graph that owns a transport already answers
+         * "when" for its own scheduling, and two answers to that question is how a move ends up on
+         * instant zero in a render that asked for it at three seconds.
+         */
+        this.clock = options.scheduleAt ?? (() => this.atSec ?? this.context.currentTime);
+        this.out = context.createGain();
+        this.out.connect(context.destination);
+        this.master = new MixBus('master', context, () => this.scheduleAt());
+        this.master.output.connect(this.out);
+        this.adopt(this.master);
+    }
+    clock;
+    /**
+     * The bus called `name`, created under `master` if it does not exist yet.
+     *
+     * One verb rather than a create and a get, because a caller declaring a bus at startup and a
+     * caller reaching for one by name are asking the same question, and two verbs would mean choosing
+     * between them on every line. Cost: a typo makes a bus instead of an error. What would make this
+     * wrong is a console large enough to lose one in, which is when a caller should be holding the
+     * reference rather than the name.
+     */
+    bus(name, options = {}) {
+        const existing = this.buses.get(name);
+        if (existing !== undefined)
+            return existing;
+        const created = new MixBus(name, this.context, () => this.scheduleAt(), {
+            ...options,
+            // `undefined` means "the usual place"; an explicit `null` means the caller wires it.
+            parent: options.parent === undefined ? this.master : options.parent,
+        });
+        this.adopt(created);
+        // A bus born while somebody is soloing must arrive already silenced, not at full level.
+        this.resolveSolo();
+        return created;
+    }
+    find(name) {
+        return this.buses.get(name);
+    }
+    get all() {
+        return [...this.buses.values()];
+    }
+    adopt(bus) {
+        this.buses.set(bus.name, bus);
+        bus.onSoloChanged = () => this.resolveSolo();
+    }
+    /**
+     * Recompute every bus's solo gate.
+     *
+     * A bus is audible under solo if it *is* soloed, contains one, or is contained by one. Walked
+     * from scratch on every change rather than cached: the set of soloed buses is tiny, and a person
+     * pressing solo is not a per-frame path. Cost: O(buses × soloed) per toggle, which at the size a
+     * game mixes at is nothing. What would make this wrong is a console with thousands of buses,
+     * which is not what this is for.
+     */
+    resolveSolo() {
+        const soloed = [...this.buses.values()].filter((bus) => bus.soloed);
+        if (soloed.length === 0) {
+            for (const bus of this.buses.values())
+                bus.setSoloGate(1);
+            return;
+        }
+        for (const bus of this.buses.values()) {
+            const audible = soloed.some((one) => one === bus || isAncestorOf(one, bus) || isAncestorOf(bus, one));
+            bus.setSoloGate(audible ? 1 : 0);
+        }
+    }
+    /**
+     * Schedule everything that follows at `seconds` on this context's timeline, or at "now" when null.
+     *
+     * An offline render sets it once per frame and gets a mix whose every move lands exactly where
+     * the picture is. Live callers never touch it.
+     *
+     * **Has no effect when a `scheduleAt` was supplied**, because then somebody else owns the answer
+     * and this console is a reader of it. That is the case whenever an `AudioGraph` built the
+     * console: the transport's own `at()` is the one to call.
+     */
+    at(seconds) {
+        this.atSec = seconds;
+    }
+    /** The instant scheduled work lands on. One reader, so "when" has one answer in a mix. */
+    scheduleAt() {
+        return this.clock();
+    }
+    /** See `MixConsoleOptions.random`. */
+    random() {
+        return this.randomSource();
+    }
+    /** Capture every level, mute and send, under a name. */
+    snapshot(name) {
+        const captured = captureSnapshot(this);
+        this.snapshots.set(name, captured);
+        return captured;
+    }
+    /** Crossfade back to a captured snapshot over `seconds`. */
+    recall(name, seconds = 0) {
+        const captured = this.snapshots.get(name);
+        if (captured === undefined)
+            return;
+        recallSnapshot(this, captured, seconds);
+    }
+}
+/** Whether `bus` is anywhere below `maybeAncestor` in the tree. */
+function isAncestorOf(maybeAncestor, bus) {
+    for (let walk = bus.parent; walk !== null; walk = walk.parent) {
+        if (walk === maybeAncestor)
+            return true;
+    }
+    return false;
+}

package/dist/mix/defaultLayout.d.ts

@@ -0,0 +1,37 @@
+import type { MixLevels } from '../graph.ts';
+import type { MixBus } from './bus.ts';
+import type { MixConsole } from './console.ts';
+import { type LiftInsert, type MasterFilterInsert, type SlamInsert } from './inserts.ts';
+import { type DelayInsert } from './returns.ts';
+/**
+ * The mix as it has always been, expressed in buses and inserts.
+ *
+ * ```
+ *   music ─ [lift] ─ tap ─ [slam] ─┐
+ *     └─ sends from tap ───────────┼→ master ─ [master lowpass] ─ out ─→ destination
+ *   effects ─────────────────────── ┘                                    ↑
+ *   reverb · longReverb · delay ────────────────────────────────────────┘
+ * ```
+ *
+ * **This is a transcription and it is meant to stay one.** Every level, every frequency and every
+ * connection order is the one `AudioGraph`'s constructor had, because the gate on this file is that
+ * an offline render through it is sample-identical to a render frozen before it existed. An
+ * improvement to the mix cannot be made here without breaking that gate — deliberately, so that a
+ * change to how the mix sounds arrives in its own commit where a diff attributes it.
+ *
+ * **The three returns are parented to nothing and wired straight to `out`.** They join the mix
+ * downstream of the master filter, which is what the mix has always done: a reverb tail put through
+ * a low-pass the dry signal has already passed reads as a duller room rather than as a room.
+ */
+export interface DefaultLayout {
+    readonly music: MixBus;
+    readonly effects: MixBus;
+    readonly reverb: MixBus;
+    readonly longReverb: MixBus;
+    readonly delay: MixBus;
+    readonly lift: LiftInsert;
+    readonly slam: SlamInsert;
+    readonly masterFilter: MasterFilterInsert;
+    readonly delayLine: DelayInsert;
+}
+export declare function defaultLayout(mix: MixConsole, levels: MixLevels): DefaultLayout;

package/dist/mix/defaultLayout.js

@@ -0,0 +1,63 @@
+import { liftInsert, masterFilterInsert, slamInsert, } from './inserts.js';
+import { convolverInsert, delayInsert } from './returns.js';
+/**
+ * The long tail: seconds of impulse, and how fast it decays inside them.
+ *
+ * Long enough to carry a whole airborne moment — a jump is under a second, a glide several — and
+ * decaying slowly enough that the music is *spread out* rather than merely echoed. Beyond about
+ * eight seconds it stops sounding like a space and starts sounding like a stuck effect.
+ */
+const LONG_REVERB_SECONDS = 6;
+const LONG_REVERB_DECAY = 1.5;
+/** The short one: the room the music is played in, rather than where it goes. */
+const SHORT_REVERB_SECONDS = 2.4;
+const SHORT_REVERB_DECAY = 2.6;
+/** Baseline delay feedback: one clear repeat, not a rhythm of its own. */
+const DELAY_FEEDBACK = 0.34;
+export function defaultLayout(mix, levels) {
+    const masterFilter = masterFilterInsert(mix.context, () => mix.scheduleAt());
+    mix.master.insert(masterFilter);
+    /*
+     * Music and effects have their own bus because players expect to turn them down independently —
+     * muting the score while keeping the game audible is the single most-used audio setting there is.
+     */
+    const music = mix.bus('music', { level: levels.music });
+    const lift = liftInsert(mix.context, () => mix.scheduleAt());
+    music.insert(lift);
+    const slam = slamInsert(mix.context, () => mix.scheduleAt());
+    /*
+     * Below the tap, so the sends never hear it: a six-second convolution of a clipped bass hit is a
+     * mess, and it would still be arriving three gates later.
+     */
+    music.insert(slam, { postSend: true });
+    // And its wet band is taken from the music as it arrives, upstream of the lift's high-pass. See
+    // `SlamInsert.wetInput` for why that is the one wiring mistake this stage can make.
+    music.feedFromInput(slam.wetInput);
+    const effects = mix.bus('effects', { level: levels.effects });
+    /*
+     * **The sends are fed from the music alone.** They hung off the shared bus first, which put
+     * reverb and delay on every sound the game made when only the score should carry them. A footstep
+     * with a six-second tail on it is not atmosphere, it is a bug, and the effects that carry the
+     * world's own sound need to stay dry and immediate to be legible.
+     */
+    const reverb = mix.bus('reverb', { parent: null });
+    reverb.insert(convolverInsert(mix.context, SHORT_REVERB_SECONDS, SHORT_REVERB_DECAY, () => mix.random()));
+    reverb.output.connect(mix.out);
+    /*
+     * A second, much longer reverb, on its own return rather than a swappable impulse: building one
+     * allocates and costs milliseconds, and doing that on a jump would put both on the input path.
+     * Two convolvers cost two returns and nothing else.
+     */
+    const longReverb = mix.bus('longReverb', { parent: null });
+    longReverb.insert(convolverInsert(mix.context, LONG_REVERB_SECONDS, LONG_REVERB_DECAY, () => mix.random()));
+    longReverb.output.connect(mix.out);
+    const delay = mix.bus('delay', { parent: null });
+    const delayLine = delayInsert(mix.context, () => mix.scheduleAt(), { feedback: DELAY_FEEDBACK });
+    delay.insert(delayLine);
+    delay.output.connect(mix.out);
+    // At zero, so an idle graph is exactly the dry mix. Every send is opened by a caller.
+    music.send(reverb, 0);
+    music.send(longReverb, 0);
+    music.send(delay, 0);
+    return { music, effects, reverb, longReverb, delay, lift, slam, masterFilter, delayLine };
+}