@hraness/dawg 0.3.0 → 0.4.1

package/src/audio/cache.ts

@@ -0,0 +1,160 @@
+/**
+ * Disk cache budgets and LRU pruning for pack downloads and decoded assets.
+ *
+ * Two caches hold audio on disk:
+ *
+ * - raw pack files, `~/.cache/dawg/packs/files/<sha256(url)>.bin`, shared by
+ *   every project (default cap `DEFAULT_PACKS_CACHE_BYTES`, env
+ *   `DAWG_PACKS_CACHE_MAX`);
+ * - decoded PCM, `<project>/.dawg/assets/<sha256>.pcm`, per project (default
+ *   cap `DEFAULT_ASSETS_CACHE_BYTES`, env `DAWG_ASSETS_CACHE_MAX`).
+ *
+ * Both evict least recently used files first (hits refresh the mtime) and
+ * never evict a protected file: the ones the open project pins. An evicted
+ * pack file is fetched again by its pinned URL and checked against its
+ * pinned sha256, so eviction only ever costs a download.
+ */
+import { readdir, stat, unlink } from "node:fs/promises";
+import { join } from "node:path";
+import { SCORE_LIMITS } from "../../core/score.ts";
+
+const MiB = 1024 * 1024;
+const GiB = 1024 * MiB;
+
+/**
+ * Raw pack downloads. 2 GiB holds every file a typical user touches across
+ * the built-in packs (a whole drum-machine bank is a few MiB, a GM
+ * instrument 1–4 MiB of MP3, a uzu wavetable 1–2 MiB) with room to spare,
+ * and stays small next to a browser cache on a laptop disk.
+ */
+export const DEFAULT_PACKS_CACHE_BYTES = 2 * GiB;
+/**
+ * Decoded float32 PCM per project. Decoding grows audio 2× (16-bit WAV) to
+ * ~10× (MP3), so 1 GiB is about 100 minutes of mono 44.1 kHz audio: far
+ * more than a project plays, while a few projects cannot fill a disk.
+ */
+export const DEFAULT_ASSETS_CACHE_BYTES = 1 * GiB;
+/** Decoded samples kept in memory by one `SampleLibrary`. */
+export const DEFAULT_MEMORY_CACHE_BYTES = SCORE_LIMITS.maxSampleCacheBytes;
+
+const SIZE =
+  /^\s*([0-9]+(?:\.[0-9]+)?)\s*(b|k|kb|kib|m|mb|mib|g|gb|gib|t|tb|tib)?\s*$/i;
+
+/**
+ * Bytes from `"2GiB"`, `"512M"`, `"1.5g"`, `"1048576"` (units are binary);
+ * undefined when malformed or negative.
+ */
+export function parseByteSize(value: string): number | undefined {
+  const match = SIZE.exec(value);
+  if (!match) return undefined;
+  const amount = Number(match[1]);
+  const unit = (match[2] ?? "b").toLowerCase()[0]!;
+  const scale =
+    unit === "k"
+      ? 1024
+      : unit === "m"
+        ? MiB
+        : unit === "g"
+          ? GiB
+          : unit === "t"
+            ? 1024 * GiB
+            : 1;
+  const bytes = Math.floor(amount * scale);
+  return Number.isFinite(bytes) && bytes >= 0 ? bytes : undefined;
+}
+
+function fromEnv(
+  name: string,
+  fallback: number,
+  env: NodeJS.ProcessEnv,
+): number {
+  const raw = env[name];
+  if (raw === undefined || raw.trim() === "") return fallback;
+  return parseByteSize(raw) ?? fallback;
+}
+
+/** Raw pack file cap: `DAWG_PACKS_CACHE_MAX` or 2 GiB. */
+export function packsCacheMax(env: NodeJS.ProcessEnv = process.env): number {
+  return fromEnv("DAWG_PACKS_CACHE_MAX", DEFAULT_PACKS_CACHE_BYTES, env);
+}
+
+/** Decoded asset cap: `DAWG_ASSETS_CACHE_MAX` or 1 GiB. */
+export function assetsCacheMax(env: NodeJS.ProcessEnv = process.env): number {
+  return fromEnv("DAWG_ASSETS_CACHE_MAX", DEFAULT_ASSETS_CACHE_BYTES, env);
+}
+
+export type CacheUsage = Readonly<{ files: number; bytes: number }>;
+
+type Entry = { name: string; path: string; bytes: number; used: number };
+
+async function entries(dir: string, pattern: RegExp): Promise<Entry[]> {
+  const names = await readdir(dir).catch(() => [] as string[]);
+  const out: Entry[] = [];
+  for (const name of names) {
+    if (!pattern.test(name)) continue;
+    const path = join(dir, name);
+    const info = await stat(path).catch(() => undefined);
+    if (info?.isFile())
+      out.push({ name, path, bytes: info.size, used: info.mtimeMs });
+  }
+  return out;
+}
+
+/** Files and bytes of the cache entries in `dir` matching `pattern`. */
+export async function cacheUsage(
+  dir: string,
+  pattern: RegExp,
+): Promise<CacheUsage> {
+  const list = await entries(dir, pattern);
+  return {
+    files: list.length,
+    bytes: list.reduce((sum, entry) => sum + entry.bytes, 0),
+  };
+}
+
+export type PruneResult = Readonly<{
+  removed: number;
+  freed: number;
+  /** Bytes left, protected files included. */
+  bytes: number;
+}>;
+
+/**
+ * Deletes least recently used entries until `dir` holds at most `maxBytes`.
+ * `keep(name)` protects an entry (the open project's pins, the file being
+ * written); protected entries count toward the total but are never removed,
+ * so a project larger than the cap keeps everything it uses.
+ */
+export async function pruneLru(
+  dir: string,
+  pattern: RegExp,
+  maxBytes: number,
+  keep: (name: string) => boolean = () => false,
+): Promise<PruneResult> {
+  const list = await entries(dir, pattern);
+  let total = list.reduce((sum, entry) => sum + entry.bytes, 0);
+  list.sort((a, b) => a.used - b.used || a.name.localeCompare(b.name));
+  let removed = 0;
+  let freed = 0;
+  for (const entry of list) {
+    if (total <= maxBytes) break;
+    if (keep(entry.name)) continue;
+    try {
+      await unlink(entry.path);
+    } catch {
+      continue;
+    }
+    total -= entry.bytes;
+    freed += entry.bytes;
+    removed += 1;
+  }
+  return { removed, freed, bytes: total };
+}
+
+/** `1.5 GiB`, `320 MiB`, `12 KiB`. */
+export function formatBytes(bytes: number): string {
+  if (bytes >= GiB) return `${Math.round((bytes / GiB) * 10) / 10} GiB`;
+  if (bytes >= MiB) return `${Math.round((bytes / MiB) * 10) / 10} MiB`;
+  if (bytes >= 1024) return `${Math.round(bytes / 1024)} KiB`;
+  return `${bytes} B`;
+}

package/src/audio/effects/bus.ts

@@ -0,0 +1,147 @@
+/**
+ * Shared orbit buses (Strudel orbits): tracks whose `fx.orbit` sets
+ * `shared` send into one delay and one reverb per orbit instead of running
+ * their own.
+ *
+ * Each member's finished stem (its chain up to, not including, delay and
+ * reverb) is sent to the bus delay at its `delay.mix` and to the bus reverb
+ * at its `reverb.mix`, both following their mix lanes. The bus delay takes
+ * its time, feedback, ping-pong and highcut from the first member in score
+ * order that has a delay; the bus reverb takes its settings (size, fade,
+ * impulse...) from the first member with a reverb. The two run in parallel
+ * and their wet outputs join the mix after every stem, in orbit order. Both
+ * are linear, so a bus with one member sounds like that track's own delay
+ * and reverb run in parallel.
+ */
+import type { Track } from "../../../core/score.ts";
+import {
+  CONTROL_SAMPLES,
+  interpolateAutomation,
+  type EffectContext,
+} from "./common.ts";
+import { applyDelay, applyReverb } from "./space.ts";
+
+/** The orbit whose shared bus a track sends to, if any. */
+export function sharedOrbitOf(track: Track | undefined): number | undefined {
+  const orbit = track?.fx?.orbit;
+  return orbit?.shared === true ? Number(orbit.orbit) : undefined;
+}
+
+export type OrbitBus = {
+  readonly orbit: number;
+  delayLead?: Track;
+  reverbLead?: Track;
+  readonly delayL: Float64Array;
+  readonly delayR: Float64Array;
+  readonly reverbL: Float64Array;
+  readonly reverbR: Float64Array;
+  /** Member stem keys in send order: the bus output's cache key. */
+  readonly keys: string[];
+};
+
+export function createOrbitBus(orbit: number, samples: number): OrbitBus {
+  return {
+    orbit,
+    delayL: new Float64Array(samples),
+    delayR: new Float64Array(samples),
+    reverbL: new Float64Array(samples),
+    reverbR: new Float64Array(samples),
+    keys: [],
+  };
+}
+
+/** Adds `level(t)·stem` into a send pair; the level steps per control block. */
+function send(
+  outL: Float64Array,
+  outR: Float64Array,
+  stemL: Float64Array,
+  stemR: Float64Array,
+  base: number,
+  lane: readonly Readonly<{ tick: number; value: number }>[],
+  samplesPerTick: number,
+): void {
+  if (base <= 0 && lane.length === 0) return;
+  let level = base;
+  for (let index = 0; index < outL.length; index += 1) {
+    if (lane.length > 0 && index % CONTROL_SAMPLES === 0)
+      level = interpolateAutomation(lane, index / samplesPerTick, base);
+    outL[index]! += stemL[index]! * level;
+    outR[index]! += stemR[index]! * level;
+  }
+}
+
+/** Sends one member's stem to its bus. */
+export function sendToBus(
+  bus: OrbitBus,
+  track: Track,
+  stemL: Float64Array,
+  stemR: Float64Array,
+  context: EffectContext,
+  key: string,
+): void {
+  bus.keys.push(key);
+  if (track.delay) {
+    bus.delayLead ??= track;
+    send(
+      bus.delayL,
+      bus.delayR,
+      stemL,
+      stemR,
+      track.delay.mix,
+      track.delayMixAutomation ?? [],
+      context.samplesPerTick,
+    );
+  }
+  if (track.reverb) {
+    bus.reverbLead ??= track;
+    send(
+      bus.reverbL,
+      bus.reverbR,
+      stemL,
+      stemR,
+      track.reverb.mix,
+      track.fxAutomation?.["reverb-mix"] ?? [],
+      context.samplesPerTick,
+    );
+  }
+}
+
+/**
+ * Runs the bus delay and reverb on their sends, wet only, into a fresh
+ * stereo pair (the send buffers are consumed).
+ */
+export function renderOrbitBus(
+  bus: OrbitBus,
+  context: EffectContext,
+): { left: Float64Array; right: Float64Array } {
+  const left = new Float64Array(bus.delayL.length);
+  const right = new Float64Array(bus.delayL.length);
+  const lead = bus.delayLead;
+  if (lead?.delay) {
+    const unity: Track = {
+      ...lead,
+      delay: { ...lead.delay, mix: 1 },
+      delayMixAutomation: [],
+    };
+    applyDelay(bus.delayL, bus.delayR, unity, context, true);
+    for (let index = 0; index < left.length; index += 1) {
+      left[index]! += bus.delayL[index]!;
+      right[index]! += bus.delayR[index]!;
+    }
+  }
+  const room = bus.reverbLead;
+  if (room?.reverb) {
+    const { "reverb-mix": _lane, ...fxAutomation } = room.fxAutomation ?? {};
+    const unity: Track = {
+      ...room,
+      reverb: { ...room.reverb, mix: 1 },
+      fxAutomation,
+    };
+    applyReverb(bus.reverbL, bus.reverbR, unity, context, true);
+    for (let index = 0; index < left.length; index += 1) {
+      left[index]! += bus.reverbL[index]!;
+      right[index]! += bus.reverbR[index]!;
+    }
+  }
+  return { left, right };
+}

package/src/audio/effects/chain.ts

@@ -0,0 +1,109 @@
+/**
+ * The fixed per-track effects chain (`FX_CHAIN` in core/fx.ts):
+ *
+ *   filter → djf → autofilter → vowel → crush → distort → tremolo →
+ *   compressor → pan → phaser → chorus → leslie → postgain → delay → reverb
+ *
+ * Stages before pan run on the mono voice sum; pan spreads it to stereo;
+ * the rest run on the stereo pair. Disabled stages cost nothing.
+ */
+import { FX_CHAIN, type FxName, type FxValues } from "../../../core/fx.ts";
+import type { Track } from "../../../core/score.ts";
+import type { EffectContext } from "./common.ts";
+import { applyCrush, applyDistort } from "./drive.ts";
+import { applyCompressor, applyPostgain, applyTremolo } from "./dynamics.ts";
+import {
+  applyAutoFilter,
+  applyDjFilter,
+  applyTrackFilter,
+  applyVowel,
+} from "./filter.ts";
+import { applyChorus, applyLeslie, applyPhaser } from "./modulation.ts";
+import { applyDelay, applyReverb } from "./space.ts";
+
+export {
+  addReverbWet,
+  delayTailFor,
+  reverbActive,
+  reverbImpulse,
+  reverbTailFor,
+  reverbWet,
+  type ReverbWet,
+} from "./space.ts";
+export { interpolateAutomation, type EffectContext } from "./common.ts";
+
+type MonoStage = (
+  buffer: Float64Array,
+  track: Track,
+  values: FxValues,
+  context: EffectContext,
+) => void;
+type StereoStage = (
+  left: Float64Array,
+  right: Float64Array,
+  track: Track,
+  values: FxValues,
+  context: EffectContext,
+) => void;
+
+const MONO: Readonly<Partial<Record<FxName, MonoStage>>> = Object.freeze({
+  djf: applyDjFilter,
+  autofilter: applyAutoFilter,
+  vowel: applyVowel,
+  crush: applyCrush,
+  distort: applyDistort,
+  tremolo: applyTremolo,
+  compressor: applyCompressor,
+});
+
+const STEREO: Readonly<Partial<Record<FxName, StereoStage>>> = Object.freeze({
+  phaser: applyPhaser,
+  chorus: applyChorus,
+  leslie: applyLeslie,
+  postgain: applyPostgain,
+});
+
+const PAN_INDEX = FX_CHAIN.indexOf("pan");
+
+/** Mono stages, in chain order, on the track's dry voice sum. */
+export function applyMonoChain(
+  buffer: Float64Array,
+  track: Track,
+  context: EffectContext,
+): void {
+  for (const stage of FX_CHAIN.slice(0, PAN_INDEX)) {
+    if (stage === "filter") {
+      applyTrackFilter(buffer, track, context);
+      continue;
+    }
+    const values = track.fx?.[stage as FxName];
+    const apply = MONO[stage as FxName];
+    if (values && apply) apply(buffer, track, values, context);
+  }
+}
+
+/**
+ * Stereo stages, in chain order, after pan. A track on a shared orbit bus
+ * (`sends: false`) skips delay and reverb: the bus applies them to the sum.
+ * `reverb: false` stops before the reverb (the stem cache runs it apart).
+ */
+export function applyStereoChain(
+  left: Float64Array,
+  right: Float64Array,
+  track: Track,
+  context: EffectContext,
+  sends = true,
+  reverb = sends,
+): void {
+  for (const stage of FX_CHAIN.slice(PAN_INDEX + 1)) {
+    if (stage === "delay") {
+      if (sends) applyDelay(left, right, track, context);
+    } else if (stage === "reverb") {
+      if (reverb) applyReverb(left, right, track, context);
+    } else {
+      const values = track.fx?.[stage as FxName];
+      const apply = STEREO[stage as FxName];
+      if (values && apply) apply(left, right, track, values, context);
+    }
+  }
+}

package/src/audio/effects/common.ts

@@ -0,0 +1,251 @@
+/**
+ * Shared DSP building blocks for the track effects chain. Everything is
+ * plain float64 arithmetic in a fixed order with no clocks or ambient
+ * randomness, so a render is byte-identical on every run, cold or cached.
+ *
+ * The DSP in `src/audio/effects/` is dawg's own, written from standard
+ * literature (RBJ Audio EQ Cookbook biquads, Schroeder/Freeverb reverb,
+ * Giannoulis–Massberg–Reiss compressor design, Zölzer DAFX modulation
+ * effects). Parameter names follow Strudel's documentation; no Strudel
+ * source is used.
+ */
+import type { AutomationPoint, Track } from "../../../core/score.ts";
+import type { FxLane, FxValues } from "../../../core/fx.ts";
+import type { DecodedSample } from "../samples.ts";
+
+/** Effect parameters are refreshed at this sample interval. */
+export const CONTROL_SAMPLES = 32;
+
+export type EffectContext = Readonly<{
+  sampleRate: number;
+  samplesPerTick: number;
+  tempoBpm: number;
+  /** Decoded `reverb.ir` samples by track id (built-in impulses need none). */
+  irs?: ReadonlyMap<string, DecodedSample>;
+}>;
+
+/** Resolve a piecewise-linear automation lane, holding the static value before its first point. */
+export 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;
+}
+
+/**
+ * One numeric effect parameter: its static value plus its automation lane
+ * (`<effect>-<param>` in `track.fxAutomation`), read at control rate.
+ */
+export class Param {
+  readonly automated: boolean;
+  private readonly points: readonly AutomationPoint[];
+
+  constructor(
+    readonly fallback: number,
+    points: readonly AutomationPoint[] | undefined,
+    private readonly samplesPerTick: number,
+  ) {
+    this.points = points ?? [];
+    this.automated = this.points.length > 0;
+  }
+
+  at(index: number): number {
+    return this.automated
+      ? interpolateAutomation(
+          this.points,
+          index / this.samplesPerTick,
+          this.fallback,
+        )
+      : this.fallback;
+  }
+}
+
+/** Reader for one `track.fx` effect's numbers, enums and lanes. */
+export function fxReader(
+  track: Track,
+  effect: string,
+  values: FxValues,
+  context: EffectContext,
+) {
+  return {
+    number(name: string): number {
+      return values[name] as number;
+    },
+    text(name: string): string {
+      return values[name] as string;
+    },
+    param(name: string): Param {
+      return new Param(
+        values[name] as number,
+        track.fxAutomation?.[`${effect}-${name}` as FxLane],
+        context.samplesPerTick,
+      );
+    },
+  };
+}
+
+export function clamp(value: number, min: number, max: number): number {
+  return Math.min(max, Math.max(min, value));
+}
+
+/** Resonance 0..1 → biquad Q 0.707..8 (the original filter's mapping). */
+export function resonanceQ(resonance: number): number {
+  return 0.707 + clamp(resonance, 0, 1) * 7.293;
+}
+
+export type FilterType = "lpf" | "hpf" | "bpf";
+
+/** Transposed direct form II biquad with RBJ cookbook coefficients. */
+export class Biquad {
+  b0 = 1;
+  b1 = 0;
+  b2 = 0;
+  a1 = 0;
+  a2 = 0;
+  z1 = 0;
+  z2 = 0;
+
+  set(type: FilterType, cutoff: number, q: number, sampleRate: number): void {
+    const frequency = clamp(cutoff, 20, 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;
+    if (type === "lpf") {
+      this.b0 = (1 - cos) / 2 / a0;
+      this.b1 = (1 - cos) / a0;
+      this.b2 = this.b0;
+    } else if (type === "hpf") {
+      this.b0 = (1 + cos) / 2 / a0;
+      this.b1 = -(1 + cos) / a0;
+      this.b2 = this.b0;
+    } else {
+      // Constant 0 dB peak gain band-pass.
+      this.b0 = alpha / a0;
+      this.b1 = 0;
+      this.b2 = -alpha / a0;
+    }
+    this.a1 = (-2 * cos) / a0;
+    this.a2 = (1 - alpha) / a0;
+  }
+
+  process(input: number): number {
+    const output = this.b0 * input + this.z1;
+    this.z1 = this.b1 * input - this.a1 * output + this.z2;
+    this.z2 = this.b2 * input - this.a2 * output;
+    return output;
+  }
+}
+
+/** One-pole low-pass; `set` takes a cutoff in Hz. */
+export class OnePole {
+  private coefficient = 0;
+  state = 0;
+
+  constructor(cutoff: number, sampleRate: number) {
+    this.set(cutoff, sampleRate);
+  }
+
+  set(cutoff: number, sampleRate: number): void {
+    this.coefficient =
+      1 -
+      Math.exp(
+        (-2 * Math.PI * clamp(cutoff, 1, sampleRate * 0.49)) / sampleRate,
+      );
+  }
+
+  process(input: number): number {
+    this.state += this.coefficient * (input - this.state);
+    return this.state;
+  }
+}
+
+export type LfoShape = "sine" | "tri" | "square" | "saw" | "ramp" | "random";
+
+/** Integer hash → 0..1, for sample-and-hold steps keyed by cycle number. */
+export function hashUnit(value: number, seed = 0): number {
+  let state = (Math.floor(value) ^ Math.imul(seed, 0x9e3779b1)) >>> 0;
+  state = Math.imul(state ^ (state >>> 16), 0x85ebca6b) >>> 0;
+  state = Math.imul(state ^ (state >>> 13), 0xc2b2ae35) >>> 0;
+  return ((state ^ (state >>> 16)) >>> 0) / 4_294_967_296;
+}
+
+/**
+ * Bipolar LFO, -1..1, at `phase` cycles (any real). `saw` falls, `ramp`
+ * rises; `random` holds one seeded value per cycle.
+ */
+export function lfo(shape: string, phase: number, seed = 0): number {
+  const cycle = phase - Math.floor(phase);
+  switch (shape) {
+    case "tri":
+      return 1 - 4 * Math.abs(cycle - 0.5);
+    case "square":
+      return cycle < 0.5 ? 1 : -1;
+    case "saw":
+      return 1 - 2 * cycle;
+    case "ramp":
+      return 2 * cycle - 1;
+    case "random":
+      return hashUnit(phase, seed) * 2 - 1;
+    default:
+      return Math.sin(2 * Math.PI * phase);
+  }
+}
+
+/** LFO frequency in Hz: tempo-synced when `sync` (beats per cycle) > 0. */
+export function lfoHz(sync: number, rate: number, tempoBpm: number): number {
+  return sync > 0 ? tempoBpm / 60 / sync : rate;
+}
+
+/** Sample-accurate LFO phase (cycles) with control-rate frequency changes. */
+export class Phasor {
+  phase: number;
+  private increment = 0;
+
+  constructor(start: number) {
+    this.phase = start;
+  }
+
+  setHz(hz: number, sampleRate: number): void {
+    this.increment = hz / sampleRate;
+  }
+
+  next(): number {
+    const value = this.phase;
+    this.phase += this.increment;
+    return value;
+  }
+}
+
+/** Read with linear interpolation `delay` samples behind `write` in a ring. */
+export function readFractional(
+  buffer: Float64Array,
+  write: number,
+  delay: number,
+): number {
+  const length = buffer.length;
+  const position = write - delay;
+  const base = Math.floor(position);
+  const fraction = position - base;
+  const a = buffer[((base % length) + length) % length]!;
+  const b = buffer[(((base + 1) % length) + length) % length]!;
+  return a + (b - a) * fraction;
+}
+
+export function dbToGain(db: number): number {
+  return 10 ** (db / 20);
+}