@hraness/dawg 0.6.0 → 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/dsp/shift.ts

@@ -0,0 +1,256 @@
+/**
+ * Pitch shift at constant duration (0.6 B2 `shift`, `formant`), ported from
+ * the granular prototype (`proto/granular/stretch.ts` `pitchShift`):
+ * phase-vocoder stretch by rho = 2^(st/12) onto an intermediate axis (bins
+ * above Nyquist/rho dropped so the read-back cannot alias), then read it
+ * rho times faster with a 4-point Hermite, so the length is kept exactly.
+ *
+ * Formants: absent follows the pitch (like a tape); a number moves them
+ * that many semitones from where they were, so `0` keeps them (cepstral
+ * envelope from `envelope.ts`: magnitudes are divided by the frame's
+ * envelope and multiplied by the envelope warped to where it must land
+ * after the read-back). Identity phase locking after Laroche and Dolson,
+ * "Improved phase vocoder time-scale modification of audio", IEEE TSAP 1999.
+ * Strudel's `stretch` (superdough's phase-vocoder worklet) is the same idea.
+ */
+import {
+  ENVELOPE_ITERATIONS,
+  ENVELOPE_LIFTER_SECONDS,
+  cepstralEnvelope,
+  envelopeScratch,
+  peakEnvelope,
+} from "./envelope.ts";
+import { hermite4 } from "./interp.ts";
+import {
+  HANN_SQUARED_OLA_QUARTER,
+  analyse,
+  frameSize,
+  hann,
+  inverse,
+  princarg,
+  sampleAt,
+} from "./stft.ts";
+
+/** Analysis frame, as the `tones` fit (85 ms). */
+export const SHIFT_FRAME_SECONDS = 0.085;
+/** Vocoder hops between yields of `pitchShiftJob`. */
+const SHIFT_YIELD_HOPS = 16;
+/** Largest per-frame level restore after formant correction (12 dB). */
+const FORMANT_LEVEL_CAP = 4;
+/** Largest formant correction gain (24 dB), so a deep envelope dip cannot explode. */
+const MAX_FORMANT_GAIN = 16;
+
+export type ShiftOptions = Readonly<{
+  /** Formant shift in semitones; 0 keeps them; absent follows the pitch. */
+  formant?: number;
+  /** Frame length in seconds (rounded up to a power of two). */
+  frame?: number;
+  /** Cepstral lifter in seconds. */
+  lifter?: number;
+  /** True-envelope passes (0 is the plain cepstral envelope; default 16). */
+  iterations?: number;
+  /** Shrink the lifter to a quarter pitch period per frame (default on). */
+  adaptive?: boolean;
+  /**
+   * Envelope used to keep formants: "peaks" (default) joins the harmonic
+   * peaks; "cepstral" is the true cepstral envelope alone.
+   */
+  envelope?: "peaks" | "cepstral";
+}>;
+
+/**
+ * Phase vocoder reading `x` at `t / rho` for `outLength` frames, with
+ * bins above Nyquist/rho removed and optional formant correction for a
+ * later read-back at `rho`.
+ */
+function* stretchForShift(
+  x: ArrayLike<number>,
+  sampleRate: number,
+  rho: number,
+  outLength: number,
+  formantRatio: number | undefined,
+  options: ShiftOptions,
+): Generator<void, Float64Array> {
+  const n = frameSize(options.frame ?? SHIFT_FRAME_SECONDS, sampleRate);
+  const hs = n / 4;
+  const half = n / 2;
+  const w = hann(n);
+  const norm = 1 / HANN_SQUARED_OLA_QUARTER;
+  const keep = rho > 1 ? Math.floor(half / rho) : half;
+  const lifter = Math.max(
+    4,
+    Math.round((options.lifter ?? ENVELOPE_LIFTER_SECONDS) * sampleRate),
+  );
+  const periodRange = [sampleRate / 800, sampleRate / 50] as const;
+  const out = new Float64Array(outLength + n);
+  const reA = new Float64Array(n);
+  const imA = new Float64Array(n);
+  const reB = new Float64Array(n);
+  const imB = new Float64Array(n);
+  const mag = new Float64Array(half + 1);
+  const phA = new Float64Array(half + 1);
+  const syn = new Float64Array(half + 1);
+  const next = new Float64Array(half + 1);
+  const omega = new Float64Array(half + 1);
+  const env = new Float64Array(half + 1);
+  const scratch = envelopeScratch(n);
+  const smooth = new Float64Array(half + 1);
+  const envPeaks: number[] = [];
+  const peaks: number[] = [];
+  for (let m = 0; m * hs < outLength; m += 1) {
+    if (m % SHIFT_YIELD_HOPS === SHIFT_YIELD_HOPS - 1) yield;
+    const at = Math.round((m * hs + half) / rho - half);
+    analyse(x, at, w, reA, imA);
+    analyse(x, at - hs, w, reB, imB);
+    for (let k = 0; k <= half; k += 1) {
+      mag[k] = Math.hypot(reA[k]!, imA[k]!);
+      phA[k] = Math.atan2(imA[k]!, reA[k]!);
+      const phB = Math.atan2(imB[k]!, reB[k]!);
+      const bin = (2 * Math.PI * k * hs) / n;
+      omega[k] = bin + princarg(phA[k]! - phB - bin);
+    }
+    if (formantRatio !== undefined)
+      cepstralEnvelope(
+        mag,
+        n,
+        lifter,
+        env,
+        scratch,
+        options.iterations ?? ENVELOPE_ITERATIONS,
+        options.adaptive === false ? undefined : periodRange,
+      );
+    if (formantRatio !== undefined && options.envelope !== "cepstral") {
+      smooth.set(env);
+      peakEnvelope(mag, half, env, smooth, envPeaks);
+    }
+    if (m === 0) syn.set(phA);
+    else {
+      peaks.length = 0;
+      for (let k = 2; k <= half - 2; k += 1) {
+        const v = mag[k]!;
+        if (
+          v > mag[k - 1]! &&
+          v >= mag[k + 1]! &&
+          v > mag[k - 2]! &&
+          v >= mag[k + 2]!
+        )
+          peaks.push(k);
+      }
+      if (peaks.length === 0)
+        for (let k = 0; k <= half; k += 1) syn[k] = syn[k]! + omega[k]!;
+      else {
+        for (const p of peaks) next[p] = syn[p]! + omega[p]!;
+        let j = 0;
+        for (let k = 0; k <= half; k += 1) {
+          while (
+            j + 1 < peaks.length &&
+            Math.abs(peaks[j + 1]! - k) < Math.abs(peaks[j]! - k)
+          )
+            j += 1;
+          const p = peaks[j]!;
+          if (k !== p) next[k] = next[p]! + phA[k]! - phA[p]!;
+        }
+        syn.set(next);
+      }
+    }
+    let before = 0;
+    let after = 0;
+    for (let k = 0; k <= half; k += 1) {
+      let a = k > keep ? 0 : mag[k]!;
+      before += a * a;
+      if (formantRatio !== undefined && a > 0) {
+        // Bin k lands at k*rho after the read-back; give it the envelope
+        // found at k*rho/formantRatio in the source frame.
+        const src = (k * rho) / formantRatio;
+        const i0 = Math.floor(src);
+        const target =
+          i0 + 1 <= half
+            ? env[i0]! + (env[i0 + 1]! - env[i0]!) * (src - i0)
+            : env[half]! * 1e-3;
+        a *= Math.min(target / env[k]!, MAX_FORMANT_GAIN);
+      }
+      after += a * a;
+      reA[k] = a * Math.cos(syn[k]!);
+      imA[k] = a * Math.sin(syn[k]!);
+      if (k > 0 && k < half) {
+        reA[n - k] = reA[k]!;
+        imA[n - k] = -imA[k]!;
+      }
+    }
+    imA[0] = 0;
+    imA[half] = 0;
+    // Formant correction reshapes the spectrum, not the loudness: give the
+    // frame back its energy (a scale moves no peak), capped at 12 dB.
+    if (formantRatio !== undefined && after > 0) {
+      const gain = Math.min(Math.sqrt(before / after), FORMANT_LEVEL_CAP);
+      for (let k = 0; k < n; k += 1) {
+        reA[k] = reA[k]! * gain;
+        imA[k] = imA[k]! * gain;
+      }
+    }
+    inverse(reA, imA);
+    const o0 = m * hs;
+    for (let i = 0; i < n; i += 1)
+      out[o0 + i] = out[o0 + i]! + reA[i]! * w[i]! * norm;
+  }
+  return out;
+}
+
+/**
+ * `x` shifted by `semitones` at the same length. `formant` (semitones)
+ * moves the formants independently; 0 keeps them.
+ */
+export function pitchShift(
+  x: ArrayLike<number>,
+  sampleRate: number,
+  semitones: number,
+  options: ShiftOptions = {},
+): Float32Array {
+  const job = pitchShiftJob(x, sampleRate, semitones, options);
+  for (;;) {
+    const step = job.next();
+    if (step.done) return step.value;
+  }
+}
+
+/**
+ * `pitchShift` as resumable work: yields every few vocoder hops so a live
+ * engine can spread a long shift over idle time (`src/audio/fit.ts`).
+ */
+export function* pitchShiftJob(
+  x: ArrayLike<number>,
+  sampleRate: number,
+  semitones: number,
+  options: ShiftOptions = {},
+): Generator<void, Float32Array> {
+  const length = x.length;
+  const out = new Float32Array(length);
+  if (semitones === 0 && options.formant === undefined) {
+    for (let i = 0; i < length; i += 1) out[i] = x[i]!;
+    return out;
+  }
+  const rho = 2 ** (semitones / 12);
+  const formantRatio =
+    options.formant === undefined ? undefined : 2 ** (options.formant / 12);
+  const midLength = Math.ceil(length * rho) + 4;
+  const y = yield* stretchForShift(
+    x,
+    sampleRate,
+    rho,
+    midLength,
+    formantRatio,
+    options,
+  );
+  for (let i = 0; i < length; i += 1) {
+    const pos = i * rho;
+    const j = Math.floor(pos);
+    out[i] = hermite4(
+      sampleAt(y, j - 1),
+      sampleAt(y, j),
+      sampleAt(y, j + 1),
+      sampleAt(y, j + 2),
+      pos - j,
+    );
+  }
+  return out;
+}

package/src/audio/effects/chain.ts

@@ -1,9 +1,10 @@
 /**
  * The fixed per-track effects chain (`FX_CHAIN` in core/fx.ts):
  *
- *   filter → djf → autofilter → vowel → crush → distort → stomp → head →
- *   cab → tremolo →
- *   compressor → pan → phaser → chorus → leslie → postgain → delay → reverb
+ *   filter → djf → autofilter → formant → vowel → crush → distort → stomp → head →
+ *   cab → wobble → bloom → swell → tremolo →
+ *   compressor → pan → double → 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.
@@ -12,6 +13,7 @@ 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 { applyBloom, applyDouble, applySwell, applyWobble } from "./gaze.ts";
 import { applyCompressor, applyPostgain, applyTremolo } from "./dynamics.ts";
 import {
   applyAutoFilter,
@@ -19,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";
@@ -32,7 +35,16 @@ export {
   reverbWet,
   type ReverbWet,
 } from "./space.ts";
-export { interpolateAutomation, type EffectContext } from "./common.ts";
+export {
+  interpolateAutomation,
+  type EffectContext,
+  type EffectNote,
+} from "./common.ts";
+
+/** Whether `track` has a stage that reads `EffectContext.notes`. */
+export function needsEffectNotes(track: Track | undefined): boolean {
+  return Boolean(track?.fx?.bloom || track?.fx?.swell);
+}
 
 type MonoStage = (
   buffer: Float64Array,
@@ -51,17 +63,22 @@ type StereoStage = (
 const MONO: Readonly<Partial<Record<FxName, MonoStage>>> = Object.freeze({
   djf: applyDjFilter,
   autofilter: applyAutoFilter,
+  formant: applyFormant,
   vowel: applyVowel,
   crush: applyCrush,
   distort: applyDistort,
   stomp: applyStomp,
   head: applyHead,
   cab: applyCab,
+  wobble: applyWobble,
+  bloom: applyBloom,
+  swell: applySwell,
   tremolo: applyTremolo,
   compressor: applyCompressor,
 });
 
 const STEREO: Readonly<Partial<Record<FxName, StereoStage>>> = Object.freeze({
+  double: applyDouble,
   phaser: applyPhaser,
   chorus: applyChorus,
   leslie: applyLeslie,

package/src/audio/effects/common.ts

@@ -25,6 +25,25 @@ export type EffectContext = Readonly<{
   irs?: ReadonlyMap<string, DecodedSample>;
   /** The song's tempo map in samples; absent: constant tempo. */
   warp?: SampleWarp;
+  /**
+   * The track's notes in buffer samples, for note-aware stages (bloom,
+   * 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. */
+export type EffectNote = Readonly<{
+  id: string;
+  start: number;
+  length: number;
+  hz: number;
+  velocity: number;
 }>;
 
 /** Score tick at sample `index`, through the tempo map when there is one. */
@@ -180,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;