@hraness/dawg 0.5.0 → 0.6.1

package/src/audio/dsp/onset.ts

@@ -0,0 +1,197 @@
+/**
+ * Onset detection: SuperFlux (Böck and Widmer, "Maximum filter vibrato
+ * suppression for onset detection", DAFx 2013): positive log-magnitude flux
+ * of each frame against a 3-bin maximum-filtered previous frame, peak-picked
+ * against a local median plus the global mean, then refined to the start of
+ * the energy rise. Deterministic; positions are sample frames.
+ *
+ * A hit at t = 0 has no previous frame to rise from, so it is reported when
+ * the signal starts loud (first 5 ms above 10 % of the peak).
+ */
+import { analyse, frameCount, hann, nextPow2 } from "./stft.ts";
+
+/** Hits closer than this merge into the first (a flam). */
+export const ONSET_MIN_GAP_SECONDS = 0.03;
+/** A refined onset sits this far before the energy rise. */
+export const ONSET_LEAD_SECONDS = 0.001;
+
+export function detectOnsets(
+  x: ArrayLike<number>,
+  sampleRate: number,
+  sensitivity = 1,
+): number[] {
+  const n = nextPow2(0.021 * sampleRate);
+  const hop = n / 4;
+  const half = n / 2;
+  const w = hann(n);
+  const frames = frameCount(x.length, n, hop);
+  const flux = new Float64Array(frames);
+  let prev = new Float64Array(half + 1);
+  let cur = new Float64Array(half + 1);
+  const re = new Float64Array(n);
+  const im = new Float64Array(n);
+  for (let m = 0; m < frames; m += 1) {
+    analyse(x, m * hop, w, re, im);
+    let f = 0;
+    for (let k = 0; k <= half; k += 1) {
+      cur[k] = Math.log1p(100 * Math.hypot(re[k]!, im[k]!));
+      const lo = k > 0 ? prev[k - 1]! : prev[k]!;
+      const hi = k < half ? prev[k + 1]! : prev[k]!;
+      const d = cur[k]! - Math.max(lo, prev[k]!, hi);
+      if (d > 0) f += d;
+    }
+    flux[m] = m === 0 ? 0 : f;
+    const swap = prev;
+    prev = cur;
+    cur = swap;
+  }
+  let mean = 0;
+  for (let m = 0; m < frames; m += 1) mean += flux[m]!;
+  mean /= Math.max(1, frames);
+  const onsets: number[] = [];
+  const minGap = Math.round(ONSET_MIN_GAP_SECONDS * sampleRate);
+  const radius = 8;
+  const local: number[] = [];
+  const startsLoud = loudStart(x, sampleRate);
+  if (startsLoud) onsets.push(0);
+  for (let m = 1; m < frames - 1; m += 1) {
+    const v = flux[m]!;
+    let isPeak = true;
+    for (let j = Math.max(0, m - 3); j <= Math.min(frames - 1, m + 3); j += 1)
+      if (flux[j]! > v || (flux[j] === v && j < m)) {
+        isPeak = false;
+        break;
+      }
+    if (!isPeak) continue;
+    local.length = 0;
+    for (
+      let j = Math.max(0, m - radius);
+      j <= Math.min(frames - 1, m + radius);
+      j += 1
+    )
+      local.push(flux[j]!);
+    local.sort((a, b) => a - b);
+    const median = local[local.length >> 1]!;
+    if (v < (median * 1.5 + mean * 0.5) / sensitivity) continue;
+    const at = refineOnset(x, sampleRate, m * hop + half);
+    if (onsets.length > 0 && at - onsets[onsets.length - 1]! < minGap) continue;
+    onsets.push(at);
+  }
+  return onsets;
+}
+
+function loudStart(x: ArrayLike<number>, sampleRate: number): boolean {
+  let peak = 0;
+  for (let i = 0; i < x.length; i += 1) peak = Math.max(peak, Math.abs(x[i]!));
+  if (peak === 0) return false;
+  const head = Math.min(x.length, Math.round(0.005 * sampleRate));
+  for (let i = 0; i < head; i += 1)
+    if (Math.abs(x[i]!) > 0.1 * peak) return true;
+  return false;
+}
+
+/**
+ * The start of the energy rise near `coarse`, less 1 ms. Within -30..+15 ms
+ * of the coarse frame, 1 ms envelope blocks of the signal and of its first
+ * difference (which favours the clicks of a transient over the low ring of a
+ * previous kick) are compared with the loudest block of the 10 ms before
+ * them; the block that rises most over that background wins, and the onset
+ * is its first sample above the background plus a quarter of the rise. A
+ * hit in silence is unchanged; one in the previous hit's ring-out no longer
+ * latches onto the tail.
+ */
+function refineOnset(
+  x: ArrayLike<number>,
+  sampleRate: number,
+  coarse: number,
+): number {
+  const from = Math.max(1, Math.round(coarse - 0.03 * sampleRate));
+  const to = Math.min(x.length, Math.round(coarse + 0.015 * sampleRate));
+  if (to <= from) return coarse;
+  const block = Math.max(1, Math.round(0.001 * sampleRate));
+  const back = 10;
+  const start = Math.max(1, from - back * block);
+  const blocks = Math.ceil((to - start) / block);
+  const raw = new Float64Array(blocks);
+  const diff = new Float64Array(blocks);
+  for (let i = start; i < to; i += 1) {
+    const b = Math.floor((i - start) / block);
+    raw[b] = Math.max(raw[b]!, Math.abs(x[i]!));
+    diff[b] = Math.max(diff[b]!, Math.abs(x[i]! - x[i - 1]!));
+  }
+  let peakRaw = 0;
+  let peakDiff = 0;
+  for (let b = 0; b < blocks; b += 1) {
+    peakRaw = Math.max(peakRaw, raw[b]!);
+    peakDiff = Math.max(peakDiff, diff[b]!);
+  }
+  if (peakRaw === 0) return coarse;
+  const first = Math.floor((from - start) / block);
+  let best = -1;
+  let bestScore = 0;
+  let bestDiff = false;
+  let bestBg = 0;
+  for (let b = Math.max(1, first); b < blocks; b += 1) {
+    let bgRaw = 0;
+    let bgDiff = 0;
+    for (let k = Math.max(0, b - back); k < b; k += 1) {
+      bgRaw = Math.max(bgRaw, raw[k]!);
+      bgDiff = Math.max(bgDiff, diff[k]!);
+    }
+    const rawScore = raw[b]! / (bgRaw + 0.02 * peakRaw);
+    const diffScore = peakDiff > 0 ? diff[b]! / (bgDiff + 0.02 * peakDiff) : 0;
+    const score = Math.max(rawScore, diffScore);
+    if (score > bestScore) {
+      bestScore = score;
+      best = b;
+      bestDiff = diffScore > rawScore;
+      bestBg = bestDiff ? bgDiff : bgRaw;
+    }
+  }
+  if (best < 0) return coarse;
+  const level = bestDiff ? diff[best]! : raw[best]!;
+  const threshold = bestBg + 0.25 * (level - bestBg);
+  const lo = Math.max(1, start + (best - 1) * block);
+  const hi = Math.min(to, start + (best + 1) * block);
+  let at = start + best * block;
+  for (let i = lo; i < hi; i += 1) {
+    const v = bestDiff ? Math.abs(x[i]! - x[i - 1]!) : Math.abs(x[i]!);
+    if (v > threshold) {
+      at = i;
+      break;
+    }
+  }
+  return Math.max(0, at - Math.round(ONSET_LEAD_SECONDS * sampleRate));
+}
+
+/**
+ * Crest factor (peak over RMS) and onset rate (per second) of a window:
+ * the content probe that suggests a fit mode.
+ */
+export function contentProbe(
+  x: ArrayLike<number>,
+  sampleRate: number,
+): { crest: number; onsetRate: number } {
+  let peak = 0;
+  let sum = 0;
+  for (let i = 0; i < x.length; i += 1) {
+    const v = x[i]!;
+    peak = Math.max(peak, Math.abs(v));
+    sum += v * v;
+  }
+  const rms = Math.sqrt(sum / Math.max(1, x.length));
+  const seconds = x.length / sampleRate;
+  return {
+    crest: rms > 0 ? peak / rms : 0,
+    onsetRate: seconds > 0 ? detectOnsets(x, sampleRate).length / seconds : 0,
+  };
+}
+
+/** Drums and speech (crest > 5 and > 2 onsets/s) fit as `beats`, the rest as `tones`. */
+export function suggestFitMode(
+  x: ArrayLike<number>,
+  sampleRate: number,
+): "beats" | "tones" {
+  const { crest, onsetRate } = contentProbe(x, sampleRate);
+  return crest > 5 && onsetRate > 2 ? "beats" : "tones";
+}

package/src/audio/dsp/oversample.ts

@@ -0,0 +1,202 @@
+/**
+ * Polyphase half-band oversampling for nonlinear stages (guitar rig, high
+ * bowed notes). Kaiser-windowed half-band FIRs: 47 taps, beta 8 for 2x and
+ * the inner stage of 4x; the 4x final stage (the one at the base rate, where
+ * aliases land in the audible band) is 127 taps, beta 10. `Decimate2` is the
+ * 47-tap downsampler alone (strings run some voices at 2x and decimate).
+ */
+
+function besselI0(x: number): number {
+  let sum = 1;
+  let term = 1;
+  for (let k = 1; k < 50; k += 1) {
+    term *= (x / (2 * k)) ** 2;
+    sum += term;
+    if (term < 1e-12 * sum) break;
+  }
+  return sum;
+}
+
+/** Kaiser-windowed half-band lowpass taps (odd length, cutoff fs/4, DC gain 1). */
+export function halfbandTaps(length = 47, beta = 8): Float64Array {
+  const taps = new Float64Array(length);
+  const mid = (length - 1) / 2;
+  const i0b = besselI0(beta);
+  for (let n = 0; n < length; n += 1) {
+    const k = n - mid;
+    const sinc = k === 0 ? 0.5 : Math.sin((Math.PI * k) / 2) / (Math.PI * k);
+    const r = k / mid;
+    const w = besselI0(beta * Math.sqrt(Math.max(0, 1 - r * r))) / i0b;
+    // Even offsets are true zeros of a half-band filter; keep them exact.
+    taps[n] = k !== 0 && k % 2 === 0 ? 0 : sinc * w;
+  }
+  return taps;
+}
+
+/** Nonzero taps of one polyphase branch: coefficients and their input offsets. */
+type Phase = Readonly<{ taps: Float64Array; offsets: Int32Array }>;
+
+function phaseOf(taps: Float64Array, parity: 0 | 1): Phase {
+  const kept: number[] = [];
+  const offsets: number[] = [];
+  for (let n = parity; n < taps.length; n += 2) {
+    if (taps[n] === 0) continue;
+    kept.push(taps[n]!);
+    offsets.push((n - parity) / 2);
+  }
+  return { taps: Float64Array.from(kept), offsets: Int32Array.from(offsets) };
+}
+
+function ringSize(length: number): number {
+  let size = 4;
+  while (size < length + 2) size *= 2;
+  return size;
+}
+
+/** Half-band 2:1 decimator: two input samples in, one out. */
+export class Decimate2 {
+  private readonly taps: Float64Array;
+  private readonly offsets: Int32Array;
+  private readonly history: Float64Array;
+  private readonly mask: number;
+  private write = 0;
+
+  constructor(taps = halfbandTaps(47, 8)) {
+    const kept: number[] = [];
+    const offsets: number[] = [];
+    for (let n = 0; n < taps.length; n += 1) {
+      if (taps[n] === 0) continue;
+      kept.push(taps[n]!);
+      offsets.push(n);
+    }
+    this.taps = Float64Array.from(kept);
+    this.offsets = Int32Array.from(offsets);
+    this.history = new Float64Array(ringSize(taps.length));
+    this.mask = this.history.length - 1;
+  }
+
+  /** `a` then `b` at the high rate → one sample at the base rate. */
+  process(a: number, b: number): number {
+    const h = this.history;
+    const m = this.mask;
+    // Output is aligned to `a`, so a 2x round trip delays by whole samples.
+    h[this.write] = a;
+    const newest = this.write;
+    this.write = (this.write + 1) & m;
+    h[this.write] = b;
+    this.write = (this.write + 1) & m;
+    let acc = 0;
+    for (let i = 0; i < this.taps.length; i += 1)
+      acc += this.taps[i]! * h[(newest - this.offsets[i]!) & m]!;
+    return acc;
+  }
+
+  reset(): void {
+    this.history.fill(0);
+  }
+}
+
+/** Half-band 1:2 interpolator: one input sample in, two out. */
+export class Interpolate2 {
+  private readonly even: Phase;
+  private readonly odd: Phase;
+  private readonly history: Float64Array;
+  private readonly mask: number;
+  private write = 0;
+
+  constructor(taps = halfbandTaps(47, 8)) {
+    this.even = phaseOf(taps, 0);
+    this.odd = phaseOf(taps, 1);
+    this.history = new Float64Array(ringSize((taps.length + 1) >> 1));
+    this.mask = this.history.length - 1;
+  }
+
+  /** Writes the two high-rate samples for input `x` into out[0], out[1]. */
+  process(x: number, out: Float64Array): void {
+    const h = this.history;
+    const m = this.mask;
+    h[this.write] = x;
+    const newest = this.write;
+    this.write = (this.write + 1) & m;
+    out[0] = 2 * branch(this.even, h, newest, m);
+    out[1] = 2 * branch(this.odd, h, newest, m);
+  }
+
+  reset(): void {
+    this.history.fill(0);
+  }
+}
+
+function branch(
+  phase: Phase,
+  history: Float64Array,
+  newest: number,
+  mask: number,
+): number {
+  let acc = 0;
+  const { taps, offsets } = phase;
+  for (let i = 0; i < taps.length; i += 1)
+    acc += taps[i]! * history[(newest - offsets[i]!) & mask]!;
+  return acc;
+}
+
+/** Runs a per-sample function at twice the rate, band-limited both ways. */
+export class Oversample2x {
+  private readonly up: Interpolate2;
+  private readonly down: Decimate2;
+  private readonly pair = new Float64Array(2);
+
+  constructor(taps = halfbandTaps(47, 8)) {
+    this.up = new Interpolate2(taps);
+    this.down = new Decimate2(taps);
+  }
+
+  /** Latency in base-rate samples (linear phase, up plus down). */
+  static latency(taps = 47): number {
+    return (taps - 1) / 2;
+  }
+
+  process(x: number, fn: (x: number) => number): number {
+    const pair = this.pair;
+    this.up.process(x, pair);
+    return this.down.process(fn(pair[0]!), fn(pair[1]!));
+  }
+
+  reset(): void {
+    this.up.reset();
+    this.down.reset();
+  }
+}
+
+/**
+ * Runs a per-sample function at four times the rate: a 2x cascade whose
+ * base-rate stage is the steep 127-tap, beta-10 half-band and whose inner
+ * stage is the 47-tap, beta-8 one (its transition band is already above
+ * the base Nyquist).
+ */
+export class Oversample4x {
+  private readonly outerUp: Interpolate2;
+  private readonly outerDown: Decimate2;
+  private readonly inner: Oversample2x;
+  private readonly pair = new Float64Array(2);
+
+  constructor(outer = halfbandTaps(127, 10), inner = halfbandTaps(47, 8)) {
+    this.outerUp = new Interpolate2(outer);
+    this.outerDown = new Decimate2(outer);
+    this.inner = new Oversample2x(inner);
+  }
+
+  process(x: number, fn: (x: number) => number): number {
+    const pair = this.pair;
+    this.outerUp.process(x, pair);
+    const a = this.inner.process(pair[0]!, fn);
+    const b = this.inner.process(pair[1]!, fn);
+    return this.outerDown.process(a, b);
+  }
+
+  reset(): void {
+    this.outerUp.reset();
+    this.outerDown.reset();
+    this.inner.reset();
+  }
+}

package/src/audio/dsp/rng.ts

@@ -0,0 +1,37 @@
+/**
+ * Seeded randomness for 0.6 instruments. `seededRandom` is the existing
+ * sequential generator (src/audio/random.ts, unchanged); `unit` is a
+ * counter-based draw that is a pure function of (seed, index, slot), so one
+ * grain's or voice's draws never depend on how many draws came before it.
+ * Integer-only, identical on every platform. Never use Math.random.
+ */
+export { seededRandom } from "../random.ts";
+
+/** FNV-1a of a string: turns a stored seed plus a note id into a 32-bit key. */
+export function seedHash(text: string): number {
+  let hash = 0x811c9dc5;
+  for (let index = 0; index < text.length; index += 1) {
+    hash ^= text.charCodeAt(index);
+    hash = Math.imul(hash, 0x01000193) >>> 0;
+  }
+  return hash >>> 0;
+}
+
+/** MurmurHash3 32-bit finaliser. */
+function fmix32(h: number): number {
+  h ^= h >>> 16;
+  h = Math.imul(h, 0x85ebca6b);
+  h ^= h >>> 13;
+  h = Math.imul(h, 0xc2b2ae35);
+  h ^= h >>> 16;
+  return h >>> 0;
+}
+
+/**
+ * Counter-based random in [0, 1): draw `slot` of item `index` under `seed`.
+ * Changing one knob (say a reverse probability) does not reshuffle the rest.
+ */
+export function unit(seed: number, index: number, slot: number): number {
+  const a = fmix32((seed ^ Math.imul(index | 0, 0x9e3779b1)) >>> 0);
+  return fmix32((a ^ Math.imul(slot + 1, 0x7feb352d)) >>> 0) / 4_294_967_296;
+}

package/src/audio/dsp/shape.ts

@@ -0,0 +1,81 @@
+/**
+ * First-order antiderivative antialiasing (ADAA; Parker et al. DAFx-16,
+ * Bilbao et al. IEEE SPL 2017): y = (F(x) - F(x1)) / (x - x1) for a shaper
+ * f with antiderivative F, falling back to f at the midpoint when the step
+ * is tiny. Stateful: one instance per signal path.
+ */
+
+/** log(cosh(x)) without overflow: the antiderivative of tanh. */
+export function logCosh(x: number): number {
+  const a = Math.abs(x);
+  return a + Math.log1p(Math.exp(-2 * a)) - Math.LN2;
+}
+
+/** Hard clip to [-1, 1]. */
+export function hardclip(x: number): number {
+  return x < -1 ? -1 : x > 1 ? 1 : x;
+}
+
+/** Antiderivative of `hardclip`, continuous at ±1. */
+export function hardclipF(x: number): number {
+  return Math.abs(x) <= 1 ? 0.5 * x * x : Math.abs(x) - 0.5;
+}
+
+/**
+ * Asymmetric soft clip: tanh(x + bias) - tanh(bias). Even harmonics come
+ * from the offset; the subtraction keeps silence at zero.
+ */
+export function asym(x: number, bias = 0.3): number {
+  return Math.tanh(x + bias) - Math.tanh(bias);
+}
+
+/** Antiderivative of `asym`. */
+export function asymF(x: number, bias = 0.3): number {
+  return logCosh(x + bias) - x * Math.tanh(bias);
+}
+
+/** Generic first-order ADAA around a shaper and its antiderivative. */
+export class Adaa1 {
+  x1 = 0;
+  F1: number;
+
+  constructor(
+    readonly f: (x: number) => number,
+    readonly F: (x: number) => number,
+  ) {
+    this.F1 = F(0);
+  }
+
+  process(x: number): number {
+    const Fx = this.F(x);
+    const dx = x - this.x1;
+    const y =
+      Math.abs(dx) < 1e-5 ? this.f(0.5 * (x + this.x1)) : (Fx - this.F1) / dx;
+    this.x1 = x;
+    this.F1 = Fx;
+    return y;
+  }
+
+  reset(): void {
+    this.x1 = 0;
+    this.F1 = this.F(0);
+  }
+}
+
+/** ADAA tanh. */
+export function adaaTanh(): Adaa1 {
+  return new Adaa1(Math.tanh, logCosh);
+}
+
+/** ADAA hard clip. */
+export function adaaHardclip(): Adaa1 {
+  return new Adaa1(hardclip, hardclipF);
+}
+
+/** ADAA asymmetric soft clip with a fixed bias. */
+export function adaaAsym(bias = 0.3): Adaa1 {
+  return new Adaa1(
+    (x) => asym(x, bias),
+    (x) => asymF(x, bias),
+  );
+}