@hraness/dawg 0.6.0 → 0.7.0

package/src/agent/xcb-agent.ts

@@ -44,22 +44,31 @@ export type TextAgentTurnOptions = Readonly<{
 export const TEXT_AGENT_SYSTEM_PROMPT = [
   "You are dawg, a loop composer inside a terminal music workstation.",
   "You edit the score by returning operations. Each op is validated and applied immediately, in order, as its own revision.",
-  "Times are in beats from the loop start (0-based). Keep notes inside loopBeats unless you extend the loop first.",
+  'Times are in beats from the loop start (0-based), while musicians count from 1: in 4/4 "beats 2 and 4" are beats 1 and 3 of each bar here, "the and of 1" is 0.5, and bar n starts at (n-1)×beats per bar. Keep notes inside loopBeats unless you extend the loop first.',
   "Prefer a few well-formed ops (one add_notes op per track part) over many tiny ones.",
-  'For drums, create a track with instrument "kit" and prefer set_rhythm (Euclidean rows: pulses over steps, rotate, repeats for rolls, accent, probability, swing) so the beat stays editable as parameters; for a genre groove start from apply_drum_pattern (list_drum_patterns) and pick a sound with set_drum_kit; use add_drums only for one-off fills. Drum pitches select voices, so do not use add_notes for beats.',
+  'For drums, create a track with instrument "kit" and prefer set_rhythm (Euclidean rows: pulses over steps, rotate, repeats for rolls, accent, probability, swing) so the beat stays editable as parameters; for a style groove start from apply_drum_pattern (list_drum_patterns) and pick a sound with set_drum_kit. Drum pitches select voices, so do not use add_notes for beats.',
   "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.",
-  "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). A track already stored as instrument piano keeps the legacy tone until you set it again.",
+  "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 modeled 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 modeled 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 modeled piano.",
+  'Organs: set_instrument tonewheel (hammond b3 gospel jazzorgan), combo (farfisa vox) or pipe (church flutes cornet reeds celeste) loads a modeled 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.",
+  "Voices (0.7): set_instrument aah ooh choir chorale (or set_sing preset oohchoir airy glass lament soprano basso drone) plays the built-in singing voice, a synthetic glottal source through formants (never a cloned voice); set_sing params voice (auto soprano alto tenor bass), vowel (a e i o u or a>o), voices 2..8 (an ensemble), breath, vib, jitter, bright; set_vowels puts vowels on notes. Throat singing: khoomei, sygyt (whistle) and kargyraa (sub growl) hold a drone (set_sing params drone D2) and each note picks a harmonic of it.",
+  "Vocoder: a vocoder is a carrier track whose vocoder.src is the modulator (usually the user's vocal). make one with create_track (instrument vocoder), then set_vocoder with src set to the vocal, and mute the vocal; talkbox suits funk and soul, choir and glass suit hyperpop, robot and smear suit electronic or ambient. Vocode only the user's own or licensed audio, never an identifiable third party's speech unless the user confirms they hold the rights.",
   "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).",
+  "Effects (set_fx 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.",
+  "Formant (0.7): set_formant shift -12..12 st moves a track's formants at constant pitch (negative deeper or bigger, positive smaller; 2-4 natural), mix 0..1, preset deep giant bright tiny, off; lanes formant-shift formant-mix. The vowel filter is set_fx vowel, whose to and morph 0..1 glide between two vowels (lane vowel-morph).",
   "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.`,
+  `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.',
@@ -74,6 +83,7 @@ export function renderToolCatalog(
   tools: readonly AgentTool[] = AGENT_TOOLS,
 ): string {
   return tools
+    .filter((tool) => !tool.hidden)
     .map(
       (tool) =>
         `- ${tool.name}: ${tool.description}\n  args schema: ${JSON.stringify(tool.parameters)}`,

package/src/argv.ts

@@ -0,0 +1,38 @@
+/** The small argv contract plain subcommands share (no dependencies). */
+
+export type SimpleArgv =
+  | { kind: "help" }
+  | { kind: "run"; positionals: readonly string[] }
+  | { kind: "error"; problem: string };
+
+/**
+ * The contract `dawg init`, `dawg check` and `dawg sessions` share: argv
+ * after the subcommand. `--help`/`-h` anywhere asks for usage; any other
+ * option, or more than `maxPositionals` words, is an error (exit 2) before
+ * the command does anything.
+ */
+export function parseSimpleArgv(
+  rest: readonly string[],
+  maxPositionals: number,
+): SimpleArgv {
+  if (rest.some((arg) => arg === "--help" || arg === "-h"))
+    return { kind: "help" };
+  const positionals: string[] = [];
+  for (const arg of rest) {
+    if (arg === "--")
+      return { kind: "error", problem: "unexpected argument · --" };
+    if (arg.startsWith("-") && arg.length > 1)
+      return { kind: "error", problem: `unknown option · ${clip(arg)}` };
+    positionals.push(arg);
+  }
+  if (positionals.length > maxPositionals)
+    return {
+      kind: "error",
+      problem: `unexpected argument · ${clip(positionals[maxPositionals]!)}`,
+    };
+  return { kind: "run", positionals };
+}
+
+function clip(value: string): string {
+  return value.length > 40 ? `${value.slice(0, 40)}…` : value;
+}

package/src/audio/analysis.ts

@@ -0,0 +1,253 @@
+/**
+ * The pitch-analysis cache (0.7). `pitchCurve` tracks a decoded sample once
+ * and keeps the canonical curve in a small in-memory LRU and on disk at
+ * `.dawg/analysis/<sha256>.<voice>.v<tracker version>.f0` (format DWF0).
+ *
+ * DWF0 holds exactly the canonical curve `trackPitch` returns (f0 Float32,
+ * prob and aperiodic u8), so a cache hit renders the same bytes as a cache
+ * miss. Layout, little endian:
+ *
+ *   0  "DWF0"          magic
+ *   4  u16 DWF0 version, u16 tracker version
+ *   8  u32 frames
+ *  12  f64 hop seconds, 20 f64 t0 seconds
+ *  28  f32[frames] f0 Hz (0 unvoiced)
+ *   …  u8[frames] prob, u8[frames] aperiodic (1/255 steps)
+ *   …  8 bytes: the sha256 prefix of every byte before it
+ *
+ * About 1.2 KB per audio second. Writes go to `<name>.<pid>.tmp` and are
+ * renamed into place; write errors are swallowed (the cache is an
+ * optimisation). Reads validate magic, versions, length and checksum, and
+ * any mismatch is a miss. Analysis stays inside the project.
+ */
+import { createHash } from "node:crypto";
+import { mkdir, readFile, rename, utimes, writeFile } from "node:fs/promises";
+import { join } from "node:path";
+import {
+  cacheUsage,
+  pruneLru,
+  type CacheUsage,
+  type PruneResult,
+} from "./cache.ts";
+import {
+  PITCH_TRACKER_VERSION,
+  trackPitchAsync,
+  type PitchCurve,
+  type PitchVoice,
+} from "./dsp/pitch.ts";
+
+export const DWF0_VERSION = 1;
+const HEAD = 28;
+const CHECK = 8;
+const MAGIC = [0x44, 0x57, 0x46, 0x30] as const;
+
+/** Disk budget for `.dawg/analysis` (curves are small; 64 MB is ~15 h). */
+export const ANALYSIS_CACHE_BYTES = 64 * 1024 * 1024;
+/** In-memory curves kept (least recently used go first). */
+export const ANALYSIS_MEMORY_ENTRIES = 64;
+
+/** Every file the analysis cache writes. */
+export const ANALYSIS_FILE = /^[0-9a-f]{64}\.\w+\.v\d+\.f0$/;
+
+function checksum(bytes: Uint8Array, length: number): Uint8Array {
+  return createHash("sha256").update(bytes.subarray(0, length)).digest();
+}
+
+/** The DWF0 bytes of a curve. */
+export function encodeCurve(curve: PitchCurve): Uint8Array {
+  const n = curve.f0.length;
+  const size = HEAD + 6 * n + CHECK;
+  const bytes = new Uint8Array(size);
+  const view = new DataView(bytes.buffer);
+  bytes.set(MAGIC);
+  view.setUint16(4, DWF0_VERSION, true);
+  view.setUint16(6, PITCH_TRACKER_VERSION, true);
+  view.setUint32(8, n, true);
+  view.setFloat64(12, curve.hop, true);
+  view.setFloat64(20, curve.t0, true);
+  for (let f = 0; f < n; f += 1)
+    view.setFloat32(HEAD + 4 * f, curve.f0[f]!, true);
+  bytes.set(curve.prob, HEAD + 4 * n);
+  bytes.set(curve.aperiodic, HEAD + 5 * n);
+  bytes.set(checksum(bytes, size - CHECK).subarray(0, CHECK), size - CHECK);
+  return bytes;
+}
+
+/** The curve in DWF0 `bytes`, or undefined for anything not exactly valid. */
+export function decodeCurve(bytes: Uint8Array): PitchCurve | undefined {
+  if (bytes.length < HEAD + CHECK) return undefined;
+  for (let i = 0; i < 4; i += 1) if (bytes[i] !== MAGIC[i]) return undefined;
+  const view = new DataView(bytes.buffer, bytes.byteOffset, bytes.byteLength);
+  if (view.getUint16(4, true) !== DWF0_VERSION) return undefined;
+  if (view.getUint16(6, true) !== PITCH_TRACKER_VERSION) return undefined;
+  const n = view.getUint32(8, true);
+  if (bytes.length !== HEAD + 6 * n + CHECK) return undefined;
+  const sum = checksum(bytes, bytes.length - CHECK);
+  for (let i = 0; i < CHECK; i += 1)
+    if (bytes[bytes.length - CHECK + i] !== sum[i]) return undefined;
+  const hop = view.getFloat64(12, true);
+  const t0 = view.getFloat64(20, true);
+  if (!(hop > 0) || !Number.isFinite(t0)) return undefined;
+  const f0 = new Float32Array(n);
+  for (let f = 0; f < n; f += 1) f0[f] = view.getFloat32(HEAD + 4 * f, true);
+  return {
+    t0,
+    hop,
+    f0,
+    prob: bytes.slice(HEAD + 4 * n, HEAD + 5 * n),
+    aperiodic: bytes.slice(HEAD + 5 * n, HEAD + 6 * n),
+  };
+}
+
+/** The cache file name of a sample's curve. */
+export function analysisFileName(sha256: string, voice: PitchVoice): string {
+  return `${sha256}.${voice}.v${PITCH_TRACKER_VERSION}.f0`;
+}
+
+/** `<projectRoot>/.dawg/analysis`. */
+export function analysisDir(projectRoot: string): string {
+  return join(projectRoot, ".dawg", "analysis");
+}
+
+/** What `pitchCurve` tracks: a decoded sample (mono mixdown) and its hash. */
+export type AnalysisSource = Readonly<{
+  sha256: string;
+  sampleRate: number;
+  mono: ArrayLike<number>;
+}>;
+
+export type PitchCurveOptions = Readonly<{
+  voice?: PitchVoice;
+  /** Project root; without one only the memory cache is used. */
+  projectRoot?: string;
+  /** Overrides `<projectRoot>/.dawg/analysis`. */
+  dir?: string;
+  /** Disk budget (default ANALYSIS_CACHE_BYTES). */
+  maxBytes?: number;
+  /** Fraction of frames tracked so far, on a cache miss. */
+  progress?: (done: number) => void;
+}>;
+
+const memory = new Map<string, PitchCurve>();
+const counters = { tracks: 0, diskHits: 0, memoryHits: 0 };
+
+/** Tracking and cache-hit counts, for tests and the doctor. */
+export function analysisCounters(): Readonly<typeof counters> {
+  return { ...counters };
+}
+
+/** Drops the in-memory curves (tests; the disk cache stays). */
+export function clearAnalysisMemory(): void {
+  memory.clear();
+}
+
+function remember(key: string, curve: PitchCurve): void {
+  memory.delete(key);
+  memory.set(key, curve);
+  while (memory.size > ANALYSIS_MEMORY_ENTRIES)
+    memory.delete(memory.keys().next().value!);
+}
+
+/** The memory-cached curve of a sample, without tracking. */
+export function cachedPitchCurve(
+  sha256: string,
+  voice: PitchVoice = "auto",
+): PitchCurve | undefined {
+  const key = analysisFileName(sha256, voice);
+  const hit = memory.get(key);
+  if (hit) remember(key, hit);
+  return hit;
+}
+
+/**
+ * The pitch curve of a decoded sample: memory, then disk, then tracked and
+ * written back. Every path returns identical curves.
+ */
+export async function pitchCurve(
+  source: AnalysisSource,
+  options: PitchCurveOptions = {},
+): Promise<PitchCurve> {
+  const voice = options.voice ?? "auto";
+  const name = analysisFileName(source.sha256, voice);
+  const hit = memory.get(name);
+  if (hit) {
+    counters.memoryHits += 1;
+    remember(name, hit);
+    return hit;
+  }
+  const dir =
+    options.dir ??
+    (options.projectRoot ? analysisDir(options.projectRoot) : undefined);
+  if (dir) {
+    const path = join(dir, name);
+    const bytes = await readFile(path).catch(() => undefined);
+    const curve = bytes ? decodeCurve(new Uint8Array(bytes)) : undefined;
+    if (curve) {
+      counters.diskHits += 1;
+      const now = new Date();
+      await utimes(path, now, now).catch(() => undefined);
+      remember(name, curve);
+      return curve;
+    }
+  }
+  counters.tracks += 1;
+  const curve = await trackPitchAsync(
+    Float64Array.from(source.mono),
+    source.sampleRate,
+    { voice },
+    options.progress,
+  );
+  remember(name, curve);
+  if (dir) await writeCurve(dir, name, curve, options.maxBytes, source.sha256);
+  return curve;
+}
+
+async function writeCurve(
+  dir: string,
+  name: string,
+  curve: PitchCurve,
+  maxBytes = ANALYSIS_CACHE_BYTES,
+  keep: string,
+): Promise<void> {
+  try {
+    await mkdir(dir, { recursive: true });
+    const path = join(dir, name);
+    const temporary = `${path}.${process.pid}.tmp`;
+    await writeFile(temporary, encodeCurve(curve));
+    await rename(temporary, path);
+    await pruneAnalysisCache(dir, maxBytes, new Set([keep]));
+  } catch {
+    /* the cache is an optimisation; a read-only project still renders */
+  }
+}
+
+/**
+ * Deletes least recently used curves until `dir` fits `maxBytes`, never
+ * the ones whose sha256 is in `keep` (the open project's samples).
+ */
+export async function pruneAnalysisCache(
+  dir: string,
+  maxBytes = ANALYSIS_CACHE_BYTES,
+  keep: ReadonlySet<string> = new Set(),
+): Promise<PruneResult> {
+  return pruneLru(dir, ANALYSIS_FILE, maxBytes, (name) =>
+    keep.has(name.slice(0, 64)),
+  );
+}
+
+/** Files and bytes in the project's analysis cache, for `/pack cache`. */
+export async function analysisCacheStatus(
+  projectRoot: string,
+): Promise<CacheUsage & { max: number }> {
+  return {
+    ...(await cacheUsage(analysisDir(projectRoot), ANALYSIS_FILE)),
+    max: ANALYSIS_CACHE_BYTES,
+  };
+}
+
+/** The `dawg media doctor` line for the project's analysis cache. */
+export async function analysisDoctorLine(projectRoot: string): Promise<string> {
+  const s = await analysisCacheStatus(projectRoot);
+  const mb = (bytes: number): string => (bytes / (1024 * 1024)).toFixed(1);
+  return `· analysis cache .dawg/analysis · ${s.files} file${s.files === 1 ? "" : "s"} · ${mb(s.bytes)} MB of ${mb(s.max)} MB (least recently used pruned) · pitch tracker v${PITCH_TRACKER_VERSION}`;
+}

package/src/audio/arrange.ts

@@ -8,6 +8,8 @@
  * that carries held notes and tails across the seam, so memory stays
  * bounded however long the form plays (up to MAX_SONG_SECONDS).
  */
+import { withClipLengths } from "./clips.ts";
+import { vocoderPrerollSeconds } from "../../core/vocoder.ts";
 import {
   SCORE_LIMITS,
   ScoreValidationError,
@@ -51,6 +53,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;
@@ -174,6 +177,8 @@ export function renderArranged(
   score: TrackScore,
   options: RenderOptions = {},
 ): RenderedAudio {
+  // Clips cut at sections, forms and windows need their files' real ends.
+  score = withClipLengths(score, options.samples);
   if (
     !(options.loop && loopedSection(score)) &&
     formSegments(score).length === 0 &&
@@ -330,8 +335,13 @@ function renderWindows(
   const slowBar = ((beatsPerBar * 60) / Math.min(...bpms)) * fermataStretch;
   const frameAt = (bar: number) =>
     Math.round(secondsAtTick(timeline, bar * ticks) * sampleRate);
-  const ring = Math.max(1, Math.ceil(OVERHANG_SECONDS / fastBar));
-  const ringTicks = Math.ceil((OVERHANG_SECONDS / fastBar) * ticks);
+  // A vocoder's envelopes need 5 releases (+0.1 s) to settle (0.7).
+  const overhang = Math.max(
+    OVERHANG_SECONDS,
+    ...score.tracks.map((track) => vocoderPrerollSeconds(track.vocoder)),
+  );
+  const ring = Math.max(1, Math.ceil(overhang / fastBar));
+  const ringTicks = Math.ceil((overhang / fastBar) * ticks);
   const budget = Math.max(1, Math.floor(WINDOW_BUDGET_SECONDS / slowBar));
   const reach = budget - 1;
   const most = Math.max(1, Math.floor(WINDOW_SECONDS / slowBar));
@@ -346,6 +356,10 @@ function renderWindows(
     /** Frames at the end that fade out under the next window. */
     fadeOut: number;
   }[] = [];
+  const nonFinite: { samples: number; tracks: string[] } = {
+    samples: 0,
+    tracks: [],
+  };
   for (let start = 0; start < totalBars;) {
     const startTick = start * ticks;
     // Every note up to the next window, in render order: tracks sum in the
@@ -393,11 +407,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
@@ -408,6 +442,11 @@ function renderWindows(
               secondsAtTick(timeline, pre * ticks),
           ),
     });
+    if (audio.nonFinite) {
+      nonFinite.samples += audio.nonFinite.samples;
+      for (const id of audio.nonFinite.tracks)
+        if (!nonFinite.tracks.includes(id)) nonFinite.tracks.push(id);
+    }
     // A restarted note's phase differs from the previous window's, so the
     // seam crossfades over the previous window's last frames instead of
     // stepping; seams without a restart join sample for sample.
@@ -477,6 +516,15 @@ function renderWindows(
     master,
     options.loop === true,
   );
+  const report =
+    nonFinite.samples > 0
+      ? {
+          nonFinite: {
+            samples: nonFinite.samples,
+            tracks: [...nonFinite.tracks],
+          },
+        }
+      : {};
   if (mastered)
     return {
       sampleRate,
@@ -484,6 +532,13 @@ function renderWindows(
       frames: length,
       pcm: mastered.pcm,
       master: mastered.report,
+      ...report,
     };
-  return { sampleRate, channels: RENDER_CHANNELS, frames: length, pcm };
+  return {
+    sampleRate,
+    channels: RENDER_CHANNELS,
+    frames: length,
+    pcm,
+    ...report,
+  };
 }

package/src/audio/autotune-engine.ts

@@ -0,0 +1,101 @@
+/**
+ * The built-in pitch engine for autotune (0.7): the pitch lane's tracker
+ * (src/audio/dsp/pitch.ts) and PSOLA (src/audio/dsp/psola.ts) behind the
+ * `PitchEngine` seam of src/audio/autotune.ts. Curves are memoised per
+ * audio (`id ?? sha256`, else the buffer itself) and voice range; a file
+ * whose curve the analysis cache already holds is not tracked again. With
+ * `defer` (live play) a missing curve is tracked in the background and the
+ * buffer plays untuned until it is ready. Deterministic: the same audio
+ * always gives the same curve and the same tuned bytes.
+ */
+import { cachedPitchCurve } from "./analysis.ts";
+import {
+  PITCH_TRACKER_VERSION,
+  trackPitch,
+  trackPitchAsync,
+  type PitchCurve,
+} from "./dsp/pitch.ts";
+import { psola } from "./dsp/psola.ts";
+import type { PitchEngine, TunableBuffer } from "./autotune.ts";
+
+/** Curves kept in memory by key; older ones are tracked again on demand. */
+const CURVE_ENTRIES = 64;
+
+const curves = new Map<string, PitchCurve>();
+const anonymous = new WeakMap<Float32Array, Map<string, PitchCurve>>();
+const pending = new Set<string>();
+
+function keyOf(buffer: TunableBuffer): string | undefined {
+  return buffer.id ?? buffer.sha256;
+}
+
+function lookup(buffer: TunableBuffer, voice: string): PitchCurve | undefined {
+  const key = keyOf(buffer);
+  if (key === undefined) return anonymous.get(buffer.mono)?.get(voice);
+  const name = `${key}|${voice}`;
+  const hit = curves.get(name);
+  if (hit) {
+    curves.delete(name);
+    curves.set(name, hit);
+    return hit;
+  }
+  // The decoded file itself: the pitch lane's analysis cache may know it.
+  if (buffer.id === undefined && buffer.sha256 !== undefined) {
+    const cached = cachedPitchCurve(
+      buffer.sha256,
+      voice as Parameters<typeof cachedPitchCurve>[1],
+    );
+    if (cached) store(buffer, voice, cached);
+    return cached;
+  }
+  return undefined;
+}
+
+function store(buffer: TunableBuffer, voice: string, curve: PitchCurve): void {
+  const key = keyOf(buffer);
+  if (key === undefined) {
+    const byVoice = anonymous.get(buffer.mono) ?? new Map<string, PitchCurve>();
+    byVoice.set(voice, curve);
+    anonymous.set(buffer.mono, byVoice);
+    return;
+  }
+  const name = `${key}|${voice}`;
+  curves.delete(name);
+  curves.set(name, curve);
+  while (curves.size > CURVE_ENTRIES)
+    curves.delete(curves.keys().next().value!);
+}
+
+/** Drops the memoised curves (tests). */
+export function clearEngineCurves(): void {
+  curves.clear();
+  pending.clear();
+}
+
+/** The pitch lane's tracker and PSOLA as an autotune engine. */
+export const builtinPitchEngine: PitchEngine = Object.freeze({
+  version: `yin${PITCH_TRACKER_VERSION}-psola1`,
+  curve(buffer, voice, options) {
+    const hit = lookup(buffer, voice);
+    if (hit) return hit;
+    const x = Float64Array.from(buffer.mono);
+    if (!options?.defer) {
+      const curve = trackPitch(x, buffer.sampleRate, { voice });
+      store(buffer, voice, curve);
+      return curve;
+    }
+    const name = `${keyOf(buffer) ?? "anon"}|${voice}`;
+    if (!pending.has(name)) {
+      pending.add(name);
+      void trackPitchAsync(x, buffer.sampleRate, { voice }).then(
+        (curve) => {
+          pending.delete(name);
+          store(buffer, voice, curve);
+        },
+        () => pending.delete(name),
+      );
+    }
+    return undefined;
+  },
+  psola: (x, sampleRate, curve) => psola(x, sampleRate, curve),
+});