@hraness/dawg 0.6.0 → 0.6.1

package/src/agent/tools.ts

@@ -14,6 +14,15 @@ import {
   type TrackModal,
 } from "../../core/resonators.ts";
 import { applyModalCommand, type ModalCommand } from "../commands/modal.ts";
+import { applyWindCommand, type WindCommand } from "../commands/wind.ts";
+import {
+  type TrackWind,
+  WIND_ALIASES,
+  WIND_PARAMS,
+  WIND_PRESET_NAMES,
+  windParamName,
+  windPresetFor,
+} from "../../core/winds.ts";
 import {
   AUTOMATION_PARAMETERS,
   automationPoints,
@@ -46,9 +55,11 @@ import {
 } from "../commands/keys.ts";
 import {
   KEYS_PRESETS,
+  ORGAN_ALIASES,
   KEYS_SIMPLE,
   isKeysPreset,
   keysParamName,
+  pianoWrite,
 } from "../../core/keys.ts";
 import {
   setSampleControls,
@@ -96,6 +107,7 @@ import { DRUM_TOOLS } from "./drum-tools.ts";
 import { TIME_TOOLS } from "./time-tools.ts";
 import { SECTION_TOOLS } from "./section-tools.ts";
 import { GRANULAR_TOOLS } from "./granular-tools.ts";
+import { RESAMPLE_TOOLS } from "./resample-tool.ts";
 import type { MediaResult, MediaRunContext } from "../media/types.ts";
 import { instrumentPatch, pitchToMidi } from "./ops.ts";
 import { TUNING_LIMITS } from "../../core/tuning.ts";
@@ -474,7 +486,7 @@ export const AGENT_TOOLS: readonly AgentTool[] = Object.freeze([
   {
     name: "set_instrument",
     description:
-      "Change a track's instrument voice. Mallets and bells (modal): modal (marimba) vibes xylophone glock celesta chimes kalimba mbira steelpan bowl gong timpani; set_modal shapes them.",
+      "Change a track's instrument voice. Mallets and bells (modal): modal (marimba) vibes xylophone glock celesta chimes kalimba mbira steelpan bowl gong timpani, gamelan saron gangsa bonang …; set_modal shapes them. Electric keys: epiano suitcase dyno wurli clav funkclav (set_keys). Winds and brass (wind engine): flute recorder clarinet oboe bassoon sax trumpet trombone tuba horn …; set_wind shapes them.",
     parameters: {
       type: "object",
       properties: {
@@ -490,7 +502,8 @@ export const AGENT_TOOLS: readonly AgentTool[] = Object.freeze([
       const track = context.score.tracks.find((t) => t.id === trackId);
       if (track && typeof args.instrument === "string") {
         const word = args.instrument.toLowerCase();
-        const preset = word === "piano" ? "grand" : word;
+        // `rhodes`, `wurlitzer`, `clavinet` name their electric presets.
+        const preset = pianoWrite(word)?.preset ?? word;
         if (isKeysPreset(preset)) {
           const patch = keysPresetPatch(track, preset);
           return {
@@ -513,7 +526,7 @@ export const AGENT_TOOLS: readonly AgentTool[] = Object.freeze([
         summary:
           patch.instrument === "marimba" && !patch.modal
             ? `${trackId} → marimba (legacy tone) · set_modal preset marimba for the mallet engine`
-            : `${trackId} → ${patch.string?.preset ?? patch.modal?.preset ?? patch.instrument}`,
+            : `${trackId} → ${patch.string?.preset ?? patch.modal?.preset ?? patch.wind?.preset ?? patch.instrument}`,
       };
     },
   },
@@ -587,7 +600,7 @@ export const AGENT_TOOLS: readonly AgentTool[] = Object.freeze([
         parameter: {
           type: "string",
           description:
-            "volume, pan, filter, resonance, delay-feedback, delay-mix, or <effect>-<param>",
+            "volume, pan, filter, resonance, delay-feedback, delay-mix, <effect>-<param>, or grain-<param> on a granular track",
         },
         mode: { type: "string", enum: ["replace", "merge"] },
         points: {
@@ -713,7 +726,7 @@ export const AGENT_TOOLS: readonly AgentTool[] = Object.freeze([
   {
     name: "set_rig",
     description:
-      "Guitar rig on a track (stomp → amp head with noise gate → speaker cab, before tremolo). rig loads a whole rig (clean crunch punk ragged lead metal fuzz octave funk wah bachata spring bassdrive reese jangle alt) or reset removes it; stomp/head/cab set stage params (stomp type fuzz|face|od|rat|octave gain tone level; head type clean|chime|crunch|lead|high|solid|bass gain bass mid treble presence master sag gate(dB); cab type 1x12|2x12|4x12|1x10|open|8x10|1x15|di mic), or null removes a stage. Heads are level-matched. `amp` is Strudel gain, not this.",
+      "Guitar rig on a track (stomp → amp head with noise gate → speaker cab, before tremolo). rig loads a whole rig (clean crunch punk ragged lead metal fuzz octave funk wah bachata spring bassdrive reese jangle alt, and the shoegaze rigs shoegaze glide dreampop swell ebow that add wobble/bloom/swell/double and a long reverb) or reset removes it; stomp/head/cab set stage params (stomp type fuzz|face|od|rat|octave gain tone level; head type clean|chime|crunch|lead|high|solid|bass gain bass mid treble presence master sag gate(dB); cab type 1x12|2x12|4x12|1x10|open|8x10|1x15|di mic), or null removes a stage. Heads are level-matched. `amp` is Strudel gain, not this.",
     parameters: {
       type: "object",
       properties: {
@@ -844,7 +857,7 @@ export const AGENT_TOOLS: readonly AgentTool[] = Object.freeze([
   {
     name: "set_string",
     description:
-      "Make a track a plucked string (physical model): preset picks the instrument; params override it (ring s, bright, damp, pos, mute, buzz = jawari, body, sym = sympathetic strings, stiff, exciter pick|finger|hammer|noise); null unsets one. reset keeps the preset and drops overrides; off returns the track to a plain pluck voice.",
+      "Make a track a plucked, struck or bowed string (physical model). Bowed presets (exciter bow): violin viola cello contrabass fiddle erhu kamancheh, sections violins violas cellos contrabasses, pizz trem. preset picks the instrument; params override it (ring s, bright, damp, pos, mute, buzz = jawari, body, sym = sympathetic strings, stiff, exciter pick|finger|hammer|noise|bow); null unsets one. Bowed presets take pressure speed attack vib vibmod vibdelay tremhz sord dyn. reset keeps the preset and drops overrides; off returns the track to a plain pluck voice.",
     parameters: {
       type: "object",
       properties: {
@@ -886,17 +899,25 @@ export const AGENT_TOOLS: readonly AgentTool[] = Object.freeze([
   },
   {
     name: "set_keys",
-    description: `Shape a modelled piano: preset (instrument, keys and its effects), params ${KEYS_SIMPLE.join(" ")}… (null unsets; DAWG.md lists all), or reset. Stored "piano" stays legacy; set_instrument piano writes grand.`,
+    description: `Shape a modelled piano, electric keys (epiano wurli clav) or organ: preset (instrument, keys and its effects), params ${KEYS_SIMPLE.join(" ")}… (pianos: sym 0.5 adds sympathetic bloom under the sustain pedal, good for Chopin and Debussy; epiano: bark bell tone vibe; wurli: trem; clav: pickup mute; null unsets; DAWG.md lists all), or reset. Stored "piano" stays legacy; set_instrument piano writes grand. Organs (not "organ", a legacy synth): presets tonewheel combo pipe… (aliases hammond b3 farfisa church); drawbars "888800008", registers "08880", stops (plenum, flute8…), rotary; params perc percdecay percvol click scanner drive (tonewheel), voice vib vibmod drive (combo), chiff wind trem (pipe). A row the family does not read is refused.`,
     parameters: {
       type: "object",
       properties: {
         trackId: trackIdSchema,
-        preset: { type: "string", enum: Object.keys(KEYS_PRESETS) },
+        preset: {
+          type: "string",
+          enum: [...Object.keys(KEYS_PRESETS), ...Object.keys(ORGAN_ALIASES)],
+        },
         reset: { type: "boolean" },
         params: {
           type: "object",
           additionalProperties: { type: ["number", "string", "null"] },
         },
+        // f061-organ
+        drawbars: { type: "string", pattern: "^[0-8]{9}$" },
+        registers: { type: "string", pattern: "^[0-8]{5}$" },
+        stops: { type: ["array", "string"], items: { type: "string" } },
+        rotary: { type: "string", enum: ["slow", "fast", "stop"] },
       },
       additionalProperties: false,
     },
@@ -935,7 +956,7 @@ export const AGENT_TOOLS: readonly AgentTool[] = Object.freeze([
   {
     name: "set_modal",
     description:
-      "Mallets and bells on the modal engine: preset (marimba vibes xylophone glock celesta chimes kalimba mbira steelpan bowl gong timpani) switches the voice and keeps overrides; mallet yarn|cord|rubber|plastic|brass; params sets MODAL_PARAMS (hardness position ring tilt release damp motor motordepth ombak buzz click strikebend strikedecay gain), null returns one to the preset; reset clears overrides. Turns the track into instrument modal.",
+      "Mallets and bells on the modal engine: preset (marimba vibes xylophone glock celesta chimes kalimba mbira steelpan bowl gong timpani) switches the voice and keeps overrides (gamelan: crotales musicbox toypiano saron demung slenthem gangsa gender bonang kenong kethuk kempul; frame drums daf bodhran tabla); mallet yarn|cord|rubber|plastic|brass; params sets MODAL_PARAMS (hardness position ring tilt release damp motor motordepth ombak buzz click strikebend strikedecay gain), null returns one to the preset; pair names a partner modal track: this track (pengisep) sounds ombak Hz above it and the partner (pengumbang) gets ombak 0, null unpairs; reset clears overrides. Turns the track into instrument modal.",
     parameters: {
       type: "object",
       properties: {
@@ -945,6 +966,7 @@ export const AGENT_TOOLS: readonly AgentTool[] = Object.freeze([
           enum: [...MODAL_PRESET_NAMES, ...Object.keys(MODAL_ALIASES)],
         },
         mallet: { type: "string", enum: [...MODAL_MALLET_NAMES] },
+        pair: { type: ["string", "null"] },
         reset: { type: "boolean" },
         params: {
           type: "object",
@@ -974,6 +996,11 @@ export const AGENT_TOOLS: readonly AgentTool[] = Object.freeze([
           throw new ToolArgumentError("mallet must be a string");
         values.mallet = args.mallet;
       }
+      if (args.pair !== undefined) {
+        if (args.pair !== null && typeof args.pair !== "string")
+          throw new ToolArgumentError("pair must be a track id or null");
+        values.pair = args.pair;
+      }
       if (args.params !== undefined) {
         if (
           typeof args.params !== "object" ||
@@ -1019,9 +1046,20 @@ export const AGENT_TOOLS: readonly AgentTool[] = Object.freeze([
         messages.push(result.message);
       }
       const next = score.tracks.find((t) => t.id === trackId)!;
+      // A pair also sets the partner (pengumbang) to ombak 0.
+      const partners = score.tracks.filter(
+        (t) =>
+          t.id !== trackId &&
+          t.modal !== context.score.tracks.find((o) => o.id === t.id)?.modal,
+      );
       return {
         kind: "score",
         operations: [
+          ...partners.map((t) => ({
+            type: "updateTrack" as const,
+            trackId: t.id,
+            patch: { modal: t.modal ?? null },
+          })),
           {
             type: "updateTrack",
             trackId,
@@ -1033,10 +1071,111 @@ export const AGENT_TOOLS: readonly AgentTool[] = Object.freeze([
       };
     },
   },
+  {
+    name: "set_wind",
+    description:
+      "Winds and brass on the wind engine (breath-driven waveguides): preset (flute recorder whistle ney shakuhachi panpipe suling bansuri clarinet bassclarinet oboe bassoon sax altosax barisax trumpet harmon plunger trombone tuba horn) switches the voice and keeps overrides; params sets WIND_PARAMS (breath bright mute players growl noise attack release vib vibmod reed stopped wah wahenv flutter gain model), null returns one to the preset; players 2..8 is a section that spreads over chord tones; reset clears overrides; off returns to the legacy wind tone. Lines slur by default (a note that starts while one note is held is not re-tongued). Turns the track into the wind engine.",
+    parameters: {
+      type: "object",
+      properties: {
+        trackId: trackIdSchema,
+        preset: {
+          type: "string",
+          enum: [...WIND_PRESET_NAMES, ...Object.keys(WIND_ALIASES)],
+        },
+        reset: { type: "boolean" },
+        off: { type: "boolean" },
+        params: {
+          type: "object",
+          additionalProperties: {
+            type: ["number", "string", "boolean", "null"],
+          },
+        },
+      },
+      additionalProperties: false,
+    },
+    plan(args, context) {
+      const trackId = targetTrack(args, context);
+      const commands: WindCommand[] = [];
+      if (args.off === true) commands.push({ type: "wind-off" });
+      if (args.reset === true) commands.push({ type: "wind-reset" });
+      if (args.preset !== undefined) {
+        const preset =
+          typeof args.preset === "string"
+            ? windPresetFor(args.preset)
+            : undefined;
+        if (!preset)
+          throw new ToolArgumentError(
+            `preset must be one of ${WIND_PRESET_NAMES.join(", ")}`,
+          );
+        commands.push({ type: "wind-preset", preset });
+      }
+      const values: Record<string, number | string | boolean | null> = {};
+      if (args.params !== undefined) {
+        if (
+          typeof args.params !== "object" ||
+          args.params === null ||
+          Array.isArray(args.params)
+        )
+          throw new ToolArgumentError("params must be an object");
+        for (const [key, value] of Object.entries(args.params)) {
+          const name = windParamName(key);
+          if (!name)
+            throw new ToolArgumentError(
+              `wind has no parameter ${key} (${Object.keys(WIND_PARAMS).join(" ")})`,
+            );
+          if (
+            value !== null &&
+            typeof value !== "number" &&
+            typeof value !== "string" &&
+            typeof value !== "boolean"
+          )
+            throw new ToolArgumentError(
+              `${key} must be a number, string or boolean`,
+            );
+          values[name] = value;
+        }
+      }
+      if (Object.keys(values).length > 0)
+        commands.push({ type: "wind-set", values });
+      if (commands.length === 0) {
+        // An empty call turns the track into the wind engine.
+        const current = context.score.tracks.find((t) => t.id === trackId);
+        commands.push({
+          type: "wind-preset",
+          preset:
+            current?.instrument === "wind" && current.wind?.preset
+              ? current.wind.preset
+              : "flute",
+        });
+      }
+      let score = context.score;
+      const messages: string[] = [];
+      for (const command of commands) {
+        const result = applyWindCommand(score, trackId, command);
+        if (!result.ok) throw new ToolArgumentError(result.message);
+        if (result.next) score = result.next;
+        messages.push(result.message);
+      }
+      const next = score.tracks.find((t) => t.id === trackId)!;
+      return {
+        kind: "score",
+        operations: [
+          {
+            type: "updateTrack",
+            trackId,
+            patch: { instrument: next.instrument, wind: next.wind ?? null },
+          },
+        ],
+        trackId,
+        summary: `${trackId} ${messages.at(-1)}`,
+      };
+    },
+  },
   {
     name: "set_sample",
     description:
-      "Set a sampler voice's Strudel sample controls: begin end gain speed unit(r|c|s) loop loopBegin loopEnd clip(legato) fit loopAt accelerate squiz cut; null unsets one.",
+      "Set a sampler voice's Strudel sample controls: begin end gain speed unit(r|c|s) loop loopBegin loopEnd clip(legato) fit loopAt accelerate squiz cut, and (0.6.1) shift (semitones, length kept) formant (0 keeps the voice's formants) fadeInTime fadeTime (seconds), vel [lo,hi] (velocity layer) rr (round-robin group). null unsets one.",
     parameters: {
       type: "object",
       properties: {
@@ -1045,7 +1184,15 @@ export const AGENT_TOOLS: readonly AgentTool[] = Object.freeze([
         params: {
           type: "object",
           additionalProperties: {
-            type: ["number", "string", "boolean", "null"],
+            anyOf: [
+              { type: ["number", "string", "boolean", "null"] },
+              {
+                type: "array",
+                items: { type: "integer", minimum: 0, maximum: 127 },
+                minItems: 2,
+                maxItems: 2,
+              },
+            ],
           },
         },
       },
@@ -1505,7 +1652,7 @@ export const AGENT_TOOLS: readonly AgentTool[] = Object.freeze([
         typeof args.instrument === "string"
           ? args.instrument.toLowerCase()
           : "";
-      const preset = word === "piano" ? "grand" : word;
+      const preset = pianoWrite(word)?.preset ?? word;
       if (isKeysPreset(preset)) {
         const patch = keysPresetPatch({}, preset);
         return {
@@ -1822,6 +1969,7 @@ export const AGENT_TOOLS: readonly AgentTool[] = Object.freeze([
   ...PACK_TOOLS,
   ...MASTER_TOOLS,
   ...GRANULAR_TOOLS,
+  ...RESAMPLE_TOOLS,
   // Looks tools up at call time, so it can plan any of the above.
   previewSoundTool((name) => findAgentTool(name)),
 ] satisfies AgentTool[]);
@@ -1969,19 +2117,54 @@ function fxToolCommand(
   return { type: "fx-set", effect, values };
 }
 
+/** f061-organ: set_keys drawbars/registers/stops/rotary as keys values. */
+function organToolValues(
+  args: Record<string, unknown>,
+): Record<string, string> {
+  const out: Record<string, string> = {};
+  for (const name of ["drawbars", "registers", "rotary"] as const) {
+    const value = args[name];
+    if (value === undefined) continue;
+    if (typeof value !== "string")
+      throw new ToolArgumentError(`keys ${name} must be a string`);
+    out[name] = value;
+  }
+  if (args.stops !== undefined) {
+    const words = Array.isArray(args.stops)
+      ? args.stops
+      : typeof args.stops === "string"
+        ? args.stops.split(/[\s,+]+/)
+        : undefined;
+    if (!words || !words.every((word) => typeof word === "string"))
+      throw new ToolArgumentError("keys stops must be stop names");
+    out.stops = words.join(" ");
+  }
+  return out;
+}
+
 function keysToolCommand(args: Record<string, unknown>): KeysCommand {
   if (args.reset === true) return { type: "keys-reset" };
+  const organ = organToolValues(args);
+  const organSet = Object.keys(organ).length > 0;
   if (args.preset !== undefined) {
-    if (typeof args.preset !== "string" || !isKeysPreset(args.preset))
+    const preset =
+      typeof args.preset === "string"
+        ? (pianoWrite(args.preset)?.preset ?? args.preset)
+        : undefined;
+    if (preset === undefined || !isKeysPreset(preset))
       throw new ToolArgumentError(
         `keys presets: ${Object.keys(KEYS_PRESETS).join(", ")}`,
       );
-    return { type: "keys-preset", preset: args.preset };
+    return organSet
+      ? { type: "keys-preset", preset, values: organ }
+      : { type: "keys-preset", preset };
   }
+  if (args.params === undefined && organSet)
+    return { type: "keys-set", values: organ };
   if (args.params === undefined)
     throw new ToolArgumentError("set_keys needs preset, reset, or params");
   const params = record(args.params, "params");
-  const values: Record<string, number | string | null> = {};
+  const values: Record<string, number | string | null> = { ...organ };
   for (const [name, value] of Object.entries(params)) {
     const param = keysParamName(name);
     if (!param)
@@ -2112,6 +2295,7 @@ function instrumentName(value: unknown): {
   instrument: string;
   string?: { preset: string };
   modal?: TrackModal;
+  wind?: TrackWind;
 } {
   const word = typeof value === "string" ? value.trim() : undefined;
   if (word === STRING_INSTRUMENT)
@@ -2124,6 +2308,7 @@ function instrumentName(value: unknown): {
     patch === undefined ||
     (!patch.string &&
       !patch.modal &&
+      !patch.wind &&
       !(AVAILABLE_INSTRUMENTS as readonly string[]).includes(patch.instrument))
   )
     throw new ToolArgumentError(

package/src/agent/xcb-agent.ts

@@ -51,15 +51,21 @@ export const TEXT_AGENT_SYSTEM_PROMPT = [
   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.",
+  "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.`,
+  `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

@@ -51,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;
@@ -393,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/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;
+}