@hraness/dawg 0.6.0 → 0.6.1

package/src/audio/winds/engine.ts

@@ -0,0 +1,302 @@
+/**
+ * The wind engine (0.6.1): renders a `wind` track's performed notes through
+ * `WindVoice` waveguides.
+ *
+ * - Lines: with no track `glide`, a note that starts while a single
+ *   earlier note is still held, and that starts alone, slurs on from it
+ *   (one breath, no re-attack) as a wind player tongues only at a new
+ *   phrase; notes that start together stay separate voices, so one track
+ *   can carry a horn-section chord. A track `glide` keeps its own meaning
+ *   (`performNotes` has already chained or split the line).
+ * - Players: `players` > 1 is a section. The players are dealt over the
+ *   tones that start together, top voice first, and each extra player on a
+ *   tone is a seeded few cents off, a few milliseconds late and a little
+ *   softer, as real section doublings are; a tone's players share its level
+ *   (1/sqrt(n)).
+ * - At most `MAX_WIND_VOICES` sound at once; the oldest onset is stolen
+ *   with an 80 ms raised-cosine fade (largest gain step -61 dB at 22.05 kHz).
+ *
+ * Deterministic: every random draw comes from `seededRandom`.
+ */
+import type { PerformedNote } from "../../../core/expression.ts";
+import {
+  MAX_WIND_VOICES,
+  WIND_LANE_PARAMS,
+  windPresetOf,
+  windSettings,
+  windTailSeconds,
+  type WindSettings,
+} from "../../../core/resonators.ts";
+import type { AutomationPoint, Track } from "../../../core/score.ts";
+import { noteHz } from "../../../core/tuning.ts";
+import { seededRandom } from "../dsp/rng.ts";
+import { interpolateAutomation } from "../effects/common.ts";
+import type { EngineContext, InstrumentEngine } from "../instruments.ts";
+import { applyModalKnee } from "../resonators.ts";
+import { warpedSpan } from "../warp.ts";
+import { windTrim } from "./trim.ts";
+import { WIND_BLOCK, WindVoice, type WindSegment } from "./voice.ts";
+
+/** A gap this short between a line's end and the next onset still slurs. */
+const SLUR_GAP_SECONDS = 0.01;
+
+/** Fade applied to a stolen voice, seconds. */
+export const WIND_STEAL_FADE = 0.08;
+/** Section doublings: the widest detune (cents) and latest entry (s). */
+const SECTION_CENTS = 9;
+const SECTION_LATE = 0.018;
+
+/** Breath push per articulation (accent and marcato blow harder). */
+const PUSH: Readonly<Record<string, number>> = Object.freeze({
+  accent: 0.15,
+  marcato: 0.25,
+  ghost: -0.4,
+});
+
+type Line = {
+  start: number;
+  length: number;
+  notes: PerformedNote[];
+  segments: WindSegment[];
+};
+
+function span(
+  note: PerformedNote,
+  context: EngineContext,
+): { start: number; length: number } {
+  if (context.warp)
+    return warpedSpan(context.warp, note.startTick, note.durationTicks);
+  const perTick =
+    (60 * context.sampleRate) / (context.tempoBpm * context.ticksPerBeat);
+  return {
+    start: Math.max(0, Math.floor(note.startTick * perTick)),
+    length: Math.max(1, Math.floor(note.durationTicks * perTick)),
+  };
+}
+
+function laneOf(
+  track: Track,
+  param: string,
+): readonly AutomationPoint[] | undefined {
+  const lanes = track.fxAutomation as
+    Readonly<Record<string, readonly AutomationPoint[]>> | undefined;
+  const points = lanes?.[`wind-${param}`];
+  return points && points.length > 0 ? points : undefined;
+}
+
+/**
+ * Groups performed notes into breaths: chords stay separate voices, a lone
+ * note entering under a lone held note slurs on (when `legato`).
+ */
+export function windLines(
+  notes: readonly PerformedNote[],
+  context: EngineContext,
+  legato: boolean,
+): Line[] {
+  const planned = notes
+    .map((note) => ({ note, ...span(note, context) }))
+    .filter((entry) => entry.start < context.samples)
+    .sort(
+      (a, b) =>
+        a.start - b.start ||
+        b.note.pitch - a.note.pitch ||
+        (a.note.id < b.note.id ? -1 : a.note.id > b.note.id ? 1 : 0),
+    );
+  const lines: Line[] = [];
+  const slurGap = Math.round(SLUR_GAP_SECONDS * context.sampleRate);
+  let index = 0;
+  let previous: Line[] = [];
+  while (index < planned.length) {
+    const at = planned[index]!.start;
+    const group: typeof planned = [];
+    while (index < planned.length && planned[index]!.start === at)
+      group.push(planned[index++]!);
+    // A note that starts where the line ends (to within a few ms, so the
+    // tick-to-sample rounding of abutting notes counts) is held through:
+    // a typed line of back-to-back quarters slurs, a real rest re-tongues.
+    const held = previous.filter(
+      (line) => line.start + line.length + slurGap > at,
+    );
+    const only = group[0]!;
+    if (
+      legato &&
+      group.length === 1 &&
+      held.length === 1 &&
+      previous.length === 1 &&
+      !only.note.performance?.cents &&
+      only.note.articulation !== "staccato"
+    ) {
+      const line = held[0]!;
+      line.notes.push(only.note);
+      line.segments.push({
+        at: at - line.start,
+        hz: noteHz(only.note.pitch, only.note.cents, context.tuning),
+      });
+      line.length = only.start + only.length - line.start;
+      continue;
+    }
+    previous = group.map(({ note, start, length }) => ({
+      start,
+      length,
+      notes: [note],
+      segments: [{ at: 0, hz: noteHz(note.pitch, note.cents, context.tuning) }],
+    }));
+    lines.push(...previous);
+  }
+  return lines;
+}
+
+type Planned = {
+  voice: WindVoice;
+  start: number;
+  end: number;
+  steal: number;
+  level: number;
+};
+
+/** Renders a wind track's performed notes into `dry` (mono). */
+export function renderWindTrack(
+  dry: Float64Array,
+  notes: readonly PerformedNote[],
+  track: Track,
+  context: EngineContext,
+): void {
+  const { sampleRate, samples } = context;
+  const tickAt = (index: number): number =>
+    context.warp ? context.warp.tick(index) : index / context.samplesPerTick;
+  const lanes = new Map<string, readonly AutomationPoint[]>();
+  for (const { param } of WIND_LANE_PARAMS) {
+    const points = laneOf(track, param);
+    if (points) lanes.set(param, points);
+  }
+  const base = windSettings(track.wind);
+  const trim = windTrim(windPresetOf(track.wind), sampleRate);
+  const players = Math.max(1, Math.round(base.players));
+  const seedTick = context.seedTick ?? 0;
+  const volumeLane = track.volumeAutomation ?? [];
+  const volume = Math.max(0, Math.min(1, track.volume ?? 1));
+  const gainAt = (index: number): number =>
+    volume *
+    (volumeLane.length > 0
+      ? interpolateAutomation(volumeLane, tickAt(index), 1)
+      : 1);
+  const lines = windLines(notes, context, track.glide === undefined);
+  const planned: Planned[] = [];
+  // Deal the section over each onset's tones, top voice first.
+  let i = 0;
+  while (i < lines.length) {
+    let j = i;
+    while (j < lines.length && lines[j]!.start === lines[i]!.start) j += 1;
+    const tones = lines.slice(i, j);
+    const counts = tones.map(() => 1);
+    for (let k = tones.length; k < players; k += 1)
+      counts[k % tones.length]! += 1;
+    tones.forEach((line, t) => {
+      const head = line.notes[0]!;
+      const seed = `${head.id}:${head.startTick + seedTick}`;
+      const push = PUSH[head.articulation ?? ""] ?? 0;
+      const count = counts[t]!;
+      const random = seededRandom(`${seed}:section`);
+      for (let player = 0; player < count; player += 1) {
+        const cents =
+          player === 0 ? 0 : SECTION_CENTS * (2 * random() - 1) || 0.5;
+        const late =
+          player === 0 ? 0 : Math.round(SECTION_LATE * random() * sampleRate);
+        const soft = player === 0 ? 1 : 0.8 + 0.15 * random();
+        const start = line.start + late;
+        if (start >= samples) continue;
+        const ratio = 2 ** (cents / 1200);
+        const bend = head.performance?.cents;
+        const voice = new WindVoice(
+          base,
+          {
+            segments: line.segments.map((s) => ({
+              at: s.at,
+              hz: s.hz * ratio,
+            })),
+            length: Math.max(1, line.length - late),
+            velocity: head.velocity,
+            seed: player === 0 ? seed : `${seed}:${player}`,
+            ...(push ? { push } : {}),
+            ...(bend ? { cents: bend } : {}),
+            ...(lanes.size > 0
+              ? {
+                  lane: (param: string, t: number) => {
+                    const points = lanes.get(param);
+                    return points
+                      ? interpolateAutomation(
+                          points,
+                          tickAt(start + t * sampleRate),
+                          base[param as keyof WindSettings] as number,
+                        )
+                      : undefined;
+                  },
+                }
+              : {}),
+          },
+          sampleRate,
+          trim,
+        );
+        planned.push({
+          voice,
+          start,
+          end: start + voice.endAt,
+          steal: Infinity,
+          level: soft / Math.sqrt(count),
+        });
+      }
+    });
+    i = j;
+  }
+  planned.sort((a, b) => a.start - b.start);
+  const fade = Math.max(1, Math.round(WIND_STEAL_FADE * sampleRate));
+  const sounding: Planned[] = [];
+  for (const entry of planned) {
+    for (let k = sounding.length - 1; k >= 0; k -= 1)
+      if (sounding[k]!.end <= entry.start) sounding.splice(k, 1);
+    while (sounding.length >= MAX_WIND_VOICES) {
+      const oldest = sounding.shift()!;
+      oldest.steal = entry.start;
+      oldest.end = Math.min(oldest.end, entry.start + fade);
+    }
+    sounding.push(entry);
+  }
+  const scratch = new Float64Array(WIND_BLOCK);
+  for (const { voice, start, end, steal, level } of planned) {
+    const stop = Math.min(samples, end);
+    let at = start;
+    while (at < stop) {
+      const count = Math.min(WIND_BLOCK, stop - at);
+      scratch.fill(0, 0, count);
+      const alive = voice.process(scratch, 0, count);
+      const gain = gainAt(at) * level;
+      for (let k = 0; k < count; k += 1) {
+        const index = at + k;
+        let g = gain;
+        if (index >= steal)
+          g *=
+            index - steal >= fade
+              ? 0
+              : 0.5 + 0.5 * Math.cos((Math.PI * (index - steal)) / fade);
+        dry[index]! += scratch[k]! * g;
+      }
+      if (!alive) break;
+      at += count;
+    }
+  }
+  // The modal engine's soft knee: transparent below -3 dBFS, so a chord or
+  // section does not clip; causal and stateless, so renders stay prefix-stable.
+  applyModalKnee(dry, samples);
+}
+
+/** The wind engine as registered in `src/audio/instruments.ts`. */
+export const WIND_ENGINE: InstrumentEngine = Object.freeze({
+  id: "wind",
+  field: "wind",
+  render(dry, _dryR, notes, track, context) {
+    renderWindTrack(dry, notes, track, context);
+  },
+  tailSeconds: (track: Track) => windTailSeconds(track.wind),
+  stereo: () => false,
+  assetDigests: (track: Track) => [`winds:1:${windPresetOf(track.wind)}`],
+});

package/src/audio/winds/filters.ts

@@ -0,0 +1,153 @@
+/**
+ * Filters the wind voice needs beyond dawg's `Biquad` (lpf, hpf, bpf):
+ * the RBJ cookbook peak and high shelf for mutes and the dynamics shelf
+ * (Robert Bristow-Johnson, "Cookbook formulae for audio EQ biquad filter
+ * coefficients"). A new class so the shared `Biquad` stays untouched.
+ */
+import { thiranFor } from "../dsp/interp.ts";
+
+export type WindFilterType = "lpf" | "hpf" | "bpf" | "peak" | "highshelf";
+
+export class WindBiquad {
+  private b0 = 1;
+  private b1 = 0;
+  private b2 = 0;
+  private a1 = 0;
+  private a2 = 0;
+  private z1 = 0;
+  private z2 = 0;
+
+  set(
+    type: WindFilterType,
+    hz: number,
+    q: number,
+    gainDb: number,
+    sampleRate: number,
+  ): this {
+    const f = Math.min(Math.max(hz, 10), 0.45 * sampleRate);
+    const w = (2 * Math.PI * f) / sampleRate;
+    const cos = Math.cos(w);
+    const alpha = Math.sin(w) / (2 * Math.max(0.05, q));
+    const A = 10 ** (gainDb / 40);
+    let b0 = 1;
+    let b1 = 0;
+    let b2 = 0;
+    let a0 = 1;
+    let a1 = 0;
+    let a2 = 0;
+    switch (type) {
+      case "lpf":
+        b0 = (1 - cos) / 2;
+        b1 = 1 - cos;
+        b2 = b0;
+        a0 = 1 + alpha;
+        a1 = -2 * cos;
+        a2 = 1 - alpha;
+        break;
+      case "hpf":
+        b0 = (1 + cos) / 2;
+        b1 = -(1 + cos);
+        b2 = b0;
+        a0 = 1 + alpha;
+        a1 = -2 * cos;
+        a2 = 1 - alpha;
+        break;
+      case "bpf":
+        b0 = alpha;
+        b2 = -alpha;
+        a0 = 1 + alpha;
+        a1 = -2 * cos;
+        a2 = 1 - alpha;
+        break;
+      case "peak":
+        b0 = 1 + alpha * A;
+        b1 = -2 * cos;
+        b2 = 1 - alpha * A;
+        a0 = 1 + alpha / A;
+        a1 = -2 * cos;
+        a2 = 1 - alpha / A;
+        break;
+      case "highshelf": {
+        const sq = 2 * Math.sqrt(A) * alpha;
+        b0 = A * (A + 1 + (A - 1) * cos + sq);
+        b1 = -2 * A * (A - 1 + (A + 1) * cos);
+        b2 = A * (A + 1 + (A - 1) * cos - sq);
+        a0 = A + 1 - (A - 1) * cos + sq;
+        a1 = 2 * (A - 1 - (A + 1) * cos);
+        a2 = A + 1 - (A - 1) * cos - sq;
+        break;
+      }
+    }
+    this.b0 = b0 / a0;
+    this.b1 = b1 / a0;
+    this.b2 = b2 / a0;
+    this.a1 = a1 / a0;
+    this.a2 = a2 / a0;
+    return this;
+  }
+
+  process(x: number): number {
+    const y = this.b0 * x + this.z1;
+    this.z1 = this.b1 * x - this.a1 * y + this.z2;
+    this.z2 = this.b2 * x - this.a2 * y;
+    return y;
+  }
+}
+
+/**
+ * A delay line read before it is written (waveguide loops read the bore
+ * output, then push the new input): an integer ring plus a first-order
+ * Thiran allpass for the fraction in [0.5, 1.5), its phase delay exact at
+ * the loop's fundamental (`thiranFor` in src/audio/dsp/interp.ts).
+ */
+export class LoopDelay {
+  private readonly buffer: Float64Array;
+  private readonly mask: number;
+  private write = 0;
+  private whole = 1;
+  private a = 0;
+  private u1 = 0;
+  private y1 = 0;
+
+  constructor(maxDelay: number) {
+    let size = 8;
+    while (size < Math.ceil(maxDelay) + 8) size *= 2;
+    this.buffer = new Float64Array(size);
+    this.mask = size - 1;
+  }
+
+  /** Total delay in samples (at least 1.5); `w` rad/sample where it is exact. */
+  set(delay: number, w = 0): void {
+    const total = Math.min(Math.max(delay, 1.5), this.mask - 3);
+    const whole = Math.floor(total - 0.5);
+    this.whole = whole;
+    this.a = thiranFor(total - whole, w);
+  }
+
+  read(): number {
+    const u = this.buffer[(this.write - this.whole) & this.mask]!;
+    const y = this.a * u + this.u1 - this.a * this.y1;
+    this.u1 = u;
+    this.y1 = y;
+    return y;
+  }
+
+  push(value: number): void {
+    this.buffer[this.write] = value;
+    this.write = (this.write + 1) & this.mask;
+  }
+}
+
+/** Phase delay in samples of the one-pole lowpass y += (1 - p)(x - y). */
+export function onePoleDelay(p: number, w: number): number {
+  if (w < 1e-9) return p / (1 - p);
+  return Math.atan2(p * Math.sin(w), 1 - p * Math.cos(w)) / w;
+}
+
+/** Phase delay of the DC blocker y = x - x1 + R y1 at `w` (negative: it leads). */
+export function dcBlockDelay(r: number, w: number): number {
+  // H = (1 - z^-1) / (1 - R z^-1)
+  const num = Math.atan2(Math.sin(w), 1 - Math.cos(w));
+  const den = Math.atan2(r * Math.sin(w), 1 - r * Math.cos(w));
+  return -(num - den) / w;
+}

package/src/audio/winds/pitch.ts

@@ -0,0 +1,104 @@
+/**
+ * Pitch measurement for wind calibration and tests (not on the render
+ * path): Hann-windowed, zero-padded FFT, the largest bin within a window
+ * around the expected fundamental, refined by a parabola on the log
+ * magnitude (J. O. Smith, "Quadratic Interpolation of Spectral Peaks").
+ */
+import { fftInPlace } from "../dsp/fft.ts";
+
+export type PitchReading = Readonly<{
+  /** Measured fundamental, Hz. */
+  hz: number;
+  /** Fundamental level over the strongest partial, dB (<= 0). */
+  fundamentalDb: number;
+}>;
+
+/** Magnitude spectrum of x[from..from+length), zero-padded to `size`. */
+function spectrum(
+  x: Float64Array,
+  from: number,
+  length: number,
+  size: number,
+): Float64Array {
+  const re = new Float64Array(size);
+  const im = new Float64Array(size);
+  for (let i = 0; i < length; i += 1) {
+    const win = 0.5 - 0.5 * Math.cos((2 * Math.PI * i) / (length - 1));
+    re[i] = (x[from + i] ?? 0) * win;
+  }
+  fftInPlace(re, im);
+  const mag = new Float64Array(size / 2);
+  for (let k = 0; k < size / 2; k += 1)
+    mag[k] = Math.hypot(re[k]!, im[k]!) + 1e-300;
+  return mag;
+}
+
+/**
+ * The fundamental near `expected` Hz in x between `fromSec` and `toSec`,
+ * searched within +-`spanCents`.
+ */
+export function measurePitch(
+  x: Float64Array,
+  sampleRate: number,
+  expected: number,
+  fromSec = 0.2,
+  toSec = 0.9,
+  spanCents = 150,
+): PitchReading {
+  const from = Math.floor(fromSec * sampleRate);
+  const length = Math.max(
+    256,
+    Math.min(x.length - from, Math.floor((toSec - fromSec) * sampleRate)),
+  );
+  let size = 1;
+  while (size < length * 8) size *= 2;
+  const mag = spectrum(x, from, length, size);
+  const binHz = sampleRate / size;
+  const lo = Math.max(
+    1,
+    Math.floor((expected * 2 ** (-spanCents / 1200)) / binHz),
+  );
+  const hi = Math.min(
+    mag.length - 2,
+    Math.ceil((expected * 2 ** (spanCents / 1200)) / binHz),
+  );
+  let best = lo;
+  for (let k = lo; k <= hi; k += 1) if (mag[k]! > mag[best]!) best = k;
+  const a = Math.log(mag[best - 1]!);
+  const b = Math.log(mag[best]!);
+  const c = Math.log(mag[best + 1]!);
+  const denom = a - 2 * b + c;
+  const delta = denom === 0 ? 0 : (0.5 * (a - c)) / denom;
+  let peak = 0;
+  for (let k = 1; k < mag.length; k += 1) peak = Math.max(peak, mag[k]!);
+  return {
+    hz: (best + clampHalf(delta)) * binHz,
+    fundamentalDb: 20 * Math.log10(mag[best]! / peak),
+  };
+}
+
+function clampHalf(d: number): number {
+  return d < -0.5 ? -0.5 : d > 0.5 ? 0.5 : d;
+}
+
+/** Spectral centroid of x over a window, Hz. */
+export function spectralCentroid(
+  x: Float64Array,
+  sampleRate: number,
+  fromSec: number,
+  toSec: number,
+): number {
+  const from = Math.floor(fromSec * sampleRate);
+  const length = Math.floor((toSec - fromSec) * sampleRate);
+  let size = 1;
+  while (size < length) size *= 2;
+  const mag = spectrum(x, from, length, size);
+  let num = 0;
+  let den = 0;
+  for (let k = 1; k < mag.length; k += 1) {
+    const hz = (k * sampleRate) / size;
+    num += hz * mag[k]!;
+    den += mag[k]!;
+  }
+  return den > 0 ? num / den : 0;
+}

package/src/audio/winds/trim.ts

@@ -0,0 +1,80 @@
+/**
+ * Pitch and level trims for the wind voice, looked up from the generated
+ * table (`trims.ts`, written by `bun scripts/calibrate-winds.ts`). The
+ * waveguides' residual pitch error (loop-filter group delay the closed
+ * forms miss, the lip resonance pull) is deterministic, so each preset
+ * carries a correction in cents per semitone of its range at each render
+ * rate, interpolated linearly in pitch, plus an output level and a per-semitone
+ * loudness curve that put the sustain RMS at WIND_HOUSE_RMS_DB at velocity
+ * 0.8 (the engine's soft knee guards the peaks). Rates without a table use the nearest
+ * one (pitch then within a few cents).
+ */
+import type { WindPresetName } from "../../../core/winds.ts";
+import { WIND_TRIM_TABLE } from "./trims.ts";
+import type { WindTrim } from "./voice.ts";
+
+/** House sustain level of every preset at velocity 0.8, dBFS RMS. */
+export const WIND_HOUSE_RMS_DB = -14;
+
+/** Rates the calibration writes tables for. */
+export const WIND_TRIM_RATES = Object.freeze([22_050, 44_100, 48_000]);
+
+export type WindTrimRow = Readonly<{
+  /** MIDI note of `cents[0]`; one entry per semitone. */
+  lo: number;
+  /** Correction in hundredths of a cent. */
+  cents: readonly number[];
+  level: number;
+  /**
+   * Loudness curve in hundredths of a dB per semitone on the `cents` grid
+   * (absent: flat), so the sustain RMS stays on the house level across the
+   * range.
+   */
+  gains?: readonly number[];
+}>;
+
+function nearestRate(sampleRate: number): number {
+  let best = WIND_TRIM_RATES[0]!;
+  for (const rate of WIND_TRIM_RATES)
+    if (Math.abs(rate - sampleRate) < Math.abs(best - sampleRate)) best = rate;
+  return best;
+}
+
+/** The trim row of `preset` at `sampleRate`, undefined before calibration. */
+export function windTrimRow(
+  preset: WindPresetName,
+  sampleRate: number,
+): WindTrimRow | undefined {
+  return WIND_TRIM_TABLE[nearestRate(sampleRate)]?.[preset];
+}
+
+function interpolate(lo: number, grid: readonly number[], hz: number): number {
+  const midi = 69 + 12 * Math.log2(hz / 440) - lo;
+  const last = grid.length - 1;
+  if (last < 0) return 0;
+  if (midi <= 0) return grid[0]! / 100;
+  if (midi >= last) return grid[last]! / 100;
+  const i = Math.floor(midi);
+  const u = midi - i;
+  return ((1 - u) * grid[i]! + u * grid[i + 1]!) / 100;
+}
+
+/** Interpolated correction of a row at `hz`, in cents. */
+export function rowCents(row: WindTrimRow, hz: number): number {
+  return interpolate(row.lo, row.cents, hz);
+}
+
+/** Interpolated loudness gain of a row at `hz`, as a factor. */
+export function rowGain(row: WindTrimRow, hz: number): number {
+  return row.gains ? 10 ** (interpolate(row.lo, row.gains, hz) / 20) : 1;
+}
+
+export function windTrim(preset: WindPresetName, sampleRate: number): WindTrim {
+  const row = windTrimRow(preset, sampleRate);
+  if (!row) return { cents: () => 0, level: 1 };
+  return {
+    cents: (hz) => rowCents(row, hz),
+    level: row.level,
+    gain: (hz) => rowGain(row, hz),
+  };
+}