@swiftbrowser/web 0.18.3 → 0.19.0

package/src/audioEngine.ts

@@ -0,0 +1,1443 @@
+/**
+ * An audio engine shaped as AVFoundation's `AVAudioEngine`: the page side of
+ * `AVAudioEngine` in @swiftbrowser/react (packages/react/src/audioEngine.ts),
+ * built on the Web Audio API. The app's objects (engines, nodes, files,
+ * buffers) are numbers it chooses, and every call is one command to
+ * `perform`, in order: an engine with its main mixer, output and input;
+ * player, sampler, mixer and effect nodes attached and connected; files
+ * opened and decoded; buffers scheduled on a player's timeline; notes on a
+ * sampler. The native app answers the same commands with `AVAudioEngine`
+ * itself (packages/native, AudioEngineBridge.swift); docs/ops-protocol.md,
+ * "An audio engine", lists them.
+ *
+ * Where Web Audio has no equivalent the page does less: `AVAudioUnitTimePitch`
+ * passes its input through unchanged, the reverb is a convolver with a
+ * generated tail for each factory preset, the distortion presets are
+ * waveshaper curves, and `loadInstrument` (sound banks) is unsupported.
+ *
+ * An optional package adds node kinds of its own with `registerAudioNodeKind`
+ * (@swiftbrowser/dsp's `program`, a synthesizer in an AudioWorklet): the host
+ * makes one for `attach`, sets its properties, and hands it the notes a
+ * sampler would take.
+ */
+
+import type { FilesHost } from './files';
+
+/** The kinds of node an app attaches. */
+export type AudioNodeKind = 'player' | 'sampler' | 'mixer' | 'reverb' | 'delay' | 'distortion' | 'eq' | 'timePitch';
+
+/** A kind an optional package adds (`registerAudioNodeKind`), by its name. */
+export type CustomAudioNodeKind = string & {};
+
+/**
+ * When something starts (`AVAudioTime`): a sample time on a player's own
+ * timeline (frames at `sampleRate` from the moment it started playing), or
+ * `delay` seconds from when the command arrives.
+ */
+export type AudioTimeSpec = { sampleTime: number; sampleRate: number } | { delay: number };
+
+/** A sample zone: a file played for the keys `low` … `high`, at its pitch on `root`. */
+export interface SamplerZone {
+  file: number;
+  root: number;
+  low: number;
+  high: number;
+}
+
+/** A property's value as it crosses: numbers, a bypass flag, an EQ band's filter type. */
+export type AudioValue = number | boolean | string;
+
+export type AudioEngineCommand =
+  | { action: 'create'; engine: number; mixer: number; output: number; input: number }
+  | { action: 'destroy'; engine: number }
+  | { action: 'attach'; engine: number; node: number; kind: AudioNodeKind | CustomAudioNodeKind; values: Record<string, AudioValue>; bands?: number }
+  | { action: 'detach'; engine: number; node: number }
+  | { action: 'connect'; engine: number; from: number; to: number[] }
+  | { action: 'disconnectOutput' | 'disconnectInput'; engine: number; node: number }
+  | { action: 'prepare' | 'start' | 'pause' | 'stop' | 'reset'; engine: number }
+  | { action: 'set'; node: number; values: Record<string, AudioValue> }
+  | { action: 'preset'; node: number; preset: string }
+  | { action: 'openFile'; file: number; url: string }
+  | { action: 'readFile'; file: number; buffer: number; start: number; frames: number }
+  | { action: 'writeBuffer'; buffer: number; sampleRate: number; channels: Float32Array[] }
+  | { action: 'release'; id: number }
+  | { action: 'scheduleFile'; node: number; file: number; start?: number; frames?: number; at?: AudioTimeSpec }
+  | { action: 'scheduleBuffer'; node: number; buffer: number; at?: AudioTimeSpec; loops?: boolean; interrupts?: boolean; interruptsAtLoop?: boolean }
+  | { action: 'play'; node: number; at?: AudioTimeSpec }
+  | { action: 'pausePlayer' | 'stopPlayer'; node: number }
+  | { action: 'playerTime'; node: number }
+  | { action: 'loadZones'; node: number; zones: SamplerZone[]; attack: number; release: number }
+  | { action: 'loadInstrument'; node: number; url: string; program?: number; bankMSB?: number; bankLSB?: number }
+  | { action: 'startNote'; node: number; note: number; velocity: number; channel: number }
+  | { action: 'stopNote'; node: number; note: number; channel: number }
+  | { action: 'controller'; node: number; controller: number; value: number; channel: number }
+  | { action: 'pitchBend'; node: number; value: number; channel: number }
+  | { action: 'meter'; node: number };
+
+/** The note commands an instrument takes: a sampler, or a node of a kind a package adds. */
+export type AudioNoteCommand = Extract<AudioEngineCommand, { action: 'startNote' | 'stopNote' | 'controller' | 'pitchBend' }>;
+
+/**
+ * A node of a kind an optional package adds: its Web Audio nodes and how it
+ * takes properties and notes. The host puts the app's volume and pan after
+ * `output`, as it does for its own sources.
+ */
+export interface CustomAudioNode {
+  /** Where upstream nodes connect; null for a source, which takes no input. */
+  readonly input: AudioNode | null;
+  readonly output: AudioNode;
+  /** A property; false for one it does not have. Throws for a value it cannot take. */
+  set(key: string, value: AudioValue): boolean;
+  /** A note, controller or bend; false (the default) for a node that takes none. */
+  note?(command: AudioNoteCommand): boolean;
+  /** The engine stopped or reset: stop sounding. */
+  halt?(): void;
+  dispose?(): void;
+}
+
+/** Makes a node of a package's kind in the page's context. */
+export type CustomAudioNodeFactory = (context: BaseAudioContext) => CustomAudioNode;
+
+const customKinds = new Map<string, CustomAudioNodeFactory>();
+
+/** Adds a node kind for `attach`, replacing one of the same name. The host's own kinds cannot be replaced. */
+export function registerAudioNodeKind(kind: string, make: CustomAudioNodeFactory): void {
+  if (OWN_KINDS.has(kind)) throw new Error(`exists: ${kind} is one of the engine's own kinds`);
+  customKinds.set(kind, make);
+}
+
+const OWN_KINDS = new Set<string>(['player', 'sampler', 'mixer', 'reverb', 'delay', 'distortion', 'eq', 'timePitch', 'output', 'input']);
+
+/** What `openFile` answers: the file's length in frames and its format. */
+export interface AudioFileInfo {
+  length: number;
+  sampleRate: number;
+  channelCount: number;
+}
+
+/** What `readFile` answers: the frames read into the buffer and its format. */
+export interface AudioBufferInfo {
+  frameLength: number;
+  sampleRate: number;
+  channelCount: number;
+}
+
+/**
+ * The engine's host: one command at a time, in the order sent; what a
+ * command answers (`openFile`'s info, `playerTime`, `meter`) resolves its
+ * promise, and a scheduled file or buffer resolves once it has played (or
+ * its player stopped), as `AVAudioPlayerNode`'s completion handler is
+ * called. A failure rejects with `kind: detail` (`unsupported`, `notFound`,
+ * `decode`, `permission`, `stopped`).
+ */
+export interface AudioEngineHost {
+  perform(command: AudioEngineCommand): Promise<unknown>;
+}
+
+/** Where the host gets its context and bytes from; tests give an `OfflineAudioContext`. */
+export interface AudioEngineSources {
+  /** The context the engines render in (one for the page, made when the first engine is). */
+  context: () => BaseAudioContext;
+  /** A file's bytes: `file:` URLs from the app's files, the rest fetched. */
+  read: (url: string) => Promise<ArrayBuffer>;
+  /** The microphone, for the input node; absent, connecting it fails `unsupported`. */
+  microphone?: () => Promise<MediaStream>;
+}
+
+/** The page's engine host, or undefined where the browser has no Web Audio. */
+export function browserAudioEngine(files: () => FilesHost | undefined): AudioEngineHost | undefined {
+  if (typeof AudioContext === 'undefined') return undefined;
+  let context: AudioContext | null = null;
+  return new WebAudioEngineHost({
+    context: () => (context ??= new AudioContext({ latencyHint: 'interactive' })),
+    read: async (url) => {
+      const host = files();
+      if (url.startsWith('file:') && host) {
+        const bytes = await host.read(url);
+        return bytes.buffer.slice(bytes.byteOffset, bytes.byteOffset + bytes.byteLength) as ArrayBuffer;
+      }
+      const response = await fetch(url);
+      if (!response.ok) throw new Error(`notFound: ${url} answered ${response.status}`);
+      return response.arrayBuffer();
+    },
+    ...(typeof navigator !== 'undefined' && navigator.mediaDevices?.getUserMedia
+      ? { microphone: () => navigator.mediaDevices.getUserMedia({ audio: { echoCancellation: false, noiseSuppression: false, autoGainControl: false } }) }
+      : {}),
+  });
+}
+
+/** Decibels as a gain. */
+export const gainOf = (decibels: number): number => Math.pow(10, decibels / 20);
+
+/** An RMS level on the meters' scale: 0 at -50 dB or below, 1 at 0 dB (as the recorder meters). */
+export function meterLevel(rms: number): number {
+  if (rms <= 0) return 0;
+  const decibels = 20 * Math.log10(rms);
+  return Math.max(0, Math.min(1, (decibels + 50) / 50));
+}
+
+/** A MIDI note's playback rate against a sample recorded at `root`, with `cents` more. */
+export const rateFor = (note: number, root: number, cents = 0): number => Math.pow(2, (note - root) / 12 + cents / 1200);
+
+/** The reverb tail of each `AVAudioUnitReverbPreset`: seconds to fall 60 dB, and how bright it is (a lowpass on the tail, Hz). */
+export const REVERB_PRESETS: Record<string, { decay: number; brightness: number }> = {
+  smallRoom: { decay: 0.4, brightness: 9000 },
+  mediumRoom: { decay: 0.7, brightness: 8000 },
+  largeRoom: { decay: 1.1, brightness: 7000 },
+  largeRoom2: { decay: 1.4, brightness: 7000 },
+  mediumHall: { decay: 1.8, brightness: 6000 },
+  mediumHall2: { decay: 2.0, brightness: 6500 },
+  mediumHall3: { decay: 2.2, brightness: 5500 },
+  largeHall: { decay: 2.6, brightness: 5000 },
+  largeHall2: { decay: 3.0, brightness: 4500 },
+  plate: { decay: 1.5, brightness: 11000 },
+  mediumChamber: { decay: 1.2, brightness: 7500 },
+  largeChamber: { decay: 1.8, brightness: 7000 },
+  cathedral: { decay: 4.5, brightness: 4000 },
+};
+
+/** The `AVAudioUnitDistortionPreset`s as waveshaper curves: how hard they drive, and how much of the result is heard. */
+export const DISTORTION_PRESETS: Record<string, { drive: number; mix: number; bits?: number }> = {
+  drumsBitBrush: { drive: 2, mix: 50, bits: 6 },
+  drumsBufferBeats: { drive: 3, mix: 50, bits: 8 },
+  drumsLoFi: { drive: 4, mix: 60, bits: 5 },
+  multiBrokenSpeaker: { drive: 20, mix: 70 },
+  multiCellphoneConcert: { drive: 8, mix: 80, bits: 7 },
+  multiDecimated1: { drive: 2, mix: 50, bits: 6 },
+  multiDecimated2: { drive: 3, mix: 60, bits: 5 },
+  multiDecimated3: { drive: 4, mix: 70, bits: 4 },
+  multiDecimated4: { drive: 5, mix: 80, bits: 3 },
+  multiDistortedFunk: { drive: 10, mix: 60 },
+  multiDistortedCubed: { drive: 15, mix: 70 },
+  multiDistortedSquared: { drive: 25, mix: 70 },
+  multiEcho1: { drive: 2, mix: 40 },
+  multiEcho2: { drive: 2, mix: 50 },
+  multiEchoTight1: { drive: 2, mix: 40 },
+  multiEchoTight2: { drive: 2, mix: 50 },
+  multiEverythingIsBroken: { drive: 40, mix: 90, bits: 4 },
+  speechAlienChatter: { drive: 6, mix: 70, bits: 6 },
+  speechCosmicInterference: { drive: 8, mix: 70, bits: 5 },
+  speechGoldenPi: { drive: 5, mix: 60 },
+  speechRadioTower: { drive: 12, mix: 80, bits: 8 },
+  speechWaves: { drive: 4, mix: 60 },
+};
+
+/** `AVAudioUnitEQFilterType` as a biquad's type, and whether its bandwidth is a resonance. */
+const EQ_TYPES: Record<string, BiquadFilterType> = {
+  parametric: 'peaking',
+  lowPass: 'lowpass',
+  highPass: 'highpass',
+  resonantLowPass: 'lowpass',
+  resonantHighPass: 'highpass',
+  bandPass: 'bandpass',
+  bandStop: 'notch',
+  lowShelf: 'lowshelf',
+  highShelf: 'highshelf',
+  resonantLowShelf: 'lowshelf',
+  resonantHighShelf: 'highshelf',
+};
+
+/** A bandwidth in octaves as a biquad's Q. */
+export function qForBandwidth(octaves: number): number {
+  const n = Math.pow(2, Math.max(0.05, Math.min(5, octaves)));
+  return Math.sqrt(n) / (n - 1);
+}
+
+/** A seeded noise source, so a reverb's tail is the same each time (and in tests). */
+function noise(seed: number): () => number {
+  let state = seed >>> 0 || 1;
+  return () => {
+    state ^= state << 13;
+    state ^= state >>> 17;
+    state ^= state << 5;
+    return ((state >>> 0) / 0xffffffff) * 2 - 1;
+  };
+}
+
+/** A stereo impulse response: decorrelated noise falling 60 dB over `decay` seconds, darker as it falls. */
+export function reverbImpulse(context: BaseAudioContext, preset: { decay: number; brightness: number }): AudioBuffer {
+  const rate = context.sampleRate;
+  const length = Math.max(1, Math.round(rate * preset.decay));
+  const buffer = context.createBuffer(2, length, rate);
+  for (let channel = 0; channel < 2; channel += 1) {
+    const data = buffer.getChannelData(channel);
+    const random = noise(0x9e3779b9 + channel * 7919);
+    // A one-pole lowpass closing over the tail: highs die first, as in a room.
+    let low = 0;
+    for (let i = 0; i < length; i += 1) {
+      const t = i / length;
+      const cutoff = preset.brightness * (1 - 0.8 * t);
+      const a = Math.exp((-2 * Math.PI * cutoff) / rate);
+      low = (1 - a) * random() + a * low;
+      data[i] = low * Math.pow(10, -3 * t) * 2;
+    }
+  }
+  return buffer;
+}
+
+/** A waveshaper curve driving `drive` times into a soft clip, quantized to `bits` where a preset crushes. */
+export function distortionCurve(drive: number, bits?: number): Float32Array<ArrayBuffer> {
+  const points = 2048;
+  const curve = new Float32Array(points);
+  const k = Math.max(1, drive);
+  const steps = bits ? Math.pow(2, bits - 1) : 0;
+  for (let i = 0; i < points; i += 1) {
+    const x = (i / (points - 1)) * 2 - 1;
+    let y = Math.tanh(k * x) / Math.tanh(k);
+    if (steps) y = Math.round(y * steps) / steps;
+    curve[i] = y;
+  }
+  return curve;
+}
+
+/** Fails a command with `kind: detail`. */
+function failure(kind: string, detail: string): Error {
+  return new Error(`${kind}: ${detail}`);
+}
+
+const num = (value: AudioValue | undefined, fallback: number): number => (typeof value === 'number' && Number.isFinite(value) ? value : fallback);
+
+/** A node in the page's graph: where connections arrive, where it sends from, its properties. */
+abstract class WebNode {
+  /** Where upstream nodes connect (null for sources: players, samplers, the input). */
+  abstract readonly input: AudioNode | null;
+  /** What it sends downstream. */
+  abstract readonly output: AudioNode;
+  /** Upstream nodes connected into it, for `disconnectInput` and one input per effect. */
+  readonly sources = new Set<WebNode>();
+  /** Where it sends to (several for a fan-out). */
+  readonly destinations = new Set<WebNode>();
+  private analyser: AnalyserNode | null = null;
+  private samples: Float32Array<ArrayBuffer> | null = null;
+
+  constructor(
+    readonly id: number,
+    readonly kind: AudioNodeKind | CustomAudioNodeKind | 'output' | 'input',
+    protected readonly context: BaseAudioContext,
+  ) {}
+
+  /** Whether it takes more than one input (a mixer sums its buses; an effect has one). */
+  get mixes(): boolean {
+    return false;
+  }
+
+  abstract set(key: string, value: AudioValue): void;
+
+  preset(name: string): void {
+    throw failure('unsupported', `a ${this.kind} node has no preset ${name}`);
+  }
+
+  /** The output's level now (0 … 1), from an analyser made the first time it is asked. */
+  meter(): number {
+    if (!this.analyser) {
+      this.analyser = this.context.createAnalyser();
+      this.analyser.fftSize = 1024;
+      this.samples = new Float32Array(this.analyser.fftSize);
+      this.output.connect(this.analyser);
+    }
+    this.analyser.getFloatTimeDomainData(this.samples!);
+    let sum = 0;
+    for (const sample of this.samples!) sum += sample * sample;
+    return meterLevel(Math.sqrt(sum / this.samples!.length));
+  }
+
+  /** Stops what it is playing (the engine stopped or reset). */
+  halt(): void {}
+
+  dispose(): void {
+    this.halt();
+    try {
+      this.output.disconnect();
+    } catch {
+      // Not connected.
+    }
+  }
+}
+
+/** `AVAudioMixing`: a source's volume and pan into whatever it connects to. */
+class Mixing {
+  readonly volume: GainNode;
+  readonly panner: StereoPannerNode;
+
+  constructor(context: BaseAudioContext) {
+    this.volume = context.createGain();
+    this.panner = context.createStereoPanner();
+    this.volume.connect(this.panner);
+  }
+
+  set(key: string, value: AudioValue): boolean {
+    if (key === 'volume') this.volume.gain.value = Math.max(0, num(value, 1));
+    else if (key === 'pan') this.panner.pan.value = Math.max(-1, Math.min(1, num(value, 0)));
+    else return false;
+    return true;
+  }
+}
+
+class MixerNode extends WebNode {
+  readonly input: GainNode;
+  readonly output: AudioNode;
+  private readonly outputVolume: GainNode;
+  private readonly mixing: Mixing;
+
+  constructor(id: number, context: BaseAudioContext) {
+    super(id, 'mixer', context);
+    this.input = context.createGain();
+    this.outputVolume = context.createGain();
+    this.mixing = new Mixing(context);
+    this.input.connect(this.outputVolume).connect(this.mixing.volume);
+    this.output = this.mixing.panner;
+  }
+
+  override get mixes(): boolean {
+    return true;
+  }
+
+  set(key: string, value: AudioValue): void {
+    if (key === 'outputVolume') this.outputVolume.gain.value = Math.max(0, num(value, 1));
+    else this.mixing.set(key, value);
+  }
+}
+
+/** The engine's output: what reaches the speakers while the engine runs. */
+class OutputNode extends WebNode {
+  readonly input: GainNode;
+  readonly output: GainNode;
+
+  constructor(id: number, context: BaseAudioContext) {
+    super(id, 'output', context);
+    this.input = context.createGain();
+    this.output = this.input;
+  }
+
+  set(): void {}
+
+  /** Sound on (`start`) or off (`pause`, `stop`). */
+  live(on: boolean): void {
+    try {
+      this.output.disconnect(this.context.destination);
+    } catch {
+      // Not connected.
+    }
+    if (on) this.output.connect(this.context.destination);
+  }
+
+  override dispose(): void {
+    this.live(false);
+  }
+}
+
+/** The microphone, opened when the engine starts with something connected to it. */
+class InputNode extends WebNode {
+  readonly input = null;
+  readonly output: AudioNode;
+  private readonly stage: GainNode;
+  private readonly mixing: Mixing;
+  private stream: MediaStream | null = null;
+  private source: MediaStreamAudioSourceNode | null = null;
+
+  constructor(id: number, context: BaseAudioContext) {
+    super(id, 'input', context);
+    this.stage = context.createGain();
+    this.mixing = new Mixing(context);
+    this.stage.connect(this.mixing.volume);
+    this.output = this.mixing.panner;
+  }
+
+  set(key: string, value: AudioValue): void {
+    this.mixing.set(key, value);
+  }
+
+  async open(microphone: (() => Promise<MediaStream>) | undefined): Promise<void> {
+    if (this.source) return;
+    if (!microphone || !('createMediaStreamSource' in this.context)) throw failure('unsupported', 'this page has no microphone');
+    try {
+      this.stream = await microphone();
+    } catch (error) {
+      throw failure('permission', `the microphone was not allowed (${String(error)})`);
+    }
+    this.source = (this.context as AudioContext).createMediaStreamSource(this.stream);
+    this.source.connect(this.stage);
+  }
+
+  override halt(): void {
+    this.source?.disconnect();
+    this.source = null;
+    for (const track of this.stream?.getTracks() ?? []) track.stop();
+    this.stream = null;
+  }
+}
+
+/** One scheduled file segment or buffer on a player's timeline. */
+interface Scheduled {
+  audio: AudioBuffer;
+  /** Seconds into `audio` it starts at, and how long it plays (once; a loop repeats it). */
+  offset: number;
+  duration: number;
+  loops: boolean;
+  /** Where on the player's timeline it starts (seconds), once known. */
+  start: number | null;
+  at: AudioTimeSpec | undefined;
+  source: AudioBufferSourceNode | null;
+  done: () => void;
+}
+
+/**
+ * `AVAudioPlayerNode`: a timeline of scheduled buffers and file segments.
+ * Each plays after the one before, or at its own time; `play` starts the
+ * timeline (player time 0 is when it first plays), `pause` holds it where
+ * it is, `stop` drops what is scheduled (each one's completion called).
+ */
+class PlayerNode extends WebNode {
+  readonly input = null;
+  readonly output: AudioNode;
+  private readonly sum: GainNode;
+  private readonly mixing: Mixing;
+  private queue: Scheduled[] = [];
+  /** The context time of player time 0 while playing. */
+  private origin: number | null = null;
+  /** The player time it was paused at. */
+  private heldAt = 0;
+  /** Whether it has played since it was last stopped (`playerTime` answers null before). */
+  private started = false;
+  /** Where the next item without a time of its own starts. */
+  private end = 0;
+  /** Whether the engine runs (a player plays only then). */
+  running = false;
+
+  constructor(id: number, context: BaseAudioContext) {
+    super(id, 'player', context);
+    this.sum = context.createGain();
+    this.mixing = new Mixing(context);
+    this.sum.connect(this.mixing.volume);
+    this.output = this.mixing.panner;
+  }
+
+  set(key: string, value: AudioValue): void {
+    this.mixing.set(key, value);
+  }
+
+  get isPlaying(): boolean {
+    return this.origin !== null;
+  }
+
+  /** The player's time now (seconds), or null before it first plays. */
+  time(): number | null {
+    if (this.origin !== null) return this.context.currentTime - this.origin;
+    return this.started ? this.heldAt : null;
+  }
+
+  /**
+   * Puts an item on the timeline. `interrupts` drops what is scheduled and
+   * plays it now; `atLoop` lets a loop that is sounding finish its pass and
+   * plays it from there (as `interrupts` when no loop sounds), which is how
+   * a sequencer swaps its pattern on the bar line; another `atLoop` while
+   * that one waits for the bar line takes its place there, as
+   * AVAudioPlayerNode drops what is scheduled and keeps what sounds.
+   */
+  schedule(item: Omit<Scheduled, 'start' | 'source'>, mode: 'after' | 'interrupts' | 'atLoop' = 'after'): void {
+    const entry: Scheduled = { ...item, start: null, source: null };
+    const looping = mode === 'atLoop' && this.origin !== null ? this.queue.find((queued) => queued.loops && queued.source && queued.start !== null) : undefined;
+    if (looping) {
+      const now = this.time()!;
+      let boundary: number;
+      if (looping.start! > now) {
+        // The loop is one waiting for the bar line (an earlier swap): the newest takes its place there, and what sounds plays on to it.
+        boundary = looping.start!;
+        for (const queued of this.queue.filter((other) => other.start !== null && other.start > now)) this.drop(queued);
+      } else {
+        const passes = Math.max(1, Math.ceil((now - looping.start!) / looping.duration));
+        boundary = looping.start! + passes * looping.duration;
+        // The loop plays to the end of this pass and ends there; the rest scheduled goes.
+        looping.loops = false;
+        looping.source!.loop = false;
+        for (const queued of this.queue.filter((other) => other !== looping)) this.drop(queued);
+      }
+      entry.start = boundary;
+      this.end = entry.loops ? boundary : boundary + entry.duration;
+      this.queue.push(entry);
+      this.sound(entry);
+      return;
+    }
+    if (mode !== 'after') {
+      // An item that interrupts at a time to come lets what sounds play on until then, as AVAudioPlayerNode does.
+      const at = entry.at;
+      const now = this.time();
+      const until = at && now !== null && 'sampleTime' in at ? at.sampleTime / at.sampleRate : at && now !== null && 'delay' in at ? now + at.delay : null;
+      this.clear(until !== null && now !== null && until > now ? until : null);
+    }
+    this.queue.push(entry);
+    this.place(entry);
+    if (this.origin !== null) this.sound(entry);
+  }
+
+  /** Takes one item off the timeline, its completion called. */
+  private drop(entry: Scheduled): void {
+    const source = entry.source;
+    entry.source = null;
+    source?.stop();
+    this.queue = this.queue.filter((item) => item !== entry);
+    entry.done();
+  }
+
+  /** Puts an item on the timeline: at its sample time, `delay` from now, or after the last one. */
+  private place(entry: Scheduled): void {
+    const at = entry.at;
+    // `delay` from now means from when it plays: placed once it does.
+    if (at && 'delay' in at && this.origin === null) return;
+    let start: number;
+    if (at && 'sampleTime' in at) start = at.sampleTime / at.sampleRate;
+    else if (at && 'delay' in at) start = this.context.currentTime + at.delay - this.origin!;
+    else start = Math.max(this.end, this.time() ?? 0);
+    entry.start = start;
+    if (!entry.loops) this.end = Math.max(this.end, start + entry.duration);
+  }
+
+  play(at: AudioTimeSpec | undefined): void {
+    if (this.origin !== null) return;
+    const delay = at && 'delay' in at ? Math.max(0, at.delay) : 0;
+    const held = this.started ? this.heldAt : 0;
+    // A sample time on `play` is when, on the timeline already there, playing resumes.
+    const from = at && 'sampleTime' in at ? at.sampleTime / at.sampleRate : held;
+    this.origin = this.context.currentTime + delay - from;
+    this.started = true;
+    for (const entry of this.queue) {
+      if (entry.at && 'delay' in entry.at && entry.start === null) this.place(entry);
+      this.sound(entry);
+    }
+  }
+
+  /** Starts an item's source where the timeline says, part-way through when the timeline is past its start. */
+  private sound(entry: Scheduled): void {
+    if (this.origin === null || entry.source || entry.start === null || !this.running) return;
+    const now = this.context.currentTime;
+    const startsAt = this.origin + entry.start;
+    let offset = entry.offset;
+    let when = startsAt;
+    if (startsAt < now) {
+      const late = now - startsAt;
+      if (!entry.loops && late >= entry.duration) {
+        this.finish(entry);
+        return;
+      }
+      offset = entry.loops ? entry.offset + (late % entry.duration) : entry.offset + late;
+      when = now;
+    }
+    const source = this.context.createBufferSource();
+    source.buffer = entry.audio;
+    if (entry.loops) {
+      source.loop = true;
+      source.loopStart = entry.offset;
+      source.loopEnd = entry.offset + entry.duration;
+      source.start(when, offset);
+    } else {
+      source.start(when, offset, entry.offset + entry.duration - offset);
+    }
+    source.connect(this.sum);
+    source.onended = () => {
+      // Ended by a pause: the item stays on the timeline for `play` to pick up.
+      if (entry.source === source) this.finish(entry);
+    };
+    entry.source = source;
+  }
+
+  private finish(entry: Scheduled): void {
+    entry.source = null;
+    this.queue = this.queue.filter((item) => item !== entry);
+    entry.done();
+  }
+
+  pause(): void {
+    if (this.origin === null) return;
+    this.heldAt = this.context.currentTime - this.origin;
+    this.origin = null;
+    for (const entry of this.queue) {
+      const source = entry.source;
+      entry.source = null;
+      source?.stop();
+    }
+  }
+
+  /** Drops everything scheduled (each completion called) and returns the timeline to 0. */
+  stop(): void {
+    this.origin = null;
+    this.started = false;
+    this.heldAt = 0;
+    this.clear();
+  }
+
+  /** Drops what is scheduled, each stopping now or, given `until`, at that time on the timeline. */
+  private clear(until: number | null = null): void {
+    const queue = this.queue;
+    this.queue = [];
+    this.end = this.origin !== null ? Math.max(0, this.context.currentTime - this.origin) : this.heldAt;
+    for (const entry of queue) {
+      const source = entry.source;
+      entry.source = null;
+      if (source && until !== null && this.origin !== null) {
+        source.onended = () => entry.done();
+        source.stop(this.origin + until);
+      } else {
+        source?.stop();
+        entry.done();
+      }
+    }
+  }
+
+  /** The engine started (`on`) or paused: the timeline sounds only while it runs. */
+  engineRunning(on: boolean): void {
+    this.running = on;
+    if (on) for (const entry of this.queue) this.sound(entry);
+  }
+
+  override halt(): void {
+    this.stop();
+  }
+}
+
+/** A voice of the sampler: its source and envelope. */
+interface Voice {
+  note: number;
+  channel: number;
+  root: number;
+  source: AudioBufferSourceNode;
+  envelope: GainNode;
+  /** Held by the sustain pedal after its key was let go. */
+  sustained: boolean;
+}
+
+/**
+ * `AVAudioUnitSampler` with per-note sample zones: a note plays the zone
+ * that covers it, pitched from the zone's root, with an attack and a
+ * release; velocity, the sustain pedal (64), volume (7), expression (11),
+ * pan (10), all notes off (123, 120) and a ±2 semitone pitch bend, as the
+ * sampler's default instrument responds.
+ */
+class SamplerNode extends WebNode {
+  readonly input = null;
+  readonly output: AudioNode;
+  private readonly gain: GainNode;
+  private readonly channelVolume: GainNode;
+  private readonly stereo: StereoPannerNode;
+  private readonly mixing: Mixing;
+  private zones: { zone: SamplerZone; audio: AudioBuffer }[] = [];
+  private attack = 0.002;
+  private release = 0.15;
+  private voices: Voice[] = [];
+  private tuning = 0;
+  private bend = 0;
+  private pedal = false;
+  private volumeCC = 1;
+  private expression = 1;
+
+  constructor(id: number, context: BaseAudioContext) {
+    super(id, 'sampler', context);
+    this.gain = context.createGain();
+    this.channelVolume = context.createGain();
+    this.stereo = context.createStereoPanner();
+    this.mixing = new Mixing(context);
+    this.gain.connect(this.channelVolume).connect(this.stereo).connect(this.mixing.volume);
+    this.output = this.mixing.panner;
+  }
+
+  set(key: string, value: AudioValue): void {
+    if (this.mixing.set(key, value)) return;
+    if (key === 'overallGain') this.gain.gain.value = gainOf(Math.max(-90, Math.min(12, num(value, 0))));
+    else if (key === 'globalTuning') {
+      this.tuning = Math.max(-2400, Math.min(2400, num(value, 0)));
+      this.retune();
+    } else if (key === 'stereoPan') this.stereo.pan.value = Math.max(-1, Math.min(1, num(value, 0) / 100));
+  }
+
+  load(zones: { zone: SamplerZone; audio: AudioBuffer }[], attack: number, release: number): void {
+    this.allOff(true);
+    this.zones = zones;
+    this.attack = Math.max(0.001, attack);
+    this.release = Math.max(0.005, release);
+  }
+
+  start(note: number, velocity: number, channel: number): void {
+    const found = this.zones.find(({ zone }) => note >= zone.low && note <= zone.high);
+    if (!found || velocity <= 0) {
+      if (velocity <= 0) this.stop(note, channel);
+      return;
+    }
+    // The same key again: the sounding one lets go first.
+    for (const voice of this.voices.filter((v) => v.note === note && v.channel === channel)) this.letGo(voice);
+    const now = this.context.currentTime;
+    const source = this.context.createBufferSource();
+    source.buffer = found.audio;
+    source.playbackRate.value = rateFor(note, found.zone.root, this.tuning + this.bend);
+    const envelope = this.context.createGain();
+    const level = Math.pow(Math.max(0, Math.min(127, velocity)) / 127, 2);
+    envelope.gain.setValueAtTime(0, now);
+    envelope.gain.linearRampToValueAtTime(level, now + this.attack);
+    source.connect(envelope).connect(this.gain);
+    const voice: Voice = { note, channel, root: found.zone.root, source, envelope, sustained: false };
+    source.onended = () => {
+      envelope.disconnect();
+      this.voices = this.voices.filter((v) => v !== voice);
+    };
+    source.start(now);
+    this.voices.push(voice);
+  }
+
+  stop(note: number, channel: number): void {
+    for (const voice of this.voices.filter((v) => v.note === note && v.channel === channel && !v.sustained)) {
+      if (this.pedal) voice.sustained = true;
+      else this.letGo(voice);
+    }
+  }
+
+  private letGo(voice: Voice, release = this.release): void {
+    const now = this.context.currentTime;
+    const gain = voice.envelope.gain;
+    gain.cancelScheduledValues(now);
+    gain.setValueAtTime(gain.value, now);
+    gain.linearRampToValueAtTime(0, now + release);
+    voice.source.stop(now + release + 0.01);
+    voice.note = -1;
+  }
+
+  controller(controller: number, value: number): void {
+    const v = Math.max(0, Math.min(127, value));
+    if (controller === 64) {
+      this.pedal = v >= 64;
+      if (!this.pedal) for (const voice of this.voices.filter((x) => x.sustained)) this.letGo(voice);
+    } else if (controller === 7) {
+      this.volumeCC = Math.pow(v / 127, 2);
+      this.channelVolume.gain.value = this.volumeCC * this.expression;
+    } else if (controller === 11) {
+      this.expression = Math.pow(v / 127, 2);
+      this.channelVolume.gain.value = this.volumeCC * this.expression;
+    } else if (controller === 10) {
+      this.stereo.pan.value = (v - 64) / 64;
+    } else if (controller === 120) {
+      this.allOff(true);
+    } else if (controller === 123) {
+      this.allOff(false);
+    }
+  }
+
+  pitchBend(value: number): void {
+    this.bend = ((Math.max(0, Math.min(16383, value)) - 8192) / 8192) * 200;
+    this.retune();
+  }
+
+  private retune(): void {
+    for (const voice of this.voices) {
+      if (voice.note >= 0) voice.source.playbackRate.value = rateFor(voice.note, voice.root, this.tuning + this.bend);
+    }
+  }
+
+  /** Every voice let go (`immediately`: cut off). */
+  private allOff(immediately: boolean): void {
+    for (const voice of [...this.voices]) this.letGo(voice, immediately ? 0.005 : this.release);
+    this.pedal = false;
+  }
+
+  override halt(): void {
+    this.allOff(true);
+  }
+}
+
+/** An effect: its input split into a dry path and a wet one through the effect, mixed by `wetDryMix` (percent). */
+/** A node of a package's kind, with the app's volume and pan after it. */
+class PackageNode extends WebNode {
+  readonly input: AudioNode | null;
+  readonly output: AudioNode;
+  private readonly mixing: Mixing;
+
+  constructor(id: number, kind: string, context: BaseAudioContext, readonly custom: CustomAudioNode) {
+    super(id, kind, context);
+    this.mixing = new Mixing(context);
+    custom.output.connect(this.mixing.volume);
+    this.input = custom.input;
+    this.output = this.mixing.panner;
+  }
+
+  set(key: string, value: AudioValue): void {
+    if (this.mixing.set(key, value)) return;
+    if (!this.custom.set(key, value)) throw failure('unsupported', `a ${this.kind} node has no ${key}`);
+  }
+
+  override halt(): void {
+    this.custom.halt?.();
+  }
+
+  override dispose(): void {
+    super.dispose();
+    this.custom.dispose?.();
+  }
+}
+
+abstract class EffectNode extends WebNode {
+  readonly input: GainNode;
+  readonly output: GainNode;
+  protected readonly dry: GainNode;
+  protected readonly wet: GainNode;
+  protected mix = 100;
+  private bypassed = false;
+
+  constructor(id: number, kind: AudioNodeKind, context: BaseAudioContext) {
+    super(id, kind, context);
+    this.input = context.createGain();
+    this.output = context.createGain();
+    this.dry = context.createGain();
+    this.wet = context.createGain();
+    this.input.connect(this.dry).connect(this.output);
+    this.wet.connect(this.output);
+  }
+
+  set(key: string, value: AudioValue): void {
+    if (key === 'wetDryMix') this.mix = Math.max(0, Math.min(100, num(value, this.mix)));
+    else if (key === 'bypass') this.bypassed = value === true;
+    else this.setEffect(key, value);
+    this.balance();
+  }
+
+  protected abstract setEffect(key: string, value: AudioValue): void;
+
+  protected balance(): void {
+    const wet = this.bypassed ? 0 : this.mix / 100;
+    this.wet.gain.value = wet;
+    this.dry.gain.value = this.bypassed ? 1 : 1 - wet;
+  }
+}
+
+class ReverbNode extends EffectNode {
+  private readonly convolver: ConvolverNode;
+
+  constructor(id: number, context: BaseAudioContext) {
+    super(id, 'reverb', context);
+    this.convolver = context.createConvolver();
+    this.input.connect(this.convolver).connect(this.wet);
+    this.preset('mediumHall');
+  }
+
+  protected setEffect(): void {}
+
+  override preset(name: string): void {
+    const preset = REVERB_PRESETS[name];
+    if (!preset) throw failure('unsupported', `no reverb preset ${name}`);
+    this.convolver.buffer = reverbImpulse(this.context, preset);
+  }
+}
+
+class DelayEffectNode extends EffectNode {
+  private readonly delay: DelayNode;
+  private readonly lowPass: BiquadFilterNode;
+  private readonly feedback: GainNode;
+
+  constructor(id: number, context: BaseAudioContext) {
+    super(id, 'delay', context);
+    this.delay = context.createDelay(2);
+    this.lowPass = context.createBiquadFilter();
+    this.lowPass.type = 'lowpass';
+    this.feedback = context.createGain();
+    this.input.connect(this.delay).connect(this.lowPass).connect(this.wet);
+    this.lowPass.connect(this.feedback).connect(this.delay);
+    this.setEffect('delayTime', 1);
+    this.setEffect('feedback', 50);
+    this.setEffect('lowPassCutoff', 15000);
+  }
+
+  protected setEffect(key: string, value: AudioValue): void {
+    if (key === 'delayTime') this.delay.delayTime.value = Math.max(0, Math.min(2, num(value, 1)));
+    else if (key === 'feedback') this.feedback.gain.value = Math.max(-100, Math.min(100, num(value, 50))) / 100;
+    else if (key === 'lowPassCutoff') this.lowPass.frequency.value = Math.max(10, Math.min(this.context.sampleRate / 2, num(value, 15000)));
+  }
+}
+
+class DistortionNode extends EffectNode {
+  private readonly preGain: GainNode;
+  private readonly shaper: WaveShaperNode;
+
+  constructor(id: number, context: BaseAudioContext) {
+    super(id, 'distortion', context);
+    this.preGain = context.createGain();
+    this.shaper = context.createWaveShaper();
+    this.shaper.oversample = '2x';
+    this.input.connect(this.preGain).connect(this.shaper).connect(this.wet);
+    this.mix = 50;
+    this.setEffect('preGain', -6);
+    this.shaper.curve = distortionCurve(4);
+    this.balance();
+  }
+
+  protected setEffect(key: string, value: AudioValue): void {
+    // The pre-gain drives into the curve: louder in, harder clipped.
+    if (key === 'preGain') this.preGain.gain.value = gainOf(Math.max(-80, Math.min(20, num(value, -6)))) * 4;
+  }
+
+  override preset(name: string): void {
+    const preset = DISTORTION_PRESETS[name];
+    if (!preset) throw failure('unsupported', `no distortion preset ${name}`);
+    this.shaper.curve = distortionCurve(preset.drive, preset.bits);
+    this.mix = preset.mix;
+    this.balance();
+  }
+}
+
+/** `AVAudioUnitEQ`: a chain of biquads, one per band (each bypassed until the app turns it on, as Apple's are), and a global gain. */
+class EQNode extends WebNode {
+  readonly input: GainNode;
+  readonly output: GainNode;
+  private readonly filters: BiquadFilterNode[] = [];
+  private readonly bands: { type: string; frequency: number; bandwidth: number; gain: number; bypass: boolean }[] = [];
+  private bypassed = false;
+
+  constructor(id: number, context: BaseAudioContext, count: number) {
+    super(id, 'eq', context);
+    this.input = context.createGain();
+    this.output = context.createGain();
+    for (let i = 0; i < Math.max(1, Math.min(32, count)); i += 1) {
+      this.filters.push(context.createBiquadFilter());
+      this.bands.push({ type: 'parametric', frequency: 1000, bandwidth: 0.5, gain: 0, bypass: true });
+    }
+    this.rewire();
+  }
+
+  set(key: string, value: AudioValue): void {
+    if (key === 'globalGain') {
+      this.output.gain.value = gainOf(Math.max(-96, Math.min(24, num(value, 0))));
+      return;
+    }
+    if (key === 'bypass') {
+      this.bypassed = value === true;
+      this.rewire();
+      return;
+    }
+    const match = /^bands\.(\d+)\.(\w+)$/.exec(key);
+    const band = match ? this.bands[Number(match[1])] : undefined;
+    if (!match || !band) return;
+    const field = match[2];
+    if (field === 'filterType' && typeof value === 'string' && value in EQ_TYPES) band.type = value;
+    else if (field === 'frequency') band.frequency = Math.max(10, Math.min(this.context.sampleRate / 2, num(value, band.frequency)));
+    else if (field === 'bandwidth') band.bandwidth = Math.max(0.05, Math.min(5, num(value, band.bandwidth)));
+    else if (field === 'gain') band.gain = Math.max(-96, Math.min(24, num(value, band.gain)));
+    else if (field === 'bypass') band.bypass = value === true;
+    this.rewire();
+  }
+
+  /** Chains the bands that are on, each filter set from its band. */
+  private rewire(): void {
+    this.input.disconnect();
+    for (const filter of this.filters) filter.disconnect();
+    let last: AudioNode = this.input;
+    if (!this.bypassed) {
+      this.bands.forEach((band, i) => {
+        const filter = this.filters[i]!;
+        if (band.bypass) return;
+        filter.type = EQ_TYPES[band.type] ?? 'peaking';
+        filter.frequency.value = band.frequency;
+        filter.gain.value = band.gain;
+        // Resonant types and the peak take the bandwidth; the plain ones are Butterworth.
+        filter.Q.value =
+          band.type === 'lowPass' || band.type === 'highPass'
+            ? Math.SQRT1_2
+            : band.type.includes('Shelf') && !band.type.startsWith('resonant')
+              ? 1
+              : qForBandwidth(band.bandwidth);
+        last.connect(filter);
+        last = filter;
+      });
+    }
+    last.connect(this.output);
+  }
+}
+
+/** `AVAudioUnitTimePitch`: Web Audio cannot change pitch and speed apart, so the page passes the sound through. */
+class TimePitchNode extends WebNode {
+  readonly input: GainNode;
+  readonly output: GainNode;
+
+  constructor(id: number, context: BaseAudioContext) {
+    super(id, 'timePitch', context);
+    this.input = context.createGain();
+    this.output = this.input;
+  }
+
+  set(): void {}
+}
+
+interface Engine {
+  id: number;
+  nodes: Map<number, WebNode>;
+  output: OutputNode;
+  input: InputNode;
+  running: boolean;
+  /** The players that were playing when it paused, to play again on `start`. */
+  paused: PlayerNode[];
+}
+
+interface DecodedFile {
+  audio: AudioBuffer;
+}
+
+export class WebAudioEngineHost implements AudioEngineHost {
+  private readonly engines = new Map<number, Engine>();
+  /** Every node by id, whichever engine it is in. */
+  private readonly nodes = new Map<number, WebNode>();
+  /** Nodes made by `attach` and not yet in an engine are not kept: a node exists only attached. */
+  private readonly files = new Map<number, DecodedFile>();
+  private readonly buffers = new Map<number, AudioBuffer>();
+  private contextValue: BaseAudioContext | null = null;
+
+  constructor(private readonly sources: AudioEngineSources) {}
+
+  private get context(): BaseAudioContext {
+    return (this.contextValue ??= this.sources.context());
+  }
+
+  perform(command: AudioEngineCommand): Promise<unknown> {
+    try {
+      return this.run(command);
+    } catch (error) {
+      return Promise.reject(error instanceof Error ? error : new Error(String(error)));
+    }
+  }
+
+  private engine(id: number): Engine {
+    const engine = this.engines.get(id);
+    if (!engine) throw failure('notFound', `no engine ${id}`);
+    return engine;
+  }
+
+  private node(id: number): WebNode {
+    const node = this.nodes.get(id);
+    if (!node) throw failure('notFound', `no node ${id} is attached`);
+    return node;
+  }
+
+  private player(id: number): PlayerNode {
+    const node = this.node(id);
+    if (!(node instanceof PlayerNode)) throw failure('unsupported', `node ${id} is not a player`);
+    return node;
+  }
+
+  /** A player to schedule on or play: connected, as natively (AVAudioEngine traps on a player that sends nowhere). */
+  private connectedPlayer(id: number): PlayerNode {
+    const player = this.player(id);
+    if (player.destinations.size === 0) throw failure('notConnected', 'connect the player before scheduling or playing');
+    return player;
+  }
+
+  private sampler(id: number): SamplerNode {
+    const node = this.node(id);
+    if (!(node instanceof SamplerNode)) throw failure('unsupported', `node ${id} is not a sampler`);
+    return node;
+  }
+
+  /** A note for a sampler, or for a package's node that takes notes. */
+  private note(command: AudioNoteCommand): Promise<unknown> {
+    const node = this.node(command.node);
+    if (node instanceof PackageNode) {
+      if (!node.custom.note?.(command)) throw failure('unsupported', `a ${node.kind} node takes no notes`);
+      return Promise.resolve({});
+    }
+    const sampler = this.sampler(command.node);
+    if (command.action === 'startNote') sampler.start(command.note, command.velocity, command.channel);
+    else if (command.action === 'stopNote') sampler.stop(command.note, command.channel);
+    else if (command.action === 'controller') sampler.controller(command.controller, command.value);
+    else sampler.pitchBend(command.value);
+    return Promise.resolve({});
+  }
+
+  /** Runs one command; what is synchronous happens before it returns, so commands keep their order. */
+  private run(command: AudioEngineCommand): Promise<unknown> {
+    const done = Promise.resolve({});
+    switch (command.action) {
+      case 'create': {
+        const context = this.context;
+        const output = new OutputNode(command.output, context);
+        const input = new InputNode(command.input, context);
+        const mixer = new MixerNode(command.mixer, context);
+        const engine: Engine = { id: command.engine, nodes: new Map(), output, input, running: false, paused: [] };
+        for (const node of [output, input, mixer]) {
+          engine.nodes.set(node.id, node);
+          this.nodes.set(node.id, node);
+        }
+        this.engines.set(command.engine, engine);
+        this.link(mixer, [output]);
+        return done;
+      }
+      case 'destroy': {
+        const engine = this.engines.get(command.engine);
+        if (!engine) return done;
+        for (const node of engine.nodes.values()) {
+          node.dispose();
+          this.nodes.delete(node.id);
+        }
+        this.engines.delete(command.engine);
+        return done;
+      }
+      case 'attach': {
+        const engine = this.engine(command.engine);
+        if (this.nodes.has(command.node)) throw failure('exists', `node ${command.node} is attached already`);
+        const node = this.make(command.node, command.kind, command.bands ?? 1);
+        for (const [key, value] of Object.entries(command.values)) {
+          if (key === 'preset' && typeof value === 'string') node.preset(value);
+          else node.set(key, value);
+        }
+        if (node instanceof PlayerNode) node.engineRunning(engine.running);
+        engine.nodes.set(node.id, node);
+        this.nodes.set(node.id, node);
+        return done;
+      }
+      case 'detach': {
+        const engine = this.engine(command.engine);
+        const node = engine.nodes.get(command.node);
+        if (!node) return done;
+        this.unlinkOutput(node);
+        this.unlinkInput(node);
+        node.dispose();
+        engine.nodes.delete(node.id);
+        this.nodes.delete(node.id);
+        return done;
+      }
+      case 'connect': {
+        const engine = this.engine(command.engine);
+        const from = engine.nodes.get(command.from);
+        const to = command.to.map((id) => engine.nodes.get(id));
+        if (!from || to.some((node) => !node)) throw failure('notFound', 'both nodes must be attached to the engine to connect them');
+        if (to.some((node) => node!.input === null)) throw failure('unsupported', 'a player, a sampler or the input takes no input');
+        if (from.kind === 'output' || to.includes(from)) throw failure('unsupported', 'the output sends nowhere, and a node cannot feed itself');
+        this.link(from, to as WebNode[]);
+        return done;
+      }
+      case 'disconnectOutput':
+        this.unlinkOutput(this.engine(command.engine).nodes.get(command.node) ?? this.node(command.node));
+        return done;
+      case 'disconnectInput':
+        this.unlinkInput(this.engine(command.engine).nodes.get(command.node) ?? this.node(command.node));
+        return done;
+      case 'prepare':
+        this.engine(command.engine);
+        return done;
+      case 'start':
+        return this.start(this.engine(command.engine));
+      case 'pause': {
+        const engine = this.engine(command.engine);
+        if (!engine.running) return done;
+        engine.running = false;
+        engine.paused = [];
+        for (const node of engine.nodes.values()) {
+          if (node instanceof PlayerNode) {
+            if (node.isPlaying) {
+              engine.paused.push(node);
+              node.pause();
+            }
+            node.engineRunning(false);
+          }
+        }
+        engine.output.live(false);
+        return done;
+      }
+      case 'stop':
+      case 'reset': {
+        const engine = this.engine(command.engine);
+        if (command.action === 'stop') {
+          engine.running = false;
+          engine.output.live(false);
+          engine.input.halt();
+        }
+        engine.paused = [];
+        for (const node of engine.nodes.values()) {
+          if (node instanceof PlayerNode) {
+            node.stop();
+            node.engineRunning(engine.running);
+          } else if (node instanceof SamplerNode) node.halt();
+        }
+        return done;
+      }
+      case 'set': {
+        const node = this.node(command.node);
+        for (const [key, value] of Object.entries(command.values)) node.set(key, value);
+        return done;
+      }
+      case 'preset':
+        this.node(command.node).preset(command.preset);
+        return done;
+      case 'openFile':
+        return this.open(command.file, command.url);
+      case 'readFile': {
+        const file = this.files.get(command.file);
+        if (!file) throw failure('notFound', `no file ${command.file} is open`);
+        const audio = file.audio;
+        const start = Math.max(0, Math.min(audio.length, Math.floor(command.start)));
+        const frames = Math.max(0, Math.min(audio.length - start, Math.floor(command.frames)));
+        const buffer = this.context.createBuffer(audio.numberOfChannels, Math.max(1, frames), audio.sampleRate);
+        for (let channel = 0; channel < audio.numberOfChannels; channel += 1) {
+          buffer.copyToChannel(audio.getChannelData(channel).subarray(start, start + frames), channel);
+        }
+        this.buffers.set(command.buffer, frames === 0 ? this.context.createBuffer(audio.numberOfChannels, 1, audio.sampleRate) : buffer);
+        return Promise.resolve({ frameLength: frames, sampleRate: audio.sampleRate, channelCount: audio.numberOfChannels } satisfies AudioBufferInfo);
+      }
+      case 'writeBuffer': {
+        // The app's own arrays: a view over a SharedArrayBuffer is its doing.
+        const channels = command.channels as Float32Array<ArrayBuffer>[];
+        const frames = Math.max(1, ...channels.map((data) => data.length));
+        const buffer = this.context.createBuffer(Math.max(1, channels.length), frames, Math.max(3000, Math.min(768000, command.sampleRate)));
+        channels.forEach((data, channel) => buffer.copyToChannel(data, channel));
+        this.buffers.set(command.buffer, buffer);
+        return done;
+      }
+      case 'release':
+        this.files.delete(command.id);
+        this.buffers.delete(command.id);
+        return done;
+      case 'scheduleFile': {
+        const player = this.connectedPlayer(command.node);
+        const file = this.files.get(command.file);
+        if (!file) throw failure('notFound', `no file ${command.file} is open`);
+        const rate = file.audio.sampleRate;
+        const start = Math.max(0, Math.min(file.audio.length, command.start ?? 0));
+        const frames = Math.max(0, Math.min(file.audio.length - start, command.frames ?? file.audio.length - start));
+        return new Promise((resolve) => {
+          player.schedule({ audio: file.audio, offset: start / rate, duration: frames / rate, loops: false, at: command.at, done: () => resolve({}) });
+        });
+      }
+      case 'scheduleBuffer': {
+        const player = this.connectedPlayer(command.node);
+        const audio = this.buffers.get(command.buffer);
+        if (!audio) throw failure('notFound', `no buffer ${command.buffer}`);
+        return new Promise((resolve) => {
+          player.schedule(
+            { audio, offset: 0, duration: audio.duration, loops: command.loops === true, at: command.at, done: () => resolve({}) },
+            command.interruptsAtLoop === true ? 'atLoop' : command.interrupts === true ? 'interrupts' : 'after',
+          );
+        });
+      }
+      case 'play': {
+        const player = this.connectedPlayer(command.node);
+        if (!player.running) throw failure('stopped', 'a player plays only while its engine runs');
+        player.play(command.at);
+        return done;
+      }
+      case 'pausePlayer':
+        this.player(command.node).pause();
+        return done;
+      case 'stopPlayer':
+        this.player(command.node).stop();
+        return done;
+      case 'playerTime': {
+        const player = this.player(command.node);
+        const time = player.time();
+        const rate = this.context.sampleRate;
+        return Promise.resolve(time === null ? null : { sampleTime: Math.round(time * rate), sampleRate: rate });
+      }
+      case 'loadZones': {
+        const sampler = this.sampler(command.node);
+        const zones = command.zones.map((zone) => {
+          const file = this.files.get(zone.file);
+          if (!file) throw failure('notFound', `no file ${zone.file} is open`);
+          return { zone, audio: file.audio };
+        });
+        sampler.load(zones, command.attack, command.release);
+        return done;
+      }
+      case 'loadInstrument':
+        this.sampler(command.node);
+        throw failure('unsupported', 'this page cannot load a sound bank or preset; load audio files instead');
+      case 'startNote':
+      case 'stopNote':
+      case 'controller':
+      case 'pitchBend':
+        return this.note(command);
+      case 'meter':
+        return Promise.resolve({ level: this.node(command.node).meter() });
+    }
+  }
+
+  private make(id: number, kind: AudioNodeKind | CustomAudioNodeKind, bands: number): WebNode {
+    const context = this.context;
+    switch (kind as AudioNodeKind) {
+      case 'player':
+        return new PlayerNode(id, context);
+      case 'sampler':
+        return new SamplerNode(id, context);
+      case 'mixer':
+        return new MixerNode(id, context);
+      case 'reverb':
+        return new ReverbNode(id, context);
+      case 'delay':
+        return new DelayEffectNode(id, context);
+      case 'distortion':
+        return new DistortionNode(id, context);
+      case 'eq':
+        return new EQNode(id, context, bands);
+      case 'timePitch':
+        return new TimePitchNode(id, context);
+      default: {
+        const custom = customKinds.get(kind);
+        if (!custom) throw failure('unsupported', `no node kind ${kind}`);
+        return new PackageNode(id, kind, context, custom(context));
+      }
+    }
+  }
+
+  /**
+   * Connects `from`'s output to `to` (several: a fan-out), replacing where
+   * it went before, as `AVAudioEngine.connect` does; a node that is not a
+   * mixer takes one input, so what was connected into it is let go.
+   */
+  private link(from: WebNode, to: WebNode[]): void {
+    this.unlinkOutput(from);
+    for (const node of to) {
+      if (!node.mixes) for (const source of [...node.sources]) this.cut(source, node);
+      from.output.connect(node.input!);
+      from.destinations.add(node);
+      node.sources.add(from);
+    }
+  }
+
+  private cut(from: WebNode, to: WebNode): void {
+    try {
+      from.output.disconnect(to.input!);
+    } catch {
+      // Not connected.
+    }
+    from.destinations.delete(to);
+    to.sources.delete(from);
+  }
+
+  private unlinkOutput(node: WebNode): void {
+    for (const destination of [...node.destinations]) this.cut(node, destination);
+  }
+
+  private unlinkInput(node: WebNode): void {
+    for (const source of [...node.sources]) this.cut(source, node);
+  }
+
+  private async start(engine: Engine): Promise<unknown> {
+    if (engine.running) return {};
+    // The input opens when something listens to it (the microphone is asked for then).
+    if (engine.input.destinations.size > 0) await engine.input.open(this.sources.microphone);
+    const context = this.context;
+    if ('resume' in context && context.state === 'suspended') await (context as AudioContext).resume().catch(() => undefined);
+    engine.running = true;
+    engine.output.live(true);
+    for (const node of engine.nodes.values()) if (node instanceof PlayerNode) node.engineRunning(true);
+    for (const player of engine.paused) player.play(undefined);
+    engine.paused = [];
+    return {};
+  }
+
+  private async open(id: number, url: string): Promise<AudioFileInfo> {
+    let bytes: ArrayBuffer;
+    try {
+      bytes = await this.sources.read(url);
+    } catch (error) {
+      const message = error instanceof Error ? error.message : String(error);
+      throw message.includes(':') ? new Error(message) : failure('notFound', `${url} could not be read (${message})`);
+    }
+    let audio: AudioBuffer;
+    try {
+      audio = await this.context.decodeAudioData(bytes);
+    } catch (error) {
+      throw failure('decode', `${url} is not audio this page can read (${String(error)})`);
+    }
+    this.files.set(id, { audio });
+    return { length: audio.length, sampleRate: audio.sampleRate, channelCount: audio.numberOfChannels };
+  }
+}