@hraness/dawg 0.3.0 → 0.4.0

package/src/audio/effects/filter.ts

@@ -0,0 +1,319 @@
+/**
+ * Filter stages: the track filter (`track.filter`, lpf/hpf/bpf with 12db,
+ * 24db or ladder slope), the one-knob DJ filter, the LFO auto filter and the
+ * vowel formant bank. All run on the mono track signal before pan.
+ */
+import { SCORE_LIMITS, type Track } from "../../../core/score.ts";
+import type { FxValues } from "../../../core/fx.ts";
+import {
+  Biquad,
+  CONTROL_SAMPLES,
+  OnePole,
+  Phasor,
+  clamp,
+  fxReader,
+  interpolateAutomation,
+  lfo,
+  lfoHz,
+  resonanceQ,
+  type EffectContext,
+  type FilterType,
+} from "./common.ts";
+
+/** Butterworth stage Qs for a 4-pole response; the second carries resonance. */
+const BUTTERWORTH_Q1 = 0.5412;
+const BUTTERWORTH_Q2_SCALE = 1.3066 / 0.707;
+
+/**
+ * A filter of any type and slope whose cutoff and resonance may change at
+ * control rate. `12db` is exactly the original track filter (one RBJ
+ * biquad), so documents without `type`/`ftype` render unchanged.
+ */
+export class SlopeFilter {
+  private readonly first = new Biquad();
+  private readonly second = new Biquad();
+  private readonly ladder = new Float64Array(4);
+  private ladderG = 0;
+  private ladderK = 0;
+
+  constructor(
+    private readonly type: FilterType,
+    private readonly slope: string,
+    private readonly sampleRate: number,
+  ) {}
+
+  private get isLadder(): boolean {
+    return this.slope === "ladder" && this.type === "lpf";
+  }
+
+  update(cutoff: number, resonance: number): void {
+    if (this.isLadder) {
+      const frequency = clamp(cutoff, 20, this.sampleRate * 0.45);
+      this.ladderG = 1 - Math.exp((-2 * Math.PI * frequency) / this.sampleRate);
+      this.ladderK = 3.9 * clamp(resonance, 0, 1);
+      return;
+    }
+    if (this.slope === "12db") {
+      this.first.set(this.type, cutoff, resonanceQ(resonance), this.sampleRate);
+      return;
+    }
+    this.first.set(this.type, cutoff, BUTTERWORTH_Q1, this.sampleRate);
+    this.second.set(
+      this.type,
+      cutoff,
+      resonanceQ(resonance) * BUTTERWORTH_Q2_SCALE,
+      this.sampleRate,
+    );
+  }
+
+  process(input: number): number {
+    if (this.isLadder) {
+      // Four one-pole stages with a saturated global feedback path
+      // (Moog-style ladder after Stilson & Smith / Huovilainen).
+      const stages = this.ladder;
+      const g = this.ladderG;
+      const k = this.ladderK;
+      const driven = Math.tanh(input - k * stages[3]!);
+      stages[0]! += g * (driven - stages[0]!);
+      stages[1]! += g * (stages[0]! - stages[1]!);
+      stages[2]! += g * (stages[1]! - stages[2]!);
+      stages[3]! += g * (stages[2]! - stages[3]!);
+      return stages[3]! * (1 + 0.5 * k);
+    }
+    const once = this.first.process(input);
+    return this.slope === "12db" ? once : this.second.process(once);
+  }
+}
+
+/**
+ * The track filter with static or automated cutoff and resonance (lanes
+ * `filter` and `resonance`). A lane alone, with no static filter, filters
+ * from a fully open low-pass, as the original renderer did.
+ */
+export function applyTrackFilter(
+  buffer: Float64Array,
+  track: Track,
+  context: EffectContext,
+): void {
+  const automation = track.filterAutomation ?? [];
+  const resonanceLane = track.resonanceAutomation ?? [];
+  if (!track.filter && automation.length === 0 && resonanceLane.length === 0)
+    return;
+  const { sampleRate, samplesPerTick } = context;
+  const staticCutoff = track.filter?.cutoff ?? SCORE_LIMITS.maxFilterCutoff;
+  const staticResonance = track.filter?.resonance ?? 0;
+  const automated = automation.length > 0 || resonanceLane.length > 0;
+  const filter = new SlopeFilter(
+    track.filter?.type ?? "lpf",
+    track.filter?.ftype ?? "12db",
+    sampleRate,
+  );
+  filter.update(staticCutoff, staticResonance);
+  for (let index = 0; index < buffer.length; index += 1) {
+    if (automated && index % CONTROL_SAMPLES === 0) {
+      const tick = index / samplesPerTick;
+      filter.update(
+        interpolateAutomation(automation, tick, staticCutoff),
+        interpolateAutomation(resonanceLane, tick, staticResonance),
+      );
+    }
+    buffer[index] = filter.process(buffer[index]!);
+  }
+}
+
+/** Cutoff for a DJ-filter position: 0 → 20 Hz low-pass … 1 → 20 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) };
+}
+
+/**
+ * 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.
+ */
+export function applyDjFilter(
+  buffer: Float64Array,
+  track: Track,
+  values: FxValues,
+  context: EffectContext,
+): void {
+  const value = fxReader(track, "djf", values, context).param("value");
+  const lowpass = new Biquad();
+  const highpass = new Biquad();
+  let position = -1;
+  for (let index = 0; index < buffer.length; index += 1) {
+    if (index % CONTROL_SAMPLES === 0) {
+      const next = value.at(index);
+      if (next !== position) {
+        position = next;
+        const { type, cutoff } = djCutoff(position);
+        // Both filters stay warm so sweeping across 0.5 never clicks.
+        lowpass.set(
+          "lpf",
+          type === "lpf" ? cutoff : 20_000,
+          0.8,
+          context.sampleRate,
+        );
+        highpass.set(
+          "hpf",
+          type === "hpf" ? cutoff : 20,
+          0.8,
+          context.sampleRate,
+        );
+      }
+    }
+    buffer[index] = highpass.process(lowpass.process(buffer[index]!));
+  }
+}
+
+/**
+ * Auto filter: an LFO sweeps the cutoff `depth` octaves around `cutoff`
+ * (half above, half below). `follow` adds an envelope follower that moves
+ * the cutoff by up to `follow` octaves at full input level.
+ */
+export function applyAutoFilter(
+  buffer: Float64Array,
+  track: Track,
+  values: FxValues,
+  context: EffectContext,
+): void {
+  const read = fxReader(track, "autofilter", values, context);
+  const cutoff = read.param("cutoff");
+  const resonance = read.param("resonance");
+  const depth = read.param("depth");
+  const follow = read.param("follow");
+  const rate = read.param("rate");
+  const sync = read.number("sync");
+  const shape = read.text("shape");
+  const filter = new SlopeFilter(
+    read.text("type") as FilterType,
+    "12db",
+    context.sampleRate,
+  );
+  const phasor = new Phasor(read.number("phase"));
+  const attack = Math.exp(-1 / (0.005 * context.sampleRate));
+  const release = Math.exp(-1 / (0.12 * context.sampleRate));
+  let envelope = 0;
+  let followOctaves = follow.at(0);
+  for (let index = 0; index < buffer.length; index += 1) {
+    const input = buffer[index]!;
+    const level = Math.abs(input);
+    envelope =
+      level > envelope
+        ? attack * envelope + (1 - attack) * level
+        : release * envelope + (1 - release) * level;
+    if (index % CONTROL_SAMPLES === 0) {
+      phasor.setHz(
+        lfoHz(sync, rate.at(index), context.tempoBpm),
+        context.sampleRate,
+      );
+      followOctaves = follow.at(index);
+      const sweep = lfo(shape, phasor.phase, 0x5eed) * depth.at(index) * 0.5;
+      const envelopeOctaves = followOctaves * Math.min(1, envelope * 2);
+      filter.update(
+        cutoff.at(index) * 2 ** (sweep + envelopeOctaves),
+        resonance.at(index),
+      );
+    }
+    phasor.next();
+    buffer[index] = filter.process(input);
+  }
+}
+
+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;
+
+/** Vowel formant filter (Strudel `vowel`): five parallel band-passes. */
+export function applyVowel(
+  buffer: Float64Array,
+  track: Track,
+  values: FxValues,
+  context: EffectContext,
+): void {
+  const read = fxReader(track, "vowel", values, context);
+  const formants = VOWEL_FORMANTS[read.text("vowel")] ?? VOWEL_FORMANTS.a!;
+  const mix = read.param("mix");
+  const bank = formants.map(([frequency, level, bandwidth]) => {
+    const filter = new Biquad();
+    filter.set("bpf", frequency, frequency / bandwidth, context.sampleRate);
+    return { filter, gain: 10 ** (level / 20) };
+  });
+  // 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);
+    const input = buffer[index]!;
+    const emphasized = input + 0.5 * (input - tilt.process(input));
+    let sum = 0;
+    for (const band of bank) sum += band.filter.process(emphasized) * band.gain;
+    buffer[index] = input + (sum * VOWEL_GAIN - input) * wet;
+  }
+}

package/src/audio/effects/modulation.ts

@@ -0,0 +1,174 @@
+/**
+ * Stereo modulation stages after pan: phaser, chorus and leslie.
+ */
+import type { Track } from "../../../core/score.ts";
+import type { FxValues } from "../../../core/fx.ts";
+import {
+  CONTROL_SAMPLES,
+  Phasor,
+  clamp,
+  fxReader,
+  lfoHz,
+  readFractional,
+  type EffectContext,
+} from "./common.ts";
+
+const PHASER_STAGES = 4;
+const PHASER_FEEDBACK = 0.3;
+
+/**
+ * Four first-order all-pass stages whose break frequency an LFO sweeps
+ * `sweep` Hz around `center`; summing with the dry signal cuts moving
+ * notches. Both channels share the LFO so the pan image holds.
+ */
+export function applyPhaser(
+  left: Float64Array,
+  right: Float64Array,
+  track: Track,
+  values: FxValues,
+  context: EffectContext,
+): void {
+  const read = fxReader(track, "phaser", values, context);
+  const rate = read.param("rate");
+  const depth = read.param("depth");
+  const sync = read.number("sync");
+  const center = read.number("center");
+  const sweep = read.number("sweep");
+  const { sampleRate } = context;
+  const states = [
+    new Float64Array(PHASER_STAGES),
+    new Float64Array(PHASER_STAGES),
+  ];
+  const feedback = [0, 0];
+  const phasor = new Phasor(0);
+  let coefficient = 0;
+  let amount = depth.at(0);
+  const channel = (side: 0 | 1, input: number): number => {
+    const state = states[side]!;
+    let signal = input + feedback[side]! * PHASER_FEEDBACK;
+    for (let stage = 0; stage < PHASER_STAGES; stage += 1) {
+      // y = a·x + x[n-1] − a·y[n-1], kept as one state per stage.
+      const output = coefficient * signal + state[stage]!;
+      state[stage] = signal - coefficient * output;
+      signal = output;
+    }
+    feedback[side] = signal;
+    return input * (1 - amount / 2) + signal * (amount / 2);
+  };
+  for (let index = 0; index < left.length; index += 1) {
+    if (index % CONTROL_SAMPLES === 0) {
+      phasor.setHz(lfoHz(sync, rate.at(index), context.tempoBpm), sampleRate);
+      if (depth.automated) amount = depth.at(index);
+      const frequency = clamp(
+        center + (sweep / 2) * Math.sin(2 * Math.PI * phasor.phase),
+        20,
+        sampleRate * 0.45,
+      );
+      const t = Math.tan((Math.PI * frequency) / sampleRate);
+      coefficient = (t - 1) / (t + 1);
+    }
+    phasor.next();
+    left[index] = channel(0, left[index]!);
+    right[index] = channel(1, right[index]!);
+  }
+}
+
+const CHORUS_BASE_MS = 12;
+const CHORUS_SWING_MS = 6;
+
+/**
+ * Stereo chorus: each side reads a delay line modulated by a sine LFO, the
+ * right a quarter cycle behind the left, blended with the dry signal.
+ */
+export function applyChorus(
+  left: Float64Array,
+  right: Float64Array,
+  track: Track,
+  values: FxValues,
+  context: EffectContext,
+): void {
+  const read = fxReader(track, "chorus", values, context);
+  const rate = read.param("rate");
+  const depth = read.param("depth");
+  const mix = read.param("mix");
+  const { sampleRate } = context;
+  const size =
+    Math.ceil(((CHORUS_BASE_MS + CHORUS_SWING_MS) / 1000) * sampleRate) + 4;
+  const lines = [new Float64Array(size), new Float64Array(size)];
+  const phasor = new Phasor(0);
+  const base = (CHORUS_BASE_MS / 1000) * sampleRate;
+  const swing = (CHORUS_SWING_MS / 1000) * sampleRate;
+  let amount = depth.at(0);
+  let wet = mix.at(0);
+  for (let index = 0; index < left.length; index += 1) {
+    if (index % CONTROL_SAMPLES === 0) {
+      phasor.setHz(rate.at(index), sampleRate);
+      if (depth.automated) amount = depth.at(index);
+      if (mix.automated) wet = mix.at(index);
+    }
+    const phase = phasor.next();
+    const write = index % size;
+    for (let side = 0; side < 2; side += 1) {
+      const buffer = side === 0 ? left : right;
+      const line = lines[side]!;
+      const input = buffer[index]!;
+      line[write] = input;
+      const delay =
+        base +
+        swing *
+          amount *
+          0.5 *
+          (1 + Math.sin(2 * Math.PI * (phase + side * 0.25)));
+      const delayed = readFractional(line, write, delay);
+      buffer[index] = input * (1 - wet) + delayed * wet;
+    }
+  }
+}
+
+const LESLIE_BASE_MS = 3;
+const LESLIE_DOPPLER_MS = 1.5;
+const LESLIE_AM = 0.35;
+
+/**
+ * Rotary speaker: the mono sum feeds a horn whose distance from two
+ * microphones (left, right) swings with the rotation, giving opposed
+ * Doppler pitch warble and amplitude rotation; `size` scales the Doppler.
+ */
+export function applyLeslie(
+  left: Float64Array,
+  right: Float64Array,
+  track: Track,
+  values: FxValues,
+  context: EffectContext,
+): void {
+  const read = fxReader(track, "leslie", values, context);
+  const rate = read.param("rate");
+  const mix = read.param("mix");
+  const size = read.number("size");
+  const { sampleRate } = context;
+  const base = (LESLIE_BASE_MS / 1000) * sampleRate;
+  const doppler = (LESLIE_DOPPLER_MS / 1000) * sampleRate * size;
+  const length = Math.ceil(base + doppler) + 4;
+  const line = new Float64Array(length);
+  const phasor = new Phasor(0);
+  let wet = mix.at(0);
+  for (let index = 0; index < left.length; index += 1) {
+    if (index % CONTROL_SAMPLES === 0) {
+      phasor.setHz(rate.at(index), sampleRate);
+      if (mix.automated) wet = mix.at(index);
+    }
+    const angle = 2 * Math.PI * phasor.next();
+    const write = index % length;
+    const dryL = left[index]!;
+    const dryR = right[index]!;
+    line[write] = (dryL + dryR) / 2;
+    const sin = Math.sin(angle);
+    const cos = Math.cos(angle);
+    const hornL = readFractional(line, write, base + doppler * 0.5 * (1 + sin));
+    const hornR = readFractional(line, write, base + doppler * 0.5 * (1 - sin));
+    const wetL = hornL * (1 + LESLIE_AM * cos);
+    const wetR = hornR * (1 - LESLIE_AM * cos);
+    left[index] = dryL * (1 - wet) + wetL * wet;
+    right[index] = dryR * (1 - wet) + wetR * wet;
+  }
+}