@hraness/dawg 0.3.0 → 0.4.0

package/src/audio/wav.ts

@@ -2,6 +2,8 @@ import {
   SCORE_LIMITS,
   isSamplerInstrument,
   isTrackAudible,
+  isWavetableInstrument,
+  wavetableOf,
   type AutomationPoint,
   type Note,
   type Track,
@@ -13,7 +15,46 @@ import {
   renderSamplerVoices,
   samplerTailSeconds,
 } from "./sampler.ts";
-import { EMPTY_SAMPLE_BANK, sampleKey, type SampleBank } from "./samples.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 }>;
 
@@ -53,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;
@@ -78,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. */
@@ -136,16 +209,23 @@ type Stem = {
 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),
@@ -168,17 +248,21 @@ export class StemRenderer {
     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) =>
-        track.reverb && track.reverb.mix > 0 ? 1 + 3 * track.reverb.size : 0,
+        reverbTailFor(track, sampleRate, bank.irs),
       ),
     );
-    const bank = options.samples ?? EMPTY_SAMPLE_BANK;
     // 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,
-      samplerTailSeconds(score, bank, sampleRate),
+      Math.max(
+        samplerTailSeconds(score, bank, sampleRate),
+        ...score.tracks.map(synthTailSeconds),
+      ),
     );
     let frames: number;
     let samples: number;
@@ -192,10 +276,13 @@ export class StemRenderer {
       );
       const tailSeconds = Math.min(
         MAX_LOOP_TAIL_SECONDS,
-        Math.max(MAX_DRUM_SECONDS, samplerTail) +
+        Math.max(MAX_DRUM_SECONDS, samplerTail, kitTailSeconds(score)) +
           0.1 +
           reverbTail +
-          delayTailSeconds(score),
+          Math.max(
+            0,
+            ...score.tracks.map((track) => delayTailFor(track, score.tempoBpm)),
+          ),
       );
       samples = frames + Math.ceil(tailSeconds * sampleRate);
     } else {
@@ -211,9 +298,11 @@ export class StemRenderer {
       sampleRate,
       samples,
       samplesPerTick: (sampleRate * 60) / (score.tempoBpm * score.ticksPerBeat),
+      tempoBpm: score.tempoBpm,
+      ...(bank.irs ? { irs: bank.irs } : {}),
     };
     this.renders += 1;
-    const { dry, left, right, mixL, mixR } = this.scratchFor(samples);
+    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]));
@@ -223,13 +312,44 @@ export class StemRenderer {
       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,
+    );
+    // 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);
-      const key = stemKey(track, notes, context, sampler ? bank : undefined);
+      // 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 {
@@ -241,8 +361,31 @@ export class StemRenderer {
             }
           : { 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) {
@@ -250,12 +393,24 @@ export class StemRenderer {
             else renderToneNote(dry, note, track, context);
           }
         }
-        if (track) applyLowPass(dry, track, context);
-        applyPan(dry, target.left, target.right, track, context);
-        if (track) {
-          applyDelay(target.left, target.right, track, context);
-          applyReverb(target.left, target.right, 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,
@@ -265,11 +420,50 @@ export class StemRenderer {
         };
         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) {
-        mixL[index]! += stem.left[index]!;
-        mixR[index]! += stem.right[index]!;
+        const g = gain ? gain[index]! : 1;
+        mixL[index]! += wet.left[index]! * g;
+        mixR[index]! += wet.right[index]! * g;
       }
     }
+    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()])
@@ -299,6 +493,7 @@ export class StemRenderer {
     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),
@@ -308,6 +503,7 @@ export class StemRenderer {
     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),
@@ -353,6 +549,8 @@ function stemKey(
   notes: readonly Note[],
   context: RenderContext,
   bank?: SampleBank,
+  wavetableId?: string,
+  impulseId?: string,
 ): string {
   let settings: Record<string, unknown> | null = null;
   if (track) {
@@ -364,11 +562,16 @@ function stemKey(
     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] : []),
   ]);
 }
 
@@ -400,27 +603,6 @@ function renderSamplerNotes(
   );
 }
 
-/** 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),
-    );
-  }
-  return longest;
-}
-
 /** Track volume and volume automation at a score tick (pan is applied in stereo). */
 function trackGainAt(track: Track | undefined, tick: number): number {
   const trackGain = Math.max(0, Math.min(1, track?.volume ?? 1));
@@ -477,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;
   }
 }
 
@@ -495,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}`);
@@ -512,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 =
@@ -560,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
@@ -629,6 +766,7 @@ function applyPan(
   right: Float64Array,
   track: Track | undefined,
   context: RenderContext,
+  dryRight?: Float64Array,
 ): void {
   const lane = track?.panAutomation ?? [];
   const staticPan = track?.pan ?? 0;
@@ -644,189 +782,53 @@ 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;
-  };
-  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;
+): 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,
+      }),
   };
 }
 
-/** 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(
   pcm: Int16Array,
   sampleRate: number,