@hraness/dawg 0.6.0 → 0.7.0

package/src/audio/dsp/follow.ts

@@ -0,0 +1,120 @@
+/**
+ * Envelope followers (0.7 vocoder): one-pole attack/release on |x|, and the
+ * gate curve built on one. Pure functions of the input buffer, so a render
+ * window with enough pre-roll settles to the full render's values.
+ */
+
+/** One-pole coefficient for a time constant in seconds (0 = instant). */
+export function followCoef(seconds: number, sampleRate: number): number {
+  return seconds <= 0 ? 0 : Math.exp(-1 / (seconds * sampleRate));
+}
+
+/**
+ * Follows |x| with separate attack and release times. Where `hold[i]` is
+ * non-zero the envelope keeps its last value (the vocoder's freeze).
+ */
+export function follow(
+  x: Float64Array,
+  attack: number,
+  release: number,
+  sampleRate: number,
+  hold?: Uint8Array,
+): Float64Array {
+  const a = followCoef(attack, sampleRate);
+  const r = followCoef(release, sampleRate);
+  const out = new Float64Array(x.length);
+  let e = 0;
+  for (let i = 0; i < x.length; i += 1) {
+    if (!hold || hold[i] === 0) {
+      const v = Math.abs(x[i]!);
+      const c = v > e ? a : r;
+      e = c * e + (1 - c) * v;
+    }
+    out[i] = e;
+  }
+  return out;
+}
+
+/**
+ * Gate gain 0..1 per sample: a broadband follower against `thresholdDb`
+ * with a 6 dB soft knee, smoothed over 5 ms. Undefined when the gate is off
+ * (threshold at or below -119 dBFS).
+ */
+export function gateCurve(
+  x: Float64Array,
+  sampleRate: number,
+  thresholdDb: number,
+): Float64Array | undefined {
+  if (thresholdDb <= -119) return undefined;
+  const level = follow(x, 0.001, 0.05, sampleRate);
+  const out = new Float64Array(x.length);
+  const c = followCoef(0.005, sampleRate);
+  let s = 0;
+  for (let i = 0; i < x.length; i += 1) {
+    const db = 20 * Math.log10(level[i]! + 1e-12);
+    const t = Math.min(1, Math.max(0, (db - thresholdDb) / 6));
+    s = c * s + (1 - c) * t;
+    out[i] = s;
+  }
+  return out;
+}
+
+/**
+ * Where `hold[i]` is non-zero, `curve` keeps its value from the sample
+ * before (in place): a frozen vocoder keeps its gate where it was, so the
+ * held vowel does not fade out once the modulator goes quiet.
+ */
+export function holdCurve(curve: Float64Array, hold: Uint8Array): void {
+  for (let i = 1; i < curve.length && i < hold.length; i += 1)
+    if (hold[i] !== 0) curve[i] = curve[i - 1]!;
+}
+
+/**
+ * The static `freeze` hold: 1 wherever the modulator is quiet (under the
+ * gate, or under -50 dBFS when the gate is lower or off), engaged
+ * `lead` seconds before the voice falls quiet so the envelopes are caught
+ * before their release. The carrier keeps the last sung vowel through every
+ * rest and follows the voice while it sings. Before the first note it holds
+ * silence. Local (the mod span plus its lookahead), so windows agree.
+ */
+export function quietHold(
+  x: Float64Array,
+  n: number,
+  sampleRate: number,
+  thresholdDb: number,
+  lead = 0.03,
+): Uint8Array {
+  const level = follow(x, 0.001, 0.01, sampleRate);
+  const floor = 10 ** (Math.max(thresholdDb, -50) / 20);
+  const ahead = Math.max(0, Math.round(lead * sampleRate));
+  const hold = new Uint8Array(n);
+  let nextQuiet = Infinity;
+  for (let i = Math.min(level.length, n + ahead) - 1; i >= 0; i -= 1) {
+    if (level[i]! < floor) {
+      // the start of a quiet run reaches back `ahead` samples
+      if (i === 0 || level[i - 1]! >= floor) nextQuiet = i;
+      if (i < n) hold[i] = 1;
+    } else if (i < n && nextQuiet - i <= ahead) hold[i] = 1;
+  }
+  for (let i = level.length; i < n; i += 1) hold[i] = 1;
+  return hold;
+}
+
+/**
+ * Auto gate threshold for a whole asset: the 10th-percentile 10 ms frame
+ * level plus 6 dB (the mean-abs follower reads about 1 dB under RMS). A
+ * property of the asset, so every render window agrees. -120 when silent.
+ */
+export function autoGateDb(asset: Float64Array, sampleRate: number): number {
+  const hop = Math.max(1, Math.round(0.01 * sampleRate));
+  const levels: number[] = [];
+  for (let s = 0; s + hop <= asset.length; s += hop) {
+    let e = 0;
+    for (let i = s; i < s + hop; i += 1) e += asset[i]! * asset[i]!;
+    const db = 10 * Math.log10(e / hop + 1e-24);
+    if (db > -100) levels.push(db);
+  }
+  if (levels.length === 0) return -120;
+  levels.sort((a, b) => a - b);
+  return levels[Math.floor(levels.length * 0.1)]! + 6;
+}

package/src/audio/dsp/formant.ts

@@ -0,0 +1,427 @@
+/**
+ * Vowel formant tables shared by the `vowel` filter (and, from the sing
+ * lane, the Klatt cascade): frequency (Hz), level (dB) and bandwidth (Hz)
+ * per formant, plus a log-frequency morph between two vowels.
+ */
+
+export 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.
+ */
+export 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],
+  ];
+}
+
+/**
+ * Formants `morph` (0..1) of the way from `from` to `to`: frequency and
+ * bandwidth interpolate on a log scale (equal steps sound equal), level in
+ * dB. 0 returns `from`'s values exactly, 1 returns `to`'s.
+ */
+export function morphFormants(
+  from: Formants,
+  to: Formants,
+  morph: number,
+): Array<[number, number, number]> {
+  const m = Math.min(1, Math.max(0, morph));
+  return from.map(([hz, level, bw], index) => {
+    if (m === 0) return [hz, level, bw];
+    const [toHz, toLevel, toBw] = to[index] ?? [hz, level, bw];
+    if (m === 1) return [toHz, toLevel, toBw];
+    return [
+      hz * (toHz / hz) ** m,
+      level + (toLevel - level) * m,
+      bw * (toBw / bw) ** m,
+    ];
+  });
+}
+
+// ---- sing lane: SATB tables, Klatt cascade, morph and tuning ----
+
+/**
+ * Vowel formant tables and the resonators that sing them.
+ *
+ * Tables: F1-F5 frequency (Hz), level (dB), bandwidth (Hz) for soprano,
+ * alto, tenor and bass singers on a e i o u: the Csound manual's "Formant
+ * Values" appendix (the FOF table, after Sundberg's singer data). The tenor
+ * rows equal VOWEL_FORMANTS above.
+ *
+ * Resonator: Klatt 1980 ("Software for a cascade/parallel formant
+ * synthesizer", JASA 67(3)) two-pole digital resonator with unity DC gain:
+ *   C = -exp(-2 pi BW T), B = 2 exp(-pi BW T) cos(2 pi F T), A = 1 - B - C,
+ *   y[n] = A x[n] + B y[n-1] + C y[n-2].
+ * In cascade the relative formant levels come out right on their own.
+ */
+
+export type Formant = readonly [hz: number, db: number, bw: number];
+export type VowelTable = readonly Formant[];
+export const VOICE_TYPES = ["soprano", "alto", "tenor", "bass"] as const;
+export type VoiceType = (typeof VOICE_TYPES)[number];
+export const VOWELS = ["a", "e", "i", "o", "u"] as const;
+
+const row = (f: number[], db: number[], bw: number[]): VowelTable =>
+  f.map((hz, i) => [hz, db[i]!, bw[i]!] as const);
+
+export const SINGER_FORMANTS: Readonly<
+  Record<VoiceType, Record<string, VowelTable>>
+> = {
+  soprano: {
+    a: row(
+      [800, 1150, 2900, 3900, 4950],
+      [0, -6, -32, -20, -50],
+      [80, 90, 120, 130, 140],
+    ),
+    e: row(
+      [350, 2000, 2800, 3600, 4950],
+      [0, -20, -15, -40, -56],
+      [60, 100, 120, 150, 200],
+    ),
+    i: row(
+      [270, 2140, 2950, 3900, 4950],
+      [0, -12, -26, -26, -44],
+      [60, 90, 100, 120, 120],
+    ),
+    o: row(
+      [450, 800, 2830, 3800, 4950],
+      [0, -11, -22, -22, -50],
+      [70, 80, 100, 130, 135],
+    ),
+    u: row(
+      [325, 700, 2700, 3800, 4950],
+      [0, -16, -35, -40, -60],
+      [50, 60, 170, 180, 200],
+    ),
+  },
+  alto: {
+    a: row(
+      [800, 1150, 2800, 3500, 4950],
+      [0, -4, -20, -36, -60],
+      [80, 90, 120, 130, 140],
+    ),
+    e: row(
+      [400, 1600, 2700, 3300, 4950],
+      [0, -24, -30, -35, -60],
+      [60, 80, 120, 150, 200],
+    ),
+    i: row(
+      [350, 1700, 2700, 3700, 4950],
+      [0, -20, -30, -36, -60],
+      [50, 100, 120, 150, 200],
+    ),
+    o: row(
+      [450, 800, 2830, 3500, 4950],
+      [0, -9, -16, -28, -55],
+      [70, 80, 100, 130, 135],
+    ),
+    u: row(
+      [325, 700, 2530, 3500, 4950],
+      [0, -12, -30, -40, -64],
+      [50, 60, 170, 180, 200],
+    ),
+  },
+  tenor: {
+    a: row(
+      [650, 1080, 2650, 2900, 3250],
+      [0, -6, -7, -8, -22],
+      [80, 90, 120, 130, 140],
+    ),
+    e: row(
+      [400, 1700, 2600, 3200, 3580],
+      [0, -14, -12, -14, -20],
+      [70, 80, 100, 120, 120],
+    ),
+    i: row(
+      [290, 1870, 2800, 3250, 3540],
+      [0, -15, -18, -20, -30],
+      [40, 90, 100, 120, 120],
+    ),
+    o: row(
+      [400, 800, 2600, 2800, 3000],
+      [0, -10, -12, -12, -26],
+      [40, 80, 100, 120, 120],
+    ),
+    u: row(
+      [350, 600, 2700, 2900, 3300],
+      [0, -20, -17, -14, -26],
+      [40, 60, 100, 120, 120],
+    ),
+  },
+  bass: {
+    a: row(
+      [600, 1040, 2250, 2450, 2750],
+      [0, -7, -9, -9, -20],
+      [60, 70, 110, 120, 130],
+    ),
+    e: row(
+      [400, 1620, 2400, 2800, 3100],
+      [0, -12, -9, -12, -18],
+      [40, 80, 100, 120, 120],
+    ),
+    i: row(
+      [250, 1750, 2600, 3050, 3340],
+      [0, -30, -16, -22, -28],
+      [60, 90, 100, 120, 120],
+    ),
+    o: row(
+      [400, 750, 2400, 2600, 2900],
+      [0, -11, -21, -20, -40],
+      [40, 80, 100, 120, 120],
+    ),
+    u: row(
+      [350, 600, 2400, 2675, 2950],
+      [0, -20, -32, -28, -36],
+      [40, 80, 100, 120, 120],
+    ),
+  },
+};
+
+/** Morph two tables: frequencies and bandwidths in log Hz, levels in dB. */
+export function morphVowel(a: VowelTable, b: VowelTable, t: number): Formant[] {
+  return a.map(([fa, da, ba], i) => {
+    const [fb, db, bb] = b[i]!;
+    return [
+      fa * (fb / fa) ** t,
+      da + (db - da) * t,
+      ba * (bb / ba) ** t,
+    ] as const;
+  });
+}
+
+/**
+ * Vowel position along a sequence, e.g. "a>o>u" at t in [0,1]; plain "a"
+ * is constant. Unknown letters fall back to "a".
+ */
+export function vowelAt(voice: VoiceType, spec: string, t: number): Formant[] {
+  const table = SINGER_FORMANTS[voice];
+  const names = spec.split(">").map((s) => (table[s] ? s : "a"));
+  if (names.length === 1) return [...table[names[0]!]!];
+  if (t >= 1) return [...table[names[names.length - 1]!]!];
+  const x = Math.min(0.999999, Math.max(0, t)) * (names.length - 1);
+  const i = Math.floor(x);
+  return morphVowel(table[names[i]!]!, table[names[i + 1]!]!, x - i);
+}
+
+/** Klatt resonator with coefficient updates at control rate. */
+export class Resonator {
+  private a = 1;
+  private b = 0;
+  private c = 0;
+  private y1 = 0;
+  private y2 = 0;
+  set(hz: number, bw: number, sampleRate: number): void {
+    const t = 1 / sampleRate;
+    const f = Math.min(hz, sampleRate * 0.45);
+    this.c = -Math.exp(-2 * Math.PI * bw * t);
+    this.b = 2 * Math.exp(-Math.PI * bw * t) * Math.cos(2 * Math.PI * f * t);
+    this.a = 1 - this.b - this.c;
+  }
+  /** Writes the coefficients at `out[at..at+2]`; returns the next index. */
+  coeffsInto(out: Float64Array, at: number): number {
+    out[at] = this.a;
+    out[at + 1] = this.b;
+    out[at + 2] = this.c;
+    return at + 3;
+  }
+  /** H(e^jw) as [re, im], given cos/sin of w and 2w. */
+  response(cw: number, sw: number, c2w: number, s2w: number): [number, number] {
+    const out = new Float64Array(2);
+    this.responseInto(cw, sw, c2w, s2w, out);
+    return [out[0]!, out[1]!];
+  }
+  /** `response` written into `out[0..1]` (no allocation on the hot path). */
+  responseInto(
+    cw: number,
+    sw: number,
+    c2w: number,
+    s2w: number,
+    out: Float64Array,
+  ): void {
+    const re = 1 - this.b * cw - this.c * c2w;
+    const im = this.b * sw + this.c * s2w;
+    const d = re * re + im * im;
+    out[0] = (this.a * re) / d;
+    out[1] = (-this.a * im) / d;
+  }
+  process(x: number): number {
+    const y = this.a * x + this.b * this.y1 + this.c * this.y2;
+    this.y2 = this.y1;
+    this.y1 = y;
+    return y;
+  }
+}
+
+/** Constant-peak-gain band-pass (RBJ, 0 dB at centre) for parallel banks. */
+export class Bandpass {
+  private b0 = 0;
+  private b2 = 0;
+  private a1 = 0;
+  private a2 = 0;
+  private x1 = 0;
+  private x2 = 0;
+  private y1 = 0;
+  private y2 = 0;
+  set(hz: number, bw: number, sampleRate: number): void {
+    const w = (2 * Math.PI * Math.min(hz, sampleRate * 0.45)) / sampleRate;
+    const q = Math.max(0.3, hz / Math.max(1, bw));
+    const alpha = Math.sin(w) / (2 * q);
+    const a0 = 1 + alpha;
+    this.b0 = alpha / a0;
+    this.b2 = -alpha / a0;
+    this.a1 = (-2 * Math.cos(w)) / a0;
+    this.a2 = (1 - alpha) / a0;
+  }
+  /** Writes the coefficients at `out[at..at+3]`; returns the next index. */
+  coeffsInto(out: Float64Array, at: number): number {
+    out[at] = this.b0;
+    out[at + 1] = this.b2;
+    out[at + 2] = this.a1;
+    out[at + 3] = this.a2;
+    return at + 4;
+  }
+  /** H(e^jw) as [re, im], given cos/sin of w and 2w. */
+  response(cw: number, sw: number, c2w: number, s2w: number): [number, number] {
+    const out = new Float64Array(2);
+    this.responseInto(cw, sw, c2w, s2w, out);
+    return [out[0]!, out[1]!];
+  }
+  /** `response` written into `out[0..1]` (no allocation on the hot path). */
+  responseInto(
+    cw: number,
+    sw: number,
+    c2w: number,
+    s2w: number,
+    out: Float64Array,
+  ): void {
+    const nr = this.b0 + this.b2 * c2w;
+    const ni = -this.b2 * s2w;
+    const dr = 1 + this.a1 * cw + this.a2 * c2w;
+    const di = -this.a1 * sw - this.a2 * s2w;
+    const d = dr * dr + di * di;
+    out[0] = (nr * dr + ni * di) / d;
+    out[1] = (ni * dr - nr * di) / d;
+  }
+  process(x: number): number {
+    const y =
+      this.b0 * x + this.b2 * this.x2 - this.a1 * this.y1 - this.a2 * this.y2;
+    this.x2 = this.x1;
+    this.x1 = x;
+    this.y2 = this.y1;
+    this.y1 = y;
+    return y;
+  }
+}
+
+/** Five-formant cascade (the Klatt voicing branch). */
+export class Cascade {
+  readonly res = [
+    new Resonator(),
+    new Resonator(),
+    new Resonator(),
+    new Resonator(),
+    new Resonator(),
+  ];
+  set(formants: readonly Formant[], scale: number, sampleRate: number): void {
+    for (let i = 0; i < 5; i += 1) {
+      const [hz, , bw] = formants[i]!;
+      this.res[i]!.set(hz * scale, bw * Math.sqrt(scale), sampleRate);
+    }
+  }
+  process(x: number): number {
+    let y = x;
+    for (const r of this.res) y = r.process(y);
+    return y;
+  }
+}
+
+/**
+ * Formant tuning for high voices (review fix; Sundberg 1987, Joliveau,
+ * Smith and Wolfe 2004): when f0 rises above F1 (and 2 f0 above F2), the
+ * singer opens the jaw so F1 tracks f0 and F2 tracks 2 f0. Applied to the
+ * effective (formant-scaled) frequencies; bandwidths widen in proportion.
+ * A no-op below the crossing, so low voices keep the table exactly.
+ */
+export function tuneToPitch(
+  formants: readonly Formant[],
+  f0: number,
+  scale: number,
+): readonly Formant[] {
+  const need1 = (1.05 * f0) / scale;
+  if (
+    formants[0]![0] >= need1 &&
+    formants[1]![0] >= Math.max((2.05 * f0) / scale, formants[0]![0] * 1.25)
+  )
+    return formants; // below the crossing: the table as-is, no allocation
+  const out = formants.map((f) => [...f] as [number, number, number]);
+  const f1 = out[0]!;
+  const want1 = (1.05 * f0) / scale;
+  if (f1[0] < want1) {
+    f1[2] *= want1 / f1[0];
+    f1[0] = want1;
+  }
+  const f2 = out[1]!;
+  const want2 = Math.max((2.05 * f0) / scale, f1[0] * 1.25);
+  if (f2[0] < want2) {
+    f2[2] *= want2 / f2[0];
+    f2[0] = want2;
+  }
+  return out;
+}