@hraness/dawg 0.5.0 → 0.6.0

package/src/audio/strings/body.ts

@@ -0,0 +1,250 @@
+/**
+ * Per-track string bodies and sympathetic strings (0.6 strings prototype,
+ * proto/strings/strings.ts). A body is a direct path plus a bank of 0 dB
+ * band-pass modes, run once per track over the summed strings; `size`
+ * scales the body (mode frequencies x 1/size). Sympathetic strings are
+ * one-way coupled loops tuned to the song key, open strings or a drone.
+ */
+import { thiranFor } from "../dsp/interp.ts";
+import { C4 } from "./pluck.ts";
+import { designLoss, onePoleDelay } from "./loop.ts";
+
+/** [frequency Hz, Q, gain] */
+export type BodyMode = readonly [number, number, number];
+export type Body = Readonly<{ direct: number; modes: readonly BodyMode[] }>;
+
+export const BODIES: Readonly<Record<string, Body>> = Object.freeze({
+  none: { direct: 1, modes: [] },
+  guitar: {
+    direct: 0.55,
+    modes: [
+      [98, 10, 1.2],
+      [204, 14, 0.9],
+      [390, 18, 0.5],
+      [560, 20, 0.35],
+      [960, 12, 0.3],
+      [2300, 5, 0.35],
+    ],
+  },
+  steel: {
+    direct: 0.6,
+    modes: [
+      [110, 10, 1.0],
+      [220, 14, 0.9],
+      [420, 16, 0.6],
+      [700, 14, 0.4],
+      [1600, 6, 0.4],
+      [3200, 4, 0.3],
+    ],
+  },
+  small: {
+    direct: 0.6,
+    modes: [
+      [140, 10, 1.0],
+      [270, 14, 0.8],
+      [520, 16, 0.5],
+      [900, 12, 0.4],
+      [2200, 5, 0.35],
+      [3600, 4, 0.3],
+    ],
+  },
+  bowl: {
+    direct: 0.55,
+    modes: [
+      [120, 10, 1.0],
+      [250, 12, 0.8],
+      [480, 14, 0.5],
+      [900, 10, 0.35],
+      [1800, 6, 0.3],
+    ],
+  },
+  gourd: {
+    direct: 0.5,
+    modes: [
+      [180, 8, 0.9],
+      [360, 10, 0.5],
+      [720, 8, 0.4],
+      [1500, 5, 0.35],
+      [3000, 4, 0.3],
+    ],
+  },
+  skin: {
+    direct: 0.45,
+    modes: [
+      [300, 6, 1.2],
+      [650, 6, 0.8],
+      [1300, 5, 0.6],
+      [2600, 4, 0.5],
+    ],
+  },
+  board: {
+    direct: 0.6,
+    modes: [
+      [95, 6, 0.8],
+      [180, 8, 0.7],
+      [350, 8, 0.6],
+      [700, 8, 0.45],
+      [1400, 6, 0.35],
+      [2800, 5, 0.25],
+    ],
+  },
+  violin: {
+    direct: 0.3,
+    modes: [
+      [275, 14, 1.0],
+      [460, 18, 0.9],
+      [540, 18, 1.1],
+      [700, 12, 0.5],
+      [1100, 8, 0.4],
+      [2500, 3, 0.9],
+      [3400, 4, 0.4],
+    ],
+  },
+});
+
+/**
+ * The body for a name and size: modes x 1/size. `bass` is the violin body
+ * at 0.3 (a double bass is about 3.3 times the size).
+ */
+export function bodyFor(name: string, size: number): Body {
+  const base =
+    name === "bass" ? BODIES.violin! : (BODIES[name] ?? BODIES.none!);
+  const k = (name === "bass" ? 0.3 : 1) / Math.max(0.05, size);
+  if (k === 1) return base;
+  return {
+    direct: base.direct,
+    modes: base.modes.map(([f, q, g]) => [f * k, q, g] as const),
+  };
+}
+
+/** Body over `x` in place: direct + modes, then a 10 Hz DC blocker. */
+export function applyBody(x: Float64Array, body: Body, sr: number): void {
+  if (body.modes.length === 0 && body.direct === 1) return;
+  const input = Float64Array.from(x);
+  for (let i = 0; i < x.length; i += 1) x[i] = body.direct * input[i]!;
+  for (const [f, q, g] of body.modes) {
+    if (f >= 0.45 * sr) continue;
+    const w = (2 * Math.PI * f) / sr;
+    const alpha = Math.sin(w) / (2 * q);
+    const a0 = 1 + alpha;
+    const b0 = alpha / a0;
+    const b2 = -alpha / a0;
+    const a1 = (-2 * Math.cos(w)) / a0;
+    const a2 = (1 - alpha) / a0;
+    let z1 = 0;
+    let z2 = 0;
+    for (let i = 0; i < x.length; i += 1) {
+      const xi = input[i]!;
+      const y = b0 * xi + z1;
+      z1 = -a1 * y + z2;
+      z2 = b2 * xi - a2 * y;
+      x[i] = x[i]! + g * y;
+    }
+  }
+  const R = Math.exp((-2 * Math.PI * 10) / sr);
+  let x1 = 0;
+  let y1 = 0;
+  for (let i = 0; i < x.length; i += 1) {
+    const xi = x[i]!;
+    const y = xi - x1 + R * y1;
+    x1 = xi;
+    y1 = y;
+    x[i] = y;
+  }
+}
+
+export type SymTune = "scale" | "open" | "drone";
+
+/** A sympathetic string: a MIDI key plus cents (quarter tones). */
+export interface SymKey {
+  key: number;
+  cents: number;
+}
+
+/**
+ * Sympathetic string keys per tuning mode. `steps` is the song key's scale
+ * in semitones above the tonic (fractional for quarter tones). `scale`
+ * tunes up to 13 strings to it; `drone` is Sa-Pa-Sa, or Sa-Ma-Sa (else
+ * Sa-Ni-Sa) when the scale has no Pa; `open` is guitar EADGBE.
+ */
+export function symKeys(
+  mode: string,
+  root: number,
+  steps: readonly number[],
+): SymKey[] {
+  const at = (step: number): SymKey => {
+    const whole = Math.round(step);
+    return { key: root + whole, cents: Math.round((step - whole) * 1000) / 10 };
+  };
+  if (mode === "open")
+    return [40, 45, 50, 55, 59, 64].map((key) => ({ key, cents: 0 }));
+  if (mode === "drone") {
+    const has = (n: number) => steps.some((s) => Math.abs(s - n) < 0.01);
+    const second = has(7)
+      ? at(-5)
+      : has(5)
+        ? at(-7)
+        : has(6)
+          ? at(-6)
+          : has(11)
+            ? at(-1)
+            : at(-5);
+    return [at(-12), second, at(0)];
+  }
+  const sorted = [...steps]
+    .map((s) => ((s % 12) + 12) % 12)
+    .sort((a, b) => a - b);
+  const keys: SymKey[] = [];
+  for (let octave = 0; octave <= 12 && keys.length < 13; octave += 12)
+    for (const step of sorted)
+      if (step + octave <= 19 && keys.length < 13) keys.push(at(step + octave));
+  return keys;
+}
+
+/**
+ * Sympathetic strings: one-way coupled loops excited by `x`; returns only
+ * what they add (the coupled input is subtracted back out).
+ */
+export function sympathetic(
+  x: Float64Array,
+  hzs: readonly number[],
+  couple: number,
+  decay: number,
+  damp: number,
+  sr: number,
+): Float64Array {
+  const out = new Float64Array(x.length);
+  for (const hz of hzs) {
+    if (!(hz > 20) || hz > 0.4 * sr) continue;
+    const t0 = decay * (hz / C4) ** -0.3;
+    const { g, p } = designLoss(
+      hz,
+      t0,
+      Math.max(3000, 3 * hz),
+      t0 / (1 + 99 * damp * damp),
+      sr,
+    );
+    const w0 = (2 * Math.PI * hz) / sr;
+    const rest = sr / hz - onePoleDelay(p, w0);
+    const N = Math.max(1, Math.floor(rest - 0.5));
+    const a = thiranFor(rest - N, w0);
+    let size = 16;
+    while (size < N + 4) size <<= 1;
+    const buf = new Float64Array(size);
+    const m = size - 1;
+    let tx = 0;
+    let ty = 0;
+    let ly = 0;
+    const lgain = g * (1 - p);
+    for (let i = 0; i < x.length; i += 1) {
+      const d = buf[(i - N) & m]!;
+      const t = a * d + tx - a * ty;
+      tx = d;
+      ty = t;
+      ly = lgain * t + p * ly;
+      buf[i & m] = couple * x[i]! + ly;
+      out[i] = out[i]! + ly;
+    }
+  }
+  return out;
+}

package/src/audio/strings/engine.ts

@@ -0,0 +1,369 @@
+/**
+ * The string engine (0.6 lane A): renders a track whose instrument is
+ * `"string"` and which carries `Track.string`. Each performed note plays
+ * one string per unison player (plus an octave course), streamed in blocks
+ * with same-pitch restrike and a chord-group voice cap; the summed strings
+ * then pass the track's body and sympathetic strings, the preset trim and
+ * the track volume, before the track's effects (wav.ts).
+ */
+import { parseKey, scaleSteps } from "../../../core/chords.ts";
+import type { PerformedNote } from "../../../core/expression.ts";
+import type { FxLane } from "../../../core/fx.ts";
+import type { Track } from "../../../core/score.ts";
+import {
+  resolveString,
+  stringPresetTableText,
+  type StringValues,
+} from "../../../core/strings.ts";
+import { noteHz } from "../../../core/tuning.ts";
+import { interpolateAutomation } from "../effects/common.ts";
+import { seedHash, unit } from "../dsp/rng.ts";
+import type { EngineContext, InstrumentEngine } from "../instruments.ts";
+import { applyBody, bodyFor, symKeys, sympathetic } from "./body.ts";
+import { clamp } from "./loop.ts";
+import { PluckString, type Exciter, type PluckSpec } from "./pluck.ts";
+
+const BLOCK = 128;
+/** Longest a single string may ring (seconds). */
+const MAX_RING = 12;
+/** Sympathetic strings' own T60 at C4 (prototype). */
+const SYM_DECAY = 4;
+
+/** Value of `name` at `tick`: the `string-<name>` lane over the stored value. */
+function valueAt(
+  track: Track,
+  values: StringValues,
+  name: string,
+  tick: number,
+): number {
+  const base = values[name] as number;
+  const points = track.fxAutomation?.[`string-${name}` as FxLane];
+  return points && points.length > 0
+    ? interpolateAutomation(points, tick, base)
+    : base;
+}
+
+/** The plucked-string spec for one note (articulations map to timbre). */
+export function noteSpec(
+  values: StringValues,
+  note: PerformedNote,
+  track: Track,
+): { spec: PluckSpec; velocity: number } {
+  const at = (name: string) => valueAt(track, values, name, note.startTick);
+  let mute = clamp(at("mute"), 0, 1);
+  let bright = clamp(values.bright as number, 0, 1);
+  let velocity = clamp(note.velocity, 0, 1);
+  const articulation = note.articulation;
+  if (articulation === "staccato") mute = Math.max(mute, 0.7);
+  if (articulation === "ghost") {
+    mute = 1;
+    bright *= 0.5;
+  }
+  if (articulation === "accent" || articulation === "marcato")
+    velocity = Math.min(1, velocity + 0.15);
+  // Velocity sensitivity: 0 plays every note at full velocity.
+  const sens = clamp(values.vel as number, 0, 1);
+  velocity = 1 - sens * (1 - velocity);
+  const damp = clamp(values.damp as number, 0, 1);
+  return {
+    spec: {
+      // Palm mute: up to 12x shorter ring and a darker loop.
+      decay: Math.max(0.02, at("ring") * (1 - 0.92 * mute)),
+      track: values.track as number,
+      damp: damp + (1 - damp) * 0.6 * mute,
+      stiff: values.stiff as number,
+      pos: clamp(values.pos as number, 0.01, 0.5),
+      exciter: values.exciter as Exciter,
+      bright,
+      noise: values.noise as number,
+      release: values.release as number,
+      jawari: clamp(at("buzz"), 0, 1),
+      pickup: values.pickup as number,
+    },
+    velocity,
+  };
+}
+
+type Voice = {
+  string: PluckString;
+  start: number;
+  pitch: number;
+  group: number;
+  gainL: number;
+  gainR: number;
+  damp?: Readonly<{ from: number; tau: number }>;
+};
+
+/** Ring-out after the last note-off, in seconds. */
+export function stringTailSeconds(track: Track): number {
+  const values = resolveString(track.string);
+  const release = values.release as number;
+  const sym = (values.sym as number) > 0 ? SYM_DECAY : 0;
+  return Math.min(MAX_RING, Math.max(release, sym) + 0.05);
+}
+
+function startSample(note: PerformedNote, context: EngineContext): number {
+  if (context.warp)
+    return Math.max(0, Math.floor(context.warp.sample(note.startTick)));
+  return Math.max(0, Math.floor(note.startTick * context.samplesPerTick));
+}
+
+function holdSamples(
+  note: PerformedNote,
+  start: number,
+  context: EngineContext,
+): number {
+  if (context.warp)
+    return Math.max(
+      1,
+      Math.floor(
+        context.warp.sample(note.startTick + note.durationTicks) - start,
+      ),
+    );
+  return Math.max(1, Math.floor(note.durationTicks * context.samplesPerTick));
+}
+
+/** Combined pitch curve: the note's own, then the preset vibrato. */
+function centsCurve(
+  note: PerformedNote,
+  values: StringValues,
+  track: Track,
+): ((t: number) => number) | undefined {
+  const own = note.performance?.cents;
+  const rate = valueAt(track, values, "vib", note.startTick);
+  const depth = valueAt(track, values, "vibmod", note.startTick) * 100;
+  const delay = values.vibdelay as number;
+  const vibrato =
+    rate > 0 && depth > 0 && !note.performance?.replaceVibrato
+      ? (t: number) => {
+          if (t <= delay) return 0;
+          const fade = Math.min(1, (t - delay) / 0.15);
+          return depth * fade * Math.sin(2 * Math.PI * rate * (t - delay));
+        }
+      : undefined;
+  if (own && vibrato) return (t) => own(t) + vibrato(t);
+  return own ?? vibrato;
+}
+
+/** Renders a string track's notes into `dry` (and `dryR` when stereo). */
+export function renderStrings(
+  dry: Float64Array,
+  dryR: Float64Array | undefined,
+  notes: readonly PerformedNote[],
+  track: Track,
+  context: EngineContext,
+): void {
+  const sr = context.sampleRate;
+  const total = Math.min(dry.length, context.samples);
+  const values = resolveString(track.string);
+  const unison = Math.max(1, Math.round(values.unison as number));
+  const detune = values.detune as number;
+  const spread = dryR ? clamp(values.spread as number, 0, 1) : 0;
+  const oct = values.oct as number;
+  const octbelow = values.octbelow as number;
+  const cap = Math.max(1, Math.round(values.voices as number));
+  const tuning = context.tuning;
+  const L = new Float64Array(total);
+  const R = dryR ? new Float64Array(total) : undefined;
+  const voices: Voice[] = [];
+  const pending = notes
+    .map((note) => ({ note, start: startSample(note, context) }))
+    .filter((item) => item.start < total)
+    .sort(
+      (a, b) =>
+        a.start - b.start ||
+        a.note.pitch - b.note.pitch ||
+        (a.note.id < b.note.id ? -1 : a.note.id > b.note.id ? 1 : 0),
+    );
+  let next = 0;
+  for (let at = 0; at < total; at += BLOCK) {
+    const count = Math.min(BLOCK, total - at);
+    while (next < pending.length && pending[next]!.start < at + count) {
+      const { note, start } = pending[next]!;
+      next += 1;
+      const baseHz = noteHz(note.pitch, note.cents, tuning);
+      if (!(baseHz > 0) || baseHz >= 0.45 * sr) continue;
+      // Restrike: the same key damps its previous string.
+      for (const v of voices)
+        if (v.pitch === note.pitch) v.string.releaseAt(start - v.start);
+      // Voice cap: count only chords not yet released, so a releasing
+      // chord never shields the newer ringing ones from the cap.
+      const held = voices.filter(
+        (v) => !v.string.done && v.string.offAt > start - v.start,
+      );
+      const groups = new Set(held.map((v) => v.group));
+      if (groups.size >= cap) {
+        const oldest = Math.min(...groups);
+        for (const v of held)
+          if (v.group === oldest) v.string.releaseAt(start - v.start);
+      }
+      const { spec, velocity } = noteSpec(values, note, track);
+      const seed = seedHash(
+        `${note.id}:${note.startTick + (context.seedTick ?? 0)}:string`,
+      );
+      const strings: { hz: number; gain: number }[] = [];
+      // The course's tuning error belongs to the key, not to the strike: it
+      // is seeded by track and key (so every velocity of a key beats the
+      // same way) and centred, so the course's mean pitch is the table's.
+      const course = seedHash(`${track.id}:${note.pitch}:course`);
+      const jitters = Array.from({ length: unison }, (_, i) =>
+        unison > 1 ? (unit(course, i, 1) - 0.5) * 2 : 0,
+      );
+      const meanJitter = jitters.reduce((a, b) => a + b, 0) / unison;
+      for (let i = 0; i < unison; i += 1) {
+        const d = unison > 1 ? (i / (unison - 1) - 0.5) * detune : 0;
+        const jitter = jitters[i]! - meanJitter;
+        strings.push({
+          hz: baseHz * 2 ** ((d * 100 + jitter) / 1200),
+          gain: 1 / Math.sqrt(unison),
+        });
+      }
+      if (oct > 0 && note.pitch < octbelow) {
+        const up = noteHz(Math.min(127, note.pitch + 12), note.cents, tuning);
+        const hz = up > 0 ? up : baseHz * 2;
+        if (hz < 0.45 * sr)
+          strings.push({
+            hz: hz * 2 ** (((unit(course, unison, 1) - 0.5) * 4) / 1200),
+            gain: oct / Math.sqrt(unison),
+          });
+      }
+      const hold = holdSamples(note, start, context) / sr;
+      const cents = centsCurve(note, values, track);
+      strings.forEach((s, i) => {
+        const pan =
+          strings.length > 1 ? (i / (strings.length - 1) - 0.5) * spread : 0;
+        const string = new PluckString(
+          spec,
+          {
+            hz: s.hz,
+            velocity,
+            hold: Math.max(0.01, hold),
+            seed: seedHash(`${seed}:${i}`),
+            ...(cents ? { cents } : {}),
+          },
+          sr,
+          MAX_RING,
+        );
+        const gl = R ? s.gain * Math.sqrt(0.5 - pan / 2) * Math.SQRT2 : s.gain;
+        const gr = s.gain * Math.sqrt(0.5 + pan / 2) * Math.SQRT2;
+        voices.push({
+          string,
+          start,
+          pitch: note.pitch,
+          group: start,
+          gainL: gl,
+          gainR: gr,
+          ...(note.performance?.damp ? { damp: note.performance.damp } : {}),
+        });
+      });
+    }
+    for (const v of voices) {
+      if (v.string.done) continue;
+      const from = Math.max(at, v.start);
+      const n = at + count - from;
+      if (n <= 0) continue;
+      let scale = 1;
+      if (v.damp) {
+        const t = (from - v.start) / sr;
+        if (t > v.damp.from) scale = Math.exp(-(t - v.damp.from) / v.damp.tau);
+      }
+      v.string.process(L, from, n, v.gainL * scale, R, v.gainR * scale);
+    }
+    for (let i = voices.length - 1; i >= 0; i -= 1)
+      if (voices[i]!.string.done) voices.splice(i, 1);
+  }
+  finishTrack(L, R, values, track, context);
+  for (let i = 0; i < total; i += 1) {
+    dry[i] = dry[i]! + L[i]!;
+    if (dryR && R) dryR[i] = dryR[i]! + R[i]!;
+  }
+}
+
+/** Body, sympathetic strings, preset trim and track volume. */
+function finishTrack(
+  L: Float64Array,
+  R: Float64Array | undefined,
+  values: StringValues,
+  track: Track,
+  context: EngineContext,
+): void {
+  const sr = context.sampleRate;
+  const sym = values.sym as number;
+  let wet: Float64Array | undefined;
+  if (sym > 0) {
+    const mono = R ? new Float64Array(L.length) : L;
+    if (R)
+      for (let i = 0; i < L.length; i += 1) mono[i] = 0.5 * (L[i]! + R[i]!);
+    // The key's own scale (a raga's or maqam's, quarter tones included),
+    // not the chord mode it harmonizes with.
+    const key = parseKey(context.score.key);
+    const root = 48 + (key?.tonic ?? 0);
+    const steps = key ? scaleSteps(key) : [0, 2, 4, 5, 7, 9, 11];
+    const hzs = symKeys(values.symtune as string, root, steps).map((k) =>
+      noteHz(k.key, k.cents || undefined, context.tuning),
+    );
+    wet = sympathetic(mono, hzs, 0.02 * sym, SYM_DECAY, 0.3, sr);
+  }
+  const body = bodyFor(values.body as string, values.size as number);
+  applyBody(L, body, sr);
+  if (R) applyBody(R, body, sr);
+  if (wet)
+    for (let i = 0; i < L.length; i += 1) {
+      L[i] = L[i]! + wet[i]!;
+      if (R) R[i] = R[i]! + wet[i]!;
+    }
+  // Preset trim (and its lane) and the track volume, every 32 samples.
+  const volume = Math.max(0, Math.min(1, track.volume ?? 1));
+  const volumeLane = track.volumeAutomation ?? [];
+  const gainLane = track.fxAutomation?.["string-gain" as FxLane];
+  const warp = context.warp;
+  for (let at = 0; at < L.length; at += 32) {
+    const tick = warp ? warp.tick(at) : at / context.samplesPerTick;
+    const trim =
+      gainLane && gainLane.length > 0
+        ? interpolateAutomation(gainLane, tick, values.gain as number)
+        : (values.gain as number);
+    const g =
+      Math.max(0, trim) *
+      volume *
+      (volumeLane.length > 0 ? interpolateAutomation(volumeLane, tick, 1) : 1);
+    const end = Math.min(L.length, at + 32);
+    for (let i = at; i < end; i += 1) {
+      L[i] = L[i]! * g;
+      if (R) R[i] = R[i]! * g;
+    }
+  }
+}
+
+/** True when the track's strings are panned apart (spread with 2+ strings). */
+export function stringStereo(track: Track): boolean {
+  const values = resolveString(track.string);
+  const strings =
+    Math.max(1, Math.round(values.unison as number)) +
+    ((values.oct as number) > 0 ? 1 : 0);
+  return (values.spread as number) > 0 && strings > 1;
+}
+
+/** Digest of the preset table text (FNV-1a, hex), computed once. */
+const STRING_PRESET_DIGEST = `strings:${fnv1a(stringPresetTableText())}`;
+
+function fnv1a(text: string): string {
+  let h = 0x811c9dc5;
+  for (let i = 0; i < text.length; i += 1) {
+    h ^= text.charCodeAt(i);
+    h = Math.imul(h, 0x01000193) >>> 0;
+  }
+  return h.toString(16).padStart(8, "0");
+}
+
+export const STRING_ENGINE: InstrumentEngine = Object.freeze({
+  id: "string",
+  field: "string" as keyof Track,
+  render: (dry, dryR, notes, track, context) =>
+    renderStrings(dry, dryR, notes, track, context),
+  tailSeconds: stringTailSeconds,
+  stereo: stringStereo,
+  // The preset table joins the stem and live keys: a code-side preset
+  // retune never serves a stem rendered from the old table.
+  assetDigests: () => [STRING_PRESET_DIGEST],
+});