@hraness/dawg 0.5.0 → 0.6.1

package/src/agent/xcb-agent.ts

@@ -1,3 +1,4 @@
+import { GRANULAR_PARAMS } from "../../core/granular.ts";
 import { compositionBrief } from "./brief.ts";
 import { CHORD_PROCESS } from "../../core/chords.ts";
 import {
@@ -49,10 +50,22 @@ export const TEXT_AGENT_SYSTEM_PROMPT = [
   "Song structure: list_sections shows named sections (bars count from 1); edit_section marks, adds, duplicates, moves, renames, deletes, mutes, varies (transpose/gain) and loops them; set_form sets the play order with repeats (intro verse chorus*2 outro); add_transition generates builds (riser, snare roll, filter sweep, uplifter), drops (cut plus impact) and drum fills at section boundaries.",
   CHORD_PROCESS,
   "Synth voices: set_synth shapes a synth track with Strudel params (ADSR, lpf/lpenv filter envelopes, fm/fmh, supersaw unison/detune, vib, penv, noise; z_* ZzFX sounds take slide/pitchJump/lfo/zcrush…) or a preset (pad lead pluck bass keys bell…).",
+  "Plucked strings: set_string makes a track a physical-model string (nylon steel electric jangle ebass slap upright motown sitar tanpura harpsichord lute oud setar tar santur dulcimer koto harp banjo tres requinto) and overrides params (ring bright damp pos mute buzz body sym). The bare words sitar, ebass, pluck keep their older voices; use set_string for the modelled ones.",
+  "Bowed strings: set_string preset violin|viola|cello|contrabass|fiddle|erhu|kamancheh|violins|violas|cellos|contrabasses|pizz|trem plays a bowed physical model (bow params pressure speed attack vib vibmod vibdelay tremhz sord dyn). Overlapping or legato notes slur in one bow. The bare words cello, contrabass and strings keep their older voices; use set_string (or the words violin, viola, fiddle, erhu, violins, cellos) for the bowed ones. Sampler voices take vel [lo, hi] velocity layers and rr round-robin groups via set_sample.",
+  "Pianos: set_instrument piano (or grand upright felt honkytonk prepared, ballad, lofi) loads a modelled piano with real hammers, stretched inharmonic strings, dampers and the sustain pedal; set_keys tweaks it (hardness touch decay release felt stretch body…, automate as keys-<param> lanes; sym 0.5 adds sympathetic bloom under the sustain pedal for pedalled Romantic and Impressionist playing). A track already stored as instrument piano keeps the legacy tone until you set it again.",
+  "Electric keys: set_instrument epiano (rhodes; suitcase stereo vibe, dyno bright 80s), wurli, clav (funkclav); set_keys tweaks bark bell tone vibe (epiano), trem (wurli), pickup neck|bridge|both|out and mute (clav). Soft and sostenuto pedals: set_piano_pedals on any modelled piano.",
+  'Organs: set_instrument tonewheel (hammond b3 gospel jazzorgan), combo (farfisa vox) or pipe (church flutes cornet reeds celeste) loads a modelled organ; instrument organ stays the legacy sine. set_keys drawbars "888800008" (16\' to 1\'), registers "08880" (combo), stops ["principal8","octave4"] or plenum|flutes|cornet|reeds|strings|full (pipe), rotary slow|fast|stop, params perc 3rd percdecay percvol click scanner c3 drive chiff wind trem (each family takes only its own rows); automate keys-rotary and keys-drive lanes.',
+  "Mallets and bells: set_instrument vibes (or marimba via modal, xylophone glock celesta chimes kalimba mbira steelpan bowl gong timpani) plays the modal engine; set_modal changes mallet (yarn…brass), hardness, position, ring, damp, motor/motordepth (vibes tremolo), buzz, click. Plain instrument marimba stays the legacy tone.",
+  "Gamelan: set_modal preset saron demung slenthem gangsa gender bonang kenong kethuk kempul (gong too) with tuning slendro or pelog; for ombak (the shimmer) put the same part on two gangsa tracks and set_modal pair <other track> on one: it sounds ombak Hz (default 6) above its partner. Frame drums: daf bodhran tabla.",
+  "Winds and brass: set_instrument flute recorder whistle ney shakuhachi panpipe suling bansuri clarinet bassclarinet oboe bassoon sax altosax barisax trumpet harmon plunger trombone tuba horn plays the wind engine; set_wind changes breath, bright, mute (open straight cup harmon plunger), players (2..8 spreads a section over chord tones), growl, vib. Lines slur unless re-tongued (gaps or articulations). Plain instrument wind stays the legacy tone.",
   "Sampler voices: set_sample sets Strudel sample controls per voice (begin end speed unit loop loopBegin loopEnd clip/legato fit loopAt accelerate squiz cut); splice = slices with fit.",
+  "Fitting samples (0.6): fit_sample sets a voice's own bpm (or len in beats) so it follows the song's tempo map; fitmode beats for drums and speech (hits stay sharp), tones for pads and vocals (pitch kept), repitch (default) like tape.",
   "Effects (set_fx; set_effects and set_automation): the brief's effects list is the fixed chain order with each effect's simple params. set_fx turns an effect on with good defaults, loads a preset or sets params by dawg or Strudel name. Lanes: volume, pan, filter, resonance, delay-feedback, delay-mix, wt and <effect>-<param> (e.g. autofilter-cutoff).",
+  "Guitar rig (set_rig): rig loads a whole rig (clean crunch punk ragged lead metal fuzz octave funk wah bachata spring bassdrive reese jangle alt) on a guitar or bass track; stomp, head and cab tweak the pedal, amp (level-matched, gate in dB) and cabinet. Tracks named jangle punk funk ragged gtr-lead gtr-metal bachata start with a guitar voice and that rig. `amp` is Strudel gain; the guitar amp is head.",
+  "Shoegaze: rig shoegaze|glide|dreampop|swell|ebow (or a track named shoegaze); set_fx wobble (tremolo-arm bend: depth cents, rate, drift), bloom (feedback swell on the top note), swell (volume swell: time), double (second take: time, drift, width); reverb ir builtin:reverse|gate|spring. Strumming: set_guitar (tune dadgad, capo, hand, ring), strum_chords (chords or the track's own, strokes folk|pop|punk… or D-DU-UDU, speed ms), write_chords perform guitar.",
   "Previewing: preview_sound renders a track, or candidate sound tool calls (changes: [{tool, args}]), without committing, returns loudness, brightness and a comparison, and plays it once in the user's window. Use it when choosing between sounds (tables, presets, effect amounts), say how it sounds, then commit with the normal tools.",
   "Wavetable synth: set_wavetable picks a table (built-ins offline, Strudel wt_ sets fetched once) and scans it by position wt.",
+  `Granular: set_granular makes a track a grain cloud (presets cloud hold sparkle swarm stutter microloop backwards dust) of a synth source (src synth:pad, the default; synth:<name>@<note>) or one of its own sampler voices, and overrides params (${Object.keys(GRANULAR_PARAMS).join(" ")}; repeat and hold latch the head for beat repeats, begin and end pick a region, root takes a MIDI number or note name); off returns to the previous voice; the same seed gives the same grains. Grain play: sync "1/16" puts grain onsets on the tempo grid, quant scale|chord snaps grain pitches, mono true glides legato notes through one cloud, pedal true freezes the head while the sustain pedal is down; set_automation grain-<param> lanes (grain-pos, grain-scan, grain-pitch …) move a parameter over beats. Resample: the resample tool renders a track, orbit or the mix (a section or bars) to a pinned WAV and adds a sampler track, or with grain a granular track, that plays it; set_sample shift (semitones, length kept, formant 0 keeps a voice's character) and fadeInTime/fadeTime shape a sampler voice.`,
   "Mastering: set_master sets the song master and loudness target; measure_mix reports LUFS, true peak, balance and correlation. Master only when asked for loudness or a finished sound, and measure before and after.",
   'Reply with exactly one JSON object and nothing else, shaped {"ops":[{"tool":"<tool name>","args":{...}}],"say":"<one short sentence describing the musical change>","done":true}.',
   'Set "done":false only if you need to see the results of these ops before continuing; you will then get each op\'s result and can send more ops.',

package/src/audio/arrange.ts

@@ -13,6 +13,7 @@ import {
   ScoreValidationError,
   TrackScore,
   type Note,
+  withNoteCap,
 } from "../../core/score.ts";
 import {
   MAX_SONG_SECONDS,
@@ -20,6 +21,7 @@ import {
   arrangedBars,
   arrangedNotes,
   arrangedSlice,
+  BAKED_NOTE_CAP,
   bakeTrackTime,
   barBeats,
   barTicks,
@@ -49,6 +51,7 @@ import {
   type RenderedAudio,
   type WavCue,
 } from "./wav.ts";
+import { engineFor } from "./instruments.ts";
 
 /** What one default render pass holds before the renderer cuts it. */
 const DEFAULT_PASS_SECONDS = 30;
@@ -67,7 +70,7 @@ const WINDOW_BUDGET_SECONDS = 50;
 export function exportScore(score: TrackScore): TrackScore {
   // A form past the score's bar limit throws here; renderArranged renders
   // such forms window by window instead, so it never needs this.
-  return flattenForm(bakeTrackTime(score));
+  return withNoteCap(BAKED_NOTE_CAP, () => flattenForm(bakeTrackTime(score)));
 }
 
 /**
@@ -109,7 +112,9 @@ export function loopedSection(score: TrackScore) {
 export function playbackScore(score: TrackScore): TrackScore {
   const section = loopedSection(score);
   return section
-    ? sectionScore(bakeTrackTime(score), section)
+    ? withNoteCap(BAKED_NOTE_CAP, () =>
+        sectionScore(bakeTrackTime(score), section),
+      )
     : exportScore(score);
 }
 
@@ -177,11 +182,22 @@ export function renderArranged(
     fitsOnePass(renderer, score, options)
   )
     return renderer.render(score, options);
+  // Baked timed tracks (cycle, rate) may hold more notes than a stored score.
+  return withNoteCap(BAKED_NOTE_CAP, () =>
+    renderArrangedBaked(renderer, score, options),
+  );
+}
+
+function renderArrangedBaked(
+  renderer: StemRenderer,
+  score: TrackScore,
+  options: RenderOptions,
+): RenderedAudio {
   score = bakeTrackTime(score);
   const section = options.loop ? loopedSection(score) : undefined;
   if (!section && formSegments(score).length > 0)
     return renderForm(renderer, score, options);
-  const played = section
+  let played = section
     ? sectionScore(score, section)
     : applySectionChanges(score);
   if (played === score && fitsOnePass(renderer, score, options))
@@ -195,6 +211,9 @@ export function renderArranged(
     );
   if (seconds <= SINGLE_PASS_SECONDS)
     return renderer.render(played, { ...options, maxSeconds: 60 });
+  // Windows pick notes by start tick, so timed tracks (cycle, rate) must be
+  // placed into song ticks first, sections or not.
+  played = bakeTrackTime(played, { always: true });
   return renderWindows(
     renderer,
     played,
@@ -375,11 +394,31 @@ function renderWindows(
       notes,
       master: null,
     });
+    // State an engine cannot rebuild in the pre-roll (organ rotors along a
+    // lane) is integrated over the song before the window.
+    const seedState: Record<string, string> = {};
+    if (
+      pre > 0 &&
+      window.tracks.some((track) => engineFor(track)?.windowSeed)
+    ) {
+      const history = frame(0, pre);
+      for (const track of history.tracks) {
+        const seed = engineFor(track)?.windowSeed?.(
+          history,
+          track,
+          frameAt(pre),
+          sampleRate,
+        );
+        if (seed !== undefined) seedState[track.id] = seed;
+      }
+    }
     const audio = renderer.render(window, {
       ...options,
       sampleRate,
       loop: false,
       seedTick: preTick,
+      ...(pre > 0 ? { seedSeconds: secondsAtTick(timeline, pre * ticks) } : {}),
+      ...(Object.keys(seedState).length > 0 ? { seedState } : {}),
       // Past `end` too, so voices that fade where the buffer stops (the
       // legacy tone voice) fade in frames this window drops.
       maxSeconds: last

package/src/audio/dsp/bank.ts

@@ -0,0 +1,233 @@
+/**
+ * Shared grain bank (0.6 granular, shared DSP): a source band-limited at
+ * one level per semitone of upward read speed, so grains read at any step
+ * stay alias-free with a 4-point Hermite read.
+ *
+ * Level `L` holds the source low-passed so that reading it at a step of up
+ * to 2^(L/12) puts the stopband edge at or below the output Nyquist (a
+ * Kaiser-windowed sinc, about -70 dB stopband, transition scaled with the
+ * step so the output passband reaches about 0.43 of the output rate at
+ * every level). Level 0 is the source itself (steps <= 1 never alias).
+ * Every level keeps the source's frame rate, so a voice that changes its
+ * step (bend, vibrato, glide) re-picks the level per 32-frame control
+ * block without moving its read position.
+ *
+ * This replaces the prototype's octave mipmap (`proto/granular/dsp.ts`,
+ * `buildMipmap`) after the 0.6 review: octave levels over-filter
+ * non-octave intervals (a shimmer fifth lost up to 11 semitones of top
+ * band) and full-length Float64 levels had no memory bound. Here a level
+ * is a sparse map of Float32 chunks filled on first read, and all chunks of
+ * all sources share one byte budget (64 MB) evicted least recently used;
+ * an eviction only costs a recompute. Output is deterministic: a chunk's
+ * contents depend only on the source, the level and the chunk index.
+ */
+
+/** Frames per chunk (a power of two). */
+export const BANK_CHUNK_FRAMES = 4096;
+const CHUNK_SHIFT = 12;
+/** Chunks carry one frame before and two after for the Hermite read. */
+export const BANK_CHUNK_PAD = 3;
+/** Highest level (five octaves up); faster reads use it and may alias. */
+export const BANK_MAX_LEVEL = 60;
+/** Byte budget shared by every source's chunks. */
+export const BANK_MAX_BYTES = 64 * 1024 * 1024;
+
+const STOPBAND_DB = 70;
+const KAISER_BETA = 0.1102 * (STOPBAND_DB - 8.7);
+/** Taps at step 1 (scaled up with the step, capped). */
+const BASE_TAPS = 96;
+const MAX_TAPS = 511;
+
+/** A mono source registered with the bank. */
+export type BankSource = Readonly<{
+  /** Content id: a sample's sha256 or a built-in render key. */
+  id: string;
+  rate: number;
+  data: Float32Array;
+}>;
+
+type Chunk = Float32Array;
+
+/**
+ * Chunks per source (`id` and rate) keyed by level and index as one number.
+ * Grains look a chunk up every 32-frame block, so the lookup avoids string
+ * keys and the LRU order is a use counter (scanned only to evict).
+ */
+type Entry = { chunk: Chunk; used: number };
+const chunks = new Map<string, Map<number, Entry>>();
+const sourceTables = new WeakMap<BankSource, Map<number, Entry>>();
+let count = 0;
+let clock = 0;
+let bytes = 0;
+let byteCap = BANK_MAX_BYTES;
+const ZERO_CHUNK = new Float32Array(BANK_CHUNK_FRAMES + BANK_CHUNK_PAD);
+const kernels = new Map<number, Float64Array>();
+
+/** The level for a read step (frames of source per output frame). */
+export function bankLevel(step: number): number {
+  const r = step < 0 ? -step : step;
+  if (r <= 1 + 1e-9) return 0;
+  const level = Math.ceil(12 * Math.log2(r) - 1e-6);
+  return level > BANK_MAX_LEVEL ? BANK_MAX_LEVEL : level;
+}
+
+function besselI0(x: number): number {
+  let sum = 1;
+  let term = 1;
+  const q = (x * x) / 4;
+  for (let k = 1; k < 64; k += 1) {
+    term *= q / (k * k);
+    sum += term;
+    if (term < sum * 1e-17) break;
+  }
+  return sum;
+}
+
+/** The low-pass kernel of a level (odd length, unity DC gain). */
+export function bankKernel(level: number): Float64Array {
+  let h = kernels.get(level);
+  if (h) return h;
+  const r = 2 ** (level / 12);
+  let taps = Math.min(MAX_TAPS, Math.ceil(BASE_TAPS * r));
+  if (taps % 2 === 0) taps += 1;
+  // Kaiser transition width for the tap count, centred inside the band.
+  const transition = (STOPBAND_DB - 8) / (2.285 * 2 * Math.PI * (taps - 1));
+  const fc = Math.max(0.01, 0.5 / r - transition / 2);
+  h = new Float64Array(taps);
+  const mid = (taps - 1) / 2;
+  const norm = besselI0(KAISER_BETA);
+  let sum = 0;
+  for (let i = 0; i < taps; i += 1) {
+    const m = i - mid;
+    const sinc =
+      m === 0 ? 2 * fc : Math.sin(2 * Math.PI * fc * m) / (Math.PI * m);
+    const ratio = m / mid;
+    const w = besselI0(KAISER_BETA * Math.sqrt(1 - ratio * ratio)) / norm;
+    h[i] = sinc * w;
+    sum += h[i]!;
+  }
+  for (let i = 0; i < taps; i += 1) h[i] = h[i]! / sum;
+  kernels.set(level, h);
+  return h;
+}
+
+function fill(source: BankSource, level: number, index: number): Chunk {
+  const out = new Float32Array(BANK_CHUNK_FRAMES + BANK_CHUNK_PAD);
+  const data = source.data;
+  const n = data.length;
+  const first = index * BANK_CHUNK_FRAMES - 1;
+  if (level === 0) {
+    for (let i = 0; i < out.length; i += 1) {
+      const k = first + i;
+      out[i] = k >= 0 && k < n ? data[k]! : 0;
+    }
+    return out;
+  }
+  const h = bankKernel(level);
+  const taps = h.length;
+  const mid = (taps - 1) >> 1;
+  for (let i = 0; i < out.length; i += 1) {
+    const centre = first + i;
+    const lo = centre - mid;
+    let from = 0;
+    let to = taps;
+    if (lo < 0) from = -lo;
+    if (lo + to > n) to = n - lo;
+    let acc = 0;
+    for (let j = from; j < to; j += 1) acc += h[j]! * data[lo + j]!;
+    out[i] = acc;
+  }
+  return out;
+}
+
+/**
+ * The chunk holding frames `index * 4096 - 1 .. (index + 1) * 4096 + 2` of
+ * `level`; a frame `i` of the level is `chunk[(i & 4095) + 1]`. Chunks
+ * wholly outside the source are a shared zero chunk.
+ */
+export function bankChunk(
+  source: BankSource,
+  level: number,
+  index: number,
+): Chunk {
+  if (index < 0 || index * BANK_CHUNK_FRAMES > source.data.length + 2)
+    return ZERO_CHUNK;
+  let table = sourceTables.get(source);
+  if (!table) {
+    const id = `${source.id}\u0000${source.rate}`;
+    table = chunks.get(id);
+    if (!table) chunks.set(id, (table = new Map()));
+    sourceTables.set(source, table);
+  }
+  const key = level * 2 ** 32 + index;
+  clock += 1;
+  const hit = table.get(key);
+  if (hit) {
+    hit.used = clock;
+    return hit.chunk;
+  }
+  const chunk = fill(source, level, index);
+  table.set(key, { chunk, used: clock });
+  count += 1;
+  bytes += chunk.byteLength;
+  if (bytes > byteCap) evict();
+  return chunk;
+}
+
+/** Drops least recently used chunks until under the budget (keeps one). */
+function evict(): void {
+  const all: { table: Map<number, Entry>; key: number; used: number }[] = [];
+  for (const table of chunks.values())
+    for (const [key, entry] of table)
+      all.push({ table, key, used: entry.used });
+  all.sort((a, b) => a.used - b.used);
+  for (const { table, key } of all) {
+    if (bytes <= byteCap || count <= 1) break;
+    bytes -= table.get(key)!.chunk.byteLength;
+    table.delete(key);
+    count -= 1;
+  }
+}
+
+/** Chunk index of a level frame. */
+export function chunkIndex(frame: number): number {
+  return frame >> CHUNK_SHIFT;
+}
+
+/** Hermite read of `level` at a fractional frame (slow path, tests). */
+export function bankRead(
+  source: BankSource,
+  level: number,
+  pos: number,
+): number {
+  const i = Math.floor(pos);
+  const t = pos - i;
+  const chunk = bankChunk(source, level, i >> CHUNK_SHIFT);
+  const o = (i & (BANK_CHUNK_FRAMES - 1)) + 1;
+  const xm1 = chunk[o - 1]!;
+  const x0 = chunk[o]!;
+  const x1 = chunk[o + 1]!;
+  const x2 = chunk[o + 2]!;
+  const c1 = 0.5 * (x1 - xm1);
+  const c2 = xm1 - 2.5 * x0 + 2 * x1 - 0.5 * x2;
+  const c3 = 0.5 * (x2 - xm1) + 1.5 * (x0 - x1);
+  return ((c3 * t + c2) * t + c1) * t + x0;
+}
+
+/** Bytes held by chunks now. */
+export function bankBytes(): number {
+  return bytes;
+}
+
+/** Chunks held now. */
+export function bankChunks(): number {
+  return count;
+}
+
+/** Drops every chunk; with `cap`, sets a new byte budget (tests). */
+export function resetBank(cap: number = BANK_MAX_BYTES): void {
+  for (const table of chunks.values()) table.clear();
+  count = 0;
+  bytes = 0;
+  byteCap = Math.max(0, cap);
+}

package/src/audio/dsp/envelope.ts

@@ -0,0 +1,161 @@
+/**
+ * Cepstral spectral envelope (0.6 B2): the smooth outline of a magnitude
+ * spectrum, used by `shift.ts` to hold formants still while the pitch moves.
+ * Log magnitude, inverse transform to the real cepstrum, keep the
+ * quefrencies below the lifter, forward transform, exponentiate
+ * (Oppenheim and Schafer, *Discrete-Time Signal Processing*, ch. 13;
+ * J. O. Smith, *Spectral Audio Signal Processing*, "Cepstral Windowing";
+ * Röbel and Rodet, "Efficient spectral envelope estimation and its
+ * application to pitch shifting and envelope preservation", DAFx 2005, for
+ * the true-envelope iteration).
+ */
+import { fftInPlace } from "./fft.ts";
+import { inverse } from "./stft.ts";
+
+/**
+ * Default lifter: quefrencies below 2 ms (measured on a synthetic vowel:
+ * with 16 true-envelope passes F1 stays within 3% after +-7 and +-12 st at
+ * 110 Hz; 1 ms smeared F1 by up to 15%).
+ */
+export const ENVELOPE_LIFTER_SECONDS = 0.002;
+/** True-envelope passes used by `pitchShift` when keeping formants. */
+export const ENVELOPE_ITERATIONS = 16;
+
+/** Adaptive lifter as a fraction of the cepstral period. */
+export const PERIOD_FRACTION = 0.25;
+
+/** Scratch buffers for one frame size, reused across frames. */
+export type EnvelopeScratch = Readonly<{
+  re: Float64Array;
+  im: Float64Array;
+  log: Float64Array;
+}>;
+
+export function envelopeScratch(n: number): EnvelopeScratch {
+  return Object.freeze({
+    re: new Float64Array(n),
+    im: new Float64Array(n),
+    log: new Float64Array(n / 2 + 1),
+  });
+}
+
+/**
+ * Writes the cepstral envelope of `mag` (bins 0..n/2 of an n-point
+ * spectrum) into `out` (length n/2 + 1). `lifter` is in samples (at least
+ * 4). With `iterations` > 0 it is the true envelope (Röbel and Rodet 2005):
+ * the log spectrum is raised to the smoothed curve wherever it lies below
+ * it and smoothed again, so the envelope rides the harmonic peaks instead
+ * of the valleys between them. With `periodRange` (samples) the lifter
+ * shrinks to a quarter of the frame's cepstral pitch period when that is
+ * shorter, so higher voices keep their harmonics out of the envelope.
+ */
+export function cepstralEnvelope(
+  mag: Float64Array,
+  n: number,
+  lifter: number,
+  out: Float64Array,
+  scratch: EnvelopeScratch = envelopeScratch(n),
+  iterations = 0,
+  periodRange?: readonly [number, number],
+): Float64Array {
+  const half = n / 2;
+  const { re, im, log } = scratch;
+  let peak = 0;
+  for (let k = 0; k <= half; k += 1) peak = Math.max(peak, mag[k]!);
+  // Floor 120 dB under the frame's peak (silence stays finite).
+  const floor = peak * 1e-6 + 1e-12;
+  for (let k = 0; k <= half; k += 1) log[k] = Math.log(mag[k]! + floor);
+  let cut = Math.max(4, Math.min(half, Math.round(lifter)));
+  for (let pass = 0; pass <= iterations; pass += 1) {
+    for (let k = 0; k < n; k += 1) {
+      re[k] = log[k <= half ? k : n - k]!;
+      im[k] = 0;
+    }
+    inverse(re, im);
+    if (pass === 0 && periodRange) {
+      // Pitch-adaptive lifter: a quarter of the period found as the
+      // strongest cepstral peak in range, never longer than `lifter`.
+      const [lo, hi] = periodRange;
+      let q = Math.max(2, Math.round(lo));
+      for (let i = q; i <= Math.min(half, Math.round(hi)); i += 1)
+        if (re[i]! > re[q]!) q = i;
+      cut = Math.max(4, Math.min(cut, Math.round(q * PERIOD_FRACTION)));
+    }
+    for (let q = cut; q <= n - cut; q += 1) {
+      re[q] = 0;
+      im[q] = 0;
+    }
+    fftInPlace(re, im);
+    if (pass < iterations)
+      for (let k = 0; k <= half; k += 1) log[k] = Math.max(log[k]!, re[k]!);
+  }
+  for (let k = 0; k <= half; k += 1) out[k] = Math.exp(re[k]!);
+  return out;
+}
+
+/**
+ * Harmonic-peak envelope (0.6.1): log magnitude interpolated linearly
+ * between the spectral peaks (each refined by a parabola to its true bin
+ * and height) of `mag` that stand within `range` of the
+ * frame's loudest, held flat past the first and last. Between harmonics it
+ * follows the line joining them instead of the smoothed valley, so it stays
+ * on the formant at any pitch where the cepstral envelope (whose lifter
+ * must shrink with the period) starts to smear or ripple. `smooth` (an
+ * envelope from `cepstralEnvelope`) is used where no peak stands.
+ * Measured with `formant 0` on a synthetic vowel: F1 within 1.1% of the
+ * same vowel sung at the new pitch for f0 110-330 Hz at +-7 and +12 st
+ * (the cepstral envelope alone: -29% to +46% above 200 Hz).
+ */
+export function peakEnvelope(
+  mag: Float64Array,
+  half: number,
+  out: Float64Array,
+  smooth: Float64Array,
+  peaks: number[],
+  range = 1e-4,
+): Float64Array {
+  let top = 0;
+  for (let k = 0; k <= half; k += 1) top = Math.max(top, mag[k]!);
+  peaks.length = 0;
+  const floor = top * range;
+  for (let k = 2; k <= half - 2; k += 1) {
+    const v = mag[k]!;
+    if (
+      v > floor &&
+      v > mag[k - 1]! &&
+      v >= mag[k + 1]! &&
+      v > mag[k - 2]! &&
+      v >= mag[k + 2]!
+    )
+      peaks.push(k);
+  }
+  if (peaks.length < 2) {
+    out.set(smooth.subarray(0, half + 1));
+    return out;
+  }
+  // Each peak refined by a parabola on log magnitude: its true frequency
+  // (fractional bin) and height.
+  const at = (i: number) => {
+    const k = peaks[i]!;
+    const a = Math.log(mag[k - 1]! + 1e-30);
+    const b = Math.log(mag[k]! + 1e-30);
+    const c = Math.log(mag[k + 1]! + 1e-30);
+    const d = a - 2 * b + c;
+    const delta =
+      d < 0 ? Math.max(-0.5, Math.min(0.5, (0.5 * (a - c)) / d)) : 0;
+    return [k + delta, b - 0.25 * (a - c) * delta] as const;
+  };
+  let j = 0;
+  let [x0, y0] = at(0);
+  let [x1, y1] = at(1);
+  for (let k = 0; k <= half; k += 1) {
+    while (j + 2 < peaks.length && x1 <= k) {
+      j += 1;
+      [x0, y0] = [x1, y1];
+      [x1, y1] = at(j + 1);
+    }
+    const t = Math.max(0, Math.min(1, (k - x0) / (x1 - x0)));
+    out[k] = Math.exp(y0 + (y1 - y0) * t);
+  }
+  return out;
+}

package/src/audio/dsp/fft.ts

@@ -0,0 +1,6 @@
+/**
+ * The shared radix-2 FFT: a re-export of the convolution reverb's
+ * `fftInPlace` (cached tables; `inverse` uses e^{+i} and no scaling).
+ * Lanes that need windows or STFTs build them on this one transform.
+ */
+export { fftInPlace } from "../effects/convolution.ts";

package/src/audio/dsp/filters.ts

@@ -0,0 +1,57 @@
+/**
+ * Small per-sample filters for 0.6 instruments. `Biquad` is the existing
+ * RBJ biquad (src/audio/effects/common.ts), re-exported unchanged.
+ */
+export { Biquad, type FilterType } from "../effects/common.ts";
+
+function clamp(x: number, lo: number, hi: number): number {
+  return x < lo ? lo : x > hi ? hi : x;
+}
+
+/** One-pole lowpass y += (1 - p)(x - y), corner `hz`. */
+export class OnePole {
+  p = 0;
+  y = 0;
+
+  constructor(hz: number, sampleRate: number) {
+    this.set(hz, sampleRate);
+  }
+
+  set(hz: number, sampleRate: number): void {
+    this.p = Math.exp(
+      (-2 * Math.PI * clamp(hz, 1, sampleRate * 0.49)) / sampleRate,
+    );
+  }
+
+  process(x: number): number {
+    this.y = x + this.p * (this.y - x);
+    return this.y;
+  }
+
+  reset(): void {
+    this.y = 0;
+  }
+}
+
+/** DC blocker y = x - x1 + R y1 (R ≈ 0.996 at 22.05 kHz for a 15 Hz corner). */
+export class DcBlock {
+  r: number;
+  x1 = 0;
+  y1 = 0;
+
+  constructor(sampleRate: number, hz = 15) {
+    this.r = Math.exp((-2 * Math.PI * hz) / sampleRate);
+  }
+
+  process(x: number): number {
+    const y = x - this.x1 + this.r * this.y1;
+    this.x1 = x;
+    this.y1 = y;
+    return y;
+  }
+
+  reset(): void {
+    this.x1 = 0;
+    this.y1 = 0;
+  }
+}