@hraness/dawg 0.2.0 → 0.4.0

package/src/audio/wav.ts

@@ -1,12 +1,60 @@
 import {
   SCORE_LIMITS,
+  isSamplerInstrument,
   isTrackAudible,
+  isWavetableInstrument,
+  wavetableOf,
   type AutomationPoint,
   type Note,
   type Track,
   type TrackScore,
 } from "../../core/score.ts";
 import { drumVoiceForPitch, isDrumInstrument } from "../../core/drums.ts";
+import {
+  planSamplerVoices,
+  renderSamplerVoices,
+  samplerTailSeconds,
+} from "./sampler.ts";
+import { EFFECT_NAMES, FX_PRESETS, effectSpec } from "../../core/fx.ts";
+import { seededRandom } from "./random.ts";
+import {
+  isStereoVoice,
+  renderSynthNote,
+  synthTailSeconds,
+  usesSynthVoice,
+  type VoiceContext,
+} from "./synth/voice.ts";
+import { legacyWave } from "./synth/oscillators.ts";
+import {
+  EMPTY_SAMPLE_BANK,
+  sampleKey,
+  type DecodedSample,
+  type SampleBank,
+} from "./samples.ts";
+import { synthKit } from "../../core/kits.ts";
+import { kitDrumSample, kitTailSeconds, newKitVoiceState } from "./kits.ts";
+import {
+  applyMonoChain,
+  applyStereoChain,
+  delayTailFor,
+  interpolateAutomation,
+  reverbImpulse,
+  reverbTailFor,
+} from "./effects/chain.ts";
+import {
+  createOrbitBus,
+  renderOrbitBus,
+  sendToBus,
+  sharedOrbitOf,
+  type OrbitBus,
+} from "./effects/bus.ts";
+import { tableFor, wavetableOscillator } from "./wavetable.ts";
+import {
+  duckGains,
+  duckSettings,
+  orbitOf,
+  type Ducker,
+} from "./effects/duck.ts";
 
 export type WavOptions = Readonly<{ sampleRate?: number; maxSeconds?: number }>;
 
@@ -18,6 +66,11 @@ export type RenderOptions = WavOptions &
      * what the streaming engine plays; exports keep the default one-shot.
      */
     loop?: boolean;
+    /**
+     * Decoded sampler voices (`SampleLibrary.load`). Without it sampler
+     * tracks render silent; scores without samplers are unaffected.
+     */
+    samples?: SampleBank;
   }>;
 
 /** Interleaved stereo 16-bit PCM plus its frame count. */
@@ -41,16 +94,46 @@ export const AVAILABLE_INSTRUMENTS = Object.freeze([
   "saw",
   "square",
   "triangle",
+  "wavetable",
   "kit",
+  // Synth-voice sounds (core/synth.ts), Strudel names; `synth` shapes them.
+  "sawtooth",
+  "supersaw",
+  "pulse",
+  "user",
+  "white",
+  "pink",
+  "brown",
+  "crackle",
+  // ZzFX sounds (src/audio/synth/zzfx.ts).
+  "z_sine",
+  "z_triangle",
+  "z_sawtooth",
+  "z_square",
+  "z_tan",
+  "z_noise",
 ] as const);
 
-/** Per-track effects understood by the renderer and the agent. */
-export const AVAILABLE_EFFECTS = Object.freeze([
-  "pan (equal-power stereo: -1 left .. 1 right, automatable)",
-  "filter (low-pass: cutoff 20..20000 Hz and resonance 0..1, both automatable)",
-  "delay (stereo send: beats 0.0625..4, feedback 0..0.9 and mix 0..1 automatable)",
-  "reverb (stereo send: mix 0..1, size 0..1)",
-] as const);
+/** Per-track effects understood by the renderer and the agent, in chain
+ * order, with each effect's simple parameters (`fx` takes the rest). */
+export const AVAILABLE_EFFECTS: readonly string[] = Object.freeze([
+  "pan(-1..1 equal-power)",
+  ...EFFECT_NAMES.map((name) => {
+    const spec = effectSpec(name);
+    return `${name}(${spec.simple.join(" ")})`;
+  }),
+]);
+
+/** `fx <effect> preset <name>` names, for the agent brief. */
+export const AVAILABLE_FX_PRESETS: Readonly<Record<string, string>> =
+  Object.freeze(
+    Object.fromEntries(
+      EFFECT_NAMES.filter((name) => FX_PRESETS[name]).map((name) => [
+        name,
+        Object.keys(FX_PRESETS[name]!).join(" "),
+      ]),
+    ),
+  );
 
 /** Longest drum one-shot, in seconds; hits ring past their note length. */
 const MAX_DRUM_SECONDS = 0.6;
@@ -66,6 +149,8 @@ type RenderContext = Readonly<{
   sampleRate: number;
   samples: number;
   samplesPerTick: number;
+  tempoBpm: number;
+  irs?: ReadonlyMap<string, DecodedSample>;
 }>;
 
 /** Exact (fractional) loop length in frames at a sample rate. */
@@ -83,7 +168,7 @@ export function clampSampleRate(sampleRate?: number): number {
 /** Render the bounded score to a stereo 16-bit PCM WAV. */
 export function renderScoreWav(
   score: TrackScore,
-  options: WavOptions = {},
+  options: WavOptions & Pick<RenderOptions, "samples"> = {},
 ): Uint8Array {
   const audio = renderScorePcm(score, options);
   return encodeWav(audio.pcm, audio.sampleRate, RENDER_CHANNELS);
@@ -98,113 +183,424 @@ export function renderScorePcm(
   score: TrackScore,
   options: RenderOptions = {},
 ): RenderedAudio {
-  const sampleRate = clampSampleRate(options.sampleRate);
-  const maxSeconds = Math.max(1, Math.min(60, options.maxSeconds ?? 30));
-  const loopSeconds = (score.bars * score.beatsPerBar * 60) / score.tempoBpm;
-  const reverbTail = Math.max(
-    0,
-    ...score.tracks.map((track) =>
-      track.reverb && track.reverb.mix > 0 ? 1 + 3 * track.reverb.size : 0,
-    ),
-  );
-  let frames: number;
-  let samples: number;
-  if (options.loop) {
-    frames = Math.max(
-      1,
-      Math.min(
-        Math.round(loopFrames(score, sampleRate)),
-        Math.ceil(maxSeconds * sampleRate),
+  return new StemRenderer({ maxCacheBytes: 0 }).render(score, options);
+}
+
+/** Default byte budget for cached per-track stems. */
+export const DEFAULT_STEM_CACHE_BYTES = 256 * 1024 * 1024;
+
+type Stem = {
+  key: string;
+  left: Float64Array;
+  right: Float64Array;
+  bytes: number;
+  used: number;
+};
+
+/**
+ * The renderer behind `renderScorePcm`, with a per-track stem cache. Each
+ * track's stereo stem (after its own effects) is keyed by everything that
+ * shapes it: the track settings, its notes, tempo, tick resolution, sample
+ * rate and buffer length. Edits re-render only the tracks whose key changed
+ * and sum the cached rest in the original order, so the result is
+ * byte-identical to a cold render; mute and solo only pick which stems are
+ * summed. Scratch buffers are reused across renders.
+ */
+export class StemRenderer {
+  private readonly maxCacheBytes: number;
+  private readonly stems = new Map<string, Stem>();
+  /** Shared orbit bus outputs by orbit, keyed by their members' stems. */
+  private readonly buses = new Map<
+    number,
+    { key: string; left: Float64Array; right: Float64Array }
+  >();
+  private cacheBytes = 0;
+  private renders = 0;
+  private scratch: {
+    dry: Float64Array;
+    dryR: Float64Array;
+    left: Float64Array;
+    right: Float64Array;
+    mixL: Float64Array;
+    mixR: Float64Array;
+  } = {
+    dry: new Float64Array(0),
+    dryR: new Float64Array(0),
+    left: new Float64Array(0),
+    right: new Float64Array(0),
+    mixL: new Float64Array(0),
+    mixR: new Float64Array(0),
+  };
+
+  public constructor(options: Readonly<{ maxCacheBytes?: number }> = {}) {
+    this.maxCacheBytes = Math.max(
+      0,
+      options.maxCacheBytes ?? DEFAULT_STEM_CACHE_BYTES,
+    );
+  }
+
+  /** Cached stems and their total size, for tests and diagnostics. */
+  public get cache(): Readonly<{ stems: number; bytes: number }> {
+    return { stems: this.stems.size, bytes: this.cacheBytes };
+  }
+
+  public render(score: TrackScore, options: RenderOptions = {}): RenderedAudio {
+    const sampleRate = clampSampleRate(options.sampleRate);
+    const maxSeconds = Math.max(1, Math.min(60, options.maxSeconds ?? 30));
+    const loopSeconds = (score.bars * score.beatsPerBar * 60) / score.tempoBpm;
+    const bank = options.samples ?? EMPTY_SAMPLE_BANK;
+    const reverbTail = Math.max(
+      0,
+      ...score.tracks.map((track) =>
+        reverbTailFor(track, sampleRate, bank.irs),
       ),
     );
-    const tailSeconds = Math.min(
+    // Zero without sampler voices, so synth-only renders are unchanged.
+    // Zero without synth-voice tracks, so legacy renders are unchanged.
+    const samplerTail = Math.min(
       MAX_LOOP_TAIL_SECONDS,
-      MAX_DRUM_SECONDS + 0.1 + reverbTail + delayTailSeconds(score),
+      Math.max(
+        samplerTailSeconds(score, bank, sampleRate),
+        ...score.tracks.map(synthTailSeconds),
+      ),
     );
-    samples = frames + Math.ceil(tailSeconds * sampleRate);
-  } else {
-    const seconds = Math.min(
-      maxSeconds,
-      loopSeconds + ONE_SHOT_TAIL_SECONDS + reverbTail,
+    let frames: number;
+    let samples: number;
+    if (options.loop) {
+      frames = Math.max(
+        1,
+        Math.min(
+          Math.round(loopFrames(score, sampleRate)),
+          Math.ceil(maxSeconds * sampleRate),
+        ),
+      );
+      const tailSeconds = Math.min(
+        MAX_LOOP_TAIL_SECONDS,
+        Math.max(MAX_DRUM_SECONDS, samplerTail, kitTailSeconds(score)) +
+          0.1 +
+          reverbTail +
+          Math.max(
+            0,
+            ...score.tracks.map((track) => delayTailFor(track, score.tempoBpm)),
+          ),
+      );
+      samples = frames + Math.ceil(tailSeconds * sampleRate);
+    } else {
+      const seconds = Math.min(
+        maxSeconds,
+        loopSeconds + Math.max(ONE_SHOT_TAIL_SECONDS, samplerTail) + reverbTail,
+      );
+      frames = Math.max(1, Math.ceil(seconds * sampleRate));
+      samples = frames;
+    }
+    const context: RenderContext = {
+      score,
+      sampleRate,
+      samples,
+      samplesPerTick: (sampleRate * 60) / (score.tempoBpm * score.ticksPerBeat),
+      tempoBpm: score.tempoBpm,
+      ...(bank.irs ? { irs: bank.irs } : {}),
+    };
+    this.renders += 1;
+    const { dry, dryR, left, right, mixL, mixR } = this.scratchFor(samples);
+    mixL.fill(0);
+    mixR.fill(0);
+    const tracks = new Map(score.tracks.map((track) => [track.id, track]));
+    const groups = new Map<string, Note[]>();
+    for (const note of score.notes) {
+      const group = groups.get(note.trackId);
+      if (group) group.push(note);
+      else groups.set(note.trackId, [note]);
+    }
+    // Orbit ducking is a gain on finished stems (src/audio/effects/duck.ts).
+    const duckers: Ducker[] = [];
+    for (const [trackId, notes] of groups) {
+      const settings = duckSettings(tracks.get(trackId));
+      if (settings && isTrackAudible(score, trackId))
+        duckers.push({
+          trackId,
+          ...settings,
+          onsets: notes.map((note) => noteSpan(note, context).start),
+        });
+    }
+    const ducked = duckGains(
+      [...groups.keys()].map((id) => ({ id, orbit: orbitOf(tracks.get(id)) })),
+      duckers,
+      samples,
+      sampleRate,
+      options.loop ? frames : undefined,
     );
-    frames = Math.max(1, Math.ceil(seconds * sampleRate));
-    samples = frames;
-  }
-  const context: RenderContext = {
-    score,
-    sampleRate,
-    samples,
-    samplesPerTick: (sampleRate * 60) / (score.tempoBpm * score.ticksPerBeat),
-  };
-  // Tracks render one at a time into reused scratch buffers so per-track
-  // effects stay bounded in memory regardless of the track count.
-  const mixL = new Float64Array(samples);
-  const mixR = new Float64Array(samples);
-  const dry = new Float64Array(samples);
-  const left = new Float64Array(samples);
-  const right = new Float64Array(samples);
-  const tracks = new Map(score.tracks.map((track) => [track.id, track]));
-  const groups = new Map<string, Note[]>();
-  for (const note of score.notes) {
-    const group = groups.get(note.trackId);
-    if (group) group.push(note);
-    else groups.set(note.trackId, [note]);
-  }
-  for (const [trackId, notes] of groups) {
-    if (!isTrackAudible(score, trackId)) continue;
-    const track = tracks.get(trackId);
-    dry.fill(0);
-    const drums = isDrumInstrument(track?.instrument);
-    for (const note of notes) {
-      if (drums) renderDrumNote(dry, note, track, context);
-      else renderToneNote(dry, note, track, context);
+    // Shared orbit buses (src/audio/effects/bus.ts), created on first send.
+    const buses = new Map<number, OrbitBus>();
+    // Tracks render one at a time; the sum order (first note per track) is
+    // part of the output, so cached and cold renders keep it.
+    for (const [trackId, notes] of groups) {
+      if (!isTrackAudible(score, trackId)) continue;
+      const track = tracks.get(trackId);
+      const busOrbit = sharedOrbitOf(track);
+      const sampler = isSamplerInstrument(track?.instrument);
+      // Wavetable hook: the oscillator factory for a wavetable track (its
+      // table id joins the stem key), undefined for every other instrument.
+      const wavetable = track ? wavetableHook(track, bank, context) : undefined;
+      const key = stemKey(
+        track,
+        notes,
+        context,
+        sampler ? bank : undefined,
+        wavetable?.id,
+        track ? reverbImpulse(track, sampleRate, bank.irs)?.id : undefined,
+      );
+      let stem = this.stems.get(trackId);
+      if (stem?.key === key) stem.used = this.renders;
+      else {
+        const caching = this.maxCacheBytes > 0;
+        const target = caching
+          ? {
+              left: new Float64Array(samples),
+              right: new Float64Array(samples),
+            }
+          : { left, right };
+        dry.fill(0);
+        const synthVoice = !sampler && usesSynthVoice(track);
+        const stereo = synthVoice && isStereoVoice(track);
+        if (stereo) dryR.fill(0);
+        if (sampler) {
+          if (track) renderSamplerNotes(dry, notes, track, context, bank);
+        } else if (synthVoice && track) {
+          const gainAt = (tick: number) => trackGainAt(track, tick);
+          const voice = {
+            ...context,
+            ticksPerBeat: score.ticksPerBeat,
+            ...(wavetable ? { oscillatorFor: wavetable.oscillatorFor } : {}),
+          };
+          for (const note of notes) {
+            const { start, length } = noteSpan(note, context);
+            renderSynthNote(
+              dry,
+              stereo ? dryR : undefined,
+              note,
+              track,
+              start,
+              length,
+              voice,
+              gainAt,
+            );
+          }
+        } else {
+          const drums = isDrumInstrument(track?.instrument);
+          for (const note of notes) {
+            if (drums) renderDrumNote(dry, note, track, context);
+            else renderToneNote(dry, note, track, context);
+          }
+        }
+        if (track) applyMonoChain(dry, track, context);
+        if (stereo && track) applyMonoChain(dryR, track, context);
+        applyPan(
+          dry,
+          target.left,
+          target.right,
+          track,
+          context,
+          stereo ? dryR : undefined,
+        );
+        if (track)
+          applyStereoChain(
+            target.left,
+            target.right,
+            track,
+            context,
+            busOrbit === undefined,
+          );
+        stem = {
+          key,
+          left: target.left,
+          right: target.right,
+          bytes: target.left.byteLength + target.right.byteLength,
+          used: this.renders,
+        };
+        if (caching) this.store(trackId, stem);
+      }
+      if (track && busOrbit !== undefined) {
+        let bus = buses.get(busOrbit);
+        if (!bus)
+          buses.set(busOrbit, (bus = createOrbitBus(busOrbit, samples)));
+        sendToBus(bus, track, stem.left, stem.right, context, key);
+      }
+      const gain = ducked.get(trackId);
+      if (gain)
+        for (let index = 0; index < samples; index += 1) {
+          mixL[index]! += stem.left[index]! * gain[index]!;
+          mixR[index]! += stem.right[index]! * gain[index]!;
+        }
+      else
+        for (let index = 0; index < samples; index += 1) {
+          mixL[index]! += stem.left[index]!;
+          mixR[index]! += stem.right[index]!;
+        }
+    }
+    // Bus returns join after every stem, in orbit order; the orbit's ducking
+    // applies to them as to its tracks.
+    const busGains = duckGains(
+      [...buses.keys()].map((orbit) => ({ id: `bus:${orbit}`, orbit })),
+      duckers,
+      samples,
+      sampleRate,
+      options.loop ? frames : undefined,
+    );
+    for (const orbit of [...buses.keys()].sort((a, b) => a - b)) {
+      const bus = buses.get(orbit)!;
+      const key = JSON.stringify(bus.keys);
+      let wet = this.buses.get(orbit);
+      if (wet?.key !== key) {
+        wet = { key, ...renderOrbitBus(bus, context) };
+        if (this.maxCacheBytes > 0) this.buses.set(orbit, wet);
+      }
+      const gain = busGains.get(`bus:${orbit}`);
+      for (let index = 0; index < samples; index += 1) {
+        const g = gain ? gain[index]! : 1;
+        mixL[index]! += wet.left[index]! * g;
+        mixR[index]! += wet.right[index]! * g;
+      }
     }
-    if (track) applyLowPass(dry, track, context);
-    applyPan(dry, left, right, track, context);
-    if (track) {
-      applyDelay(left, right, track, context);
-      applyReverb(left, right, track, context);
+    for (const orbit of [...this.buses.keys()])
+      if (!buses.has(orbit)) this.buses.delete(orbit);
+    // Stems of tracks that left the score are not worth keeping; muted and
+    // unsoloed tracks keep theirs so toggling them back is free.
+    for (const trackId of [...this.stems.keys()])
+      if (!groups.has(trackId)) this.evict(trackId);
+    if (samples > frames) {
+      // Linear effects superpose, so folding the tail onto the start yields
+      // the steady state of the loop playing forever.
+      for (let index = frames; index < samples; index += 1) {
+        mixL[index % frames]! += mixL[index]!;
+        mixR[index % frames]! += mixR[index]!;
+      }
     }
-    for (let index = 0; index < samples; index += 1) {
-      mixL[index]! += left[index]!;
-      mixR[index]! += right[index]!;
+    const pcm = new Int16Array(frames * RENDER_CHANNELS);
+    for (let index = 0; index < frames; index += 1) {
+      pcm[index * 2] = clamp16(mixL[index]! * 32767);
+      pcm[index * 2 + 1] = clamp16(mixR[index]! * 32767);
     }
+    return Object.freeze({
+      sampleRate,
+      channels: RENDER_CHANNELS,
+      frames,
+      pcm,
+    });
   }
-  if (samples > frames) {
-    // Linear effects superpose, so folding the tail onto the start yields
-    // the steady state of the loop playing forever.
-    for (let index = frames; index < samples; index += 1) {
-      mixL[index % frames]! += mixL[index]!;
-      mixR[index % frames]! += mixR[index]!;
+
+  private scratchFor(samples: number) {
+    if (this.scratch.dry.length < samples) {
+      this.scratch = {
+        dry: new Float64Array(samples),
+        dryR: new Float64Array(samples),
+        left: new Float64Array(samples),
+        right: new Float64Array(samples),
+        mixL: new Float64Array(samples),
+        mixR: new Float64Array(samples),
+      };
     }
+    const view = (buffer: Float64Array) => buffer.subarray(0, samples);
+    return {
+      dry: view(this.scratch.dry),
+      dryR: view(this.scratch.dryR),
+      left: view(this.scratch.left),
+      right: view(this.scratch.right),
+      mixL: view(this.scratch.mixL),
+      mixR: view(this.scratch.mixR),
+    };
   }
-  const pcm = new Int16Array(frames * RENDER_CHANNELS);
-  for (let index = 0; index < frames; index += 1) {
-    pcm[index * 2] = clamp16(mixL[index]! * 32767);
-    pcm[index * 2 + 1] = clamp16(mixR[index]! * 32767);
+
+  private store(trackId: string, stem: Stem): void {
+    this.evict(trackId);
+    // Make room by dropping the least recently used stems from other
+    // renders; a score whose stems exceed the budget is simply not cached.
+    while (
+      this.cacheBytes + stem.bytes > this.maxCacheBytes &&
+      this.stems.size > 0
+    ) {
+      let oldest: string | undefined;
+      for (const [id, candidate] of this.stems)
+        if (
+          candidate.used !== this.renders &&
+          (oldest === undefined ||
+            candidate.used < this.stems.get(oldest)!.used)
+        )
+          oldest = id;
+      if (oldest === undefined) break;
+      this.evict(oldest);
+    }
+    if (this.cacheBytes + stem.bytes > this.maxCacheBytes) return;
+    this.stems.set(trackId, stem);
+    this.cacheBytes += stem.bytes;
+  }
+
+  private evict(trackId: string): void {
+    const stem = this.stems.get(trackId);
+    if (!stem) return;
+    this.stems.delete(trackId);
+    this.cacheBytes -= stem.bytes;
   }
-  return Object.freeze({ sampleRate, channels: RENDER_CHANNELS, frames, pcm });
 }
 
-/** Seconds until the slowest delay decays below -60 dB, bounded. */
-function delayTailSeconds(score: TrackScore): number {
-  let longest = 0;
-  for (const track of score.tracks) {
-    if (!track.delay) continue;
-    const feedback = Math.max(
-      track.delay.feedback,
-      ...(track.delayFeedbackAutomation ?? []).map((point) => point.value),
-    );
-    const repeats =
-      feedback <= 0.001
-        ? 1
-        : Math.min(64, Math.log(0.001) / Math.log(feedback));
-    longest = Math.max(
-      longest,
-      ((track.delay.beats * 60) / score.tempoBpm) * (repeats + 1),
-    );
+/** Everything a track's stem depends on, except mute and solo. */
+function stemKey(
+  track: Track | undefined,
+  notes: readonly Note[],
+  context: RenderContext,
+  bank?: SampleBank,
+  wavetableId?: string,
+  impulseId?: string,
+): string {
+  let settings: Record<string, unknown> | null = null;
+  if (track) {
+    const { muted: _muted, solo: _solo, ...rest } = track;
+    settings = rest;
   }
-  return longest;
+  return JSON.stringify([
+    settings,
+    notes,
+    context.score.tempoBpm,
+    context.score.ticksPerBeat,
+    // Bar length: sampler `unit: "c"` stretches a window to whole bars.
+    context.score.beatsPerBar,
+    context.sampleRate,
+    context.samples,
+    // Sampler stems also depend on the decoded files: a replaced or missing
+    // sample changes the key even when the score did not change.
+    ...(bank && track?.sampler ? [samplerVoiceDigest(track, bank)] : []),
+    ...(wavetableId ? [wavetableId] : []),
+    // A convolution reverb's impulse (its sha256 for a sample).
+    ...(impulseId ? [impulseId] : []),
+  ]);
+}
+
+function samplerVoiceDigest(track: Track, bank: SampleBank): string[] {
+  return Object.keys(track.sampler?.voices ?? {})
+    .sort()
+    .map((voice) => {
+      const sample = bank.voices.get(sampleKey(track.id, voice));
+      return sample
+        ? `${voice}:${sample.sha256}:${sample.sampleRate}:${sample.frames}`
+        : `${voice}:-`;
+    });
+}
+
+/** Sample voices of a sampler track into its mono dry buffer. */
+function renderSamplerNotes(
+  target: Float64Array,
+  notes: readonly Note[],
+  track: Track,
+  context: RenderContext,
+  bank: SampleBank,
+): void {
+  const timing = { score: context.score, sampleRate: context.sampleRate };
+  renderSamplerVoices(
+    target,
+    planSamplerVoices(track, notes, bank, timing),
+    timing,
+    (tick) => trackGainAt(track, tick),
+  );
 }
 
 /** Track volume and volume automation at a score tick (pan is applied in stereo). */
@@ -263,8 +659,7 @@ function renderToneNote(
       0.28 *
       trackGainAt(track, note.startTick + elapsed / samplesPerTick);
     const phase = (frequency * elapsed) / sampleRate;
-    target[index]! +=
-      synthSample(instrument, phase, frequency, sampleRate) * envelope;
+    target[index]! += legacyWave(instrument, phase) * envelope;
   }
 }
 
@@ -281,9 +676,13 @@ function renderDrumNote(
 ): void {
   const { sampleRate, samples, samplesPerTick } = context;
   const { start } = noteSpan(note, context);
+  // A track `kit` swaps in a synthesized kit (src/audio/kits.ts); without
+  // one the voices below render exactly as they always have.
+  const kit = synthKit(track?.kit);
+  const kitState = kit ? newKitVoiceState() : undefined;
   const end = Math.min(
     samples,
-    start + Math.ceil(MAX_DRUM_SECONDS * sampleRate),
+    start + Math.ceil((kit?.seconds ?? MAX_DRUM_SECONDS) * sampleRate),
   );
   const voice = drumVoiceForPitch(note.pitch);
   const random = seededRandom(`${note.id}:${note.startTick}`);
@@ -298,7 +697,17 @@ function renderDrumNote(
     const bright = noise - previousNoise;
     previousNoise = noise;
     let sample = 0;
-    if (voice === "kick") {
+    if (kit && kitState)
+      sample = kitDrumSample(
+        kit,
+        voice,
+        t,
+        noise,
+        bright,
+        kitState,
+        sampleRate,
+      );
+    else if (voice === "kick") {
       const frequency = 45 + 105 * Math.exp(-t * 28);
       phase += frequency / sampleRate;
       sample =
@@ -346,64 +755,6 @@ function renderDrumNote(
   }
 }
 
-/**
- * RBJ biquad low-pass with static or automated cutoff and resonance.
- * Resonance 0..1 maps to Q 0.707..8 and the cutoff is kept under 45% of the
- * sample rate, so the filter is stable for every value the score accepts.
- */
-function applyLowPass(
-  buffer: Float64Array,
-  track: Track,
-  context: RenderContext,
-): void {
-  const automation = track.filterAutomation ?? [];
-  const resonanceLane = track.resonanceAutomation ?? [];
-  if (!track.filter && automation.length === 0 && resonanceLane.length === 0)
-    return;
-  const { sampleRate, samplesPerTick } = context;
-  const staticCutoff = track.filter?.cutoff ?? SCORE_LIMITS.maxFilterCutoff;
-  const staticResonance = track.filter?.resonance ?? 0;
-  const automated = automation.length > 0 || resonanceLane.length > 0;
-  let b0 = 0;
-  let b1 = 0;
-  let b2 = 0;
-  let a1 = 0;
-  let a2 = 0;
-  let z1 = 0;
-  let z2 = 0;
-  const update = (cutoff: number, resonance: number) => {
-    const q = 0.707 + Math.max(0, Math.min(1, resonance)) * 7.293;
-    const frequency = Math.max(
-      SCORE_LIMITS.minFilterCutoff,
-      Math.min(cutoff, sampleRate * 0.45),
-    );
-    const omega = (2 * Math.PI * frequency) / sampleRate;
-    const alpha = Math.sin(omega) / (2 * q);
-    const cos = Math.cos(omega);
-    const a0 = 1 + alpha;
-    b0 = (1 - cos) / 2 / a0;
-    b1 = (1 - cos) / a0;
-    b2 = b0;
-    a1 = (-2 * cos) / a0;
-    a2 = (1 - alpha) / a0;
-  };
-  update(staticCutoff, staticResonance);
-  for (let index = 0; index < buffer.length; index += 1) {
-    if (automated && index % CONTROL_SAMPLES === 0) {
-      const tick = index / samplesPerTick;
-      update(
-        interpolateAutomation(automation, tick, staticCutoff),
-        interpolateAutomation(resonanceLane, tick, staticResonance),
-      );
-    }
-    const input = buffer[index]!;
-    const output = b0 * input + z1;
-    z1 = b1 * input - a1 * output + z2;
-    z2 = b2 * input - a2 * output;
-    buffer[index] = output;
-  }
-}
-
 /**
  * Equal-power pan of the mono track into the stereo pair: left = cos(θ),
  * right = sin(θ) with θ = (pan + 1)·π/4, so the summed power is constant
@@ -415,6 +766,7 @@ function applyPan(
   right: Float64Array,
   track: Track | undefined,
   context: RenderContext,
+  dryRight?: Float64Array,
 ): void {
   const lane = track?.panAutomation ?? [];
   const staticPan = track?.pan ?? 0;
@@ -430,187 +782,51 @@ function applyPan(
       );
     const sample = dry[index]!;
     left[index] = sample * gainL;
-    right[index] = sample * gainR;
-  }
-}
-
-/**
- * Tempo-synced stereo feedback delay. Each side echoes its own input and
- * feeds back into the opposite side, so repeats ping-pong across the field.
- * Feedback and mix follow their automation lanes when present.
- */
-function applyDelay(
-  left: Float64Array,
-  right: Float64Array,
-  track: Track,
-  context: RenderContext,
-): void {
-  const delay = track.delay;
-  if (!delay) return;
-  const feedbackLane = track.delayFeedbackAutomation ?? [];
-  const mixLane = track.delayMixAutomation ?? [];
-  if (delay.mix <= 0 && mixLane.length === 0) return;
-  const { score, sampleRate, samplesPerTick } = context;
-  const length = Math.max(
-    1,
-    Math.round(((delay.beats * 60) / score.tempoBpm) * sampleRate),
-  );
-  const lineL = new Float64Array(length);
-  const lineR = new Float64Array(length);
-  let feedback = delay.feedback;
-  let mix = delay.mix;
-  const automated = feedbackLane.length > 0 || mixLane.length > 0;
-  for (let index = 0; index < left.length; index += 1) {
-    if (automated && index % CONTROL_SAMPLES === 0) {
-      const tick = index / samplesPerTick;
-      feedback = interpolateAutomation(feedbackLane, tick, delay.feedback);
-      mix = interpolateAutomation(mixLane, tick, delay.mix);
-    }
-    const slot = index % length;
-    const wetL = lineL[slot]!;
-    const wetR = lineR[slot]!;
-    const dryL = left[index]!;
-    const dryR = right[index]!;
-    lineL[slot] = dryL + wetR * feedback;
-    lineR[slot] = dryR + wetL * feedback;
-    left[index] = dryL + wetL * mix;
-    right[index] = dryR + wetR * mix;
+    // A stereo voice pans its own right channel the same way.
+    right[index] = (dryRight ? dryRight[index]! : sample) * gainR;
   }
 }
 
-/** Freeverb comb and allpass tunings at 44.1 kHz; the right side is spread. */
-const COMB_TUNING = [1116, 1188, 1277, 1356, 1422, 1491, 1557, 1617] as const;
-const ALLPASS_TUNING = [556, 441, 341, 225] as const;
-const STEREO_SPREAD = 23;
-const REVERB_INPUT_GAIN = 0.015;
-const REVERB_WET_SCALE = 3;
+type WavetableHook = Readonly<{
+  /** Joins the stem key: a different or missing table re-renders. */
+  id: string;
+  oscillatorFor: NonNullable<VoiceContext["oscillatorFor"]>;
+}>;
 
 /**
- * Schroeder/Freeverb-style stereo reverb send: eight damped feedback combs
- * in parallel, then four series allpasses, per channel. Size sets the comb
- * feedback (0.7..0.98) and darkens the tail; the wet signal is added to the
- * dry stereo pair at `mix`.
+ * Wavetable hook: for a wavetable track, each note's oscillator reads the
+ * track's table (`src/audio/wavetable.ts`); the synth voice does the rest.
  */
-function applyReverb(
-  left: Float64Array,
-  right: Float64Array,
+function wavetableHook(
   track: Track,
+  bank: SampleBank,
   context: RenderContext,
-): void {
-  const reverb = track.reverb;
-  if (!reverb || reverb.mix <= 0) return;
-  const scale = context.sampleRate / 44_100;
-  const feedback = 0.7 + 0.28 * reverb.size;
-  const damp = 0.2 + 0.3 * reverb.size;
-  const wet = reverb.mix * REVERB_WET_SCALE;
-  const channel = (spread: number) => ({
-    combs: COMB_TUNING.map((tuning) => ({
-      buffer: new Float64Array(
-        Math.max(1, Math.round((tuning + spread) * scale)),
-      ),
-      index: 0,
-      store: 0,
-    })),
-    allpasses: ALLPASS_TUNING.map((tuning) => ({
-      buffer: new Float64Array(
-        Math.max(1, Math.round((tuning + spread) * scale)),
-      ),
-      index: 0,
-    })),
-  });
-  const sides = [channel(0), channel(STEREO_SPREAD)] as const;
-  const process = (side: (typeof sides)[number], input: number): number => {
-    let output = 0;
-    for (const comb of side.combs) {
-      const delayed = comb.buffer[comb.index]!;
-      comb.store = delayed * (1 - damp) + comb.store * damp;
-      comb.buffer[comb.index] = input + comb.store * feedback;
-      comb.index = comb.index + 1 === comb.buffer.length ? 0 : comb.index + 1;
-      output += delayed;
-    }
-    for (const allpass of side.allpasses) {
-      const delayed = allpass.buffer[allpass.index]!;
-      allpass.buffer[allpass.index] = output + delayed * 0.5;
-      output = delayed - output;
-      allpass.index =
-        allpass.index + 1 === allpass.buffer.length ? 0 : allpass.index + 1;
-    }
-    return output;
+): WavetableHook | undefined {
+  if (!isWavetableInstrument(track.instrument)) return undefined;
+  const settings = wavetableOf(track);
+  const table = tableFor(track, settings, bank.wavetables);
+  // A pack table that failed to load renders silent (the problem is reported).
+  if (!table)
+    return {
+      id: `missing:${settings.table.src}`,
+      oscillatorFor: () => () => () => 0,
+    };
+  const lane = track.wtAutomation ?? [];
+  const positionAt =
+    lane.length > 0
+      ? (tick: number) => interpolateAutomation(lane, tick, settings.wt ?? 0)
+      : undefined;
+  return {
+    id: table.id,
+    oscillatorFor: (note) =>
+      wavetableOscillator(table, settings, note, {
+        sampleRate: context.sampleRate,
+        samplesPerTick: context.samplesPerTick,
+        secondsPerTick: context.samplesPerTick / context.sampleRate,
+        gate: noteSpan(note, context).length / context.sampleRate,
+        positionAt,
+      }),
   };
-  for (let index = 0; index < left.length; index += 1) {
-    const input = (left[index]! + right[index]!) * REVERB_INPUT_GAIN;
-    left[index]! += process(sides[0], input) * wet;
-    right[index]! += process(sides[1], input) * wet;
-  }
-}
-
-/** FNV-1a seeded mulberry32: integer-only, so identical on every platform. */
-function seededRandom(seed: string): () => number {
-  let hash = 0x811c9dc5;
-  for (let index = 0; index < seed.length; index += 1) {
-    hash ^= seed.charCodeAt(index);
-    hash = Math.imul(hash, 0x01000193) >>> 0;
-  }
-  let state = hash;
-  return () => {
-    state = (state + 0x6d2b79f5) >>> 0;
-    let value = Math.imul(state ^ (state >>> 15), 1 | state);
-    value = (value + Math.imul(value ^ (value >>> 7), 61 | value)) ^ value;
-    return ((value ^ (value >>> 14)) >>> 0) / 4_294_967_296;
-  };
-}
-
-/** Resolve a piecewise-linear automation lane, holding the static value before its first point. */
-function interpolateAutomation(
-  points: readonly AutomationPoint[],
-  tick: number,
-  fallback: number,
-): number {
-  if (points.length === 0 || !Number.isFinite(tick)) return fallback;
-  const first = points[0]!;
-  if (tick < first.tick) return fallback;
-  const last = points[points.length - 1]!;
-  if (tick >= last.tick) return last.value;
-  for (let index = 1; index < points.length; index += 1) {
-    const right = points[index]!;
-    if (tick > right.tick) continue;
-    const left = points[index - 1]!;
-    const span = right.tick - left.tick;
-    const ratio = span <= 0 ? 1 : (tick - left.tick) / span;
-    return left.value + (right.value - left.value) * ratio;
-  }
-  return last.value;
-}
-
-/** A tiny deterministic instrument bank. Names come from the score's track metadata. */
-function synthSample(
-  instrument: string,
-  phase: number,
-  frequency: number,
-  sampleRate: number,
-): number {
-  const name = instrument.trim().toLowerCase();
-  const cycle = phase - Math.floor(phase);
-  const sine = Math.sin(2 * Math.PI * phase);
-  if (name.includes("square")) return cycle < 0.5 ? 1 : -1;
-  if (name.includes("saw")) return 2 * cycle - 1;
-  if (name.includes("triangle")) return 1 - 4 * Math.abs(cycle - 0.5);
-  if (name.includes("bass")) {
-    // A rounded fundamental plus a quiet octave gives bass tracks useful weight.
-    return Math.tanh(
-      0.9 * Math.sin(2 * Math.PI * phase) +
-        0.25 * Math.sin(4 * Math.PI * phase),
-    );
-  }
-  if (name.includes("piano") || name.includes("pluck")) {
-    // Add stable harmonics; the envelope above supplies the note decay.
-    const harmonic =
-      Math.sin(4 * Math.PI * phase) * 0.28 +
-      Math.sin(6 * Math.PI * phase) * 0.12;
-    return Math.tanh(sine + harmonic);
-  }
-  // Unknown instruments deliberately fall back to the original sine voice.
-  return sine;
 }
 
 export function encodeWav(