@hraness/dawg 0.4.1 → 0.6.0

package/src/audio/clock.ts

@@ -1,7 +1,40 @@
+import { loopTicksOf, timeMapFor, type TimeScore } from "../../core/tempo.ts";
+
+/**
+ * Beats and seconds through a song's tempo map, one loop at a time: the
+ * transport runs in score beats, and the map says how long each loop pass
+ * takes. Absent, the clock keeps its constant-tempo arithmetic.
+ */
+export type TransportMap = Readonly<{
+  loopBeats: number;
+  loopSeconds: number;
+  /** Seconds into a loop pass at `beat` (0..loopBeats). */
+  seconds(beat: number): number;
+  /** Beat inside a loop pass at `seconds` (0..loopSeconds). */
+  beat(seconds: number): number;
+}>;
+
+/** The transport map for a score, or undefined at a constant tempo. */
+export function transportMapFor(score: TimeScore): TransportMap | undefined {
+  const map = timeMapFor(score);
+  if (!map) return undefined;
+  const tpb = score.ticksPerBeat;
+  const loopBeats = loopTicksOf(score) / tpb;
+  const loopSeconds = map.seconds(loopTicksOf(score));
+  if (!(loopBeats > 0) || !(loopSeconds > 0)) return undefined;
+  return Object.freeze({
+    loopBeats,
+    loopSeconds,
+    seconds: (beat: number) => map.seconds(beat * tpb),
+    beat: (seconds: number) => map.tick(seconds) / tpb,
+  });
+}
+
 export class TransportClock {
   private startedAtMs: number | undefined;
   private pausedBeat = 0;
   private bpm: number;
+  private map: TransportMap | undefined;
 
   constructor(bpm = 120) {
     this.bpm = bpm;
@@ -24,6 +57,7 @@ export class TransportClock {
 
   beatAt(nowMs = performance.now()): number {
     if (this.startedAtMs === undefined) return this.pausedBeat;
+    if (this.map) return Math.max(0, this.msToBeat(nowMs - this.startedAtMs));
     return Math.max(0, (nowMs - this.startedAtMs) / this.beatToMs(1));
   }
 
@@ -40,6 +74,25 @@ export class TransportClock {
     else this.pausedBeat = beat;
   }
 
+  /**
+   * Follow a song's tempo map (`transportMapFor`), keeping the current
+   * beat; undefined returns to the constant `bpm`.
+   */
+  setTimeMap(map: TransportMap | undefined, nowMs = performance.now()): void {
+    if (map === this.map) return;
+    const beat = this.beatAt(nowMs);
+    this.map = map;
+    if (this.startedAtMs !== undefined)
+      this.startedAtMs = nowMs - this.beatToMs(beat);
+    else this.pausedBeat = beat;
+  }
+
+  /** Follow a score's start tempo and tempo map. */
+  follow(score: TimeScore, nowMs = performance.now()): void {
+    this.setTempo(score.tempoBpm, nowMs);
+    this.setTimeMap(transportMapFor(score), nowMs);
+  }
+
   /** Converge to a timestamped transport event from another TUI process. */
   sync(
     beat: number,
@@ -50,10 +103,10 @@ export class TransportClock {
   ): void {
     if (!Number.isFinite(beat) || beat < 0) return;
     if (!Number.isFinite(eventAtMs) || !Number.isFinite(nowWallMs)) return;
-    const elapsed = playing
-      ? Math.max(0, nowWallMs - eventAtMs) / this.beatToMs(1)
-      : 0;
-    const currentBeat = beat + elapsed;
+    const elapsedMs = playing ? Math.max(0, nowWallMs - eventAtMs) : 0;
+    const currentBeat = this.map
+      ? this.msToBeat(this.beatToMs(beat) + elapsedMs)
+      : beat + elapsedMs / this.beatToMs(1);
     if (playing) {
       this.startedAtMs = nowMonotonicMs - this.beatToMs(currentBeat);
     } else {
@@ -63,6 +116,19 @@ export class TransportClock {
   }
 
   private beatToMs(beats: number): number {
-    return (beats * 60_000) / this.bpm;
+    const map = this.map;
+    if (!map) return (beats * 60_000) / this.bpm;
+    const loops = Math.floor(beats / map.loopBeats);
+    const inner = beats - loops * map.loopBeats;
+    return (loops * map.loopSeconds + map.seconds(inner)) * 1000;
+  }
+
+  private msToBeat(ms: number): number {
+    const map = this.map;
+    if (!map) return ms / this.beatToMs(1);
+    const seconds = ms / 1000;
+    const loops = Math.floor(seconds / map.loopSeconds);
+    const inner = seconds - loops * map.loopSeconds;
+    return loops * map.loopBeats + map.beat(inner);
   }
 }

package/src/audio/dsp/bank.ts

@@ -0,0 +1,233 @@
+/**
+ * Shared grain bank (0.6 granular, shared DSP): a source band-limited at
+ * one level per semitone of upward read speed, so grains read at any step
+ * stay alias-free with a 4-point Hermite read.
+ *
+ * Level `L` holds the source low-passed so that reading it at a step of up
+ * to 2^(L/12) puts the stopband edge at or below the output Nyquist (a
+ * Kaiser-windowed sinc, about -70 dB stopband, transition scaled with the
+ * step so the output passband reaches about 0.43 of the output rate at
+ * every level). Level 0 is the source itself (steps <= 1 never alias).
+ * Every level keeps the source's frame rate, so a voice that changes its
+ * step (bend, vibrato, glide) re-picks the level per 32-frame control
+ * block without moving its read position.
+ *
+ * This replaces the prototype's octave mipmap (`proto/granular/dsp.ts`,
+ * `buildMipmap`) after the 0.6 review: octave levels over-filter
+ * non-octave intervals (a shimmer fifth lost up to 11 semitones of top
+ * band) and full-length Float64 levels had no memory bound. Here a level
+ * is a sparse map of Float32 chunks filled on first read, and all chunks of
+ * all sources share one byte budget (64 MB) evicted least recently used;
+ * an eviction only costs a recompute. Output is deterministic: a chunk's
+ * contents depend only on the source, the level and the chunk index.
+ */
+
+/** Frames per chunk (a power of two). */
+export const BANK_CHUNK_FRAMES = 4096;
+const CHUNK_SHIFT = 12;
+/** Chunks carry one frame before and two after for the Hermite read. */
+export const BANK_CHUNK_PAD = 3;
+/** Highest level (five octaves up); faster reads use it and may alias. */
+export const BANK_MAX_LEVEL = 60;
+/** Byte budget shared by every source's chunks. */
+export const BANK_MAX_BYTES = 64 * 1024 * 1024;
+
+const STOPBAND_DB = 70;
+const KAISER_BETA = 0.1102 * (STOPBAND_DB - 8.7);
+/** Taps at step 1 (scaled up with the step, capped). */
+const BASE_TAPS = 96;
+const MAX_TAPS = 511;
+
+/** A mono source registered with the bank. */
+export type BankSource = Readonly<{
+  /** Content id: a sample's sha256 or a built-in render key. */
+  id: string;
+  rate: number;
+  data: Float32Array;
+}>;
+
+type Chunk = Float32Array;
+
+/**
+ * Chunks per source (`id` and rate) keyed by level and index as one number.
+ * Grains look a chunk up every 32-frame block, so the lookup avoids string
+ * keys and the LRU order is a use counter (scanned only to evict).
+ */
+type Entry = { chunk: Chunk; used: number };
+const chunks = new Map<string, Map<number, Entry>>();
+const sourceTables = new WeakMap<BankSource, Map<number, Entry>>();
+let count = 0;
+let clock = 0;
+let bytes = 0;
+let byteCap = BANK_MAX_BYTES;
+const ZERO_CHUNK = new Float32Array(BANK_CHUNK_FRAMES + BANK_CHUNK_PAD);
+const kernels = new Map<number, Float64Array>();
+
+/** The level for a read step (frames of source per output frame). */
+export function bankLevel(step: number): number {
+  const r = step < 0 ? -step : step;
+  if (r <= 1 + 1e-9) return 0;
+  const level = Math.ceil(12 * Math.log2(r) - 1e-6);
+  return level > BANK_MAX_LEVEL ? BANK_MAX_LEVEL : level;
+}
+
+function besselI0(x: number): number {
+  let sum = 1;
+  let term = 1;
+  const q = (x * x) / 4;
+  for (let k = 1; k < 64; k += 1) {
+    term *= q / (k * k);
+    sum += term;
+    if (term < sum * 1e-17) break;
+  }
+  return sum;
+}
+
+/** The low-pass kernel of a level (odd length, unity DC gain). */
+export function bankKernel(level: number): Float64Array {
+  let h = kernels.get(level);
+  if (h) return h;
+  const r = 2 ** (level / 12);
+  let taps = Math.min(MAX_TAPS, Math.ceil(BASE_TAPS * r));
+  if (taps % 2 === 0) taps += 1;
+  // Kaiser transition width for the tap count, centred inside the band.
+  const transition = (STOPBAND_DB - 8) / (2.285 * 2 * Math.PI * (taps - 1));
+  const fc = Math.max(0.01, 0.5 / r - transition / 2);
+  h = new Float64Array(taps);
+  const mid = (taps - 1) / 2;
+  const norm = besselI0(KAISER_BETA);
+  let sum = 0;
+  for (let i = 0; i < taps; i += 1) {
+    const m = i - mid;
+    const sinc =
+      m === 0 ? 2 * fc : Math.sin(2 * Math.PI * fc * m) / (Math.PI * m);
+    const ratio = m / mid;
+    const w = besselI0(KAISER_BETA * Math.sqrt(1 - ratio * ratio)) / norm;
+    h[i] = sinc * w;
+    sum += h[i]!;
+  }
+  for (let i = 0; i < taps; i += 1) h[i] = h[i]! / sum;
+  kernels.set(level, h);
+  return h;
+}
+
+function fill(source: BankSource, level: number, index: number): Chunk {
+  const out = new Float32Array(BANK_CHUNK_FRAMES + BANK_CHUNK_PAD);
+  const data = source.data;
+  const n = data.length;
+  const first = index * BANK_CHUNK_FRAMES - 1;
+  if (level === 0) {
+    for (let i = 0; i < out.length; i += 1) {
+      const k = first + i;
+      out[i] = k >= 0 && k < n ? data[k]! : 0;
+    }
+    return out;
+  }
+  const h = bankKernel(level);
+  const taps = h.length;
+  const mid = (taps - 1) >> 1;
+  for (let i = 0; i < out.length; i += 1) {
+    const centre = first + i;
+    const lo = centre - mid;
+    let from = 0;
+    let to = taps;
+    if (lo < 0) from = -lo;
+    if (lo + to > n) to = n - lo;
+    let acc = 0;
+    for (let j = from; j < to; j += 1) acc += h[j]! * data[lo + j]!;
+    out[i] = acc;
+  }
+  return out;
+}
+
+/**
+ * The chunk holding frames `index * 4096 - 1 .. (index + 1) * 4096 + 2` of
+ * `level`; a frame `i` of the level is `chunk[(i & 4095) + 1]`. Chunks
+ * wholly outside the source are a shared zero chunk.
+ */
+export function bankChunk(
+  source: BankSource,
+  level: number,
+  index: number,
+): Chunk {
+  if (index < 0 || index * BANK_CHUNK_FRAMES > source.data.length + 2)
+    return ZERO_CHUNK;
+  let table = sourceTables.get(source);
+  if (!table) {
+    const id = `${source.id}\u0000${source.rate}`;
+    table = chunks.get(id);
+    if (!table) chunks.set(id, (table = new Map()));
+    sourceTables.set(source, table);
+  }
+  const key = level * 2 ** 32 + index;
+  clock += 1;
+  const hit = table.get(key);
+  if (hit) {
+    hit.used = clock;
+    return hit.chunk;
+  }
+  const chunk = fill(source, level, index);
+  table.set(key, { chunk, used: clock });
+  count += 1;
+  bytes += chunk.byteLength;
+  if (bytes > byteCap) evict();
+  return chunk;
+}
+
+/** Drops least recently used chunks until under the budget (keeps one). */
+function evict(): void {
+  const all: { table: Map<number, Entry>; key: number; used: number }[] = [];
+  for (const table of chunks.values())
+    for (const [key, entry] of table)
+      all.push({ table, key, used: entry.used });
+  all.sort((a, b) => a.used - b.used);
+  for (const { table, key } of all) {
+    if (bytes <= byteCap || count <= 1) break;
+    bytes -= table.get(key)!.chunk.byteLength;
+    table.delete(key);
+    count -= 1;
+  }
+}
+
+/** Chunk index of a level frame. */
+export function chunkIndex(frame: number): number {
+  return frame >> CHUNK_SHIFT;
+}
+
+/** Hermite read of `level` at a fractional frame (slow path, tests). */
+export function bankRead(
+  source: BankSource,
+  level: number,
+  pos: number,
+): number {
+  const i = Math.floor(pos);
+  const t = pos - i;
+  const chunk = bankChunk(source, level, i >> CHUNK_SHIFT);
+  const o = (i & (BANK_CHUNK_FRAMES - 1)) + 1;
+  const xm1 = chunk[o - 1]!;
+  const x0 = chunk[o]!;
+  const x1 = chunk[o + 1]!;
+  const x2 = chunk[o + 2]!;
+  const c1 = 0.5 * (x1 - xm1);
+  const c2 = xm1 - 2.5 * x0 + 2 * x1 - 0.5 * x2;
+  const c3 = 0.5 * (x2 - xm1) + 1.5 * (x0 - x1);
+  return ((c3 * t + c2) * t + c1) * t + x0;
+}
+
+/** Bytes held by chunks now. */
+export function bankBytes(): number {
+  return bytes;
+}
+
+/** Chunks held now. */
+export function bankChunks(): number {
+  return count;
+}
+
+/** Drops every chunk; with `cap`, sets a new byte budget (tests). */
+export function resetBank(cap: number = BANK_MAX_BYTES): void {
+  for (const table of chunks.values()) table.clear();
+  count = 0;
+  bytes = 0;
+  byteCap = Math.max(0, cap);
+}

package/src/audio/dsp/fft.ts

@@ -0,0 +1,6 @@
+/**
+ * The shared radix-2 FFT: a re-export of the convolution reverb's
+ * `fftInPlace` (cached tables; `inverse` uses e^{+i} and no scaling).
+ * Lanes that need windows or STFTs build them on this one transform.
+ */
+export { fftInPlace } from "../effects/convolution.ts";

package/src/audio/dsp/filters.ts

@@ -0,0 +1,57 @@
+/**
+ * Small per-sample filters for 0.6 instruments. `Biquad` is the existing
+ * RBJ biquad (src/audio/effects/common.ts), re-exported unchanged.
+ */
+export { Biquad, type FilterType } from "../effects/common.ts";
+
+function clamp(x: number, lo: number, hi: number): number {
+  return x < lo ? lo : x > hi ? hi : x;
+}
+
+/** One-pole lowpass y += (1 - p)(x - y), corner `hz`. */
+export class OnePole {
+  p = 0;
+  y = 0;
+
+  constructor(hz: number, sampleRate: number) {
+    this.set(hz, sampleRate);
+  }
+
+  set(hz: number, sampleRate: number): void {
+    this.p = Math.exp(
+      (-2 * Math.PI * clamp(hz, 1, sampleRate * 0.49)) / sampleRate,
+    );
+  }
+
+  process(x: number): number {
+    this.y = x + this.p * (this.y - x);
+    return this.y;
+  }
+
+  reset(): void {
+    this.y = 0;
+  }
+}
+
+/** DC blocker y = x - x1 + R y1 (R ≈ 0.996 at 22.05 kHz for a 15 Hz corner). */
+export class DcBlock {
+  r: number;
+  x1 = 0;
+  y1 = 0;
+
+  constructor(sampleRate: number, hz = 15) {
+    this.r = Math.exp((-2 * Math.PI * hz) / sampleRate);
+  }
+
+  process(x: number): number {
+    const y = x - this.x1 + this.r * this.y1;
+    this.x1 = x;
+    this.y1 = y;
+    return y;
+  }
+
+  reset(): void {
+    this.x1 = 0;
+    this.y1 = 0;
+  }
+}

package/src/audio/dsp/interp.ts

@@ -0,0 +1,112 @@
+/**
+ * Interpolation and fractional delay for 0.6 instruments: 4-point Hermite
+ * reads (grains, modulated delays) and a first-order Thiran allpass
+ * fractional delay (string loops: flat magnitude, exact phase delay).
+ */
+
+/** 4-point, 3rd-order Hermite (Catmull-Rom) through xm1 x0 x1 x2 at t in [0, 1). */
+export function hermite4(
+  xm1: number,
+  x0: number,
+  x1: number,
+  x2: number,
+  t: number,
+): number {
+  const c1 = 0.5 * (x1 - xm1);
+  const c2 = xm1 - 2.5 * x0 + 2 * x1 - 0.5 * x2;
+  const c3 = 0.5 * (x2 - xm1) + 1.5 * (x0 - x1);
+  return ((c3 * t + c2) * t + c1) * t + x0;
+}
+
+/** Hermite read of `x` at fractional position `pos`; zero outside the buffer. */
+export function hermiteAt(x: Float64Array, pos: number): number {
+  const i = Math.floor(pos);
+  const n = x.length;
+  const at = (k: number): number => (k >= 0 && k < n ? x[k]! : 0);
+  return hermite4(at(i - 1), at(i), at(i + 1), at(i + 2), pos - i);
+}
+
+function clamp(x: number, lo: number, hi: number): number {
+  return x < lo ? lo : x > hi ? hi : x;
+}
+
+/** Phase delay (samples) at `w` rad/sample of the allpass (a + z^-1)/(1 + a z^-1). */
+export function allpassDelay(a: number, w: number): number {
+  if (w < 1e-9) return (1 - a) / (1 + a);
+  const s = Math.sin(w);
+  const c = Math.cos(w);
+  const num = Math.atan2(-s, a + c);
+  const den = Math.atan2(-a * s, 1 + a * c);
+  let phase = num - den;
+  while (phase > 0) phase -= 2 * Math.PI;
+  while (phase <= -2 * Math.PI) phase += 2 * Math.PI;
+  return -phase / w;
+}
+
+/**
+ * First-order Thiran allpass coefficient whose phase delay at `w` is exactly
+ * `d` samples (d in [0.5, 1.5)): Thiran's closed form, then Newton steps.
+ * With w = 0 this is (1 - d) / (1 + d), exact at DC.
+ */
+export function thiranFor(d: number, w = 0): number {
+  let a = (1 - d) / (1 + d);
+  if (w < 1e-9) return a;
+  for (let i = 0; i < 4; i += 1) {
+    const f = allpassDelay(a, w) - d;
+    if (Math.abs(f) < 1e-10) break;
+    const h = 1e-6;
+    const df = (allpassDelay(a + h, w) - allpassDelay(a - h, w)) / (2 * h);
+    if (df === 0) break;
+    a = clamp(a - f / df, -0.9, 0.9);
+  }
+  return a;
+}
+
+/**
+ * A delay of `delay` samples (>= 0.5): an integer delay line plus a Thiran
+ * allpass for the fraction in [0.5, 1.5), so the pole stays well inside the
+ * unit circle. `set` may be called between samples (string pitch moves);
+ * the allpass state carries over, which is the usual small transient.
+ */
+export class FracDelay {
+  private readonly buffer: Float64Array;
+  private readonly mask: number;
+  private write = 0;
+  private whole = 0;
+  private a = 0;
+  private u1 = 0;
+  private y1 = 0;
+
+  constructor(maxDelay: number, delay = 1, w = 0) {
+    let size = 4;
+    while (size < Math.ceil(maxDelay) + 4) size *= 2;
+    this.buffer = new Float64Array(size);
+    this.mask = size - 1;
+    this.set(delay, w);
+  }
+
+  /** Total delay in samples; `w` is where the phase delay is exact (rad/sample). */
+  set(delay: number, w = 0): void {
+    const total = clamp(delay, 0.5, this.mask - 2);
+    const whole = Math.max(0, Math.floor(total - 0.5));
+    this.whole = whole;
+    this.a = thiranFor(total - whole, w);
+  }
+
+  process(x: number): number {
+    const b = this.buffer;
+    b[this.write] = x;
+    const u = b[(this.write - this.whole) & this.mask]!;
+    this.write = (this.write + 1) & this.mask;
+    const y = this.a * u + this.u1 - this.a * this.y1;
+    this.u1 = u;
+    this.y1 = y;
+    return y;
+  }
+
+  reset(): void {
+    this.buffer.fill(0);
+    this.u1 = 0;
+    this.y1 = 0;
+  }
+}