@hraness/dawg 0.5.0 → 0.6.0

package/src/audio/strings/loop.ts

@@ -0,0 +1,119 @@
+/**
+ * Loop filters for the string waveguides (ported from the 0.6 strings
+ * prototype, proto/strings/dsp.ts): the two-decay loss filter and the
+ * dispersion allpass fit. Pure functions; the delay interpolation comes from
+ * the shared contract (src/audio/dsp/interp.ts).
+ */
+import { allpassDelay } from "../dsp/interp.ts";
+
+export const clamp = (x: number, lo: number, hi: number): number =>
+  x < lo ? lo : x > hi ? hi : x;
+
+/** Phase delay (samples) of the one-pole low-pass 1/(1 - p z^-1) at w. */
+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;
+}
+
+/**
+ * Loop-loss filter g(1-p)/(1 - p z^-1) from two decay times (Valimaki et
+ * al. 1996): the per-period gain at f0 gives T60 `t0`, at `fh` gives `th`.
+ * The pole is capped at 0.95 and the gain at 0.99995, so the loop's DC gain
+ * (g) stays below 1 and no setting can grow.
+ */
+export function designLoss(
+  f0: number,
+  t0: number,
+  fh: number,
+  th: number,
+  sr: number,
+): { g: number; p: number } {
+  const w0 = (2 * Math.PI * f0) / sr;
+  const wh = (2 * Math.PI * Math.min(fh, 0.45 * sr)) / sr;
+  const g0 = 0.001 ** (1 / (t0 * f0));
+  const gh = 0.001 ** (1 / (th * f0));
+  const want = gh / g0;
+  const ratio = (p: number) =>
+    Math.sqrt(
+      (1 - 2 * p * Math.cos(w0) + p * p) / (1 - 2 * p * Math.cos(wh) + p * p),
+    );
+  let lo = 0;
+  let hi = 0.95;
+  if (wh <= w0 || want >= 1) hi = 0;
+  for (let i = 0; i < 50 && hi > 0; i += 1) {
+    const mid = (lo + hi) / 2;
+    if (ratio(mid) > want) lo = mid;
+    else hi = mid;
+  }
+  // DC gain g must stay below 1, so cap the pole where the f0 gain would
+  // need g > 0.99995: high keys keep their designed fundamental T60 and
+  // give up some of the requested treble damping (design review: high
+  // nylon and harp notes decayed several times too fast).
+  const gFor = (q: number) =>
+    (g0 * Math.sqrt(1 - 2 * q * Math.cos(w0) + q * q)) / (1 - q);
+  let p = (lo + hi) / 2;
+  if (gFor(p) > 0.99995) {
+    let a = 0;
+    let b = p;
+    for (let i = 0; i < 50; i += 1) {
+      const mid = (a + b) / 2;
+      if (gFor(mid) > 0.99995) b = mid;
+      else a = mid;
+    }
+    p = a;
+  }
+  const g = Math.min(0.99995, gFor(p));
+  return { g, p };
+}
+
+/** Inharmonicity B for the `stiff` knob: 1e-6 x 400^stiff, 0 at 0. */
+export function stiffnessB(stiff: number): number {
+  return stiff > 0 ? 1e-6 * 400 ** stiff : 0;
+}
+
+/**
+ * Dispersion allpass cascade (Van Duyne and Smith 1994): one shared
+ * coefficient fitted by golden-section search so partial k lands at
+ * k f1 sqrt((1 + B k^2) / (1 + B)).
+ */
+export function designDispersion(
+  f1: number,
+  B: number,
+  sections: number,
+  sr: number,
+  maxDelay: number,
+): number {
+  if (!(B > 0) || sections === 0) return 0;
+  const w1 = (2 * Math.PI * f1) / sr;
+  const ks: number[] = [];
+  for (let k = 2; k <= 16; k += 1) {
+    const fk = k * f1 * Math.sqrt((1 + B * k * k) / (1 + B));
+    if (fk > 0.42 * sr) break;
+    ks.push(k);
+  }
+  if (ks.length === 0) return 0;
+  const cost = (a: number): number => {
+    if (sections * allpassDelay(a, w1) > maxDelay) return 1e9;
+    let e = 0;
+    for (const k of ks) {
+      const fk = k * f1 * Math.sqrt((1 + B * k * k) / (1 + B));
+      const wk = (2 * Math.PI * fk) / sr;
+      const target = (2 * Math.PI * k) / wk - (2 * Math.PI) / w1;
+      const got = sections * (allpassDelay(a, wk) - allpassDelay(a, w1));
+      e += (got - target) ** 2;
+    }
+    return e;
+  };
+  let lo = -0.95;
+  let hi = 0;
+  const gr = (Math.sqrt(5) - 1) / 2;
+  let c = hi - gr * (hi - lo);
+  let d = lo + gr * (hi - lo);
+  for (let i = 0; i < 60; i += 1) {
+    if (cost(c) < cost(d)) hi = d;
+    else lo = c;
+    c = hi - gr * (hi - lo);
+    d = lo + gr * (hi - lo);
+  }
+  return (lo + hi) / 2;
+}

package/src/audio/strings/measure.test-helpers.ts

@@ -0,0 +1,198 @@
+/**
+ * Measurement helpers for the string engine's tests (ported from the 0.6
+ * design prototype): FFT pitch with parabolic interpolation, a partial's
+ * T60 by regression and the spectral centroid.
+ */
+import { createScore, type Track } from "../../../core/score.ts";
+import type { PerformedNote } from "../../../core/expression.ts";
+import type { TuningTable } from "../../../core/tuning.ts";
+import { fft } from "../wavetable.ts";
+import type { EngineContext } from "../instruments.ts";
+import { renderStrings } from "./engine.ts";
+
+/** 12-TET Hz of a MIDI key. */
+export const tetHz = (pitch: number): number => 440 * 2 ** ((pitch - 69) / 12);
+
+export const SR = 22050;
+const TPB = 480;
+const BPM = 120;
+const SPT = (SR * 60) / (BPM * TPB);
+
+export type TestNote = {
+  pitch: number;
+  start?: number;
+  seconds?: number;
+  velocity?: number;
+  performance?: PerformedNote["performance"];
+};
+
+/** Renders notes on a string track (mono, before effects). */
+export function render(
+  string: Record<string, number | string>,
+  notes: readonly TestNote[],
+  seconds: number,
+  tuning?: TuningTable,
+): Float64Array {
+  const track = {
+    id: "s",
+    name: "s",
+    instrument: "string",
+    volume: 1,
+    string,
+  } as unknown as Track;
+  const samples = Math.round(seconds * SR);
+  const context: EngineContext = {
+    score: createScore({ bars: 1, tracks: [] }),
+    sampleRate: SR,
+    samples,
+    samplesPerTick: SPT,
+    tempoBpm: BPM,
+    ticksPerBeat: TPB,
+    ...(tuning ? { tuning } : {}),
+  };
+  const performed = notes.map((n, i) => ({
+    id: `n${i}`,
+    trackId: "s",
+    pitch: n.pitch,
+    velocity: n.velocity ?? 0.8,
+    startTick: Math.round(((n.start ?? 0) * SR) / SPT),
+    durationTicks: Math.round(((n.seconds ?? seconds) * SR) / SPT),
+    ...(n.performance ? { performance: n.performance } : {}),
+  })) as unknown as PerformedNote[];
+  const dry = new Float64Array(samples);
+  renderStrings(dry, undefined, performed, track, context);
+  return dry;
+}
+
+function spectrum(x: Float64Array, start: number, len: number, pad: number) {
+  let n = 1;
+  while (n < len * pad) n *= 2;
+  const re = new Float64Array(n);
+  const im = new Float64Array(n);
+  for (let i = 0; i < len && start + i < x.length; i += 1)
+    re[i] =
+      x[start + i]! * (0.5 - 0.5 * Math.cos((2 * Math.PI * i) / (len - 1)));
+  fft(re, im);
+  const mag = new Float64Array(n / 2);
+  for (let i = 0; i < n / 2; i += 1) mag[i] = Math.hypot(re[i]!, im[i]!);
+  return mag;
+}
+
+function peakNear(mag: Float64Array, binHz: number, hz: number, cents = 60) {
+  const lo = Math.max(1, Math.floor((hz * 2 ** (-cents / 1200)) / binHz));
+  const hi = Math.min(
+    mag.length - 2,
+    Math.ceil((hz * 2 ** (cents / 1200)) / binHz),
+  );
+  let best = lo;
+  for (let i = lo; i <= hi; i += 1) if (mag[i]! > mag[best]!) best = i;
+  const a = Math.log(mag[best - 1]! + 1e-30);
+  const b = Math.log(mag[best]! + 1e-30);
+  const c = Math.log(mag[best + 1]! + 1e-30);
+  const off = (a - c) / (2 * (a - 2 * b + c));
+  return (best + (Number.isFinite(off) ? off : 0)) * binHz;
+}
+
+export const centsOff = (hz: number, ref: number): number =>
+  1200 * Math.log2(hz / ref);
+
+/**
+ * Measured frequency (Hz) of the partial near hz: Hann window over
+ * [t0, t0 + 1 s) as in the design spec, zero-padded at least 8x.
+ */
+export function measurePitch(
+  x: Float64Array,
+  hz: number,
+  t0 = 0.3,
+  cents = 60,
+): number {
+  const start = Math.round(t0 * SR);
+  const len = Math.min(x.length - start, SR);
+  const mag = spectrum(x, start, len, 8);
+  let n = 1;
+  while (n < len * 8) n *= 2;
+  return peakNear(mag, SR / n, hz, cents);
+}
+
+function partialEnvelope(
+  x: Float64Array,
+  hz: number,
+  frame: number,
+  hop: number,
+) {
+  const frames = Math.max(0, Math.floor((x.length - frame) / hop));
+  const out = new Float64Array(frames);
+  const w = (2 * Math.PI * hz) / SR;
+  const cos = new Float64Array(frame);
+  const sin = new Float64Array(frame);
+  for (let i = 0; i < frame; i += 1) {
+    const win = 0.5 - 0.5 * Math.cos((2 * Math.PI * i) / (frame - 1));
+    cos[i] = win * Math.cos(w * i);
+    sin[i] = win * Math.sin(w * i);
+  }
+  for (let f = 0; f < frames; f += 1) {
+    let re = 0;
+    let im = 0;
+    for (let i = 0; i < frame; i += 1) {
+      const v = x[f * hop + i]!;
+      re += v * cos[i]!;
+      im -= v * sin[i]!;
+    }
+    out[f] = Math.hypot(re, im);
+  }
+  return out;
+}
+
+/** T60 of a partial: regression of dB from -5 to -40 below its peak. */
+export function partialT60(x: Float64Array, hz: number): number {
+  const frame = Math.max(
+    256,
+    Math.min(4096, 2 ** Math.ceil(Math.log2((SR / hz) * 6))),
+  );
+  const hop = frame >> 1;
+  const env = partialEnvelope(x, hz, frame, hop);
+  let peak = 0;
+  let pi = 0;
+  for (let i = 0; i < env.length; i += 1)
+    if (env[i]! > peak) {
+      peak = env[i]!;
+      pi = i;
+    }
+  const xs: number[] = [];
+  const ys: number[] = [];
+  for (let i = pi; i < env.length; i += 1) {
+    const db = 20 * Math.log10(env[i]! / peak + 1e-30);
+    if (db > -5) continue;
+    if (db < -40) break;
+    xs.push((i * hop) / SR);
+    ys.push(db);
+  }
+  if (xs.length < 3) return NaN;
+  const mx = xs.reduce((s, v) => s + v, 0) / xs.length;
+  const my = ys.reduce((s, v) => s + v, 0) / ys.length;
+  let sxy = 0;
+  let sxx = 0;
+  for (let i = 0; i < xs.length; i += 1) {
+    sxy += (xs[i]! - mx) * (ys[i]! - my);
+    sxx += (xs[i]! - mx) ** 2;
+  }
+  return -60 / (sxy / sxx);
+}
+
+/** Magnitude-weighted spectral centroid (Hz) of x[start, start+len). */
+export function centroid(x: Float64Array, start: number, len: number): number {
+  const mag = spectrum(x, start, len, 1);
+  let num = 0;
+  let den = 0;
+  for (let i = 1; i < mag.length; i += 1) {
+    num += ((i * SR) / len) * mag[i]!;
+    den += mag[i]!;
+  }
+  return num / den;
+}
+
+export function peakOf(x: Float64Array): number {
+  let p = 0;
+  for (const v of x) p = Math.max(p, Math.abs(v));
+  return p;
+}

package/src/audio/strings/pluck.ts

@@ -0,0 +1,354 @@
+/**
+ * A plucked or struck string: a single-delay-loop waveguide (Karplus-Strong
+ * as extended by Jaffe and Smith 1983), ported from the 0.6 strings
+ * prototype. The loop holds an integer delay, an exact first-order Thiran
+ * fraction, a two-decay loss filter, an optional dispersion cascade
+ * (stiffness) and an optional jawari bridge (sitar, tanpura buzz).
+ *
+ * Jawari (strings review, dsp blocker #2): the bridge is a lattice
+ * first-order allpass whose delay shortens with the string's one-sided
+ * displacement max(0, y - profile). An allpass has magnitude exactly 1 at
+ * every coefficient, so the buzz moves energy upward without adding DC; an
+ * in-loop DC blocker removes what the time-varying delay leaves. The pitch
+ * lock retunes the main fraction for the mean shortening, so a buzzing note
+ * stays on its target Hz.
+ */
+import { allpassDelay, thiranFor } from "../dsp/interp.ts";
+import { unit } from "../dsp/rng.ts";
+import {
+  clamp,
+  designDispersion,
+  designLoss,
+  onePoleDelay,
+  stiffnessB,
+} from "./loop.ts";
+
+export const C4 = 261.6255653005986;
+/** Control-rate step for pitch moves, the same as dawg's lanes. */
+const CONTROL = 32;
+/** Jawari bridge segment: rest length in samples and the shortest. */
+const JAW_BASE = 1.5;
+const JAW_SHORTEST = 0.5;
+/**
+ * Pitch-lock gain on the mean bridge shortening: the buzz also pulls the
+ * fundamental flat by moving energy upward, so the lock over-compensates
+ * by this frozen constant (calibrated at 22.05 kHz over keys 55-81 so the
+ * fundamental holds within 1 cent from 0.3 s; design review asked for a
+ * constant, not runtime state).
+ */
+const JAW_LOCK = 1.3;
+
+/** Phase delay (samples) at w of the DC blocker (1 - z^-1)/(1 - R z^-1). */
+function dcBlockDelay(R: number, w: number): number {
+  if (w < 1e-9) return 0;
+  const zero = Math.atan2(Math.sin(w), 1 - Math.cos(w));
+  const pole = Math.atan2(R * Math.sin(w), 1 - R * Math.cos(w));
+  return -(zero - pole) / w;
+}
+
+export type Exciter = "pick" | "finger" | "hammer" | "noise";
+
+/** Resolved plucked-string parameters for one note. */
+export type PluckSpec = Readonly<{
+  /** T60 (s) of the fundamental at C4. */
+  decay: number;
+  /** Decay key tracking: T60 x (f/C4)^-track. */
+  track: number;
+  /** 0..1 high-frequency loss. */
+  damp: number;
+  /** Stiffness knob; inharmonicity B = 1e-6 x 400^stiff. */
+  stiff: number;
+  /** Pluck position, fraction of the string from the bridge. */
+  pos: number;
+  exciter: Exciter;
+  /** 0..1 excitation brightness at full velocity. */
+  bright: number;
+  /** 0..1 noise share of the excitation. */
+  noise: number;
+  /** T60 (s) after note-off. */
+  release: number;
+  /** 0..1 bridge buzz. */
+  jawari: number;
+  /** 0 = bridge force; else magnetic pickup position (fraction). */
+  pickup: number;
+}>;
+
+export type PluckNote = Readonly<{
+  /** noteHz(pitch, cents, table) from the 0.5 tunings. */
+  hz: number;
+  /** 0..1 after the velocity curve and the preset's sensitivity. */
+  velocity: number;
+  /** Seconds to note-off (after articulation and pedal). */
+  hold: number;
+  /** Seed for the excitation noise (counter-based, src/audio/dsp/rng.ts). */
+  seed: number;
+  /** Pitch offset in cents at `t` seconds (bend, glide, vibrato). */
+  cents?: (t: number) => number;
+}>;
+
+function minHz(note: PluckNote, seconds: number): number {
+  let lo = note.hz;
+  if (note.cents)
+    for (let t = 0; t <= seconds; t += 0.01)
+      lo = Math.min(lo, note.hz * 2 ** (note.cents(t) / 1200));
+  return lo;
+}
+
+/** One plucked or struck string, streamed in blocks. */
+export class PluckString {
+  private readonly buf: Float64Array;
+  private readonly mask: number;
+  private w = 0;
+  private N = 1;
+  private a = 0;
+  private tx1 = 0;
+  private ty1 = 0;
+  private readonly lg: number;
+  private readonly lp: number;
+  private ly = 0;
+  private readonly da: number;
+  private readonly dn: number;
+  private readonly dx: Float64Array;
+  private readonly dy: Float64Array;
+  private readonly jaw: number;
+  private jv = 0;
+  private jsum = 0;
+  private jcount = 0;
+  private jmean = 0;
+  private hz: number;
+  private readonly dcR: number;
+  private dcx = 0;
+  private dcy = 0;
+  private readonly exc: Float64Array;
+  private n = 0;
+  /** Sample index of note-off; a restrike or steal moves it earlier. */
+  offAt: number;
+  private readonly rel: number;
+  private readonly pickupTap: number;
+  private readonly base: number;
+  private quiet = 0;
+  done = false;
+
+  constructor(
+    readonly spec: PluckSpec,
+    readonly note: PluckNote,
+    readonly sr: number,
+    readonly maxSeconds = 12,
+  ) {
+    const f0 = note.hz;
+    const t0 = spec.decay * (f0 / C4) ** -spec.track;
+    const th = t0 / (1 + 99 * spec.damp * spec.damp);
+    // The high decay point sits at least 3 f0 up, so a high note's loss
+    // filter is not fitted between its own first partials (T60 accuracy).
+    const loss = designLoss(f0, t0, Math.max(3000, 3 * f0), th, sr);
+    this.lg = loss.g;
+    this.lp = loss.p;
+    const P = sr / f0;
+    this.jaw = spec.jawari;
+    this.base = spec.jawari > 0 ? JAW_BASE : 0;
+    this.dcR = spec.jawari > 0 ? Math.exp((-2 * Math.PI * 10) / sr) : 0;
+    const B = stiffnessB(spec.stiff);
+    const sections = B > 0 ? 4 : 0;
+    const w0 = (2 * Math.PI * f0) / sr;
+    this.dn = sections;
+    this.da = designDispersion(
+      f0,
+      B,
+      sections,
+      sr,
+      Math.max(0, P - 2.5 - onePoleDelay(this.lp, w0) - this.base),
+    );
+    this.dx = new Float64Array(sections);
+    this.dy = new Float64Array(sections);
+    const lowest = minHz(note, note.hold + spec.release);
+    let size = 16;
+    while (size < sr / lowest + 16) size <<= 1;
+    this.buf = new Float64Array(size);
+    this.mask = size - 1;
+    this.hz = f0;
+    this.retune(f0, true);
+    this.exc = excitation(spec, note, sr, P);
+    this.offAt = Math.round(note.hold * sr);
+    this.rel = 0.001 ** (1 / (Math.max(0.005, spec.release) * sr));
+    this.pickupTap =
+      spec.pickup > 0 ? Math.max(1, Math.round(spec.pickup * P)) : 0;
+  }
+
+  /** Loop delay for `hz`: integer N plus an exact Thiran fraction. */
+  private retune(hz: number, first = false): void {
+    const sr = this.sr;
+    this.hz = hz;
+    const w0 = (2 * Math.PI * hz) / sr;
+    let rest = sr / hz - onePoleDelay(this.lp, w0);
+    if (this.jaw > 0) {
+      // Pitch lock: the bridge allpass at its mean shortening and the
+      // in-loop DC blocker are both counted in the loop length.
+      const frac = this.base - JAW_LOCK * this.jmean;
+      rest -= allpassDelay((1 - frac) / (1 + frac), w0);
+      rest -= dcBlockDelay(this.dcR, w0);
+    }
+    if (this.dn > 0) rest -= this.dn * allpassDelay(this.da, w0);
+    const N = Math.max(1, Math.floor(rest - 0.5));
+    const D = clamp(rest - N, 0.5, 1.5);
+    const a = thiranFor(D, w0);
+    if (!first && N !== this.N) {
+      // Restate the allpass memory for the new read position.
+      const m = this.mask;
+      this.tx1 = this.buf[(this.w - 1 - N) & m]!;
+      const pos = this.w - 1 - N - D;
+      const i0 = Math.floor(pos);
+      const fr = pos - i0;
+      this.ty1 = this.buf[i0 & m]! * (1 - fr) + this.buf[(i0 + 1) & m]! * fr;
+    }
+    this.N = N;
+    this.a = a;
+  }
+
+  /** Moves note-off to `at` samples from the string's start (restrike, steal). */
+  releaseAt(at: number): void {
+    if (at < this.offAt) this.offAt = Math.max(this.n, at);
+  }
+
+  /**
+   * Adds `count` samples x `gain` into out[offset..] (and x `gainR` into
+   * `right` when given); returns false once silent.
+   */
+  process(
+    out: Float64Array,
+    offset: number,
+    count: number,
+    gain = 1,
+    right?: Float64Array,
+    gainR = 0,
+  ): boolean {
+    if (this.done) return false;
+    const { buf, mask, lp, exc, dx, dy, da, dn, jaw } = this;
+    const lgain = this.lg * (1 - lp);
+    const cents = this.note.cents;
+    const sr = this.sr;
+    let peak = 0;
+    for (let i = 0; i < count; i += 1) {
+      const n = this.n;
+      if (n % CONTROL === 0 && (cents || jaw > 0)) {
+        if (jaw > 0 && this.jcount > 0) {
+          // Mean bridge shortening over the last control block (pitch lock).
+          this.jmean += 0.25 * (this.jsum / this.jcount - this.jmean);
+          this.jsum = 0;
+          this.jcount = 0;
+        }
+        this.retune(
+          cents ? this.note.hz * 2 ** (cents(n / sr) / 1200) : this.hz,
+        );
+      }
+      const d = buf[(this.w - this.N) & mask]!;
+      const t = this.a * d + this.tx1 - this.a * this.ty1;
+      this.tx1 = d;
+      this.ty1 = t;
+      this.ly = lgain * t + lp * this.ly;
+      let s = this.ly;
+      for (let k = 0; k < dn; k += 1) {
+        const y = da * s + dx[k]! - da * dy[k]!;
+        dx[k] = s;
+        dy[k] = y;
+        s = y;
+      }
+      if (jaw > 0) {
+        // Bridge: a lattice allpass whose delay shortens with the
+        // one-sided displacement (bridge profile at rest = 0).
+        const short = Math.min(
+          JAW_BASE - JAW_SHORTEST,
+          jaw * 40 * Math.max(0, s),
+        );
+        this.jsum += short;
+        this.jcount += 1;
+        const frac = JAW_BASE - short;
+        const k = (1 - frac) / (1 + frac);
+        // Lattice form of (k + z^-1)/(1 + k z^-1): |H| = 1 for any k(n).
+        const y = k * s + this.jv;
+        this.jv = s - k * y;
+        // In-loop DC blocker (10 Hz).
+        const blocked = y - this.dcx + this.dcR * this.dcy;
+        this.dcx = y;
+        this.dcy = blocked;
+        s = blocked;
+      }
+      if (n >= this.offAt) {
+        const ramp = Math.min(1, (n - this.offAt) / (0.005 * sr));
+        s *= 1 - (1 - this.rel) * ramp;
+      }
+      const x = n < exc.length ? exc[n]! : 0;
+      const y = x + s;
+      buf[this.w & mask] = y;
+      const o = this.pickupTap ? y - buf[(this.w - this.pickupTap) & mask]! : y;
+      this.w += 1;
+      this.n += 1;
+      out[offset + i] = out[offset + i]! + gain * o;
+      if (right) right[offset + i] = right[offset + i]! + gainR * o;
+      const ay = Math.abs(y);
+      if (ay > peak) peak = ay;
+    }
+    // Tail limit: after note-off, stop once 2048 samples stay below -100 dBFS.
+    if (this.n > this.offAt && peak < 1e-5) {
+      this.quiet += count;
+      if (this.quiet >= 2048) this.done = true;
+    } else this.quiet = 0;
+    if (this.n >= this.maxSeconds * sr) this.done = true;
+    return !this.done;
+  }
+}
+
+/**
+ * Excitation: a raised-cosine pulse (pick, finger, hammer) or noise,
+ * shaped by the pluck-position comb (Jaffe and Smith 1983) and a velocity
+ * brightness low-pass, normalised to a loop RMS of 0.25 x velocity gain.
+ */
+function excitation(
+  spec: PluckSpec,
+  note: PluckNote,
+  sr: number,
+  P: number,
+): Float64Array {
+  const vel = clamp(note.velocity, 0, 1);
+  const b = clamp(spec.bright * (0.3 + 0.7 * vel), 0, 1);
+  const lerp = (x: number, y: number) => x + (y - x) * b;
+  const width =
+    spec.exciter === "pick"
+      ? lerp(1.2e-3, 0.1e-3)
+      : spec.exciter === "finger"
+        ? lerp(5e-3, 0.9e-3)
+        : spec.exciter === "hammer"
+          ? lerp(4e-3, 0.3e-3)
+          : P / sr;
+  const L = Math.max(
+    2,
+    Math.min(
+      Math.round(width * sr),
+      Math.round(spec.exciter === "noise" ? P : 0.6 * P),
+    ),
+  );
+  const M = Math.max(1, Math.round(spec.pos * P));
+  const len = L + M + 1;
+  const raw = new Float64Array(len);
+  const noisy = spec.exciter === "noise";
+  for (let i = 0; i < L; i += 1) {
+    const env = 0.5 - 0.5 * Math.cos((2 * Math.PI * (i + 0.5)) / L);
+    const pulse = noisy ? 0 : env;
+    const r = 2 * unit(note.seed, i, 0) - 1;
+    raw[i] = pulse * (1 - spec.noise) + (noisy ? 1 : spec.noise) * env * r;
+  }
+  const e = new Float64Array(len);
+  for (let i = 0; i < len; i += 1) e[i] = raw[i]! - (i >= M ? raw[i - M]! : 0);
+  // Velocity brightness: one-pole low-pass 300 Hz .. 13.6 kHz.
+  const fc = Math.min(0.45 * sr, 300 * 2 ** (5.5 * b));
+  const al = 1 - Math.exp((-2 * Math.PI * fc) / sr);
+  let y = 0;
+  let energy = 0;
+  for (let i = 0; i < len; i += 1) {
+    y += al * (e[i]! - y);
+    e[i] = y;
+    energy += y * y;
+  }
+  const gain = (0.25 * (0.15 + 0.85 * vel)) / Math.sqrt(energy / P + 1e-30);
+  for (let i = 0; i < len; i += 1) e[i] = e[i]! * gain;
+  return e;
+}