@hraness/dawg 0.6.0 → 0.7.0

package/src/audio/effects/convolution.ts

@@ -10,7 +10,7 @@
  * right impulses share one transform: G = FFT(hL + i·hR), and because the
  * input is real, Re(IFFT(X·G)) is the left output and Im(…) the right.
  *
- * Built-in impulses (`builtin:room`, `builtin:hall`, `builtin:plate`) are
+ * Built-in impulses (`builtin:room`, `hall`, `plate`, `reverse`, `gate`, `spring`) are
  * generated from a seeded integer PRNG, so they need no files and are
  * identical on every render path. Everything here is plain float64
  * arithmetic over fixed loops: deterministic. Clean-room, from standard DSP
@@ -79,10 +79,13 @@ export function fftInPlace(
   for (let length = 2; length <= n; length <<= 1) {
     const half = length >> 1;
     const stride = n / length;
-    for (let k = 0; k < half; k += 1) {
-      const wr = cos[k * stride]!;
-      const wi = sign * sin[k * stride]!;
-      for (let a = k; a < n; a += length) {
+    // Butterfly groups outer, twiddles inner: memory is walked in order
+    // (the same operations as twiddle-outer, so the same bits).
+    for (let start = 0; start < n; start += length) {
+      for (let k = 0; k < half; k += 1) {
+        const wr = cos[k * stride]!;
+        const wi = sign * sin[k * stride]!;
+        const a = start + k;
         const b = a + half;
         const xr = re[b]! * wr - im[b]! * wi;
         const xi = re[b]! * wi + im[b]! * wr;
@@ -236,6 +239,31 @@ export const BUILTIN_IMPULSES = Object.freeze({
     attack: 0.06,
   },
   plate: { title: "plate", seconds: 1.8, damp: 9000, early: 0, attack: 0 },
+  // 0.6.1 shaped impulses (`shape`, see `shapedSide`).
+  reverse: {
+    title: "reverse",
+    seconds: 1.2,
+    damp: 7000,
+    early: 0,
+    attack: 0,
+    shape: "rise",
+  },
+  gate: {
+    title: "gated",
+    seconds: 0.45,
+    damp: 8000,
+    early: 6,
+    attack: 0.005,
+    shape: "gate",
+  },
+  spring: {
+    title: "spring tank",
+    seconds: 2.2,
+    damp: 4500,
+    early: 0,
+    attack: 0,
+    shape: "spring",
+  },
 } as const);
 export type BuiltinImpulse = keyof typeof BUILTIN_IMPULSES;
 
@@ -259,6 +287,15 @@ export function builtinImpulse(
   if (cached) return cached;
   const spec = BUILTIN_IMPULSES[name as BuiltinImpulse];
   const length = Math.max(1, Math.round(spec.seconds * sampleRate));
+  if ("shape" in spec) {
+    const impulse = normalizeImpulse(
+      `builtin:${name}`,
+      shapedSide(name, "L", spec, sampleRate),
+      shapedSide(name, "R", spec, sampleRate),
+    );
+    BUILTIN_CACHE.set(key, impulse);
+    return impulse;
+  }
   const sides = ["L", "R"].map((side) => {
     const random = seededRandom(`dawg-ir:${name}:${side}`);
     const out = new Float64Array(length);
@@ -289,6 +326,77 @@ export function builtinImpulse(
   return impulse;
 }
 
+/**
+ * One side of a shaped built-in (0.6.1), all seeded noise through a
+ * one-pole low-pass at `damp`:
+ * - rise: the Yamaha SPX90 "reverse gate": energy rises exponentially to a
+ *   hard cut at `seconds`, so the wash swells into the cut (a reverse
+ *   reverb that stays causal and works in play mode).
+ * - gate: dense flat tail cut hard at `seconds` (the 1980s gated snare).
+ * - spring: a decaying noise tail plus a train of dispersive chirps every
+ *   ~33 ms (high frequencies arrive first, the drip of a spring tank).
+ */
+function shapedSide(
+  name: string,
+  side: string,
+  spec: Readonly<{
+    seconds: number;
+    damp: number;
+    early: number;
+    attack: number;
+    shape: string;
+  }>,
+  sampleRate: number,
+): Float64Array {
+  const random = seededRandom(`dawg-ir:${name}:${side}`);
+  const length = Math.max(16, Math.round(spec.seconds * sampleRate));
+  const out = new Float64Array(length);
+  const coefficient =
+    1 -
+    Math.exp(
+      (-2 * Math.PI * Math.min(spec.damp, sampleRate * 0.45)) / sampleRate,
+    );
+  const fadeOut = Math.min(length >> 2, Math.round(0.003 * sampleRate));
+  let state = 0;
+  for (let index = 0; index < length; index += 1) {
+    const x = (index + 0.5) / length;
+    const t = index / sampleRate;
+    state += coefficient * (random() * 2 - 1 - state);
+    let env: number;
+    if (spec.shape === "rise") env = Math.exp(4 * (x - 1));
+    else if (spec.shape === "gate")
+      env = Math.min(1, t / Math.max(1e-4, spec.attack)) * (1 - 0.3 * x);
+    else env = 0.35 * Math.exp((-Math.log(1000) * t) / spec.seconds);
+    // A short fade into the cut, so it clicks no more than a real gate.
+    if (spec.shape !== "spring" && index >= length - fadeOut)
+      env *= (length - index) / fadeOut;
+    out[index] = state * env;
+  }
+  for (let tap = 0; tap < spec.early; tap += 1) {
+    const at = Math.floor((0.004 + random() * 0.036) * sampleRate);
+    if (at < length) out[at]! += (random() < 0.5 ? -1 : 1) * (0.5 - tap * 0.05);
+  }
+  if (spec.shape === "spring") {
+    // Dispersive chirps: 4 kHz falling to 300 Hz over 25 ms, each echo
+    // -1.6 dB down on the last, the period jittered per side.
+    const period = (0.031 + 0.004 * random()) * sampleRate;
+    const chirp = 0.025;
+    const decay = Math.log(1000) / spec.seconds;
+    for (let echo = 0; echo * period < length; echo += 1) {
+      const start = Math.round(echo * period);
+      const level = Math.exp((-decay * start) / sampleRate);
+      let phase = random() * 2 * Math.PI;
+      for (let k = 0; k < chirp * sampleRate && start + k < length; k += 1) {
+        const u = k / (chirp * sampleRate);
+        const hz = 4000 * (300 / 4000) ** u;
+        phase += (2 * Math.PI * hz) / sampleRate;
+        out[start + k]! += level * Math.sin(phase) * Math.sin(Math.PI * u);
+      }
+    }
+  }
+  return out;
+}
+
 /**
  * An impulse from a decoded sample (mono, any rate): resampled linearly to
  * the render rate, cut to `MAX_IMPULSE_SECONDS`, energy-normalized; both

package/src/audio/effects/filter.ts

@@ -5,10 +5,12 @@
  */
 import { SCORE_LIMITS, type Track } from "../../../core/score.ts";
 import type { FxValues } from "../../../core/fx.ts";
+import { morphFormants, VOWEL_FORMANTS } from "../dsp/formant.ts";
 import {
   Biquad,
   CONTROL_SAMPLES,
   OnePole,
+  Param,
   Phasor,
   clamp,
   fxReader,
@@ -123,16 +125,26 @@ export function applyTrackFilter(
   }
 }
 
-/** Cutoff for a DJ-filter position: 0 → 20 Hz low-pass … 1 → 20 kHz high-pass. */
+/**
+ * Where the DJ filter's high-pass stops rising, as on a DJ mixer: a 20 kHz
+ * high-pass at 44.1 kHz left nothing (q08), so the top of the knob is thin.
+ * The curve below about 0.95 is unchanged.
+ */
+const DJ_HPF_MAX_HZ = 10_000;
+
+/** Cutoff for a DJ-filter position: 0 → 20 Hz low-pass … 1 → 10 kHz high-pass. */
 function djCutoff(value: number): { type: FilterType; cutoff: number } {
   return value < 0.5
     ? { type: "lpf", cutoff: 20 * 1000 ** (value / 0.5) }
-    : { type: "hpf", cutoff: 20 * 1000 ** ((value - 0.5) / 0.5) };
+    : {
+        type: "hpf",
+        cutoff: Math.min(DJ_HPF_MAX_HZ, 20 * 1000 ** ((value - 0.5) / 0.5)),
+      };
 }
 
 /**
  * One-knob DJ filter (Strudel `djf`): below 0.5 a low-pass closes toward
- * 20 Hz, above 0.5 a high-pass rises toward 20 kHz; 0.5 passes unchanged.
+ * 20 Hz, above 0.5 a high-pass rises toward 10 kHz; 0.5 passes unchanged.
  */
 export function applyDjFilter(
   buffer: Float64Array,
@@ -223,72 +235,6 @@ export function applyAutoFilter(
   }
 }
 
-type Formants = readonly (readonly [number, number, number])[];
-
-/**
- * Formant frequency (Hz), level (dB) and bandwidth (Hz). The five plain
- * vowels use the classic tenor formant table (published acoustic
- * phonetics data); the extended set approximates F1–F3 from standard
- * vowel charts with tenor-typical F4/F5.
- */
-const VOWEL_FORMANTS: Readonly<Record<string, Formants>> = Object.freeze({
-  a: [
-    [650, 0, 80],
-    [1080, -6, 90],
-    [2650, -7, 120],
-    [2900, -8, 130],
-    [3250, -22, 140],
-  ],
-  e: [
-    [400, 0, 70],
-    [1700, -14, 80],
-    [2600, -12, 100],
-    [3200, -14, 120],
-    [3580, -20, 120],
-  ],
-  i: [
-    [290, 0, 40],
-    [1870, -15, 90],
-    [2800, -18, 100],
-    [3250, -20, 120],
-    [3540, -30, 120],
-  ],
-  o: [
-    [400, 0, 40],
-    [800, -10, 80],
-    [2600, -12, 100],
-    [2800, -12, 120],
-    [3000, -26, 120],
-  ],
-  u: [
-    [350, 0, 40],
-    [600, -20, 60],
-    [2700, -17, 100],
-    [2900, -14, 120],
-    [3300, -26, 120],
-  ],
-  ae: extended(660, 1720, 2410),
-  aa: extended(710, 1100, 2540),
-  oe: extended(390, 1680, 2400),
-  ue: extended(300, 1600, 2200),
-  y: extended(250, 1750, 2160),
-  uh: extended(600, 1170, 2390),
-  un: extended(500, 1400, 2500),
-  en: extended(550, 1650, 2500),
-  an: extended(650, 1050, 2550),
-  on: extended(450, 850, 2550),
-});
-
-function extended(f1: number, f2: number, f3: number): Formants {
-  return [
-    [f1, 0, 70],
-    [f2, -8, 90],
-    [f3, -14, 110],
-    [3300, -16, 130],
-    [3750, -24, 140],
-  ];
-}
-
 /** Gain that brings the summed formant bank near unity for speech-band input. */
 const VOWEL_GAIN = 2.2;
 
@@ -307,11 +253,44 @@ export function applyVowel(
     filter.set("bpf", frequency, frequency / bandwidth, context.sampleRate);
     return { filter, gain: 10 ** (level / 20) };
   });
+  // 0.7 morph: present only with `to`; absent keeps the static bank exactly.
+  const toName = values.to as string | undefined;
+  const to = toName === undefined ? undefined : VOWEL_FORMANTS[toName];
+  // Absent morph means 0, so a vowel-morph lane still sweeps without it.
+  const morph = to
+    ? new Param(
+        (values.morph as number | undefined) ?? 0,
+        track.fxAutomation?.["vowel-morph"],
+        context.samplesPerTick,
+        context.warp,
+      )
+    : undefined;
+  const moving = morph !== undefined && (morph.automated || morph.fallback > 0);
+  let at = -1;
+  const retune = (position: number) => {
+    if (position === at) return;
+    at = position;
+    morphFormants(formants, to!, position).forEach(
+      ([frequency, level, bandwidth], index) => {
+        const band = bank[index]!;
+        band.filter.set(
+          "bpf",
+          frequency,
+          frequency / bandwidth,
+          context.sampleRate,
+        );
+        band.gain = 10 ** (level / 20);
+      },
+    );
+  };
+  if (moving) retune(morph.at(0));
   // Formant peaks are narrow; a gentle pre-emphasis keeps the vowel bright.
   const tilt = new OnePole(8000, context.sampleRate);
   let wet = mix.at(0);
   for (let index = 0; index < buffer.length; index += 1) {
     if (mix.automated && index % CONTROL_SAMPLES === 0) wet = mix.at(index);
+    if (moving && morph.automated && index % CONTROL_SAMPLES === 0)
+      retune(morph.at(index));
     const input = buffer[index]!;
     const emphasized = input + 0.5 * (input - tilt.process(input));
     let sum = 0;

package/src/audio/effects/formant.ts

@@ -0,0 +1,263 @@
+/**
+ * Formant shift at constant pitch (0.7 `fx.formant`): the throat or gender
+ * knob. Per STFT frame the cepstral spectral envelope E is taken and each
+ * bin is scaled by E(k / a) / E(k), a = 2^(shift / 12), with its phase left
+ * untouched, then the frames overlap-add. The pitch never moves, so no
+ * phase vocoder is needed (Röbel and Rodet, "Efficient spectral envelope
+ * estimation and its application to pitch shifting and envelope
+ * preservation", DAFx 2005; Little AlterBoy and VocalSynth's formant knob).
+ *
+ * The lifter adapts to the voice: 0.75 periods of a 5-frame median
+ * autocorrelation f0, clamped to 1-2 ms, 1 ms when unvoiced. A fixed 2 ms
+ * lifter resolves single harmonics above about 500 Hz and makes high
+ * voices worse than no processing (design formant.md section 2).
+ *
+ * Frames sit at multiples of the hop in absolute track samples (an
+ * arranged window passes its origin as `seedSeconds`), and a window padded
+ * back by `FORMANT_PAD` samples and forward by one frame equals the same
+ * span of a full render bit for bit.
+ */
+import type { FxValues } from "../../../core/fx.ts";
+import type { Track } from "../../../core/score.ts";
+import { cepstralEnvelope, envelopeScratch } from "../dsp/envelope.ts";
+import { fftInPlace } from "../dsp/fft.ts";
+import { hann, HANN_SQUARED_OLA_QUARTER } from "../dsp/stft.ts";
+import { fxReader, type EffectContext } from "./common.ts";
+
+/** Per-bin gain clamp (24 dB), as shift.ts holds formants. */
+const MAX_GAIN = 10 ** (24 / 20);
+/** Lifter periods and clamps (design formant.md section 2). */
+const LIFTER_PERIODS = 0.75;
+const LIFTER_MIN_SECONDS = 0.001;
+const LIFTER_MAX_SECONDS = 0.002;
+/** Frames in the f0 median (this one and the four before it). */
+const F0_MEDIAN = 5;
+const F0_MIN_HZ = 60;
+const F0_MAX_HZ = 1500;
+/** Below this normalized autocorrelation a frame counts as unvoiced. */
+const VOICED = 0.45;
+/** The first peak within this fraction of the best is the period. */
+const FIRST_PEAK = 0.85;
+
+/** Frame length: 1024 at or below 24 kHz, 2048 above. */
+export function formantFrame(sampleRate: number): number {
+  return sampleRate > 24_000 ? 2048 : 1024;
+}
+
+/**
+ * Samples a window render must start before its first output sample (4
+ * hops for the f0 median plus one frame), and it renders one frame past
+ * its last.
+ */
+export function formantPad(sampleRate: number): number {
+  const n = formantFrame(sampleRate);
+  return n + 4 * (n / 4);
+}
+
+export type FormantShiftOptions = Readonly<{
+  /** Wet amount 0..1 (1: fully shifted). */
+  mix?: number | ((index: number) => number);
+  /** Absolute track sample of `x[0]`; frames anchor at hop multiples of it. */
+  origin?: number;
+}>;
+
+type Analysis = {
+  n: number;
+  hop: number;
+  win: Float64Array;
+  wac: Float64Array;
+  minLag: number;
+  maxLag: number;
+};
+
+const analyses = new Map<number, Analysis>();
+
+function analysisFor(sampleRate: number): Analysis {
+  let a = analyses.get(sampleRate);
+  if (a) return a;
+  const n = formantFrame(sampleRate);
+  const win = hann(n);
+  const minLag = Math.floor(sampleRate / F0_MAX_HZ);
+  const maxLag = Math.min(n / 2 - 1, Math.ceil(sampleRate / F0_MIN_HZ));
+  // The window's own autocorrelation, divided out so long lags are not
+  // biased down (Boersma 1993).
+  const wac = new Float64Array(maxLag + 1);
+  for (let t = 0; t <= maxLag; t += 1) {
+    let sum = 0;
+    for (let i = 0; i + t < n; i += 1) sum += win[i]! * win[i + t]!;
+    wac[t] = sum;
+  }
+  a = { n, hop: n / 4, win, wac, minLag, maxLag };
+  analyses.set(sampleRate, a);
+  return a;
+}
+
+/** One frame's f0 from its power spectrum (0: unvoiced). */
+function frameF0(
+  mag: Float64Array,
+  a: Analysis,
+  sampleRate: number,
+  re: Float64Array,
+  im: Float64Array,
+): number {
+  const { n, wac, minLag, maxLag } = a;
+  const half = n / 2;
+  for (let k = 0; k <= half; k += 1) {
+    re[k] = mag[k]! * mag[k]!;
+    im[k] = 0;
+    if (k > 0 && k < half) {
+      re[n - k] = re[k]!;
+      im[n - k] = 0;
+    }
+  }
+  fftInPlace(re, im, true);
+  const r0 = re[0]!;
+  if (r0 <= 1e-12) return 0;
+  const w0 = wac[0]! / r0;
+  for (let t = minLag - 1; t <= maxLag; t += 1) re[t] = (re[t]! * w0) / wac[t]!;
+  let best = 0;
+  for (let t = minLag; t <= maxLag; t += 1) best = Math.max(best, re[t]!);
+  if (best < VOICED) return 0;
+  for (let t = minLag + 1; t < maxLag; t += 1) {
+    const v = re[t]!;
+    if (v >= FIRST_PEAK * best && v >= re[t - 1]! && v >= re[t + 1]!) {
+      const l = re[t - 1]!;
+      const r = re[t + 1]!;
+      const d = l - 2 * v + r;
+      const offset = d < 0 ? (0.5 * (l - r)) / d : 0;
+      return sampleRate / (t + offset);
+    }
+  }
+  return 0;
+}
+
+/**
+ * Shift the formants of `x` by `shift` semitones (a number, or a function
+ * of the buffer index read once per hop) at constant pitch. Returns a new
+ * buffer; `shift` 0 everywhere returns a copy of `x`.
+ */
+export function formantShift(
+  x: Float64Array,
+  sampleRate: number,
+  shift: number | ((index: number) => number),
+  options: FormantShiftOptions = {},
+): Float64Array {
+  if (shift === 0) return Float64Array.from(x);
+  const a = analysisFor(sampleRate);
+  const { n, hop, win } = a;
+  const half = n / 2;
+  const origin = Math.round(options.origin ?? 0);
+  const out = new Float64Array(x.length);
+  const re = new Float64Array(n);
+  const im = new Float64Array(n);
+  const acRe = new Float64Array(n);
+  const acIm = new Float64Array(n);
+  const mag = new Float64Array(half + 1);
+  const env = new Float64Array(half + 1);
+  const scratch = envelopeScratch(n);
+  const history = new Float64Array(F0_MEDIAN);
+  const sorted = new Float64Array(F0_MEDIAN);
+  let frames = 0;
+  const ola = 1 / HANN_SQUARED_OLA_QUARTER;
+  const auto = typeof shift === "function";
+  // First frame: the latest hop multiple (absolute) whose frame still
+  // reaches x[0].
+  const firstAbs = Math.floor((origin - n + 1 + (hop - 1)) / hop) * hop;
+  for (let start = firstAbs - origin; start < x.length; start += hop) {
+    const st = auto ? shift(Math.max(0, start + half)) : shift;
+    for (let i = 0; i < n; i += 1) {
+      const j = start + i;
+      re[i] = j >= 0 && j < x.length ? x[j]! * win[i]! : 0;
+      im[i] = 0;
+    }
+    fftInPlace(re, im);
+    for (let k = 0; k <= half; k += 1) mag[k] = Math.hypot(re[k]!, im[k]!);
+    // Every frame joins the f0 history, so a window and the full render
+    // agree whatever the shift was.
+    history[frames % F0_MEDIAN] = frameF0(mag, a, sampleRate, acRe, acIm);
+    frames += 1;
+    if (st === 0) {
+      fftInPlace(re, im, true);
+    } else {
+      const m = Math.min(frames, F0_MEDIAN);
+      for (let i = 0; i < m; i += 1) sorted[i] = history[i]!;
+      for (let i = 1; i < m; i += 1)
+        for (let j = i; j > 0 && sorted[j - 1]! > sorted[j]!; j -= 1) {
+          const tmp = sorted[j]!;
+          sorted[j] = sorted[j - 1]!;
+          sorted[j - 1] = tmp;
+        }
+      const f0 = sorted[m >> 1]!;
+      const seconds =
+        f0 > 0
+          ? Math.min(
+              LIFTER_MAX_SECONDS,
+              Math.max(LIFTER_MIN_SECONDS, LIFTER_PERIODS / f0),
+            )
+          : LIFTER_MIN_SECONDS;
+      const lifter = Math.max(4, Math.round(seconds * sampleRate));
+      cepstralEnvelope(mag, n, lifter, env, scratch);
+      const ratio = 2 ** (-st / 12);
+      for (let k = 0; k <= half; k += 1) {
+        const source = k * ratio;
+        const i0 = Math.floor(source);
+        const f = source - i0;
+        const e =
+          i0 >= half
+            ? env[half]!
+            : env[i0]! + (env[Math.min(half, i0 + 1)]! - env[i0]!) * f;
+        const g = Math.min(
+          MAX_GAIN,
+          Math.max(1 / MAX_GAIN, e / Math.max(env[k]!, 1e-12)),
+        );
+        re[k] = re[k]! * g;
+        im[k] = im[k]! * g;
+        if (k > 0 && k < half) {
+          re[n - k] = re[k]!;
+          im[n - k] = -im[k]!;
+        }
+      }
+      fftInPlace(re, im, true);
+    }
+    for (let i = 0; i < n; i += 1) {
+      const j = start + i;
+      if (j >= 0 && j < x.length)
+        out[j] = out[j]! + (re[i]! / n) * win[i]! * ola;
+    }
+  }
+  const mix = options.mix ?? 1;
+  if (typeof mix === "function")
+    for (let i = 0; i < x.length; i += 1)
+      out[i] = x[i]! + (out[i]! - x[i]!) * mix(i);
+  else if (mix < 1)
+    for (let i = 0; i < x.length; i += 1)
+      out[i] = x[i]! + (out[i]! - x[i]!) * mix;
+  return out;
+}
+
+/** `fx.formant`: formant shift with mix, both automatable. */
+export function applyFormant(
+  buffer: Float64Array,
+  track: Track,
+  values: FxValues,
+  context: EffectContext,
+): void {
+  const read = fxReader(track, "formant", values, context);
+  const shift = read.param("shift");
+  const mix = read.param("mix");
+  if (!shift.automated && shift.fallback === 0) return;
+  if (!mix.automated && mix.fallback <= 0) return;
+  const origin = context.seedSeconds
+    ? Math.round(context.seedSeconds * context.sampleRate)
+    : 0;
+  const out = formantShift(
+    buffer,
+    context.sampleRate,
+    shift.automated ? (index) => shift.at(index) : shift.fallback,
+    {
+      origin,
+      mix: mix.automated ? (index) => mix.at(index) : mix.fallback,
+    },
+  );
+  buffer.set(out);
+}