@hraness/dawg 0.4.1 → 0.6.0

package/src/audio/measure.ts

@@ -0,0 +1,110 @@
+/**
+ * Render a score and measure the result: the shared path behind
+ * `master measure`, `dawg render`'s loudness line and the measure_mix agent
+ * tool. The loop is measured as a loop playing forever (its steady state),
+ * a one-shot as rendered, so every reading matches what playback and export
+ * produce. Measuring never changes the score.
+ */
+import type { TrackScore } from "../../core/score.ts";
+import type { MeasureReply, MeasureRequest } from "./measure-worker.ts";
+import { measureMix, pcmChannels, type MixMeasurement } from "./loudness.ts";
+import type { MasterReport } from "./master.ts";
+import {
+  DEFAULT_SAMPLE_RATE,
+  renderScorePcm,
+  type RenderedAudio,
+  type RenderOptions,
+} from "./wav.ts";
+
+/** The rate a song with a master exports (and is measured) at. */
+export const MASTER_SAMPLE_RATE = 48_000;
+
+/**
+ * The rate `dawg render` writes and measurements use, so a reading matches
+ * the exported file: 48 kHz once the song has a master (a deliverable, with
+ * room for the high shelf and a true peak a platform's resampler will not
+ * raise), the engine's 22,050 Hz otherwise (dawg 0.4 exports unchanged).
+ */
+export function exportSampleRate(score: TrackScore): number {
+  return score.master ? MASTER_SAMPLE_RATE : DEFAULT_SAMPLE_RATE;
+}
+
+export type ScoreMeasurement = Readonly<{
+  mix: MixMeasurement;
+  master?: MasterReport;
+  sampleRate: number;
+  seconds: number;
+  loop: boolean;
+}>;
+
+/** Measure audio rendered elsewhere (the export, a preview). */
+export function measureRendered(
+  audio: RenderedAudio,
+  loop: boolean,
+): ScoreMeasurement {
+  const [left, right] = pcmChannels(audio.pcm);
+  return Object.freeze({
+    mix: measureMix(left, right, audio.sampleRate, { loop }),
+    ...(audio.master ? { master: audio.master } : {}),
+    sampleRate: audio.sampleRate,
+    seconds: audio.frames / audio.sampleRate,
+    loop,
+  });
+}
+
+/** Render `score` (as a loop by default) and measure it. */
+export function measureScore(
+  score: TrackScore,
+  options: RenderOptions = {},
+): ScoreMeasurement {
+  const loop = options.loop ?? true;
+  const audio = renderScorePcm(score, {
+    sampleRate: exportSampleRate(score),
+    ...options,
+    loop,
+  });
+  return measureRendered(audio, loop);
+}
+
+/**
+ * `measureScore` in a worker, so the caller's thread keeps running; falls
+ * back to measuring inline if the worker cannot start or fails.
+ */
+export async function measureScoreOffThread(
+  score: TrackScore,
+  options: Readonly<{
+    sampleRate?: number;
+    loop?: boolean;
+    projectRoot?: string;
+  }> = {},
+): Promise<ScoreMeasurement> {
+  let worker: Worker | undefined;
+  try {
+    worker = new Worker(new URL("./measure-worker.ts", import.meta.url).href);
+    const running = worker;
+    const reply = await new Promise<MeasureReply>((resolve, reject) => {
+      running.addEventListener("message", (event) =>
+        resolve((event as MessageEvent<MeasureReply>).data),
+      );
+      running.addEventListener("error", (event) =>
+        reject(new Error((event as ErrorEvent).message ?? "worker error")),
+      );
+      const request: MeasureRequest = {
+        score: score.toJSON(),
+        ...options,
+      };
+      running.postMessage(request);
+    });
+    if (reply.ok) return reply.measured;
+    throw new Error(reply.error);
+  } catch {
+    return measureScore(score, {
+      ...(options.sampleRate === undefined
+        ? {}
+        : { sampleRate: options.sampleRate }),
+      ...(options.loop === undefined ? {} : { loop: options.loop }),
+    });
+  } finally {
+    worker?.terminate();
+  }
+}

package/src/audio/player.ts

@@ -2,7 +2,9 @@ import { unlink } from "node:fs/promises";
 import type { TrackScore } from "../../core/score.ts";
 import { PlaybackLock } from "./lock.ts";
 import { SampleLibrary, hasSamplerTracks, type SampleBank } from "./samples.ts";
-import { RENDER_CHANNELS, encodeWav, renderScorePcm } from "./wav.ts";
+import { RENDER_CHANNELS, encodeWav } from "./wav.ts";
+import { transportMapFor } from "./clock.ts";
+import { playbackTime, renderArrangedPcm } from "./arrange.ts";
 
 /** Small best-effort local player. The score and transport remain testable without a sound device. */
 export class LoopPlayer {
@@ -118,12 +120,15 @@ export function renderLoopWav(
   beat = 0,
   samples?: SampleBank,
 ): Uint8Array {
-  const audio = renderScorePcm(score, { loop: true, samples });
-  const framesPerBeat = (60 * audio.sampleRate) / score.tempoBpm;
+  const audio = renderArrangedPcm(score, { loop: true, samples });
+  const timeline = playbackTime(score);
+  const framesPerBeat = (60 * audio.sampleRate) / timeline.tempoBpm;
+  const map = transportMapFor(timeline);
+  const first = map
+    ? map.seconds(Math.max(0, beat) % map.loopBeats) * audio.sampleRate
+    : Math.max(0, beat) * framesPerBeat;
   const start =
-    ((Math.round(Math.max(0, beat) * framesPerBeat) % audio.frames) +
-      audio.frames) %
-    audio.frames;
+    ((Math.round(first) % audio.frames) + audio.frames) % audio.frames;
   const rotated = new Int16Array(audio.pcm.length);
   rotated.set(audio.pcm.subarray(start * RENDER_CHANNELS));
   rotated.set(

package/src/audio/preview.ts

@@ -16,6 +16,7 @@
  * wavetables so position changes are audible.
  */
 import { isDrumInstrument } from "../../core/drums.ts";
+import type { SongMaster } from "../../core/master.ts";
 import { MODES, parseKey } from "../../core/chords.ts";
 import { rhythmVoicePitch } from "../../core/rhythm.ts";
 import {
@@ -28,7 +29,9 @@ import {
   type NoteInput,
   type Track,
 } from "../../core/score.ts";
+import { barAt, barStartTick, songTimeSlice } from "../../core/tempo.ts";
 import { interpolateAutomation } from "./effects/common.ts";
+import { loopedSection, scoreBeatAt } from "./arrange.ts";
 import { RENDER_CHANNELS } from "./wav.ts";
 
 /** Longest preview loop, in bars. */
@@ -56,6 +59,14 @@ export type PreviewOptions = Readonly<{
    * the staged settings this way, so a voicing or arp change is audible.
    */
   phrase?: (score: TrackScore, track: Track, bars: number) => NoteInput[];
+  /**
+   * The limiter drive the song's master solved for its loudness target on
+   * the full mix, dB. A preview plays the master at this fixed drive instead
+   * of re-solving the target on its few bars, so a volume edit stays
+   * audible. Without it a solo plays the master with no target (the
+   * limiter at its own gain), and a context preview solves on its bars.
+   */
+  masterGainDb?: number;
 }>;
 
 export type Preview = Readonly<{
@@ -72,23 +83,42 @@ export function previewRegion(
   trackId: string,
   beat = 0,
 ): PreviewRegion {
-  if (score.bars <= MAX_PREVIEW_BARS) return { startBar: 0, bars: score.bars };
+  // A looped section bounds the audition, and the playhead (an arranged
+  // beat when the song has a form) maps back to the bars it is playing.
+  const section = loopedSection(score);
+  const bounded = section !== undefined && section.startBar < score.bars;
+  const lo = bounded ? section.startBar : 0;
+  const hi = bounded
+    ? Math.min(score.bars, section.startBar + section.bars)
+    : score.bars;
+  if (hi - lo <= MAX_PREVIEW_BARS) return { startBar: lo, bars: hi - lo };
   const bars = PREVIEW_REGION_BARS;
-  const barTicks = score.beatsPerBar * score.ticksPerBeat;
-  const last = score.bars - bars;
+  const last = hi - bars;
   const clampBar = (bar: number) =>
-    Math.max(0, Math.min(last, Number.isFinite(bar) ? Math.floor(bar) : 0));
-  let startBar = clampBar(beat / score.beatsPerBar);
+    Math.max(lo, Math.min(last, Number.isFinite(bar) ? Math.floor(bar) : lo));
+  // Bars through the meter changes; 0.4 scores keep `beat / beatsPerBar`.
+  const barOfTick = (tick: number) => barAt(score, tick).bar;
+  const scoreBeat = scoreBeatAt(score, beat);
+  let startBar = clampBar(
+    Number.isFinite(scoreBeat) ? barOfTick(scoreBeat * score.ticksPerBeat) : lo,
+  );
   const notes = score.notes.filter((note) => note.trackId === trackId);
   const inRegion = (from: number) =>
     notes.some(
       (note) =>
-        note.startTick >= from * barTicks &&
-        note.startTick < (from + bars) * barTicks,
+        note.startTick >= barStartTick(score, from) &&
+        note.startTick < barStartTick(score, from + bars),
     );
-  if (notes.length > 0 && !inRegion(startBar)) {
-    const first = Math.min(...notes.map((note) => note.startTick));
-    startBar = clampBar(first / barTicks);
+  const loTick = barStartTick(score, lo);
+  const hiTick = barStartTick(score, hi);
+  const pool = bounded
+    ? notes.filter(
+        (note) => note.startTick >= loTick && note.startTick < hiTick,
+      )
+    : notes;
+  if (pool.length > 0 && !inRegion(startBar)) {
+    const first = Math.min(...pool.map((note) => note.startTick));
+    startBar = clampBar(barOfTick(first));
   }
   return { startBar, bars };
 }
@@ -99,6 +129,8 @@ export function phraseRole(track: Track): PhraseRole {
   if (isSamplerInstrument(track.instrument))
     return track.sampler?.mode === "keyed" ? "chord" : "groove";
   if (isWavetableInstrument(track.instrument)) return "drone";
+  // Grain clouds are textures: held notes let them evolve.
+  if (track.instrument === "granular") return "drone";
   const words = `${track.instrument} ${track.name} ${track.id}`.toLowerCase();
   if (/\b(bass|sub|808)/.test(words)) return "riff";
   if (/\b(lead|arp|pluck|saw|square|pulse|z_|mono|melody|hook)/.test(words))
@@ -277,9 +309,8 @@ export function previewScore(
     Math.min(region.bars, score.bars - Math.max(0, region.startBar)),
   );
   const startBar = Math.max(0, Math.min(region.startBar, score.bars - 1));
-  const barTicks = score.beatsPerBar * score.ticksPerBeat;
-  const start = startBar * barTicks;
-  const end = start + bars * barTicks;
+  const start = barStartTick(score, startBar);
+  const end = barStartTick(score, startBar + bars);
   const context = options.context === true;
   const anySolo = score.tracks.some((candidate) => candidate.solo === true);
   const tracks = score.tracks
@@ -313,14 +344,23 @@ export function previewScore(
     role = phraseRole(track);
     notes.push(...defaultPhrase(score, track, bars, role));
   }
+  // The song's tempo map and meter, rebased to the region's first bar.
+  const timing = songTimeSlice(score, startBar, bars);
   const preview = new TrackScore({
-    tempoBpm: score.tempoBpm,
+    tempoBpm: timing.tempoBpm,
+    ...(timing.time ? { time: timing.time } : {}),
     beatsPerBar: score.beatsPerBar,
     bars,
     ticksPerBeat: score.ticksPerBeat,
     key: score.key,
     tracks,
     notes,
+    // The master is the song's output stage, so a soloed preview passes
+    // through it too, the way a DAW solo still reaches the master bus: at
+    // the song's fixed drive, not a target re-solved on what is soloed.
+    ...(score.master
+      ? { master: previewMaster(score.master, context, options.masterGainDb) }
+      : {}),
   });
   return {
     score: preview,
@@ -330,6 +370,28 @@ export function previewScore(
   };
 }
 
+/**
+ * The master a preview plays: the song's, with its loudness target swapped
+ * for a fixed limiter drive (see PreviewOptions.masterGainDb).
+ */
+export function previewMaster(
+  master: SongMaster,
+  context: boolean,
+  masterGainDb: number | undefined,
+): SongMaster {
+  if (master.target === undefined) return master;
+  if (masterGainDb === undefined && context) return master;
+  const { target: _target, ...rest } = master;
+  if (!rest.limiter || masterGainDb === undefined) return rest;
+  return {
+    ...rest,
+    limiter: {
+      ...rest.limiter,
+      gain: Math.max(0, Math.min(24, masterGainDb)),
+    },
+  };
+}
+
 // ── analysis ──────────────────────────────────────────────────────────
 
 export type SoundStats = Readonly<{

package/src/audio/render-worker.ts

@@ -5,6 +5,8 @@
  */
 import { scoreFromJSON } from "../../core/score.ts";
 import { SampleLibrary, hasSamplerTracks } from "./samples.ts";
+import type { MasterReport } from "./master.ts";
+import { renderArranged } from "./arrange.ts";
 import { StemRenderer } from "./wav.ts";
 
 export type RenderRequest = Readonly<{
@@ -24,6 +26,8 @@ export type RenderReply =
       pcm: Int16Array;
       /** Milliseconds spent rendering, excluding transfer. */
       renderMs: number;
+      /** Loudness after the song master; absent without one. */
+      master?: MasterReport;
     }>
   | Readonly<{ id: number; ok: false; error: string }>;
 
@@ -43,7 +47,7 @@ self.onmessage = async (event: MessageEvent<RenderRequest>) => {
         library = new SampleLibrary({ projectRoot });
       samples = await library.load(parsed);
     }
-    const audio = renderer.render(parsed, {
+    const audio = renderArranged(renderer, parsed, {
       sampleRate,
       loop: true,
       samples,
@@ -55,6 +59,7 @@ self.onmessage = async (event: MessageEvent<RenderRequest>) => {
       sampleRate: audio.sampleRate,
       pcm: audio.pcm,
       renderMs: performance.now() - started,
+      ...(audio.master ? { master: audio.master } : {}),
     };
     self.postMessage(reply, [audio.pcm.buffer]);
   } catch (error) {

package/src/audio/renderer.ts

@@ -1,6 +1,8 @@
 import type { TrackScore } from "../../core/score.ts";
+import type { MasterReport } from "./master.ts";
 import type { RenderReply, RenderRequest } from "./render-worker.ts";
 import { SampleLibrary, hasSamplerTracks } from "./samples.ts";
+import { renderArranged } from "./arrange.ts";
 import { StemRenderer } from "./wav.ts";
 
 export type LoopRender = Readonly<{
@@ -9,6 +11,8 @@ export type LoopRender = Readonly<{
   sampleRate: number;
   /** Milliseconds the render itself took (worker or inline). */
   renderMs: number;
+  /** Loudness after the song master; absent without one. */
+  master?: MasterReport;
 }>;
 
 export type LoopRendererOptions = Readonly<{
@@ -80,7 +84,7 @@ export class LoopRenderer {
       this.library ??= new SampleLibrary({ projectRoot: this.projectRoot });
       samples = await this.library.load(score);
     }
-    const audio = this.inline.render(score, {
+    const audio = renderArranged(this.inline, score, {
       sampleRate: this.sampleRate,
       loop: true,
       samples,
@@ -90,6 +94,7 @@ export class LoopRenderer {
       frames: audio.frames,
       sampleRate: audio.sampleRate,
       renderMs: performance.now() - started,
+      ...(audio.master ? { master: audio.master } : {}),
     };
   }
 
@@ -143,6 +148,7 @@ export class LoopRenderer {
           frames: reply.frames,
           sampleRate: reply.sampleRate,
           renderMs: reply.renderMs,
+          ...(reply.master ? { master: reply.master } : {}),
         });
       else waiter.reject(new Error(reply.error));
     });

package/src/audio/resonators.ts

@@ -0,0 +1,287 @@
+/**
+ * The modal percussion engine (0.6, lane f06-modal): renders a track whose
+ * instrument is `"modal"` and that carries a `modal` field. Registered in
+ * `src/audio/instruments.ts`; without the field the legacy tone voice plays.
+ *
+ * Per track: notes in onset order, at most `MAX_RESONATOR_VOICES` sounding
+ * (the oldest onset is stolen with a 5 ms fade), each a `ModalBank` struck
+ * once and rung for up to `MAX_RESONATOR_TAIL` seconds after note-off with
+ * early stop on silence. Stealing depends only on earlier onsets, so a
+ * render is prefix-stable: adding a later note never changes earlier audio
+ * before that note starts.
+ *
+ * 0.5 hooks: tuning and note cents (`noteHz`), bends and glides
+ * (`performance.cents`, faded per tick above 0.45 sr), articulation as
+ * timbre only (accent and marcato harden the mallet; staccato damps sooner
+ * through the shorter length), sustain pedal (longer lengths) and half
+ * pedal (`performance.damp`), velocity curve and humanize (already in the
+ * performed notes), and the tempo map (`context.warp`).
+ */
+import type { PerformedNote } from "../../core/expression.ts";
+import {
+  MAX_RESONATOR_TAIL,
+  MAX_RESONATOR_VOICES,
+  MODAL_LANE_PARAMS,
+  modalSettings,
+  modalTailSeconds,
+  RESONATOR_TABLE_VERSION,
+  type ModalSettings,
+} from "../../core/resonators.ts";
+import type { AutomationPoint, Track } from "../../core/score.ts";
+import { noteHz } from "../../core/tuning.ts";
+import { ModalBank, MODAL_BLOCK } from "./dsp/modal.ts";
+import { logCosh } from "./dsp/shape.ts";
+import { interpolateAutomation } from "./effects/common.ts";
+import type { EngineContext, InstrumentEngine } from "./instruments.ts";
+import { warpedSpan } from "./warp.ts";
+
+/**
+ * Raised-cosine fade applied to a stolen voice, seconds. At 80 ms the
+ * largest per-sample gain step is pi/(2*fade samples): -61 dB at 22.05 kHz,
+ * -68 dB at 48 kHz, so stealing a long gong or kempul does not click.
+ */
+const STEAL_FADE = 0.08;
+/** Extra mallet hardness for accent and marcato. */
+const ACCENT_HARDNESS = 0.2;
+/**
+ * Track-level safety knee: exactly linear up to KNEE, then a tanh shoulder
+ * that never passes CEILING. Single notes (about 0.8 at velocity 0.8) and
+ * dyads pass bit-exact; only dense velocity-1 chords reach the shoulder. A
+ * six-note chord at velocity 1 sums to about 4-5 and lands under the
+ * ceiling, which the centre pan and track gain keep below 0 dBFS (spec
+ * test 13).
+ */
+export const MODAL_KNEE = 1;
+const KNEE = MODAL_KNEE;
+const CEILING = 1.38;
+const SPAN = CEILING - KNEE;
+
+function knee(x: number): number {
+  const a = Math.abs(x);
+  if (a <= KNEE) return x;
+  return Math.sign(x) * (KNEE + SPAN * Math.tanh((a - KNEE) / SPAN));
+}
+
+/** Antiderivative of `knee` (even), for first-order ADAA. */
+function kneeF(x: number): number {
+  const a = Math.abs(x);
+  if (a <= KNEE) return 0.5 * x * x;
+  return (
+    0.5 * KNEE * KNEE +
+    KNEE * (a - KNEE) +
+    SPAN * SPAN * logCosh((a - KNEE) / SPAN)
+  );
+}
+
+/**
+ * The knee with first-order ADAA only inside the shoulder: while this and
+ * the previous sample are both under KNEE the output is the input itself, so
+ * the limiter adds no two-tap low-pass or half-sample delay to normal play.
+ */
+export function applyModalKnee(dry: Float64Array, samples: number): void {
+  let x1 = 0;
+  let F1 = 0;
+  for (let index = 0; index < samples; index += 1) {
+    const x = dry[index]!;
+    const Fx = kneeF(x);
+    if (Math.abs(x) > KNEE || Math.abs(x1) > KNEE) {
+      const dx = x - x1;
+      dry[index] = Math.abs(dx) < 1e-5 ? knee(0.5 * (x + x1)) : (Fx - F1) / dx;
+    }
+    x1 = x;
+    F1 = Fx;
+  }
+}
+
+type Planned = Readonly<{
+  note: PerformedNote;
+  start: number;
+  length: number;
+}>;
+
+function span(
+  note: PerformedNote,
+  context: EngineContext,
+): { start: number; length: number } {
+  if (context.warp)
+    return warpedSpan(context.warp, note.startTick, note.durationTicks);
+  const perTick =
+    (60 * context.sampleRate) / (context.tempoBpm * context.ticksPerBeat);
+  return {
+    start: Math.max(0, Math.floor(note.startTick * perTick)),
+    length: Math.max(1, Math.floor(note.durationTicks * perTick)),
+  };
+}
+
+function laneOf(
+  track: Track,
+  param: string,
+): readonly AutomationPoint[] | undefined {
+  const lanes = track.fxAutomation as
+    Readonly<Record<string, readonly AutomationPoint[]>> | undefined;
+  const points = lanes?.[`modal-${param}`];
+  return points && points.length > 0 ? points : undefined;
+}
+
+/** Renders a modal track's performed notes into `dry` (mono). */
+export function renderResonatorTrack(
+  dry: Float64Array,
+  notes: readonly PerformedNote[],
+  track: Track,
+  context: EngineContext,
+): void {
+  const { sampleRate, samples } = context;
+  const samplesPerTick = context.samplesPerTick;
+  const tickAt = (index: number): number =>
+    context.warp ? context.warp.tick(index) : index / samplesPerTick;
+  const planned: Planned[] = notes
+    .map((note) => ({ note, ...span(note, context) }))
+    .filter((entry) => entry.start < samples)
+    .sort(
+      (a, b) =>
+        a.start - b.start ||
+        a.note.pitch - b.note.pitch ||
+        (a.note.id < b.note.id ? -1 : a.note.id > b.note.id ? 1 : 0),
+    );
+  const lanes = new Map<string, readonly AutomationPoint[]>();
+  for (const { param } of MODAL_LANE_PARAMS) {
+    const points = laneOf(track, param);
+    if (points) lanes.set(param, points);
+  }
+  const motorLane = lanes.get("motordepth");
+  const volumeLane = track.volumeAutomation ?? [];
+  const volume = Math.max(0, Math.min(1, track.volume ?? 1));
+  const gainAt = (index: number): number =>
+    volume *
+    (volumeLane.length > 0
+      ? interpolateAutomation(volumeLane, tickAt(index), 1)
+      : 1);
+  const seedTick = context.seedTick ?? 0;
+  const base = modalSettings(track.modal);
+  const banks: ModalBank[] = [];
+  // Conservative end of each planned voice (its ring cap, or a steal).
+  const ends: number[] = [];
+  const steals: number[] = [];
+  const sounding: number[] = [];
+  for (let i = 0; i < planned.length; i += 1) {
+    const { note, start, length } = planned[i]!;
+    const onsetTick = note.startTick;
+    const settings =
+      lanes.size === 0
+        ? base
+        : clampLanes(
+            modalSettings(track.modal, (param) => {
+              const points = lanes.get(param);
+              return points
+                ? interpolateAutomation(
+                    points,
+                    onsetTick,
+                    base[param as keyof typeof base] as number,
+                  )
+                : undefined;
+            }),
+          );
+    const performance = note.performance;
+    const accent =
+      performance?.accent || note.articulation === "marcato"
+        ? ACCENT_HARDNESS
+        : 0;
+    const bank = new ModalBank(
+      settings,
+      {
+        hz: noteHz(note.pitch, note.cents, context.tuning),
+        velocity: note.velocity,
+        start: start / sampleRate,
+        duration: length / sampleRate,
+        seed: `${note.id}:${note.startTick + seedTick}:modal`,
+        ...(accent ? { accent } : {}),
+        ...(performance?.cents ? { cents: performance.cents } : {}),
+        ...(motorLane
+          ? {
+              motordepth: (t: number) =>
+                interpolateAutomation(
+                  motorLane,
+                  tickAt(start + t * sampleRate),
+                  settings.motordepth,
+                ),
+            }
+          : {}),
+      },
+      sampleRate,
+      MAX_RESONATOR_TAIL,
+    );
+    banks.push(bank);
+    ends.push(start + bank.endAt);
+    steals.push(Infinity);
+    // Voice stealing in onset order: drop finished voices, then steal the
+    // oldest onset while the pool is full.
+    for (let k = sounding.length - 1; k >= 0; k -= 1)
+      if (ends[sounding[k]!]! <= start) sounding.splice(k, 1);
+    while (sounding.length >= MAX_RESONATOR_VOICES) {
+      const oldest = sounding.shift()!;
+      steals[oldest] = start;
+      ends[oldest] = Math.min(
+        ends[oldest]!,
+        start + Math.round(STEAL_FADE * sampleRate),
+      );
+    }
+    sounding.push(i);
+  }
+  const scratch = new Float64Array(MODAL_BLOCK);
+  const fade = Math.max(1, Math.round(STEAL_FADE * sampleRate));
+  for (let i = 0; i < planned.length; i += 1) {
+    const { note, start } = planned[i]!;
+    const bank = banks[i]!;
+    const stop = Math.min(samples, ends[i]!);
+    const steal = steals[i]!;
+    const damp = note.performance?.damp;
+    const dampFrom = damp ? start + Math.round(damp.from * sampleRate) : 0;
+    let at = start;
+    while (at < stop) {
+      const count = Math.min(MODAL_BLOCK, stop - at);
+      scratch.fill(0, 0, count);
+      const alive = bank.process(scratch, 0, count);
+      const gain = gainAt(at);
+      for (let j = 0; j < count; j += 1) {
+        const index = at + j;
+        let level = gain;
+        if (index >= steal)
+          level *=
+            index - steal >= fade
+              ? 0
+              : 0.5 + 0.5 * Math.cos((Math.PI * (index - steal)) / fade);
+        if (damp && index > dampFrom)
+          level *= Math.exp(-(index - dampFrom) / (damp.tau * sampleRate));
+        dry[index]! += scratch[j]! * level;
+      }
+      if (!alive) break;
+      at += count;
+    }
+  }
+  // Causal and stateless across renders, so the output stays prefix-stable.
+  applyModalKnee(dry, samples);
+}
+
+/** Lane values land inside each parameter's range. */
+function clampLanes(settings: ModalSettings): ModalSettings {
+  const out: Record<string, number | string> = { ...settings };
+  for (const { param, spec } of MODAL_LANE_PARAMS) {
+    const value = out[param];
+    if (typeof value === "number")
+      out[param] = Math.max(spec.min, Math.min(spec.max, value));
+  }
+  return Object.freeze(out) as ModalSettings;
+}
+
+/** The modal engine as registered in `src/audio/instruments.ts`. */
+export const MODAL_ENGINE: InstrumentEngine = Object.freeze({
+  id: "modal",
+  field: "modal",
+  render(dry, _dryR, notes, track, context) {
+    renderResonatorTrack(dry, notes, track, context);
+  },
+  tailSeconds: (track: Track, lowestPitch?: number) =>
+    modalTailSeconds(track.modal, lowestPitch),
+  stereo: () => false,
+  assetDigests: () => [`resonators:${RESONATOR_TABLE_VERSION}`],
+});