@hraness/dawg 0.5.0 → 0.6.0

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}`],
+});

package/src/audio/sampler.ts

@@ -38,7 +38,15 @@ import {
   performedNotes,
   secondsAtTick,
 } from "../../core/tempo.ts";
-import { sampleWarpFor, warpedSpan, type SampleWarp } from "./warp.ts";
+import {
+  beatFitMap,
+  sampleWarpFor,
+  spanFitMap,
+  warpedSpan,
+  type FitMap,
+  type SampleWarp,
+} from "./warp.ts";
+import { fittedBuffer, windowAt } from "./fit.ts";
 import {
   performanceTimingFor,
   tunedTiming,
@@ -55,6 +63,8 @@ const ATTACK_SECONDS = 0.001;
 /** Fade at a natural end, a held release, a choke and a voice steal. */
 const END_FADE_SECONDS = 0.003;
 const RELEASE_SECONDS = 0.01;
+/** Extra fitted frames past a note's reach (read interpolation). */
+const REACH_MARGIN_FRAMES = 64;
 const CHOKE_SECONDS = 0.005;
 /** Loop seam crossfade (source time). */
 const LOOP_CROSSFADE_SECONDS = 0.005;
@@ -221,22 +231,47 @@ export function planSamplerVoices(
       ? { ...resolved, ratio: resolved.ratio * 2 ** (note.cents / 1200) }
       : resolved;
     const ref: SampleRef | undefined = sampler.voices[target.voice];
-    const sample = bank.voices.get(sampleKey(track.id, target.voice));
-    if (!ref || !sample) continue;
-    const speed = ref.speed ?? 1;
-    const regionStart = (ref.begin ?? 0) * sample.frames;
-    const regionEnd = (ref.end ?? 1) * sample.frames;
+    const decoded = bank.voices.get(sampleKey(track.id, target.voice));
+    if (!ref || !decoded) continue;
     const held = noteLengthFrames(note, timing);
+    // 0.6 fit (`bpm`, `len`, or `fit` with fitmode beats|tones): the window
+    // is fitted once into a render-rate buffer that plays forward at step 1
+    // (times the keyed ratio). Absent fields keep the 0.5 path untouched.
+    // Only the frames this note can reach are fitted: a keyed or clipped
+    // note (not looping, no accelerate) ends at its held length plus the
+    // release, read at the keyed ratio; anything else may play it all.
+    const reach =
+      ref.loop !== true &&
+      (ref.accelerate ?? 0) === 0 &&
+      (sampler.mode === "keyed" || ref.clip !== undefined)
+        ? Math.ceil(
+            ((ref.clip === undefined
+              ? held
+              : Math.max(1, Math.floor(held * ref.clip))) +
+              Math.round(RELEASE_SECONDS * sampleRate)) *
+              target.ratio,
+          ) + REACH_MARGIN_FRAMES
+        : Infinity;
+    const fitted = isFitted(ref)
+      ? fitVoice(ref, decoded, note.startTick, held, timing, reach)
+      : undefined;
+    if (fitted === null) continue;
+    const sample = fitted?.sample ?? decoded;
+    const speed = fitted ? 1 : (ref.speed ?? 1);
+    const regionStart = fitted ? 0 : (ref.begin ?? 0) * sample.frames;
+    const regionEnd = fitted ? sample.frames : (ref.end ?? 1) * sample.frames;
     // `fit`, `unit: "c"` and `unit: "s"` give the window a duration; the
     // keyed ratio still repitches on top.
     const unit = ref.unit ?? "r";
-    const seconds = ref.fit
-      ? held / sampleRate
-      : unit === "c"
-        ? cycleSeconds(timing.score, note.startTick) / Math.abs(speed)
-        : unit === "s"
-          ? Math.abs(speed)
-          : undefined;
+    const seconds = fitted
+      ? undefined
+      : ref.fit
+        ? held / sampleRate
+        : unit === "c"
+          ? cycleSeconds(timing.score, note.startTick) / Math.abs(speed)
+          : unit === "s"
+            ? Math.abs(speed)
+            : undefined;
     const step =
       seconds === undefined
         ? ((Math.abs(speed) * sample.sampleRate) / sampleRate) * target.ratio
@@ -276,10 +311,16 @@ export function planSamplerVoices(
         fade = Math.max(1, Math.round(END_FADE_SECONDS * sampleRate));
       }
     }
-    const loopFrom =
-      ref.loopBegin === undefined ? regionStart : ref.loopBegin * sample.frames;
-    const loopTo =
-      ref.loopEnd === undefined ? regionEnd : ref.loopEnd * sample.frames;
+    const loopFrom = fitted
+      ? fitted.loopFrom
+      : ref.loopBegin === undefined
+        ? regionStart
+        : ref.loopBegin * sample.frames;
+    const loopTo = fitted
+      ? fitted.loopTo
+      : ref.loopEnd === undefined
+        ? regionEnd
+        : ref.loopEnd * sample.frames;
     const start = noteStartFrame(note, timing);
     const performance = (note as PerformedNote).performance;
     const voice: SamplerVoice = {
@@ -318,6 +359,111 @@ export function planSamplerVoices(
   return voices;
 }
 
+/** A SampleRef that fits its window to the song (0.6 `bpm`, `len`, fitmode). */
+export function isFitted(ref: SampleRef): boolean {
+  return (
+    ref.bpm !== undefined ||
+    ref.len !== undefined ||
+    (ref.fit === true && (ref.fitmode === "beats" || ref.fitmode === "tones"))
+  );
+}
+
+type FittedVoice = Readonly<{
+  sample: DecodedSample;
+  loopFrom: number;
+  loopTo: number;
+}>;
+
+/**
+ * The fitted window of one note. Precedence `fit` > `bpm` > `len`:
+ * - `fit`: the window fills the note (Strudel `fit`, with an algorithm);
+ * - `bpm`: the window advances `|speed|` source beats per song beat,
+ *   following the tempo map (ramps, steps, fermatas);
+ * - `len`: the window spans `len` song beats through the tempo map.
+ * A negative `speed` reverses the window; `unit` is ignored once fitted.
+ * Returns null while a live fit is still computing (the voice stays
+ * silent rather than playing at the wrong pitch).
+ */
+function fitVoice(
+  ref: SampleRef,
+  decoded: DecodedSample,
+  startTick: number,
+  held: number,
+  timing: SamplerTiming,
+  reach: number,
+): FittedVoice | null {
+  const { sampleRate, score, warp } = timing;
+  const speed = ref.speed ?? 1;
+  const reverse = speed < 0;
+  const from = (ref.begin ?? 0) * decoded.frames;
+  const to = (ref.end ?? 1) * decoded.frames;
+  const rate = decoded.sampleRate / sampleRate;
+  const window = windowAt(decoded.mono, from, to, rate, reverse);
+  const frames = window.length;
+  let map: FitMap;
+  if (ref.fit === true) map = spanFitMap(frames, held);
+  else {
+    const perBeat =
+      ref.bpm !== undefined
+        ? ((sampleRate * 60) / ref.bpm) * Math.abs(speed)
+        : frames / ref.len!;
+    map = beatFitMap(
+      warp,
+      {
+        tempoBpm: score.tempoBpm,
+        ticksPerBeat: score.ticksPerBeat,
+        sampleRate,
+      },
+      startTick,
+      frames,
+      perBeat,
+    );
+  }
+  const algorithm = ref.fitmode ?? "repitch";
+  const windowKey = `${decoded.sha256}:${decoded.sampleRate}:${from}:${to}:${sampleRate}:${reverse ? 1 : 0}`;
+  const length = Math.min(map.length, reach);
+  const key = `${windowKey}:${algorithm}:${mapPrint(map, frames)}:${Math.round(length)}`;
+  const buffer = fittedBuffer(
+    key,
+    window,
+    sampleRate,
+    map,
+    algorithm,
+    windowKey,
+    length,
+  );
+  if (!buffer) return null;
+  const sample: DecodedSample = Object.freeze({
+    sha256: decoded.sha256,
+    sampleRate,
+    channels: 1,
+    frames: buffer.length,
+    mono: buffer,
+  });
+  // Loop points move with the map (in window frames, then out frames).
+  const loopAt = (fraction: number | undefined, fallback: number) => {
+    if (fraction === undefined) return fallback;
+    const source = fraction * decoded.frames;
+    const inWindow = (reverse ? to - source : source - from) / rate;
+    return Math.max(0, Math.min(buffer.length, map.outAt(inWindow)));
+  };
+  const a = loopAt(ref.loopBegin, 0);
+  const b = loopAt(ref.loopEnd, buffer.length);
+  return Object.freeze({
+    sample,
+    loopFrom: Math.min(a, b),
+    loopTo: Math.max(a, b),
+  });
+}
+
+/** Fingerprint of a position map: its length and 64 exact samples. */
+function mapPrint(map: FitMap, frames: number): string {
+  const parts = [map.length.toString()];
+  for (let i = 1; i <= 64; i += 1)
+    parts.push(map.outAt((frames * i) / 64).toString());
+  return parts.join(",");
+}
+
 /** Linear-interpolated read, clamped to the sample. */
 function readAt(mono: Float32Array, position: number): number {
   const last = mono.length - 1;

package/src/audio/samples.ts

@@ -32,8 +32,10 @@ import {
   isLocalTableSrc,
   isWavetableInstrument,
   type SampleRef,
+  type Track,
   type TrackScore,
 } from "../../core/score.ts";
+import { GRANULAR_SOURCE_VOICE } from "../../core/granular.ts";
 import { PackError, PackStore } from "./packs.ts";
 import {
   DEFAULT_MEMORY_CACHE_BYTES,
@@ -94,10 +96,35 @@ export function hasSamplerTracks(score: TrackScore): boolean {
         Object.keys(track.sampler.voices).length > 0) ||
       packWavetable(track) !== undefined ||
       localWavetable(track) !== undefined ||
-      reverbIrSample(track) !== undefined,
+      reverbIrSample(track) !== undefined ||
+      granularSample(track) !== undefined,
   );
 }
 
+/**
+ * A granular track's sample source (0.6): its `granular.src` when that is a
+ * SampleRef, loaded and sha256-pinned like a sampler voice under the voice
+ * name `granular:src`. A `synth:` source or no source needs no loading.
+ */
+export function granularSample(track: Track): SampleRef | undefined {
+  if (track.instrument !== "granular") return undefined;
+  const src = track.granular?.src;
+  return src !== undefined && typeof src !== "string" ? src : undefined;
+}
+
+/** The sample voices a track loads: sampler voices, then a granular source. */
+function trackSampleRefs(track: Track): [string, SampleRef][] {
+  const refs: [string, SampleRef][] = [];
+  if (isSamplerInstrument(track.instrument) && track.sampler) {
+    const names = Object.keys(track.sampler.voices).sort();
+    for (const voice of names.slice(0, SCORE_LIMITS.maxSamplerVoices))
+      refs.push([voice, track.sampler.voices[voice]!]);
+  }
+  const granular = granularSample(track);
+  if (granular) refs.push([GRANULAR_SOURCE_VOICE, granular]);
+  return refs;
+}
+
 /** The project WAV a wavetable track plays, if any. */
 export function localWavetable(
   track: TrackScore["tracks"][number],
@@ -585,8 +612,7 @@ export class SampleLibrary implements SampleSource {
     this.inUse = new Set();
     const urls: string[] = [];
     for (const track of score.tracks) {
-      if (!isSamplerInstrument(track.instrument) || !track.sampler) continue;
-      for (const ref of Object.values(track.sampler.voices)) {
+      for (const [, ref] of trackSampleRefs(track)) {
         if (ref.sha256) this.inUse.add(ref.sha256);
         if (ref.url) urls.push(ref.url);
       }
@@ -656,10 +682,7 @@ export class SampleLibrary implements SampleSource {
       }
     }
     for (const track of score.tracks) {
-      if (!isSamplerInstrument(track.instrument) || !track.sampler) continue;
-      const names = Object.keys(track.sampler.voices).sort();
-      for (const voice of names.slice(0, SCORE_LIMITS.maxSamplerVoices)) {
-        const ref = track.sampler.voices[voice]!;
+      for (const [voice, ref] of trackSampleRefs(track)) {
         let src = ref.src;
         if (src.startsWith(PACK_PREFIX)) {
           try {