@hraness/dawg 0.6.1 → 0.7.0

package/src/audio/dsp/psola.ts

@@ -0,0 +1,199 @@
+/**
+ * Time-varying TD-PSOLA (Moulines and Charpentier, Speech Communication
+ * 1990) for 0.7 Voice. Analysis marks sit one per period on voiced runs;
+ * two-period Hann grains are re-spaced at the corrected period and
+ * overlap-added at the same time position, so duration is kept and the
+ * spectral envelope (formants) stays where it was. Unvoiced stretches are
+ * copied with fixed 4 ms grains at ratio 1, so breath and consonants pass
+ * through unchanged.
+ *
+ * Review fixes over the prototype: mark polarity is chosen once per voiced
+ * run (the sign of sum x^3), so negative-going glottal closures and inverted
+ * microphones mark the same way every period; grains are placed at
+ * fractional output positions with 4-point Hermite reads instead of a 2-tap
+ * split; stereo shares one set of marks found on the mid signal.
+ *
+ * Autotune and the 0.7.1 harmony lane import these unchanged.
+ */
+import { hermiteAt } from "./interp.ts";
+
+/** Unvoiced grain spacing in seconds. */
+export const UNVOICED_PERIOD = 0.004;
+
+/** What a psola pass does, per input sample. */
+export type ShiftCurve = Readonly<{
+  /** Input f0 in Hz per input sample (0 = unvoiced). */
+  f0: Float64Array;
+  /** Shift in cents per input sample (ignored where unvoiced). */
+  cents: Float64Array;
+}>;
+
+export type PsolaOptions = Readonly<{
+  /**
+   * Formant factor: grains are read this many times faster, which moves the
+   * spectral envelope by the same ratio (1 keeps it, the default). Limited to
+   * 0.5..2.
+   */
+  formant?: number;
+  /** First input sample of the output (default 0). */
+  offset?: number;
+  /** Output length in samples (default the rest of the input). */
+  length?: number;
+  /** Precomputed analysis marks (from `pitchMarks`), e.g. shared by L/R. */
+  marks?: Int32Array;
+}>;
+
+/**
+ * Analysis marks: one per period at the waveform's largest peak (in the
+ * run's polarity) near the expected place, and one every 4 ms where
+ * unvoiced.
+ */
+export function pitchMarks(
+  x: Float64Array,
+  sampleRate: number,
+  f0: Float64Array,
+): Int32Array {
+  const n = x.length;
+  const up = Math.max(1, Math.round(UNVOICED_PERIOD * sampleRate));
+  const polarity = new Int8Array(n).fill(1);
+  for (let a = 0; a < n;) {
+    if (!(f0[a]! > 0)) {
+      a += 1;
+      continue;
+    }
+    let b = a;
+    let s3 = 0;
+    while (b < n && f0[b]! > 0) {
+      s3 += x[b]! ** 3;
+      b += 1;
+    }
+    if (s3 < 0) polarity.fill(-1, a, b);
+    a = b;
+  }
+  const marks: number[] = [];
+  let i = 0;
+  while (i < n) {
+    const hz = f0[i]!;
+    if (!(hz > 0)) {
+      marks.push(i);
+      i += up;
+      continue;
+    }
+    const period = sampleRate / hz;
+    const last = marks.length ? marks[marks.length - 1]! : -1;
+    const afterVoiced = last >= 0 && f0[last]! > 0;
+    const lo = Math.max(0, Math.round(i - (afterVoiced ? period / 4 : 0)));
+    const hi = Math.min(
+      n - 1,
+      Math.round(i + (afterVoiced ? period / 4 : period)),
+    );
+    const sign = polarity[i]!;
+    let best = lo;
+    for (let j = lo + 1; j <= hi; j += 1)
+      if (sign * x[j]! > sign * x[best]!) best = j;
+    if (last >= 0 && best <= last)
+      best = last + Math.max(1, Math.round(period / 2));
+    if (best >= n) break;
+    marks.push(best);
+    const next = f0[best]! > 0 ? sampleRate / f0[best]! : period;
+    i = best + Math.max(1, Math.round(next));
+  }
+  return Int32Array.from(marks);
+}
+
+/**
+ * Shifts the pitch of `x` by `curve.cents` while keeping duration and (at
+ * formant 1) the formants. Deterministic: same input, same bytes.
+ */
+export function psola(
+  x: Float64Array,
+  sampleRate: number,
+  curve: ShiftCurve,
+  options: PsolaOptions = {},
+): Float64Array {
+  const n = x.length;
+  const offset = Math.max(0, Math.min(n, Math.round(options.offset ?? 0)));
+  const length = Math.max(0, Math.round(options.length ?? n - offset));
+  const out = new Float64Array(length);
+  const marks = options.marks ?? pitchMarks(x, sampleRate, curve.f0);
+  if (marks.length === 0 || length === 0) return out;
+  const formant = Math.min(2, Math.max(0.5, options.formant ?? 1));
+  const up = UNVOICED_PERIOD * sampleRate;
+  const end = offset + length;
+  // synthesis marks walk the output at the target period; each takes the
+  // nearest analysis mark
+  // The walk always starts at the first mark, so a window (offset, length)
+  // renders exactly the samples of the whole pass.
+  let k = 0;
+  let t = marks[0]!;
+  while (t < end + up) {
+    while (
+      k + 1 < marks.length &&
+      Math.abs(marks[k + 1]! - t) <= Math.abs(marks[k]! - t)
+    )
+      k += 1;
+    const m = marks[k]!;
+    const hz = curve.f0[m]!;
+    const voiced = hz > 0;
+    const period = voiced ? sampleRate / hz : up;
+    // the analysis spacing: the next mark when it is about a period away,
+    // so ratio 1 lands every synthesis mark on its analysis mark
+    const gap = k + 1 < marks.length ? marks[k + 1]! - m : 0;
+    const pin = gap >= period * 0.5 && gap <= period * 1.5 ? gap : period;
+    const at = Math.min(n - 1, Math.max(0, Math.round(t)));
+    const ratio = voiced ? 2 ** ((curve.cents[at] || 0) / 1200) : 1;
+    const pout = pin / ratio;
+    // the grain spans the neighbouring marks, capped at 1.5 periods a side
+    const left =
+      k > 0 ? Math.min(period * 1.5, Math.max(2, m - marks[k - 1]!)) : period;
+    const right =
+      k + 1 < marks.length
+        ? Math.min(period * 1.5, Math.max(2, marks[k + 1]! - m))
+        : period;
+    const f = voiced ? formant : 1;
+    const gain = voiced ? Math.min(2, (pout * f) / pin) : 1;
+    // output span of the grain, in output samples around t
+    const lo = Math.max(offset, Math.ceil(t - left / f));
+    const hi = Math.min(end - 1, Math.floor(t + right / f));
+    for (let o = lo; o <= hi; o += 1) {
+      const j = (o - t) * f;
+      const w =
+        j < 0
+          ? 0.5 * (1 + Math.cos((Math.PI * j) / left))
+          : 0.5 * (1 + Math.cos((Math.PI * j) / right));
+      out[o - offset]! += hermiteAt(x, m + j) * w * gain;
+    }
+    // unvoiced grains are copied in place, so the walk re-anchors on the
+    // marks there and enters every voiced run on its first mark
+    t = !voiced && k + 1 < marks.length ? marks[k + 1]! : t + pout;
+    if (k + 1 >= marks.length && t > m + 2 * period) break;
+  }
+  return out;
+}
+
+/**
+ * Stereo PSOLA: marks found once on the mid signal and shared by both
+ * channels, so the image does not smear. `curve.f0` comes from the mono
+ * mixdown.
+ */
+export function psolaStereo(
+  left: Float64Array,
+  right: Float64Array,
+  sampleRate: number,
+  curve: ShiftCurve,
+  options: PsolaOptions = {},
+): [Float64Array, Float64Array] {
+  const mid = new Float64Array(left.length);
+  for (let i = 0; i < mid.length; i += 1)
+    mid[i] = 0.5 * (left[i]! + (right[i] ?? 0));
+  const marks = options.marks ?? pitchMarks(mid, sampleRate, curve.f0);
+  return [
+    psola(left, sampleRate, curve, { ...options, marks }),
+    psola(right, sampleRate, curve, { ...options, marks }),
+  ];
+}
+
+/** A constant shift of `cents` over an f0-per-sample curve. */
+export function constantShift(f0: Float64Array, cents: number): ShiftCurve {
+  return { f0, cents: new Float64Array(f0.length).fill(cents) };
+}

package/src/audio/effects/chain.ts

@@ -1,7 +1,7 @@
 /**
  * The fixed per-track effects chain (`FX_CHAIN` in core/fx.ts):
  *
- *   filter → djf → autofilter → vowel → crush → distort → stomp → head →
+ *   filter → djf → autofilter → formant → vowel → crush → distort → stomp → head →
  *   cab → wobble → bloom → swell → tremolo →
  *   compressor → pan → double → phaser → chorus → leslie → postgain →
  *   delay → reverb
@@ -21,6 +21,7 @@ import {
   applyTrackFilter,
   applyVowel,
 } from "./filter.ts";
+import { applyFormant } from "./formant.ts";
 import { applyChorus, applyLeslie, applyPhaser } from "./modulation.ts";
 import { applyCab, applyHead, applyStomp } from "./rig/index.ts";
 import { applyDelay, applyReverb } from "./space.ts";
@@ -62,6 +63,7 @@ type StereoStage = (
 const MONO: Readonly<Partial<Record<FxName, MonoStage>>> = Object.freeze({
   djf: applyDjFilter,
   autofilter: applyAutoFilter,
+  formant: applyFormant,
   vowel: applyVowel,
   crush: applyCrush,
   distort: applyDistort,

package/src/audio/effects/common.ts

@@ -30,6 +30,11 @@ export type EffectContext = Readonly<{
    * swell; 0.6.1). Filled only when such a stage is on.
    */
   notes?: readonly EffectNote[];
+  /**
+   * Song seconds at buffer sample 0 when an arranged window renders (the
+   * renderer's `seedSeconds`): the formant stage anchors its frames there.
+   */
+  seedSeconds?: number;
 }>;
 
 /** One note as a note-aware effect sees it: where it sounds and its pitch. */
@@ -194,6 +199,44 @@ export class Biquad {
   }
 }
 
+/**
+ * Topology-preserving-transform state-variable filter (Zavalishin, Cytomic):
+ * g = tan(pi fc / fs), k = 1 / Q. Its state stays valid when the cutoff
+ * moves between samples, so it is the filter for modulated cutoffs where a
+ * direct-form biquad's state would no longer match its new coefficients.
+ * `bpf` is normalized to 0 dB at the peak, like `Biquad`'s band-pass.
+ */
+export class Svf {
+  private k = Math.SQRT2;
+  private a1 = 1;
+  private a2 = 0;
+  private a3 = 0;
+  private ic1 = 0;
+  private ic2 = 0;
+
+  constructor(private readonly type: FilterType) {}
+
+  set(cutoff: number, q: number, sampleRate: number): void {
+    const frequency = clamp(cutoff, 20, sampleRate * 0.45);
+    const g = Math.tan((Math.PI * frequency) / sampleRate);
+    this.k = 1 / Math.max(0.1, q);
+    this.a1 = 1 / (1 + g * (g + this.k));
+    this.a2 = g * this.a1;
+    this.a3 = g * this.a2;
+  }
+
+  process(input: number): number {
+    const v3 = input - this.ic2;
+    const v1 = this.a1 * this.ic1 + this.a2 * v3;
+    const v2 = this.ic2 + this.a2 * this.ic1 + this.a3 * v3;
+    this.ic1 = 2 * v1 - this.ic1;
+    this.ic2 = 2 * v2 - this.ic2;
+    if (this.type === "lpf") return v2;
+    if (this.type === "hpf") return input - this.k * v1 - v2;
+    return this.k * v1;
+  }
+}
+
 /** One-pole low-pass; `set` takes a cutoff in Hz. */
 export class OnePole {
   private coefficient = 0;

package/src/audio/effects/convolution.ts

@@ -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;

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;