@hraness/dawg 0.4.1 → 0.6.0

package/src/audio/sampler.ts

@@ -13,7 +13,8 @@
  *   `accelerate` ramps the rate; `squiz` raises pitch per zero-crossing
  *   cycle (described in Tidal/SuperDirt docs; implemented here from that
  *   description).
- * - keyed mode repitches from `root` (rate × 2^((pitch − root)/12)) and holds
+ * - keyed mode repitches from `root` (rate × 2^((pitch − root)/12), or the
+ *   tuning's key frequency over the root's 12-TET frequency) and holds
  *   for the note's length; oneshot mode maps voices to pitch slots from 36 in
  *   voice-name order and plays the whole window unless `loop` is set.
  *
@@ -31,6 +32,29 @@ import {
   type TrackScore,
 } from "../../core/score.ts";
 import { sampleKey, type DecodedSample, type SampleBank } from "./samples.ts";
+import {
+  barAt,
+  loopSecondsOf,
+  performedNotes,
+  secondsAtTick,
+} from "../../core/tempo.ts";
+import {
+  beatFitMap,
+  sampleWarpFor,
+  spanFitMap,
+  warpedSpan,
+  type FitMap,
+  type SampleWarp,
+} from "./warp.ts";
+import { fittedBuffer, windowAt } from "./fit.ts";
+import {
+  performanceTimingFor,
+  tunedTiming,
+  performNotes,
+  type NotePerformance,
+  type PerformedNote,
+} from "../../core/expression.ts";
+import { resolveTuning, type TuningTable } from "../../core/tuning.ts";
 
 /** Output level of a full-scale sample at velocity 1 and gain 1. */
 export const SAMPLE_LEVEL = 0.7;
@@ -39,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;
@@ -46,6 +72,8 @@ const LOOP_CROSSFADE_SECONDS = 0.005;
 export type SamplerTiming = Readonly<{
   score: TrackScore;
   sampleRate: number;
+  /** The song's tempo map in samples; absent keeps constant tempo. */
+  warp?: SampleWarp;
 }>;
 
 /** One planned voice: when it sounds and how it reads its sample. */
@@ -74,6 +102,10 @@ export type SamplerVoice = {
   readonly ramp: number;
   /** `squiz` ratio; 1 is off. */
   readonly squiz: number;
+  /** Note expression: pitch in cents over time (glide, bend, vibrato). */
+  readonly cents?: NotePerformance["cents"];
+  /** Half pedal: the level fades from `from` seconds. */
+  readonly damp?: NotePerformance["damp"];
 };
 
 /**
@@ -96,7 +128,8 @@ function framesToTravel(distance: number, step: number, ramp: number): number {
 }
 
 function noteStartFrame(note: Note, timing: SamplerTiming): number {
-  const { score, sampleRate } = timing;
+  const { score, sampleRate, warp } = timing;
+  if (warp) return warpedSpan(warp, note.startTick, note.durationTicks).start;
   return Math.max(
     0,
     Math.floor(
@@ -107,7 +140,8 @@ function noteStartFrame(note: Note, timing: SamplerTiming): number {
 }
 
 function noteLengthFrames(note: Note, timing: SamplerTiming): number {
-  const { score, sampleRate } = timing;
+  const { score, sampleRate, warp } = timing;
+  if (warp) return warpedSpan(warp, note.startTick, note.durationTicks).length;
   return Math.max(
     1,
     Math.floor(
@@ -117,9 +151,15 @@ function noteLengthFrames(note: Note, timing: SamplerTiming): number {
   );
 }
 
-/** Which voice a note plays and the pitch ratio it plays at. */
+/**
+ * Which voice a note plays and the pitch ratio it plays at. A keyed voice
+ * repitches to the tuning's key frequency over its root's 12-TET frequency
+ * (a sample is recorded at concert pitch); one-shot slots ignore tuning,
+ * since their pitch picks a voice rather than a note.
+ */
 function voiceResolver(
   track: Track,
+  tuning?: TuningTable,
 ): (pitch: number) => { voice: string; ratio: number } | undefined {
   const sampler = track.sampler!;
   if (sampler.mode === "oneshot") {
@@ -141,7 +181,14 @@ function voiceResolver(
     for (const candidate of keyed)
       if (candidate.root <= pitch) chosen = candidate;
     if (!chosen) return undefined;
-    return { voice: chosen.voice, ratio: 2 ** ((pitch - chosen.root) / 12) };
+    if (!tuning)
+      return { voice: chosen.voice, ratio: 2 ** ((pitch - chosen.root) / 12) };
+    const hz = tuning.hz[pitch]!;
+    if (!(hz > 0)) return undefined;
+    return {
+      voice: chosen.voice,
+      ratio: hz / (440 * 2 ** ((chosen.root - 69) / 12)),
+    };
   };
 }
 
@@ -154,7 +201,10 @@ export function planSamplerVoices(
 ): SamplerVoice[] {
   const sampler = track.sampler;
   if (!sampler) return [];
-  const resolve = voiceResolver(track);
+  const resolve = voiceResolver(
+    track,
+    resolveTuning(timing.score.tuning, track.tuning, timing.score.key),
+  );
   const ordered = [...notes].sort(
     (a, b) =>
       a.startTick - b.startTick ||
@@ -174,27 +224,54 @@ export function planSamplerVoices(
     voice.fade = Math.min(fade, end - voice.start);
   };
   for (const note of ordered) {
-    const target = resolve(note.pitch);
-    if (!target) continue;
+    const resolved = resolve(note.pitch);
+    if (!resolved) continue;
+    // A note's cents repitch every voice, keyed or one-shot.
+    const target = note.cents
+      ? { ...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"
-        ? (timing.score.beatsPerBar * 60) /
-          timing.score.tempoBpm /
-          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
@@ -234,11 +311,18 @@ 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 = {
       voice: target.voice,
       sample,
@@ -257,6 +341,8 @@ export function planSamplerVoices(
       loopSpan: loopTo - loopFrom,
       ramp,
       squiz: ref.squiz ?? 1,
+      ...(performance?.cents ? { cents: performance.cents } : {}),
+      ...(performance?.damp ? { damp: performance.damp } : {}),
     };
     if (voice.choke !== undefined) {
       const previous = lastInGroup.get(voice.choke);
@@ -273,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;
@@ -293,7 +484,7 @@ export function renderSamplerVoices(
   timing: SamplerTiming,
   gainAt: (tick: number) => number,
 ): void {
-  const { sampleRate, score } = timing;
+  const { sampleRate, score, warp } = timing;
   const samplesPerTick =
     (sampleRate * 60) / (score.tempoBpm * score.ticksPerBeat);
   const attack = Math.max(1, ATTACK_SECONDS * sampleRate);
@@ -311,10 +502,31 @@ export function renderSamplerVoices(
     const level = SAMPLE_LEVEL * voice.gain;
     const at = (offset: number) =>
       readAt(mono, reverse ? regionEnd - 1 - offset : regionStart + offset);
+    // A bent voice (note expression) integrates its rate frame by frame;
+    // reads arrive in order, so the running sum is kept between calls.
+    const bent = voice.cents;
+    let bentAt = 0;
+    let bentTravel = 0;
+    const travel = (elapsed: number): number => {
+      if (!bent)
+        return ramp === 0 ? elapsed * step : travelAt(elapsed, step, ramp);
+      if (elapsed < bentAt) {
+        bentAt = 0;
+        bentTravel = 0;
+      }
+      while (bentAt < elapsed) {
+        const rate =
+          step *
+          (ramp === 0 ? 1 : Math.max(0, 1 + ramp * bentAt)) *
+          2 ** (bent(bentAt / sampleRate) / 1200);
+        bentTravel += rate;
+        bentAt += 1;
+      }
+      return bentTravel;
+    };
     // The raw read at an elapsed frame, or undefined past a one-shot's end.
     const read = (elapsed: number): number | undefined => {
-      const travelled =
-        ramp === 0 ? elapsed * step : travelAt(elapsed, step, ramp);
+      const travelled = travel(elapsed);
       if (!loop) return travelled >= span ? undefined : at(travelled);
       if (travelled < loopStart) return at(travelled);
       const into = travelled - loopStart;
@@ -339,11 +551,16 @@ export function renderSamplerVoices(
       if (value === undefined) break;
       let envelope = Math.min(1, elapsed / attack);
       if (index >= fadeFrom) envelope *= (voice.end - index) / voice.fade;
+      const damp = voice.damp;
+      if (damp && elapsed / sampleRate > damp.from)
+        envelope *= Math.exp(-(elapsed / sampleRate - damp.from) / damp.tau);
       target[index]! +=
         value *
         envelope *
         level *
-        gainAt(voice.startTick + elapsed / samplesPerTick);
+        gainAt(
+          warp ? warp.tick(index) : voice.startTick + elapsed / samplesPerTick,
+        );
     }
   }
 }
@@ -406,15 +623,33 @@ export function samplerTailSeconds(
   sampleRate: number,
 ): number {
   if (bank.voices.size === 0) return 0;
-  const loopEnd =
-    ((score.bars * score.beatsPerBar * 60) / score.tempoBpm) * sampleRate;
-  const timing = { score, sampleRate };
+  const loopEnd = loopSecondsOf(score) * sampleRate;
+  const warp = sampleWarpFor(score, sampleRate);
+  const timing = { score, sampleRate, ...(warp ? { warp } : {}) };
   let latest = 0;
+  const performance = performanceTimingFor(score);
   for (const track of score.tracks) {
     if (!track.sampler) continue;
-    const notes = score.notes.filter((note) => note.trackId === track.id);
+    const notes = performNotes(
+      track,
+      performedNotes(score).filter((note) => note.trackId === track.id),
+      tunedTiming(performance, score, track),
+    );
     for (const voice of planSamplerVoices(track, notes, bank, timing))
       latest = Math.max(latest, voice.end - loopEnd);
   }
   return latest / sampleRate;
 }
+
+/**
+ * Seconds of the bar (a `c` cycle) holding `tick`: through the meter and
+ * the tempo map when the song has `time`, else the 0.4 arithmetic.
+ */
+function cycleSeconds(score: TrackScore, tick: number): number {
+  if (!score.time) return (score.beatsPerBar * 60) / score.tempoBpm;
+  const bar = barAt(score, tick);
+  return (
+    secondsAtTick(score, bar.tick + bar.barTicks) -
+    secondsAtTick(score, bar.tick)
+  );
+}

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 {