polyphon 0.0.0-stage → 0.1.0

package/src/instruments/dsp/piano.ts

@@ -0,0 +1,226 @@
+// Acoustic piano (modal, calibrated against real pianos) and electric piano (FM).
+
+import { Biquad, normalize, rng, tailFade } from './core.ts';
+
+//
+// Modal synthesis: each partial of each string is a decaying oscillator. The parameters are calibrated against measurements of real pianos and piano recordings from Apple Loops:
+// - 1 to 3 strings per note (1 for the bass, 2 for the low-mid, 3 for the rest); each string is out of tune by a fraction of a cent and has a slightly different inharmonicity coefficient,
+//   and the beating between partials makes the sound alive rather than an electronic organ.
+// - Two-stage decay: the vertical vibration of the string hands its energy quickly to the soundboard (dropping about 12 dB right after the attack), while the horizontal vibration leaves a long tail;
+//   high partials get an extra loss proportional to the square of frequency (the Chaigne and Askenfelt string damping model).
+// - Excitation spectrum: partial amplitude is about inversely proportional to the square root of frequency, then falls away past a knee; the hammer strikes at about 1/8 to 1/13 of the string length, so partials near that point are weak.
+//   The sample is struck brightest (forte) and at playback is rolled off with a low-pass according to velocity (tone in instruments.ts): a light touch is dark, a hard strike bright.
+// - Soundboard: a fixed set of resonance peaks shapes the body's timbre; on the attack, the low-frequency thud of the soundboard being struck, and the hammer's brief scrape.
+// - Stretch tuning: bass slightly flat and treble slightly sharp (the Railsback curve), so octaves do not clash because of inharmonicity.
+
+/** Stretch tuning (cents) */
+export function pianoStretch(m: number): number {
+  const d = m - 64;
+  return Math.sign(d) * 0.004 * Math.pow(Math.abs(d), 2.2);
+}
+
+/** Inharmonicity coefficient: smallest in the low-mid register, growing toward the lowest notes and the treble */
+function pianoB(m: number): number {
+  return m <= 40 ? 6e-5 * Math.pow(2, (40 - m) / 14) : 6e-5 * Math.pow(2, (m - 40) / 9.3);
+}
+
+/** Seconds for the tail to decay 60 dB (fundamental) */
+export const pianoSustain = (m: number): number => Math.min(30, Math.max(1.2, 30 * Math.pow(2, -(m - 21) / 24)));
+
+/** Frequency response of the soundboard and body (dB): shared by every note of the same piano */
+let boardDb: ((f: number) => number) | null = null;
+function board(f: number): number {
+  if (!boardDb) {
+    const r = rng(90210);
+    const modes: [number, number, number][] = [];
+    for (let i = 0; i < 34; i++) {
+      const fc = 70 * Math.pow(3200 / 70, (i + 0.5 + r() * 0.45) / 34);
+      modes.push([fc, 4.5 * r(), 3 + 4 * Math.abs(r())]);
+    }
+    boardDb = (x) => {
+      let g = 0;
+      for (const [fc, gain, q] of modes) {
+        const u = ((x - fc) * 2 * q) / fc;
+        g += gain / (1 + u * u);
+      }
+      return g;
+    };
+  }
+  // The soundboard radiates poorly at very low frequencies: it drops 12 dB per octave below 45 Hz
+  const hp = 1 / Math.sqrt(1 + Math.pow(45 / f, 4));
+  return Math.pow(10, boardDb(f) / 20) * hp;
+}
+
+/** Piano sample: soft is the soft voicing (felt, warm, used for narrative and the ending) */
+export function piano(sr: number, m: number, soft = false): Float32Array {
+  const r = rng(m * 31 + (soft ? 7 : 0));
+  const f0 = 440 * Math.pow(2, (m - 69 + pianoStretch(m) / 100) / 12);
+  const Ts = pianoSustain(m);
+  const len = Math.min(9, Math.max(1.6, Ts * 0.85));
+  const n = Math.floor(len * sr);
+  const acc = new Float64Array(n);
+  const nyq = sr * 0.45;
+  const B = pianoB(m);
+  // Strings: how many, each one's detuning (cents), and the differences in inharmonicity coefficient
+  const nStr = m < 30 ? 1 : m < 42 ? 2 : 3;
+  const strings: [number, number][] = [];
+  for (let k = 0; k < nStr; k++) {
+    const cents = nStr === 1 ? 0 : (k - (nStr - 1) / 2) * (0.9 + 0.6 * r()) + 0.35 * r();
+    strings.push([f0 * Math.pow(2, cents / 1200), B * (1 + 0.02 * r())]);
+  }
+  // The knee of the excitation spectrum moves up with pitch; the soft voicing is darker
+  const oct = Math.pow(2, (m - 40) / 24);
+  const fk = (soft ? 650 : 1200) * oct;
+  const fe = (soft ? 1700 : 3000) * oct;
+  // Hammer strike point (as a fraction of string length): about 1/8 for the bass, about 1/13 for the treble
+  const beta = 1 / (8 + Math.max(0, m - 21) * 0.058);
+  // From the middle of the keyboard up, the felt stays on the string for about a period of the note, which filters the upper
+  // partials away (12 dB per octave above the cutoff: ~530 Hz at C4, 420 Hz from C5 up) and leaves the treble round; it fades in between C3 and C4
+  const felt = Math.min(1, Math.max(0, (m - 48) / 12));
+  const feltCut = (soft ? 0.8 : 1) * 420 * Math.pow(2, Math.max(0, 72 - m) / 36);
+  // Decay: σ = base loss + b3·ω²; the early stage (handed over to the soundboard) is fast, the later stage (the tail) is slow
+  const Tf = Ts / 2;
+  const prompt = soft ? 0.55 : 0.6;
+  // Frequency-dependent loss at the level measured on real strings (Chaigne and Askenfelt): the highs die well before the fundamental
+  const b3 = soft ? 9e-9 : 6e-9;
+  /** [frequency, amplitude] of the first partials, for the sympathetic strings */
+  const struck: [number, number][] = [];
+  for (let p = 1; p < 400; p++) {
+    const fp = p * f0 * Math.sqrt(1 + B * p * p);
+    if (fp > nyq) break;
+    const lp = 1 / (1 + (fp / fk) * (fp / fk));
+    const ex = Math.exp(-fp / fe);
+    let amp = Math.sqrt((f0 / fp) * lp * ex);
+    amp *= Math.pow(1 + Math.pow(fp / feltCut, 4), -felt / 2);
+    amp *= Math.abs(Math.sin(Math.PI * p * beta)) * 0.92 + 0.08;
+    amp *= board(fp);
+    if (amp < 3e-4) {
+      if (fp > fk * 4) break;
+      continue;
+    }
+    if (p <= 8) struck.push([fp, amp]);
+    const w2 = Math.pow(2 * Math.PI * fp, 2);
+    const s1 = 6.9 / Tf + b3 * w2;
+    const s2 = 6.9 / Ts + b3 * w2;
+    const k1 = Math.exp(-s1 / sr);
+    const k2 = Math.exp(-s2 / sr);
+    for (const [fs, Bs] of strings) {
+      // Each partial is also shifted a tiny bit (string non-uniformity, bridge coupling), so the beats between strings do not all cancel neatly together
+      const jit = nStr > 1 ? Math.pow(2, (0.45 * r()) / 1200) : 1;
+      const w = (2 * Math.PI * p * fs * jit * Math.sqrt(1 + Bs * p * p)) / sr;
+      const cw = Math.cos(w);
+      const sw = Math.sin(w);
+      // A struck string starts from rest: every partial starts from sin 0
+      let re = 1;
+      let im = 0;
+      let e1 = (amp * prompt) / nStr;
+      let e2 = (amp * (1 - prompt)) / nStr;
+      const stop = amp * 1e-4 / nStr;
+      for (let i = 0; i < n; i++) {
+        acc[i] += im * (e1 + e2);
+        const nr = re * cw - im * sw;
+        im = re * sw + im * cw;
+        re = nr;
+        e1 *= k1;
+        e2 *= k2;
+        if (e1 + e2 < stop) break;
+      }
+    }
+  }
+  sympathetic(acc, sr, m, struck, b3);
+  const y = new Float32Array(n);
+  for (let i = 0; i < n; i++) y[i] = acc[i];
+  // Set the volume by the energy in the first 0.25 s after the attack (rather than the peak): every note sounds equally loud, and loudness is left to playback velocity
+  let e = 0;
+  const w = Math.min(n, Math.floor(sr * 0.25));
+  for (let i = 0; i < w; i++) e += y[i] * y[i];
+  const rms = Math.sqrt(e / w) || 1;
+  // The soundboard thud when struck: a few low-frequency soundboard modes, brief; relatively noticeable in the treble (short strings, quiet string sound)
+  const knockAmp = rms * (soft ? 0.35 : 0.55) * Math.min(1.6, Math.max(0.5, (m - 30) / 40));
+  const knock: [number, number, number][] = [[96, 0.13, 1], [168, 0.09, 0.8], [281, 0.06, 0.6], [470, 0.035, 0.4]];
+  for (const [fq, dec, a] of knock) {
+    const bp = new Biquad(sr, 'bp', fq, 2.2);
+    const kd = Math.pow(10, -3 / (dec * sr));
+    let env = knockAmp * a * 6;
+    for (let i = 0; i < n && env > 1e-6; i++) {
+      y[i] += bp.run(r()) * env;
+      env *= kd;
+    }
+  }
+  // The hammer's scrape: mid-high frequencies, a few milliseconds
+  const hb = new Biquad(sr, 'bp', Math.min(5000, 1400 + f0 * 2), 0.9);
+  let he = rms * (soft ? 0.12 : 0.3);
+  const hk = Math.pow(10, -3 / (0.006 * sr));
+  for (let i = 0; i < n && he > 1e-6; i++) {
+    y[i] += hb.run(r()) * he;
+    he *= hk;
+  }
+  // Attack: it takes a moment for the hammer to push the string away (longer with the soft voicing's felt)
+  const att = Math.floor(sr * (soft ? 0.004 : 0.0015));
+  for (let i = 0; i < att && i < n; i++) y[i] *= i / att;
+  const g = 0.25 / rms;
+  for (let i = 0; i < n; i++) y[i] *= g;
+  return tailFade(y, sr);
+}
+
+/**
+ * Sympathetic resonance: strings left free by the dampers (the whole keyboard with the pedal down; the top of the treble always)
+ * pick up this note's partials through the bridge. A string answers in its n-th mode when that mode lands within a Hz or two of a partial:
+ * the strings an octave and a twelfth around a note answer, an equal-tempered third (14 cents off) barely does.
+ * Each answers at its own frequency (stretched tuning and inharmonicity differ), blooming in over a tenth of a second and ringing
+ * with its own decay, so the sound grows a soft halo that beats gently against the struck strings.
+ * The bloom is slow, so short unpedalled notes are damped before it is heard; held and pedalled notes carry it.
+ */
+function sympathetic(acc: Float64Array, sr: number, m: number, struck: [number, number][], b3: number): void {
+  const n = acc.length;
+  for (const [fp, amp] of struck) {
+    if (fp > 4000) break;
+    for (const mode of [1, 2, 3]) {
+      const key = Math.round(69 + 12 * Math.log2(fp / mode / 440));
+      if (key === m || key < 21 || key > 108) continue;
+      const fs = 440 * Math.pow(2, (key - 69 + pianoStretch(key) / 100) / 12);
+      const f = mode * fs * Math.sqrt(1 + pianoB(key) * mode * mode);
+      const match = 1 / (1 + Math.pow((f - fp) / 1.5, 2));
+      const level = (amp * 0.12 * match) / mode;
+      if (level < 1e-4) continue;
+      const decay = Math.exp(-(6.9 / pianoSustain(key) + b3 * Math.pow(2 * Math.PI * f, 2)) / sr);
+      const bloom = Math.exp(-1 / (0.08 * sr));
+      const w = (2 * Math.PI * f) / sr;
+      let env = level;
+      let rise = 1;
+      for (let i = 0; i < n && env > level * 1e-3; i++) {
+        acc[i] += Math.sin(w * i) * env * (1 - rise);
+        rise *= bloom;
+        env *= decay;
+      }
+    }
+  }
+}
+
+/** Electric piano (Rhodes feel): 1:1 FM, modulation index decaying over time, plus a tuning-fork tine ring in the highs */
+export function epiano(sr: number, m: number): Float32Array {
+  const f = 440 * Math.pow(2, (m - 69) / 12);
+  const t60 = Math.max(1.2, 6 * Math.pow(0.5, (m - 48) / 24));
+  const len = Math.min(5, t60 * 0.8);
+  const n = Math.floor(len * sr);
+  const y = new Float32Array(n);
+  const w = (2 * Math.PI * f) / sr;
+  const k = Math.pow(10, -3 / (t60 * sr));
+  const kt = Math.pow(10, -3 / (0.35 * sr));
+  let env = 1;
+  let tine = 0.12;
+  let pc = 0;
+  let pm = 0;
+  for (let i = 0; i < n; i++) {
+    const t = i / sr;
+    const I = 1.6 * Math.exp(-t / 0.3) + 0.35;
+    pc += w;
+    pm += w;
+    y[i] = Math.sin(pc + I * Math.sin(pm)) * env + Math.sin(pc * 7.1) * tine;
+    env *= k;
+    tine *= kt;
+  }
+  const att = Math.floor(sr * 0.003);
+  for (let i = 0; i < att; i++) y[i] *= i / att;
+  return tailFade(normalize(y), sr);
+}

package/src/instruments/dsp/pluck.ts

@@ -0,0 +1,240 @@
+// Plucked strings: Karplus-Strong for guitars, harps and dulcimers; an additive model for bass plucks.
+
+import { Biquad, normalize, rng, tailFade } from './core.ts';
+
+// ───────────────────────── Plucked string: Karplus-Strong ─────────────────────────
+//
+// A digital waveguide string (Karplus-Strong, with an allpass for exact tuning), shaped by what a real pluck does:
+// - The pluck: the finger or plectrum draws the string aside into a triangle and lets go. The force on the bridge is then a rectangular wave
+//   whose n-th harmonic is ∝ sin(nπ·pos)/n: the overtones fall 6 dB per octave, with gaps at multiples of 1/pos. The string slips off a finger
+//   over a fraction of a millisecond (off a nail or plectrum faster), a low-pass on top. Plain Karplus-Strong plucks with noise instead, which
+//   leaves every overtone at a random level, some 10-30 dB above the fundamental: a twangy, synthetic tone that changes from note to note.
+// - The loss: a string loses energy to the air and to internal friction at a rate that grows with the square of frequency
+//   (σ = b1 + b3·ω², Chaigne and Askenfelt), whatever string the partial is on. The plain Karplus-Strong loop filter loses a fixed fraction
+//   per round trip instead, so a bass string (a long round trip) keeps its highs ringing like an organ while a treble string collapses to a sine
+//   within a few tenths of a second (a 2 kHz partial lasted 4.5 s on the harp's C2 and 0.9 s on its C5). Here the loop filter is a one-pole
+//   low-pass designed for each note so that every partial decays at the rate σ prescribes; the fundamental keeps the T60 asked for.
+// - The body: the bridge drives the guitar top (the violin body, the harp soundboard). Its response is broadly flat, with strong peaks at the lowest
+//   modes (the air in the cavity, the top plate) that lift the partials near them and ring for a moment on their own, knocked by the release of the string.
+
+/** A body mode: [frequency Hz, boost at the peak in dB, Q]; it rings for about 2.2·Q/f seconds */
+export type BodyMode = [number, number, number];
+
+/** Classical guitar: the air in the body (~95 Hz) coupled to the top plate (~200 Hz), and the top's next modes around 400 Hz */
+export const GUITAR_BODY: BodyMode[] = [[96, 7, 14], [205, 6, 16], [400, 3.5, 12], [560, 2, 10]];
+/** Steel-string guitar: a larger, stiffer top braced for the strings' higher tension */
+export const STEEL_BODY: BodyMode[] = [[102, 6, 14], [190, 5, 16], [380, 3, 12], [650, 2, 10]];
+/** Lute and oud: a light bowl-backed body with a thin top, modes higher than a guitar's */
+export const LUTE_BODY: BodyMode[] = [[125, 5, 12], [260, 5, 14], [520, 3, 10]];
+/** Violin family (pizzicato): the air mode A0 and the corpus modes B1-, B1+ */
+export const VIOLIN_BODY: BodyMode[] = [[275, 6, 12], [460, 5, 14], [540, 4, 14]];
+/** Concert harp: the long soundboard and the box behind it */
+export const HARP_BODY: BodyMode[] = [[110, 3, 8], [190, 3, 10], [330, 2, 10]];
+/** Hammered dulcimer: a shallow trapezoid box */
+export const DULCIMER_BODY: BodyMode[] = [[180, 4, 12], [320, 4, 12], [610, 2.5, 10]];
+
+export interface KsOpts {
+  /** Length in seconds */
+  len: number;
+  /** Seconds for the fundamental to decay to -60 dB (at this pitch) */
+  t60: number;
+  /** How fast the string is let go, 0-1: the pluck's low-pass, from 2 kHz (soft flesh) to 16 kHz (plectrum, hammer) */
+  bright: number;
+  /** Pluck position as a fraction of the string length, 0-0.5 (the nearer the bridge, the more overtones) */
+  pos: number;
+  /** Frequency-dependent string loss b3 (s⁻¹ per (rad/s)²): a partial at ω decays b3·(ω² − ω0²) per second faster than the fundamental. 2e-8 lets a 2 kHz partial ring about 1.5 s (steel), 6e-8 about 0.6 s (nylon) */
+  loss: number;
+  /** Detune of the second string (cents); 0 means a single string */
+  detune?: number;
+  /** Body modes */
+  body?: BodyMode[];
+  /** Loudness by register, dB per octave from middle C (the shorter, lighter treble strings move less air) */
+  tilt?: number;
+}
+
+/**
+ * The whole body: the listed low modes, then the many plate and cavity modes above them, too dense to list (24 of them log-spaced up to 4 kHz,
+ * -2 to +3 dB, Q 12-30). Each colours the partials near it and rings for some tens of milliseconds, so the bridge's sharp pulse each period
+ * comes out as a short wooden ring rather than a bare click train.
+ */
+function bodyModes(body: BodyMode[]): BodyMode[] {
+  const r = rng(Math.round(body[0][0] * 97));
+  const lo = body[body.length - 1][0] * 1.25;
+  const dense: BodyMode[] = [];
+  for (let i = 0; i < 24; i++) dense.push([lo * Math.pow(4000 / lo, (i + 0.5 + 0.4 * r()) / 24), 0.5 + 2.5 * r(), 21 + 9 * r()]);
+  return [...body, ...dense];
+}
+
+/** Pass x through the body (in place): each mode adds a resonant band-pass, so a mode of gain G dB lifts its frequency by G dB */
+function throughBody(sr: number, modes: BodyMode[], x: Float32Array): void {
+  const bank = modes.map(([hz, gain, q]) => [new Biquad(sr, 'bp', hz, q), Math.pow(10, gain / 20) - 1] as const);
+  for (let i = 0; i < x.length; i++) {
+    const v = x[i];
+    let s = v;
+    for (const [bp, k] of bank) s += k * bp.run(v);
+    x[i] = s;
+  }
+}
+
+/** Per round trip, the one-pole loop filter g·(1−p)/(1−p·z⁻¹) passes this much at ω relative to its gain g */
+const onePole = (p: number, w: number): number => (1 - p) / Math.sqrt(1 - 2 * p * Math.cos(w) + p * p);
+
+/**
+ * One string, heard through the body; returns the output and the bridge force it starts from (its level the instant before the string is let go).
+ * Body and string are both linear, so the body can come first (commuted synthesis): it filters the pluck, a fraction of a second long, rather than the whole note.
+ */
+function ksString(sr: number, f: number, o: KsOpts, body: BodyMode[], ring: number): [Float32Array, number] {
+  const n = Math.floor(o.len * sr);
+  const y = new Float32Array(n);
+  const P = sr / f;
+  const w0 = (2 * Math.PI * f) / sr;
+  // Decay per second of a partial at x Hz, σ = b1 + b3·ω²: b1 is set so the fundamental keeps the T60 asked for, unless the string's own
+  // loss at that frequency is already faster (the top of the harp)
+  const b1 = Math.max(0.1, 6.91 / o.t60 - o.loss * Math.pow(2 * Math.PI * f, 2));
+  const sigma = (x: number) => b1 + o.loss * Math.pow(2 * Math.PI * x, 2);
+  // The loop filter g·(1−p)/(1−p·z⁻¹) loses σ(x)/f per round trip: matched at the fundamental and at a frequency high in the spectrum
+  const fr = Math.min(0.4 * sr, Math.max(4000, 3 * f));
+  const wr = (2 * Math.PI * fr) / sr;
+  const G0 = Math.exp(-sigma(f) / f);
+  const want = Math.exp(-(sigma(fr) - sigma(f)) / f);
+  let lo = 0;
+  let hi = 0.995;
+  for (let i = 0; i < 40; i++) {
+    const p = (lo + hi) / 2;
+    if (onePole(p, wr) / onePole(p, w0) > want) lo = p;
+    else hi = p;
+  }
+  // It must not gain at 0 Hz, where it loses b1 (on the highest strings this caps how fast the highs can die)
+  const gMax = Math.exp(-b1 / f);
+  if (G0 / onePole(hi, w0) > gMax) {
+    lo = 0;
+    for (let i = 0; i < 40; i++) {
+      const p = (lo + hi) / 2;
+      if (G0 / onePole(p, w0) > gMax) hi = p;
+      else lo = p;
+    }
+  }
+  const p = lo;
+  const g = G0 / onePole(p, w0);
+  // Tuning: the loop filter's phase delay at the fundamental comes off the delay line, and an allpass supplies the remaining fraction of a sample
+  const tau = Math.atan2(p * Math.sin(w0), 1 - p * Math.cos(w0)) / w0;
+  const L = Math.max(2, Math.floor(P - tau - 0.2));
+  const frac = P - tau - L;
+  const C = (1 - frac) / (1 + frac);
+  // The pluck: one period of the bridge force, summed from its harmonics (a rectangular wave of duty pos, centred on the start, rounded by the release)
+  const fc = 2000 * Math.pow(8, o.bright);
+  const exc = new Float32Array(L + 1 + ring);
+  for (let h = 1; h * f < sr * 0.45; h++) {
+    const a = (2 * Math.sin(Math.PI * h * o.pos)) / (Math.PI * h) / Math.sqrt(1 + Math.pow((h * f) / fc, 2));
+    const dw = (2 * Math.PI * h) / P;
+    for (let i = 0; i <= L; i++) exc[i] += a * Math.cos(dw * i);
+  }
+  const held = exc[0];
+  throughBody(sr, body, exc);
+  let lpv = 0;
+  let apIn = 0;
+  let apOut = 0;
+  for (let i = 0; i < n; i++) {
+    const d = i >= L ? y[i - L] : 0;
+    lpv = (1 - p) * d + p * lpv;
+    const ap = C * lpv + apIn - C * apOut;
+    apIn = lpv;
+    apOut = ap;
+    y[i] = (i < exc.length ? exc[i] : 0) + g * ap;
+  }
+  return [y, held];
+}
+
+/** A plucked string (or a course of two) through its instrument's body */
+export function ks(sr: number, f: number, o: KsOpts): Float32Array {
+  const body = o.body ? bodyModes(o.body) : [];
+  const ring = Math.ceil(sr * Math.max(0, ...body.map(([hz, , q]) => (2.6 * q) / hz)));
+  const [y, held1] = ksString(sr, f, o, body, ring);
+  let held = held1;
+  if (o.detune) {
+    const [y2, held2] = ksString(sr, f * Math.pow(2, o.detune / 1200), o, body, ring);
+    for (let i = 0; i < y.length; i++) y[i] = 0.55 * (y[i] + y2[i]);
+    held = 0.55 * (held1 + held2);
+  }
+  // Before the release the finger holds the string with a steady force on the bridge, which makes no sound. Measured from there the sound
+  // starts from silence (no click), and letting go is a sudden push on the body; the body radiates poorly below its air mode, so the push
+  // fades within a couple of milliseconds, knocking the body modes on its way
+  const knock = new Float32Array(Math.min(y.length, Math.floor(sr * 0.02) + ring));
+  const kd = Math.exp((-2 * Math.PI * 90) / sr);
+  for (let i = 0; i < knock.length; i++, held *= kd) knock[i] = -held;
+  throughBody(sr, body, knock);
+  for (let i = 0; i < knock.length; i++) y[i] += knock[i];
+  // Remove DC and soften the highest frequencies
+  const hp = new Biquad(sr, 'hp', 40);
+  const lpf = new Biquad(sr, 'lp', 12000);
+  for (let i = 0; i < y.length; i++) y[i] = lpf.run(hp.run(y[i]));
+  // Loudness is set by the energy of the first half second rather than the peak (which the sharp edge of the pluck decides), falling by tilt dB per octave
+  const w = Math.min(y.length, Math.floor(sr * 0.5));
+  let e = 0;
+  for (let i = 0; i < w; i++) e += y[i] * y[i];
+  const k = (0.2 * Math.pow(10, ((o.tilt ?? 0) * Math.log2(f / 261.63)) / 20)) / (Math.sqrt(e / w) || 1);
+  for (let i = 0; i < y.length; i++) y[i] *= k;
+  return tailFade(y, sr);
+}
+
+// ───────────────────────── Plucked string (additive): bass plucks ─────────────────────────
+
+export interface PluckOpts {
+  len: number;
+  /** Seconds for the fundamental to decay to -60 dB; higher harmonics progressively faster */
+  t60: number;
+  /** Pluck position 0-0.5 (decides which harmonics are weakened) */
+  pos: number;
+  /** Harmonic slope (the larger, the darker) */
+  tilt: number;
+  /** Frequencies of the body resonances (Hz): they sound together at the instant of the pluck and vanish quickly */
+  body: number[];
+  /** Amount of the finger's dull thump */
+  thump: number;
+}
+
+/**
+ * Additive-synthesis plucked string: each harmonic decays on its own (the higher, the faster), slightly inharmonic, plus body resonance and the finger's dull thump.
+ * In the bass range Karplus-Strong decays down to a pure sine (like a synthesizer); this model keeps the woody mid-range.
+ */
+export function pluckAdd(sr: number, f: number, o: PluckOpts): Float32Array {
+  const n = Math.floor(o.len * sr);
+  const y = new Float32Array(n);
+  const nyq = Math.min(sr * 0.42, 7000);
+  const B = 0.00012;
+  const r = rng(Math.round(f * 11));
+  for (let h = 1; h <= 40; h++) {
+    const fh = h * f * Math.sqrt(1 + B * h * h);
+    if (fh > nyq) break;
+    const amp = (Math.abs(Math.sin(Math.PI * h * o.pos)) + 0.05) / Math.pow(h, o.tilt);
+    const t60 = o.t60 / (1 + 0.45 * (h - 1));
+    const k = Math.pow(10, -3 / (t60 * sr));
+    const w = (2 * Math.PI * fh) / sr;
+    let env = amp;
+    let ph = r() * 0.2;
+    for (let i = 0; i < n && env > 1e-6; i++) {
+      ph += w;
+      y[i] += Math.sin(ph) * env;
+      env *= k;
+    }
+  }
+  for (const hz of o.body) {
+    const w = (2 * Math.PI * hz) / sr;
+    const k = Math.pow(10, -3 / (0.22 * sr));
+    let env = 0.35;
+    for (let i = 0; i < n && env > 1e-6; i++) {
+      y[i] += Math.sin(w * i) * env;
+      env *= k;
+    }
+  }
+  const lp = new Biquad(sr, 'lp', 350, 0.7);
+  const kt = Math.pow(10, -3 / (0.05 * sr));
+  let env = o.thump;
+  for (let i = 0; i < n && env > 1e-6; i++) {
+    y[i] += lp.run(r()) * env * 3;
+    env *= kt;
+  }
+  const att = Math.floor(sr * 0.003);
+  for (let i = 0; i < att && i < n; i++) y[i] *= i / att;
+  return tailFade(normalize(y), sr);
+}

package/src/instruments/dsp/reverb.ts

@@ -0,0 +1,56 @@
+// Procedural reverb: a stereo impulse response of decaying noise whose highs fade faster than its lows.
+
+import { rng } from './core.ts';
+
+/** The acoustic space a song plays in */
+export interface Room {
+  /** Reverb time (seconds, decay by 60 dB) */
+  size: number;
+  /** 0 bright to 1 dark (how fast the highs decay; default 0.45) */
+  damp?: number;
+  /** Pre-delay (seconds; default 0.012) */
+  preDelay?: number;
+  /** Early reflection amount 0-1 (default 0.3) */
+  early?: number;
+  /** Attack time (seconds); above 0 it is a reverb that "grows in" (a reversed, ghostly feel) */
+  bloom?: number;
+}
+
+/** Generate a stereo impulse response: decaying noise, with the highs eaten away over time */
+export function impulse(sr: number, o: Room): [Float32Array, Float32Array] {
+  const len = Math.floor(sr * Math.min(8, o.size * 1.15 + (o.preDelay ?? 0) + 0.05));
+  const pre = Math.floor((o.preDelay ?? 0.012) * sr);
+  const damp = o.damp ?? 0.45;
+  const out: [Float32Array, Float32Array] = [new Float32Array(len), new Float32Array(len)];
+  for (let ch = 0; ch < 2; ch++) {
+    const r = rng(1234 + ch * 777);
+    const d = out[ch];
+    const k = Math.pow(10, -3 / (o.size * sr));
+    let env = 1;
+    let lp = 0;
+    for (let i = pre; i < len; i++) {
+      const t = (i - pre) / sr;
+      // The low-pass coefficient shrinks over time: darker toward the end
+      const a = Math.max(0.02, (1 - damp * 0.85) * Math.exp((-t * damp * 3) / Math.max(0.5, o.size)));
+      lp += a * (r() - lp);
+      let v = lp * env;
+      if (o.bloom) v *= 1 - Math.exp(-t / o.bloom);
+      d[i] = v;
+      env *= k;
+    }
+    // Early reflections
+    const er = o.early ?? 0.3;
+    if (er > 0) {
+      for (let j = 0; j < 8; j++) {
+        const at = pre + Math.floor((0.004 + Math.abs(r()) * 0.06) * sr);
+        if (at < len) d[at] += er * (0.5 + 0.5 * Math.abs(r())) * (r() > 0 ? 1 : -1) * 0.6;
+      }
+    }
+  }
+  // Energy normalization: rooms of different sizes come out equally loud
+  let e = 0;
+  for (const d of out) for (let i = 0; i < d.length; i++) e += d[i] * d[i];
+  const g = 1 / Math.sqrt(e / 2 + 1e-9);
+  for (const d of out) for (let i = 0; i < d.length; i++) d[i] *= g * 0.5;
+  return out;
+}

package/src/instruments/dsp/staccato.ts

@@ -0,0 +1,141 @@
+// Short sampled notes for fast figures (much cheaper than live synthesis): spiccato strings and brass stabs.
+
+import { Biquad, rng, tailFade } from './core.ts';
+
+/**
+ * Spiccato strings: the bow drops onto the string, draws a few periods of sawtooth (Helmholtz) motion, bounces off, and the string rings on freely.
+ * - Bowed for the first 40-65 ms: harmonics falling as 1/k through the body, the bite of the bow lightening as it bounces, and the rustle
+ *   of the hair catching the string.
+ * - Then free: each partial decays at its own rate. The string's internal losses and the bridge take more energy per second from the
+ *   upper partials (the decay rate grows with frequency), so they are gone within ~0.1 s while the fundamental rings on and the note
+ *   darkens as it dies, like a pizzicato. (One envelope on every partial kept the attack's bright tone to the end, like a gated synth.)
+ * - Five players a few cents and a few milliseconds apart: three copies at ±7 cents beat like a chorus.
+ */
+export function spicc(sr: number, m: number): Float32Array {
+  const f = 440 * Math.pow(2, (m - 69) / 12);
+  const y = new Float32Array(Math.floor(sr * 0.42));
+  const nyq = sr * 0.42;
+  const body = (hz: number) => 0.4 + 1.2 / (1 + ((hz - 450) / 250) ** 2) + 0.7 / (1 + ((hz - 1300) / 500) ** 2) + 0.5 / (1 + ((hz - 3000) / 900) ** 2);
+  const r = rng(m * 5 + 1);
+  // The bow bites and lightens as it bounces (shared by every partial)
+  const acc = new Float32Array(y.length);
+  for (let i = 0; i < y.length; i++) acc[i] = Math.min(1, i / sr / 0.008) * (0.25 + 0.75 * Math.exp(-i / sr / 0.06));
+  for (let p = 0; p < 5; p++) {
+    const ff = f * Math.pow(2, (5 * r()) / 1200);
+    const i0 = Math.floor(((r() + 1) / 2) * 0.012 * sr);
+    // The bow leaves the string
+    const i1 = i0 + Math.floor((0.052 + 0.012 * r()) * sr);
+    for (let k = 1; k < 40; k++) {
+      const hz = ff * k;
+      if (hz > nyq) break;
+      // Decay rate of the free string (nepers per second): T60 ≈ 0.5 s for the fundamental of A3, 0.09 s at 3 kHz
+      const dk = Math.exp(-(6 + 0.025 * hz) / sr);
+      let e = (0.77 * body(hz)) / k / (1 + (hz / 4500) ** 2);
+      // A rotating phasor from a random phase (cheaper than Math.sin per sample)
+      const w = (2 * Math.PI * hz) / sr;
+      const c = Math.cos(w);
+      const s = Math.sin(w);
+      const ph = r() * Math.PI;
+      let x = Math.cos(ph);
+      let z = Math.sin(ph);
+      for (let i = i0; i < y.length; i++) {
+        y[i] += z * e * acc[i - i0];
+        const nx = x * c - z * s;
+        z = x * s + z * c;
+        x = nx;
+        if (i >= i1) e *= dk;
+      }
+    }
+  }
+  const noise = new Biquad(sr, 'bp', Math.min(7000, f * 5), 1.2);
+  for (let i = 0; i < y.length; i++) y[i] += noise.run(r()) * 0.6 * Math.exp(-i / sr / 0.03);
+  // Levelled on the first 150 ms (the old peak normalization left notes ±3 dB apart at random; this is their average)
+  let e = 0;
+  const w = Math.floor(sr * 0.15);
+  for (let i = 0; i < w; i++) e += y[i] * y[i];
+  const g = 0.24 / (Math.sqrt(e / w) || 1);
+  for (let i = 0; i < y.length; i++) y[i] *= g;
+  return tailFade(y, sr);
+}
+
+/**
+ * Brass stab: a short forte blat from two players, a few cents and 12 ms apart. As in the live brass (voices.ts), the lips are a valve whose
+ * harmonics fall as e^(-f/F), with F following the loudness: the harmonics come in one after another during the attack, the note is brassiest
+ * at its peak and darkens as it dies away. The bell radiates the lows poorly and the cup rolls off the top (first-order corners at 1.1 and 6 kHz).
+ * Levelled on its first 250 ms, so every pitch hits equally hard.
+ */
+export function brassStab(sr: number, m: number): Float32Array {
+  const f = 440 * Math.pow(2, (m - 69) / 12);
+  const y = new Float32Array(Math.floor(sr * 0.55));
+  const nyq = sr * 0.42;
+  const r = rng(m * 3 + 9);
+  const lo = 1100;
+  const hi = 6000;
+  const env = (t: number) => Math.min(1, t / 0.02) * Math.exp(-t / 0.28);
+  const BLOCK = 32;
+  for (const [det, delay] of [[-6, 0], [6, 0.012]]) {
+    const ff = f * Math.pow(2, det / 1200);
+    const n = Math.min(80, Math.floor(nyq / ff));
+    // Each harmonic is a rotating phasor (cheap sines) from a random phase, with the bell's response and the rotation over one block
+    const bell = new Float64Array(n + 1);
+    const re = new Float64Array(n + 1);
+    const im = new Float64Array(n + 1);
+    const cw = new Float64Array(n + 1);
+    const sw = new Float64Array(n + 1);
+    const cb = new Float64Array(n + 1);
+    const sb = new Float64Array(n + 1);
+    for (let k = 1; k <= n; k++) {
+      const hz = ff * k;
+      bell[k] = ((lo + hi) * hz) / Math.sqrt((hz * hz + lo * lo) * (hz * hz + hi * hi));
+      const ph = r() * Math.PI;
+      const w = (2 * Math.PI * hz) / sr;
+      re[k] = Math.cos(ph);
+      im[k] = Math.sin(ph);
+      cw[k] = Math.cos(w);
+      sw[k] = Math.sin(w);
+      cb[k] = Math.cos(w * BLOCK);
+      sb[k] = Math.sin(w * BLOCK);
+    }
+    const amp = new Float64Array(n + 1);
+    const i0 = Math.floor(delay * sr);
+    // (The last part-block falls inside the tail fade and is left silent)
+    for (let b = i0; b + BLOCK <= y.length; b += BLOCK) {
+      // Per block: the fall-off F from the loudness, then the harmonics' amplitudes, scaled so the loudness follows the envelope
+      const e = env((b - i0) / sr);
+      const rr = Math.exp(-ff / (2400 * (0.25 + 0.75 * Math.pow(e, 0.7))));
+      let rn = 1;
+      let s = 0;
+      for (let k = 1; k <= n; k++) {
+        rn *= rr;
+        amp[k] = rn * bell[k];
+        s += amp[k] * amp[k];
+      }
+      const g = e / (Math.sqrt(s) || 1);
+      for (let k = 1; k <= n; k++) {
+        const a = amp[k] * g;
+        let x = re[k];
+        let z = im[k];
+        if (a < 1e-6) {
+          // Too weak to hear: just turn the phasor on by a block
+          re[k] = x * cb[k] - z * sb[k];
+          im[k] = x * sb[k] + z * cb[k];
+          continue;
+        }
+        for (let i = b; i < b + BLOCK; i++) {
+          y[i] += z * a;
+          const nx = x * cw[k] - z * sw[k];
+          z = x * sw[k] + z * cw[k];
+          x = nx;
+        }
+        re[k] = x;
+        im[k] = z;
+      }
+    }
+  }
+  let e = 0;
+  const w = Math.min(y.length, Math.floor(sr * 0.25));
+  for (let i = 0; i < w; i++) e += y[i] * y[i];
+  const k = 0.29 / (Math.sqrt(e / w) || 1);
+  for (let i = 0; i < y.length; i++) y[i] *= k;
+  return tailFade(y, sr);
+}