polyphon 0.0.0-stage → 0.1.0

package/src/engine/automation.ts

@@ -0,0 +1,65 @@
+// Mixer automation, scheduled ahead like the notes: sidechain pumping (a track dips at every hit of another, then swells back)
+// and filter sweeps through a section.
+
+import type { Sweep } from '../song.ts';
+
+/** A ducking track's gain, and how it pumps */
+export interface Pump {
+  gain: AudioParam;
+  /** How far it dips, 0-1 */
+  depth: number;
+  /** Seconds until it is back up */
+  release: number;
+}
+
+/** The dip starts this far ahead of the hit, so the level is down when the hit lands (seconds) */
+const LEAD = 0.004;
+
+/** Level of a ducking track `t` seconds after a hit: down for the first quarter of the release, then swelling back (95% there at the end) */
+export function duckLevel(depth: number, release: number, t: number): number {
+  const swell = release / 4;
+  return 1 - depth * Math.exp(-Math.max(0, t - swell) / swell);
+}
+
+/** Pump at a hit (context seconds). A hit before `from`, when a playback starts mid-swell, is picked up where it would be by then */
+export function pump({ gain, depth, release }: Pump, hit: number, from = hit): void {
+  const swell = release / 4;
+  if (from > hit) gain.setValueAtTime(duckLevel(depth, release, from - hit), from);
+  else gain.setTargetAtTime(1 - depth, hit - LEAD, LEAD / 3);
+  gain.setTargetAtTime(1, Math.max(from, hit + swell), swell);
+}
+
+/** A sweep's breakpoints as [step, Hz], in order */
+export function breakpoints(sweep: Sweep): [number, number][] {
+  return Object.entries(sweep)
+    .map(([step, hz]): [number, number] => [Number(step), Math.max(10, hz)])
+    .sort((a, b) => a[0] - b[0]);
+}
+
+/** A sweep's cutoff at a step: held before the first breakpoint and after the last, gliding exponentially (evenly in pitch) between */
+export function cutoffAt(points: [number, number][], step: number): number {
+  const i = points.findIndex(([s]) => s > step);
+  if (i === 0) return points[0][1];
+  if (i < 0) return points[points.length - 1][1];
+  const [s0, f0] = points[i - 1];
+  const [s1, f1] = points[i];
+  return f0 * Math.pow(f1 / f0, (step - s0) / (s1 - s0));
+}
+
+/** How long a sweep takes to get back to its start when its section repeats (seconds) */
+const GLIDE = 0.02;
+
+/**
+ * Schedule one pass of a sweep through a section that lasts `steps`, from `from` steps in; `time` gives the context time of a step.
+ * A pass that follows another (`again`) glides back from where the last one ended: a filter retuned in one jump while it carries
+ * sound thumps.
+ */
+export function sweep(cutoff: AudioParam, points: [number, number][], from: number, steps: number, time: (step: number) => number, again = false): void {
+  const at = time(from);
+  if (again) {
+    cutoff.setValueAtTime(cutoffAt(points, steps), at);
+    cutoff.exponentialRampToValueAtTime(cutoffAt(points, from), at + GLIDE);
+  } else cutoff.setValueAtTime(cutoffAt(points, from), at);
+  const knots = new Set(points.map(([s]) => Math.min(s, steps)).filter((s) => s > from));
+  for (const s of knots) cutoff.exponentialRampToValueAtTime(cutoffAt(points, s), time(s));
+}

package/src/engine/compile.ts

@@ -0,0 +1,124 @@
+// Compile a song's sections into flat, time-sorted note lists, and list the samples a song needs rendered.
+
+import { DESKS } from '../instruments/bowed.ts';
+import type { SampledInstrument } from '../instruments/definition.ts';
+import { getInstrument } from '../instruments/registry.ts';
+import { bowLayers, type SampleRequest } from '../instruments/samples.ts';
+import type { Meter } from '../notation/part.ts';
+import { sectionSteps, trackName, trackPart, type Song, type Track } from '../song.ts';
+
+/** A note ready to schedule */
+export interface ScheduledNote {
+  /** Steps from the start of the section */
+  time: number;
+  duration: number;
+  pitches: number[];
+  velocity: number;
+  /** Index of the track in its section */
+  track: number;
+  /** Glides merged into this note: [steps after its start, target MIDI pitch] */
+  bends?: [number, number][];
+  strum?: number;
+}
+
+export interface CompiledSection {
+  /** Length in steps (whole bars) */
+  duration: number;
+  notes: ScheduledNote[];
+  /** For each track, the tracks that duck under its hits */
+  ducks: number[][];
+  /** For each track, the desk it plays at (see deskList) */
+  desks: number[];
+}
+
+/** Compile one section into sorted notes; shorter tracks repeat to fill the whole section */
+export function compileSection(tracks: Song['tracks'], meter: Meter): CompiledSection {
+  const parts = tracks.map((t) => trackPart(t, meter));
+  const duration = sectionSteps(parts, meter);
+  const notes: ScheduledNote[] = [];
+  tracks.forEach((track, ti) => {
+    const p = parts[ti];
+    if (!p.duration) return;
+    const reps = track.repeat === false ? 1 : Math.max(1, Math.floor(duration / p.duration + 1e-6));
+    const src = [...p.notes].sort((a, b) => a.time - b.time);
+    const glides = getInstrument(track.instrument).glide ?? false;
+    for (let r = 0; r < reps; r++) {
+      const off = r * p.duration;
+      for (let i = 0; i < src.length; i++) {
+        const n = src[i];
+        if (n.time + off >= duration) break;
+        const c: ScheduledNote = { time: n.time + off, duration: n.duration, pitches: n.pitches, velocity: n.velocity, track: ti, strum: n.strum };
+        // Glide: merge the following notes in, turning them into pitch changes of the same voice
+        if (glides && n.glide) {
+          c.bends = [];
+          let j = i;
+          while (src[j]?.glide && src[j + 1]) {
+            const next = src[j + 1];
+            c.bends.push([next.time - n.time, next.pitches[0]]);
+            c.duration = next.time + next.duration - n.time;
+            j++;
+          }
+          i = j;
+        }
+        notes.push(c);
+      }
+    }
+  });
+  notes.sort((a, b) => a.time - b.time);
+  return { duration, notes, ducks: duckLists(tracks), desks: deskList(tracks) };
+}
+
+/** For each track, the tracks that duck under its hits (a pad with `duck: 'Kick'` is on the kick's list) */
+function duckLists(tracks: Track[]): number[][] {
+  const ducks = tracks.map((): number[] => []);
+  tracks.forEach((track, i) => {
+    if (!track.duck) return;
+    const by = typeof track.duck === 'string' ? track.duck : track.duck.by;
+    const triggers = tracks.flatMap((t, k) => (k !== i && trackName(t) === by ? [k] : []));
+    if (!triggers.length) throw new Error(`"${trackName(track)}" ducks under "${by}", but no other track in its section is called that`);
+    for (const k of triggers) ducks[k].push(i);
+  });
+  return ducks;
+}
+
+/**
+ * For each track, the desk it plays at. Tracks of one section that share a bowed instrument (or its samples: strPad plays the strings') are
+ * different players, as the desks of a string section are: the first sits at desk 0 and sounds as a lone track always has, the next at desk 1
+ * with its own tuning, vibrato and bow (see DESKS), then desk 2, and round again. Other tracks are at desk 0.
+ */
+export function deskList(tracks: Track[]): number[] {
+  const seated = new Map<string, number>();
+  return tracks.map((track) => {
+    const def = getInstrument(track.instrument);
+    if (def.kind !== 'sample' || !def.bow) return 0;
+    const k = seated.get(def.bow.name) ?? 0;
+    seated.set(def.bow.name, k + 1);
+    return k % DESKS.length;
+  });
+}
+
+/** Every sample a song will play, so they can be rendered before it starts */
+export function sampleRequests(song: Song): SampleRequest[] {
+  const out = new Map<string, SampleRequest>();
+  const meter = song.meter ?? 16;
+  for (const tracks of [song.intro ?? [], song.tracks]) {
+    const desks = deskList(tracks);
+    tracks.forEach((track, ti) => {
+      const def = getInstrument(track.instrument);
+      if (def.kind !== 'sample') return;
+      const desk = desks[ti];
+      for (const n of trackPart(track, meter).notes) {
+        for (const m of n.pitches.length ? n.pitches : [0]) {
+          const midi = m + (track.transpose ?? 0);
+          if (def.bow) {
+            // Bowed strings: only the velocity layers that will be used, at the track's desk
+            for (const layer of bowLayers(def, n.velocity, track.params?.bright)) out.set(`${track.instrument}|${midi}|${layer}|${desk}`, request(def, track.instrument, midi, layer, desk));
+          } else out.set(`${track.instrument}|${midi}`, request(def, track.instrument, midi));
+        }
+      }
+    });
+  }
+  return [...out.values()];
+}
+
+const request = (def: SampledInstrument, name: string, midi: number, layer?: number, desk?: number): SampleRequest => ({ def, name, midi, layer, desk });

package/src/engine/jukebox.ts

@@ -0,0 +1,322 @@
+// The Jukebox: the one object a game needs. It owns the clock, crossfades between songs, prepares samples ahead of time,
+// and handles the browser's audio unlock. One song plays at a time; jingles can be layered on top.
+
+import type { Song } from '../song.ts';
+import { createOutputStage, mastersItself } from './output.ts';
+import { Playback } from './playback.ts';
+import { prepareSong, prepareSongSync } from './prepare.ts';
+
+/** A song, or a function that loads one (`() => import('./songs/title.ts')` works: a module's default export is used) */
+export type SongSource = Song | (() => Promise<Song | { default: Song }>);
+
+export interface JukeboxOptions {
+  /** Use this AudioContext (default: one is created on first use) */
+  context?: AudioContext;
+  /** Where the music goes (default: the speakers) */
+  destination?: AudioNode;
+  /** Songs that can be played by name */
+  songs?: Record<string, SongSource>;
+  /** 0-1 (default 1) */
+  volume?: number;
+}
+
+export interface PlayOptions {
+  /** Seconds to fade the previous song out (default 0.9) */
+  fadeOut?: number;
+  /** Seconds to fade this song in (default: 0.05 if it has an intro, otherwise 1.2) */
+  fadeIn?: number;
+  /** Start this many seconds into the song */
+  from?: number;
+  /** How many times the body plays before the song ends (default: forever, or once if `song.loop` is false) */
+  loops?: number;
+}
+
+export interface DuckOptions {
+  /** Seconds to reach the ducked level (default 0: instantly) */
+  attack?: number;
+  /** Seconds to stay there (default 0) */
+  hold?: number;
+  /** Seconds to come back (default 0.35) */
+  release?: number;
+}
+
+export type JukeboxState = 'idle' | 'loading' | 'playing' | 'paused';
+
+/** How far ahead notes are scheduled: a little while visible, much more in a background tab (whose timers are throttled to about once a second) */
+const AHEAD = 0.25;
+const AHEAD_HIDDEN = 1.6;
+
+export class Jukebox {
+  private ctx: AudioContext | null;
+  private readonly destination?: AudioNode;
+  private readonly songs: Record<string, SongSource>;
+  private readonly loaded = new Map<SongSource, Promise<Song>>();
+  /** The music buses, each a volume and a duck gain: [into the output stage, around it for songs mastered loud] */
+  private buses: { volume: GainNode; duck: GainNode }[] = [];
+  private volumeLevel: number;
+  private timer: ReturnType<typeof setInterval> | null = null;
+  /** Incremented whenever the current song changes: a song still loading only starts if nothing replaced it */
+  private token = 0;
+  /** The song asked for last (it may still be loading) */
+  private wanted: SongSource | null = null;
+  private pending: Promise<Playback | null> | null = null;
+  private song: Song | null = null;
+  /** The loop count the current song was asked to play with */
+  private loops: number | undefined;
+  private active: Playback | null = null;
+  private pausedAt: number | null = null;
+  /** Mute states to carry into the next playback of the same song (after a seek or a pause) */
+  private carry = new Set<string>();
+  /** Preloads queue up behind each other, so they never compete with each other for the main thread */
+  private preloads: Promise<unknown> = Promise.resolve();
+
+  constructor(options: JukeboxOptions = {}) {
+    this.ctx = options.context ?? null;
+    this.destination = options.destination;
+    this.songs = options.songs ?? {};
+    this.volumeLevel = options.volume ?? 1;
+  }
+
+  /** The audio context (created on first use; it starts on the first click, tap or key press if the browser requires one) */
+  get context(): AudioContext {
+    if (!this.ctx) this.ctx = new AudioContext();
+    if (!this.buses.length) this.connect(this.ctx);
+    return this.ctx;
+  }
+
+  /** The song playing, paused, or about to start (null when idle) */
+  get current(): Song | null {
+    return this.song;
+  }
+
+  /** The current playback, for positions, durations and per-track mixing (a new one starts after every seek or resume) */
+  get playback(): Playback | null {
+    return this.active;
+  }
+
+  get state(): JukeboxState {
+    if (this.pausedAt !== null) return 'paused';
+    if (this.pending) return 'loading';
+    return this.active?.playing ? 'playing' : 'idle';
+  }
+
+  /** Seconds into the current song */
+  get position(): number {
+    if (this.pausedAt !== null) return this.pausedAt;
+    return this.active ? this.active.position().seconds : 0;
+  }
+
+  get volume(): number {
+    return this.volumeLevel;
+  }
+
+  set volume(value: number) {
+    this.volumeLevel = Math.min(1, Math.max(0, value));
+    if (this.ctx) for (const { volume } of this.buses) volume.gain.setTargetAtTime(this.volumeLevel, this.ctx.currentTime, 0.02);
+  }
+
+  /**
+   * Play a song (by name, or a song / loader), crossfading from the one before.
+   * Asking for the song that is already playing does nothing; asking for a paused one resumes it.
+   * Resolves with the playback once it starts, or null if another song was asked for before this one was ready.
+   */
+  play(song: string | SongSource, options: PlayOptions = {}): Promise<Playback | null> {
+    const source = this.resolve(song);
+    if (source === this.wanted) {
+      if (this.pausedAt !== null) {
+        this.resume();
+        return Promise.resolve(this.active);
+      }
+      if (this.pending) return this.pending;
+      if (this.active?.playing) return Promise.resolve(this.active);
+    }
+    this.halt(options.fadeOut ?? 0.9);
+    this.carry = new Set();
+    this.wanted = source;
+    this.loops = options.loops;
+    this.pending = this.begin(source, this.token, options);
+    return this.pending;
+  }
+
+  /** Fade the music out and go silent */
+  stop(fade = 0.9): void {
+    this.halt(fade);
+    this.wanted = null;
+    this.song = null;
+    if (this.timer !== null) clearInterval(this.timer);
+    this.timer = null;
+  }
+
+  /** Pause the current song (resume() continues from the same point) */
+  pause(): void {
+    if (!this.active?.playing) return;
+    const at = this.active.position().seconds;
+    this.carry = mutedTracks(this.active);
+    this.halt(0.12);
+    this.pausedAt = at;
+  }
+
+  /** Continue a paused song */
+  resume(): void {
+    if (this.pausedAt === null || !this.song) return;
+    const from = this.pausedAt;
+    this.pausedAt = null;
+    this.start(this.song, { fadeIn: 0.05, from });
+  }
+
+  /** Jump to a point in the current song (seconds) */
+  seek(seconds: number): void {
+    if (this.pausedAt !== null) {
+      this.pausedAt = Math.max(0, seconds);
+      return;
+    }
+    if (!this.song || !this.active) return;
+    this.carry = mutedTracks(this.active);
+    this.active.stop(0.12);
+    this.start(this.song, { fadeIn: 0.08, from: seconds });
+  }
+
+  /** Render a song's samples ahead of time, so playing it later starts without a wait */
+  preload(song: string | SongSource): Promise<void> {
+    const source = this.resolve(song);
+    const ctx = this.context;
+    const job = this.preloads.then(() => this.load(source)).then((def) => prepareSong(ctx, def));
+    this.preloads = job.catch(() => undefined);
+    return job;
+  }
+
+  /** Play a short song once on top of whatever is playing (victory jingles, fanfares). Its samples are rendered on the spot. */
+  playOnce(song: Song): Playback {
+    const ctx = this.context;
+    prepareSongSync(ctx, song);
+    const active = new Playback(ctx, this.busFor(song), song, { at: ctx.currentTime + 0.03, loops: 1 });
+    active.schedule(active.startTime + active.duration);
+    return active;
+  }
+
+  /**
+   * Lower the music for a moment, for example under a big sound effect or a line of dialogue.
+   *
+   * @example
+   * jukebox.duck(-10);                                        // a hit: drop 10 dB, recover over 0.35 s
+   * jukebox.duck(-30, { attack: 0.12, hold: 4, release: 0.6 }); // near silence for a cutscene beat
+   */
+  duck(db: number, { attack = 0, hold = 0, release = 0.35 }: DuckOptions = {}): void {
+    if (!this.ctx) return;
+    const t = this.ctx.currentTime;
+    const level = Math.pow(10, db / 20);
+    for (const { duck } of this.buses) {
+      const g = duck.gain;
+      g.cancelScheduledValues(t);
+      g.setValueAtTime(attack > 0 ? g.value : level, t);
+      if (attack > 0) g.linearRampToValueAtTime(level, t + attack);
+      g.setValueAtTime(level, t + attack + hold);
+      g.linearRampToValueAtTime(1, t + attack + hold + release);
+    }
+  }
+
+  /** Bring ducked music back now */
+  unduck(release = 0.3): void {
+    if (!this.ctx) return;
+    const t = this.ctx.currentTime;
+    for (const { duck } of this.buses) {
+      const g = duck.gain;
+      g.cancelScheduledValues(t);
+      g.setValueAtTime(g.value, t);
+      g.linearRampToValueAtTime(1, t + release);
+    }
+  }
+
+  /** Resume the audio context; call from a click or key handler if you want sound to start on that exact gesture */
+  unlock(): Promise<void> {
+    return this.context.resume();
+  }
+
+  private async begin(source: SongSource, token: number, options: PlayOptions): Promise<Playback | null> {
+    try {
+      const ctx = this.context;
+      const song = await this.load(source);
+      if (token !== this.token) return null;
+      this.song = song;
+      await prepareSong(ctx, song);
+      if (token !== this.token) return null;
+      return this.start(song, { fadeIn: options.fadeIn ?? (song.intro?.length ? 0.05 : 1.2), from: options.from });
+    } finally {
+      if (token === this.token) this.pending = null;
+    }
+  }
+
+  private start(song: Song, options: { fadeIn: number; from?: number }): Playback {
+    const ctx = this.context;
+    const active = new Playback(ctx, this.busFor(song), song, { ...options, loops: this.loops, at: ctx.currentTime + 0.08 });
+    for (const t of active.tracks) if (this.carry.has(`${t.section}|${t.name}`)) t.muted = true;
+    this.carry = new Set();
+    this.active = active;
+    this.runClock();
+    return active;
+  }
+
+  /** Fade out what is playing and cancel anything still loading; the current song is remembered (for resume and seek) */
+  private halt(fade: number): void {
+    this.token++;
+    this.pending = null;
+    this.pausedAt = null;
+    this.active?.stop(fade);
+    this.active = null;
+  }
+
+  private resolve(song: string | SongSource): SongSource {
+    if (typeof song !== 'string') return song;
+    const source = this.songs[song];
+    if (!source) throw new Error(`Unknown song "${song}". Known: ${Object.keys(this.songs).join(', ') || '(none)'}`);
+    return source;
+  }
+
+  private load(source: SongSource): Promise<Song> {
+    if (typeof source !== 'function') return Promise.resolve(source);
+    let p = this.loaded.get(source);
+    if (!p) {
+      p = source().then((m) => ('default' in m ? m.default : m));
+      p.catch(() => this.loaded.delete(source));
+      this.loaded.set(source, p);
+    }
+    return p;
+  }
+
+  /** Where a song goes in: songs mastered loud have their own limiter, so they go around the output stage */
+  private busFor(song: Song): GainNode {
+    return this.buses[mastersItself(song) ? 1 : 0].volume;
+  }
+
+  /** Build the music buses (volume → duck → output stage, and volume → duck straight out) and arrange for the context to start on the first user gesture */
+  private connect(ctx: AudioContext): void {
+    const out = this.destination ?? ctx.destination;
+    this.buses = [createOutputStage(ctx, out), out].map((to) => {
+      const volume = ctx.createGain();
+      volume.gain.value = this.volumeLevel;
+      const duck = ctx.createGain();
+      volume.connect(duck).connect(to);
+      return { volume, duck };
+    });
+    if (ctx.state !== 'suspended' || typeof window === 'undefined') return;
+    const events = ['pointerdown', 'keydown', 'touchend'] as const;
+    const unlock = () => void ctx.resume();
+    for (const e of events) window.addEventListener(e, unlock, { capture: true });
+    ctx.addEventListener('statechange', () => {
+      if (ctx.state === 'running') for (const e of events) window.removeEventListener(e, unlock, { capture: true });
+    });
+  }
+
+  private runClock(): void {
+    if (this.timer !== null) return;
+    this.timer = setInterval(() => {
+      if (!this.active || !this.ctx) return;
+      const hidden = typeof document !== 'undefined' && document.hidden;
+      this.active.schedule(this.ctx.currentTime + (hidden ? AHEAD_HIDDEN : AHEAD));
+    }, 25);
+  }
+}
+
+function mutedTracks(active: Playback): Set<string> {
+  return new Set(active.tracks.filter((t) => t.muted).map((t) => `${t.section}|${t.name}`));
+}

package/src/engine/mixer.ts

@@ -0,0 +1,166 @@
+// Each song brings its own mixing console: per-track level, filters, ducking, pan and effect sends, a convolution reverb, a ping-pong delay
+// and the mastering (EQ, glue compression, and a limiter of its own for songs mastered loud).
+//
+//   track input ── filters ── duck ─┬─ pan ───────────────────────┐
+//                                   ├─ reverb send ── reverb ─────┤
+//                                   └─ delay send ─── delay ──────┼── master ── EQ ── glue ── (loud stage) ── gate ── output
+//                                                       └→ reverb │
+
+import { impulse, type Room } from '../instruments/dsp/reverb.ts';
+import { DEFAULT_REVERB, type Song, type Track } from '../song.ts';
+import { breakpoints, cutoffAt, type Pump } from './automation.ts';
+import { createLoudStage } from './output.ts';
+
+export interface Mixer {
+  /** The song's output (its fades are applied here) */
+  output: GainNode;
+  /** Closes for the song's silences: after the reverb and delay, so their tails stop dead too */
+  gate: GainNode;
+  /** One strip per track, per section: [intro tracks, body tracks] */
+  strips: [Strip[], Strip[]];
+}
+
+/** A track's channel on the console */
+export interface Strip {
+  /** Where its notes go: the track's level (and mute) */
+  input: GainNode;
+  /** After its filters and ducking, before pan and effects */
+  output: AudioNode;
+  /** Its duck gain, when it ducks under another track */
+  pump?: Pump;
+  /** Its filters' cutoffs that sweep, with their breakpoints */
+  sweeps: { cutoff: AudioParam; points: [number, number][] }[];
+}
+
+/** Q of the two stages of a 24 dB/octave filter, in dB as Web Audio reads it for low- and high-pass: Butterworth, with a touch of resonance */
+const FILTER_Q = [-5.3, 4];
+
+export function createMixer(ctx: BaseAudioContext, song: Song, destination: AudioNode): Mixer {
+  // The delay and the ducking keep time with the opening tempo
+  const stepSeconds = 60 / song.bpm / 4;
+  const output = ctx.createGain();
+  output.connect(destination);
+  const gate = ctx.createGain();
+  gate.connect(output);
+  const master = createMaster(ctx, song, gate);
+  const reverb = createReverb(ctx, song, master);
+  const delay = song.delay ? createDelay(ctx, song.delay, stepSeconds, master, reverb) : null;
+  const strip = (track: Track): Strip => {
+    const input = ctx.createGain();
+    input.gain.value = track.gain ?? 1;
+    let out: AudioNode = input;
+    const sweeps: Strip['sweeps'] = [];
+    for (const type of ['lowpass', 'highpass'] as const) {
+      const setting = track[type];
+      if (setting === undefined) continue;
+      const points = breakpoints(typeof setting === 'number' ? { 0: setting } : setting);
+      for (const q of FILTER_Q) {
+        const f = biquad(ctx, type, cutoffAt(points, 0), q);
+        out = out.connect(f);
+        if (points.length > 1) sweeps.push({ cutoff: f.frequency, points });
+      }
+    }
+    let pump: Pump | undefined;
+    if (track.duck) {
+      const duck = ctx.createGain();
+      out = out.connect(duck);
+      const { depth = 0.7, release = 4 } = typeof track.duck === 'string' ? {} : track.duck;
+      pump = { gain: duck.gain, depth, release: release * stepSeconds };
+    }
+    const pan = ctx.createStereoPanner();
+    pan.pan.value = track.pan ?? 0;
+    out.connect(pan).connect(master);
+    send(ctx, out, reverb, track.reverb ?? 0.25);
+    if (delay && track.delay) send(ctx, out, delay, track.delay);
+    return { input, output: out, pump, sweeps };
+  };
+  return { output, gate, strips: [(song.intro ?? []).map(strip), song.tracks.map(strip)] };
+}
+
+function send(ctx: BaseAudioContext, from: AudioNode, to: AudioNode, amount: number): void {
+  const g = ctx.createGain();
+  g.gain.value = amount;
+  from.connect(g).connect(to);
+}
+
+/** Master bus: overall level, then (each only when asked for) the mastering EQ, glue compression and the loud stage */
+function createMaster(ctx: BaseAudioContext, song: Song, output: AudioNode): GainNode {
+  const master = ctx.createGain();
+  const m = song.master ?? {};
+  master.gain.value = (song.gain ?? 1) * Math.pow(10, (m.trim ?? 0) / 20);
+  let out: AudioNode = master;
+  if (m.warm || m.cut) {
+    // Cut the rumble below 30 Hz first, so adding body does not eat the dynamics
+    const hp = biquad(ctx, 'highpass', 30, 0.6);
+    const warm = biquad(ctx, 'peaking', 150, 0.7, m.warm ?? 0);
+    const cut = biquad(ctx, 'peaking', 1300, 0.9, -(m.cut ?? 0));
+    out = out.connect(hp).connect(warm).connect(cut);
+  }
+  // Glue: the more of it, the lower the threshold and the higher the ratio; the slow attack lets the drums' hits through
+  if (m.glue) out = out.connect(new DynamicsCompressorNode(ctx, { threshold: -4 - 12 * m.glue, knee: 6, ratio: 2 + 2 * m.glue, attack: 0.02, release: 0.25 }));
+  out.connect(m.loud === undefined ? output : createLoudStage(ctx, m.loud, output));
+  return master;
+}
+
+function biquad(ctx: BaseAudioContext, type: BiquadFilterType, frequency: number, q: number, gain = 0): BiquadFilterNode {
+  const f = ctx.createBiquadFilter();
+  f.type = type;
+  f.frequency.value = frequency;
+  f.Q.value = q;
+  f.gain.value = gain;
+  return f;
+}
+
+/** Convolution reverb with the song's room; returns its input */
+function createReverb(ctx: BaseAudioContext, song: Song, master: AudioNode): ConvolverNode {
+  const room = song.reverb ?? DEFAULT_REVERB;
+  const rev = ctx.createConvolver();
+  rev.normalize = false;
+  rev.buffer = impulseBuffer(ctx, room);
+  const ret = ctx.createGain();
+  ret.gain.value = room.mix ?? 1;
+  rev.connect(ret).connect(master);
+  return rev;
+}
+
+/** Tempo-synced ping-pong delay (left, then right); its echoes also feed a little into the reverb. Returns its input */
+function createDelay(ctx: BaseAudioContext, d: NonNullable<Song['delay']>, stepSeconds: number, master: AudioNode, reverb: AudioNode): GainNode {
+  const time = Math.min(1.9, d.steps * stepSeconds);
+  const input = ctx.createGain();
+  const left = ctx.createDelay(2);
+  const right = ctx.createDelay(2);
+  left.delayTime.value = time;
+  right.delayTime.value = time;
+  const tone = biquad(ctx, 'lowpass', d.tone ?? 2800, 1);
+  const feedback = ctx.createGain();
+  feedback.gain.value = d.feedback ?? 0.35;
+  const ret = ctx.createGain();
+  ret.gain.value = d.mix ?? 0.8;
+  const panL = ctx.createStereoPanner();
+  const panR = ctx.createStereoPanner();
+  panL.pan.value = -0.7;
+  panR.pan.value = 0.7;
+  input.connect(tone).connect(left);
+  left.connect(panL).connect(ret);
+  left.connect(right);
+  right.connect(panR).connect(ret);
+  right.connect(feedback).connect(left);
+  ret.connect(master);
+  send(ctx, ret, reverb, 0.3);
+  return input;
+}
+
+const irCache = new Map<string, AudioBuffer>();
+/** Impulse response of a room (each room is computed once per sample rate) */
+export function impulseBuffer(ctx: BaseAudioContext, room: Room): AudioBuffer {
+  const key = `${ctx.sampleRate}|${room.size}|${room.damp}|${room.preDelay}|${room.early}|${room.bloom}`;
+  let b = irCache.get(key);
+  if (!b) {
+    const [l, r] = impulse(ctx.sampleRate, room);
+    b = ctx.createBuffer(2, l.length, ctx.sampleRate);
+    b.getChannelData(0).set(l);
+    b.getChannelData(1).set(r);
+    irCache.set(key, b);
+  }
+  return b;
+}