@driftengine/audio 3.61.0

package/src/index.ts

@@ -0,0 +1,84 @@
+/*! DriftEngine | Copyright 2026 Drift Technologies | Apache-2.0 | https://github.com/drftrun/driftengine */
+/**
+ * Sound: layered stems, synthesis, rhythm analysis, and where a source sits.
+ *
+ * A package because nothing in the renderer ever imported it — the cleanest boundary in the
+ * tree, and 3,151 lines a silent game does not carry.
+ */
+
+export { SoundRegistry } from './registry.ts';
+export { AudioGraph } from './graph.ts';
+export { cutoffForSpeed } from './filters.ts';
+/* The two lines that make Web Audio audible on an iPhone, for a consumer whose audio is one
+   decoded file through its own chain rather than a stem player. `AudioGraph` already calls both
+   and in this order; anything building its own context has to do the same. */
+export { audioContextConstructor, claimPlaybackSession } from './session.ts';
+export { AUDIO_FORMATS, audioCandidateUrls } from './formats.ts';
+export { fetchAudioManifest, parseAudioManifest } from './manifest.ts';
+export type { AudioFormat } from './formats.ts';
+export { AmbientLoop } from './ambientLoop.ts';
+export { analyseTrack, emptyBeatMap } from './rhythm/beatMap.ts';
+export { TapTempo, beatGrid } from './rhythm/beatGrid.ts';
+export { KickDetector, kickPulseAfter } from './rhythm/kickDetector.ts';
+export type { KickDetectorNodes } from './rhythm/kickDetector.ts';
+export type { BeatMap } from './rhythm/beatMap.ts';
+export { RHYTHM_BANDS } from './rhythm/bands.ts';
+export type { Band, BandEnergies, BandName } from './rhythm/bands.ts';
+export { distanceGain, stereoPan } from './positional.ts';
+/* The mix as a tree. `AudioGraph` is built on this and forwards to it, so a consumer only reaches
+   for these when it wants a bus of its own. */
+export { MixConsole } from './mix/console.ts';
+export { MixBus } from './mix/bus.ts';
+export type { MixInsert, InsertOptions, BusOptions } from './mix/bus.ts';
+export type { MixConsoleOptions, MixSnapshot } from './mix/console.ts';
+export { liftInsert, masterFilterInsert, slamInsert } from './mix/inserts.ts';
+export type { LiftInsert, MasterFilterInsert, SlamInsert } from './mix/inserts.ts';
+export { convolverInsert, delayInsert, impulseResponse } from './mix/returns.ts';
+export type { DelayInsert } from './mix/returns.ts';
+export { defaultLayout } from './mix/defaultLayout.ts';
+export type { DefaultLayout } from './mix/defaultLayout.ts';
+/* Placing a sound in the world. Standalone rather than methods on the console, so a consumer that
+   never places one does not carry the panner — see `SpatialSource` and the size gate. */
+export { createListener, AudioListenerGraph } from './spatial/listener.ts';
+export type { OcclusionProbe } from './spatial/listener.ts';
+export { createSpatialSource, SpatialSource } from './spatial/source.ts';
+export type { SpatialOptions } from './spatial/source.ts';
+export {
+  occlusionCutoffHz,
+  occlusionGainFor,
+  smoothToward,
+  ProbeScheduler,
+} from './spatial/occlusion.ts';
+export { MAX_OPEN_ZONES, addReverbZone, ReverbZone, SourceZoneSend } from './spatial/zones.ts';
+/* A soundfield rather than a source: four channels of direction, decoded at a fixed cost. */
+export {
+  ACN_W,
+  ACN_X,
+  ACN_Y,
+  ACN_Z,
+  AmbisonicSoundfield,
+  FOA_CHANNELS,
+  FOA_SPEAKERS,
+  ambisonicFromWorld,
+  createAmbisonicSoundfield,
+  encodeFoa,
+  foaDecodeGain,
+  foaDecodeMatrix,
+} from './spatial/ambisonic.ts';
+export type { AmbisonicOptions } from './spatial/ambisonic.ts';
+export type { ZoneShape, ZoneOptions } from './spatial/zones.ts';
+export {
+  ambienceBuffer,
+  driftScrapeBuffer,
+  fireLoopBuffer,
+  metalBuffer,
+  noiseBuffer,
+  silentBuffer,
+  toneBuffer,
+  waterLoopBuffer,
+  windLoopBuffer,
+} from './synth.ts';
+export type { AmbienceOptions } from './synth.ts';
+export type { AudioGraphOptions, MixLevels } from './graph.ts';
+export type { SoundSlot, SoundSource, SoundOrigin, FetchLike } from './registry.ts';
+export { RenderedPulse } from './rhythm/renderedPulse.ts';

package/src/manifest.ts

@@ -0,0 +1,73 @@
+import type { FetchLike } from './registry.ts';
+
+/**
+ * Discovering how many sound assets exist, without a hard limit.
+ *
+ * A browser cannot list a directory, so an asset folder has to announce itself
+ * somehow. The three options are a fixed list in code (which caps the library
+ * at whatever number somebody typed), probing upward until requests start
+ * failing (a burst of 404s on every load, and one gap in the numbering silently
+ * truncates the set), or a manifest.
+ *
+ * A manifest, generated from the folder at build time, is the only one of the
+ * three with no ceiling and no wasted requests. Adding an asset stays a matter
+ * of dropping the file in; the manifest catches up on the next build.
+ *
+ * Deliberately not a game concept: this returns names, and the caller decides
+ * that some of them are music.
+ */
+
+/** Every name in a manifest, or an empty list if there is not one. */
+export async function fetchAudioManifest(
+  url: string,
+  fetchImpl: FetchLike = (target) => fetch(target),
+): Promise<string[]> {
+  let parsed: unknown;
+  try {
+    const response = await fetchImpl(url);
+    if (!response.ok) return [];
+    parsed = await response.json();
+  } catch {
+    /*
+     * A missing or unreadable manifest is silence, never a failure. The whole
+     * asset system is built so a game runs with no files at all — a folder that
+     * has not been scanned yet must behave exactly like an empty one.
+     */
+    return [];
+  }
+  return parseAudioManifest(parsed);
+}
+
+/**
+ * Validate a manifest's contents.
+ *
+ * Separated from fetching so the rules can be tested without a network, and
+ * because the rules are the part that matters: a manifest is generated by a
+ * script, and a script that emits one bad entry must not take the rest of the
+ * library down with it.
+ */
+export function parseAudioManifest(value: unknown): string[] {
+  if (!Array.isArray(value)) return [];
+
+  const names: string[] = [];
+  const seen = new Set<string>();
+  for (const entry of value) {
+    if (typeof entry !== 'string') continue;
+    const name = entry.trim();
+    if (name.length === 0 || seen.has(name)) continue;
+    // A name is a slot, not a path. Anything with a separator or an extension
+    // in it is a generator bug, and following it would mean fetching whatever
+    // the manifest asked for from wherever it asked.
+    if (name.includes('/') || name.includes('\\') || name.includes('.')) continue;
+    seen.add(name);
+    names.push(name);
+  }
+  /*
+   * Sorted, because the caller picks one by seed and that pick has to be the
+   * same everywhere. Directory order is filesystem order, which differs between
+   * machines — two players on the same day would get different music, and the
+   * daily would quietly stop being shared.
+   */
+  names.sort();
+  return names;
+}

package/src/mix/bus.ts

@@ -0,0 +1,356 @@
+import type { ScheduleClock } from '../ambientLoop.ts';
+import { clamp01 } from '../filters.ts';
+
+/**
+ * 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;
+
+/** A stage a bus can put in its own signal path. Internally it may be anything, including parallel. */
+export interface MixInsert {
+  readonly input: AudioNode;
+  readonly output: AudioNode;
+}
+
+export interface InsertOptions {
+  /**
+   * Place this insert *below* the send tap, so the sends do not hear it.
+   *
+   * Cost: an insert down here cannot be heard in a reverb tail even when a caller wants it to be.
+   * What would make this wrong is an insert that is a colour rather than an event — a bus-wide EQ
+   * belongs above the tap, because a reverb of an unequalised signal is a reverb of a different
+   * instrument.
+   */
+  readonly postSend?: boolean;
+}
+
+export interface BusOptions {
+  /**
+   * Where this bus sends its output. Omitted, the console parents it to `master`.
+   *
+   * **`null` means nowhere**, and the caller wires the output itself. That is not a hole in the
+   * model: a return bus joins the mix *downstream* of the master filter, so parenting one to master
+   * would put every reverb tail through a filter the dry signal has already been through. The mix
+   * this replaces has always done it that way, and `mixOutput.test.ts` exists because getting it
+   * wrong once meant every exported clip carried the dry track and nothing wet.
+   */
+  readonly parent?: MixBus | null;
+  /**
+   * Where the fader starts. Unity when omitted.
+   *
+   * Assigned rather than ramped, for the reason `AudioGraphOptions.levels` gives: a level that does
+   * not change for the whole of a render is not a move, it is where the parameter starts, and
+   * ramping it would open every rendered clip with a glide down from unity.
+   */
+  readonly level?: number;
+}
+
+export class MixBus {
+  /** The fader. Sources and child buses connect here. */
+  readonly input: GainNode;
+  /** Where sends listen from. Unity, always. */
+  readonly tap: GainNode;
+  /** What the parent hears. Unity, always. */
+  readonly output: GainNode;
+  readonly parent: MixBus | null;
+
+  private readonly kids: MixBus[] = [];
+  private readonly inserts: { insert: MixInsert; postSend: boolean }[] = [];
+  /**
+   * 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.
+   */
+  private readonly inputTaps: AudioNode[] = [];
+  private readonly sends = new Map<MixBus, GainNode>();
+  /**
+   * 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.
+   */
+  private readonly sendAmounts = new Map<MixBus, number>();
+  private levelValue: number;
+  private mutedValue = false;
+  private 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.
+   */
+  private 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.
+   */
+  private duckFactor = 1;
+
+  constructor(
+    readonly name: string,
+    private readonly context: BaseAudioContext,
+    private readonly scheduleAt: ScheduleClock,
+    options: BusOptions = {},
+  ) {
+    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(): readonly MixBus[] {
+    return this.kids;
+  }
+  get level(): number {
+    return this.levelValue;
+  }
+  get muted(): boolean {
+    return this.mutedValue;
+  }
+  get soloed(): boolean {
+    return this.soloedValue;
+  }
+
+  /** Feed a node from this bus's signal as it arrives, before any insert. See `inputTaps`. */
+  feedFromInput(node: AudioNode): void {
+    this.inputTaps.push(node);
+    this.input.connect(node);
+  }
+
+  /** Append a stage to this bus's own signal path. See `InsertOptions.postSend`. */
+  insert(insert: MixInsert, options: InsertOptions = {}): void {
+    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: MixBus, amount: number): void {
+    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: MixBus): number {
+    return this.sendAmounts.get(returnBus) ?? 0;
+  }
+
+  /** Every return this bus feeds, for a snapshot to capture. */
+  get sendTargets(): readonly MixBus[] {
+    return [...this.sends.keys()];
+  }
+
+  setLevel(level: number): void {
+    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: number, seconds: number): void {
+    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: number, seconds: number): void {
+    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(): number {
+    return this.duckFactor;
+  }
+
+  setMute(muted: boolean): void {
+    this.mutedValue = muted;
+    this.applyGain();
+  }
+
+  setSolo(soloed: boolean): void {
+    this.soloedValue = soloed;
+    this.onSoloChanged?.();
+  }
+
+  /** Set by the console when it adopts this bus, so a solo anywhere re-resolves the whole tree. */
+  onSoloChanged: (() => void) | null = null;
+
+  /** Written by the console alone. 1 is audible, 0 is silenced by somebody else's solo. */
+  setSoloGate(gate: number): void {
+    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.
+   */
+  private applyGain(): void {
+    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.
+   */
+  private rebuild(): void {
+    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: AudioNode = 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.
+   */
+  private ramp(param: AudioParam, value: number): void {
+    const at = this.scheduleAt();
+    param.cancelScheduledValues(at);
+    param.setTargetAtTime(value, at, RAMP);
+  }
+}

package/src/mix/console.ts

@@ -0,0 +1,181 @@
+import type { ScheduleClock } from '../ambientLoop.ts';
+import { MixBus, type BusOptions } from './bus.ts';
+import { captureSnapshot, recallSnapshot, 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 class MixConsole {
+  /** 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 = new Map<string, MixBus>();
+  private readonly snapshots = new Map<string, MixSnapshot>();
+  private atSec: number | null = null;
+  private readonly randomSource: () => number;
+
+  constructor(
+    readonly context: BaseAudioContext,
+    options: MixConsoleOptions = {},
+  ) {
+    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 ?? ((): number => 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);
+  }
+
+  private readonly clock: ScheduleClock;
+
+  /**
+   * 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 {
+    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: string): MixBus | undefined {
+    return this.buses.get(name);
+  }
+
+  get all(): readonly MixBus[] {
+    return [...this.buses.values()];
+  }
+
+  private adopt(bus: MixBus): void {
+    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.
+   */
+  private resolveSolo(): void {
+    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: number | null): void {
+    this.atSec = seconds;
+  }
+
+  /** The instant scheduled work lands on. One reader, so "when" has one answer in a mix. */
+  scheduleAt(): number {
+    return this.clock();
+  }
+
+  /** See `MixConsoleOptions.random`. */
+  random(): number {
+    return this.randomSource();
+  }
+
+  /** Capture every level, mute and send, under a name. */
+  snapshot(name: string): MixSnapshot {
+    const captured = captureSnapshot(this);
+    this.snapshots.set(name, captured);
+    return captured;
+  }
+
+  /** Crossfade back to a captured snapshot over `seconds`. */
+  recall(name: string, seconds = 0): void {
+    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: MixBus, bus: MixBus): boolean {
+  for (let walk = bus.parent; walk !== null; walk = walk.parent) {
+    if (walk === maybeAncestor) return true;
+  }
+  return false;
+}