@hraness/dawg 0.6.0 → 0.7.0

package/core/sdk/eval-child.ts

@@ -83,8 +83,8 @@ function diagnostic(error: unknown, project: string): Diagnostic {
 }
 
 /**
- * Adds `sha256` to sampler voices and project wavetable files that exist
- * and are within the size limit.
+ * Adds `sha256` to sampler voices, project wavetable files, audio clips and
+ * takes that exist and are within the size limit.
  */
 async function withSampleHashes(
   song: object,
@@ -106,6 +106,11 @@ async function withSampleHashes(
       refs.push(wavetable.table);
     const granular = track.granular;
     if (isObject(granular) && isObject(granular.src)) refs.push(granular.src);
+    // 0.7 audio clips and takes: a fresh `audio("samples/x.wav")` is pinned
+    // here; a written pin is kept and `dawg check` re-hashes it.
+    for (const key of ["clips", "takes"])
+      for (const item of Array.isArray(track[key]) ? track[key] : [])
+        if (isObject(item)) refs.push(item);
   }
   for (const ref of refs) {
     if (

package/core/sdk/eval.ts

@@ -1,11 +1,16 @@
 /**
- * Evaluates a project's `song.ts` in a sandboxed Bun subprocess and parses
+ * Evaluates a project's `song.ts` in an isolated Bun subprocess and parses
  * the result from `unknown` into a validated `TrackScore`.
  *
  * The child runs `eval-child.ts` with a scrubbed environment, the project as
  * its working directory, no native addons or auto-install, a 10 second
- * budget and a 1 MiB output bound. Anything it prints that is not the
+ * budget and a 32 MiB output bound. Anything it prints that is not the
  * expected JSON line is a diagnostic.
+ *
+ * Isolation is not a sandbox: the child runs project code as the user, with
+ * the user's filesystem and network access. It protects dawg's own process
+ * (a crash, hang or runaway output in song.ts never takes the window down),
+ * not the machine, so only evaluate projects you trust.
  */
 
 import { dirname, join } from "node:path";
@@ -15,7 +20,11 @@ import { refreshRhythm } from "../rhythm.ts";
 import { ScoreValidationError, TrackScore } from "../score.ts";
 
 export const EVAL_TIMEOUT_MS = 10_000;
-export const EVAL_MAX_OUTPUT_BYTES = 1024 * 1024;
+/**
+ * Above the JSON of the largest score `SCORE_LIMITS` allows (64 tracks with
+ * every automation lane full plus 4096 notes stays well under 16 MiB).
+ */
+export const EVAL_MAX_OUTPUT_BYTES = 32 * 1024 * 1024;
 
 /** A problem in a project file; `file` is project-relative when known. */
 export type Diagnostic = Readonly<{
@@ -39,7 +48,14 @@ export type EvalSpawn = (
     maxOutputBytes: number;
   }>,
 ) => Promise<
-  Readonly<{ code: number; stdout: string; stderr: string; killed: boolean }>
+  Readonly<{
+    code: number;
+    stdout: string;
+    stderr: string;
+    killed: boolean;
+    /** Why the child was killed; absent means the time budget ran out. */
+    reason?: "timeout" | "output";
+  }>
 >;
 
 export type EvalOptions = Readonly<{
@@ -86,12 +102,21 @@ export async function evaluateProject(
       failure(started, [{ message: `could not start bun: ${text(error)}` }]),
     );
   }
+  if (run.killed && run.reason === "output")
+    return done(
+      failure(started, [
+        {
+          file: "song.ts",
+          message: `evaluation printed more than ${EVAL_MAX_OUTPUT_BYTES / (1024 * 1024)} MiB; song.ts must not log`,
+        },
+      ]),
+    );
   if (run.killed)
     return done(
       failure(started, [
         {
           file: "song.ts",
-          message: "evaluation timed out (10 s); song.ts must be pure",
+          message: `evaluation timed out (${Math.round((options.timeoutMs ?? EVAL_TIMEOUT_MS) / 1000)} s); song.ts must be pure`,
         },
       ]),
     );
@@ -224,6 +249,7 @@ export const bunSpawn: EvalSpawn = async (args, options) => {
     stderr: "pipe",
   });
   let killed = false;
+  let reason: "timeout" | "output" = "timeout";
   const timer = setTimeout(() => {
     killed = true;
     child.kill();
@@ -237,6 +263,7 @@ export const bunSpawn: EvalSpawn = async (args, options) => {
       const { value, done } = await reader.read();
       if (done || !value) break;
       if (total + value.byteLength > options.maxOutputBytes) {
+        if (!killed) reason = "output";
         killed = true;
         child.kill();
         break;
@@ -253,7 +280,9 @@ export const bunSpawn: EvalSpawn = async (args, options) => {
       read(child.stderr),
       child.exited,
     ]);
-    return { code, stdout, stderr, killed };
+    return killed
+      ? { code, stdout, stderr, killed, reason }
+      : { code, stdout, stderr, killed };
   } finally {
     clearTimeout(timer);
   }

package/core/sdk/print.ts

@@ -21,12 +21,26 @@ import {
   type FxValues,
 } from "../fx.ts";
 import { MASTER_SPECS, MASTER_UNITS, type SongMaster } from "../master.ts";
+import type { SongStyle } from "../style-provenance.ts";
 import { midiToPitch } from "../pitch.ts";
 import {
   MODAL_INSTRUMENT,
   MODAL_PARAMS,
   type TrackModal,
 } from "../resonators.ts";
+import { WIND_INSTRUMENT, WIND_PARAMS, type TrackWind } from "../winds.ts";
+import {
+  SING_INSTRUMENT,
+  SING_KEY_ORDER,
+  singNoteName,
+  type TrackSing,
+} from "../sing.ts";
+import {
+  VOCODER_INSTRUMENT,
+  VOCODER_PARAMS,
+  type TrackVocoder,
+} from "../vocoder.ts";
+import { AUTOTUNE_FIELDS, type TrackAutotune } from "../autotune.ts";
 import { rhythmVoicePitch, rowInSync } from "../rhythm.ts";
 import {
   BUILTIN_TABLE_PREFIX,
@@ -44,13 +58,15 @@ import {
   type SampleRef,
   type Sampler,
   type Section,
+  type AudioClip,
+  type Take,
   type Track,
 } from "../score.ts";
 import { trackSlug } from "../slug.ts";
-import { barStartTick } from "../tempo.ts";
+import { barStartTick, timeWithinSong } from "../tempo.ts";
 import type { Tuning } from "../tuning.ts";
 import { DEFAULT_STRING_PRESET, type TrackString } from "../strings.ts";
-import { DEFAULT_HIT_LENGTH, DEFAULT_VELOCITY } from "./v1.ts";
+import { DEFAULT_HIT_LENGTH, DEFAULT_VELOCITY, defaultClipId } from "./v1.ts";
 
 const WIDTH = 80;
 const INDENT = "  ";
@@ -155,6 +171,14 @@ const RESERVED = new Set([
   "rig",
   "granular",
   "modal",
+  "wind",
+  "sing",
+  "audio",
+  "take",
+  "lyrics",
+  "repeatAudio",
+  "vocoder",
+  "autotune",
   "slices",
   "euclid",
   "euclidRot",
@@ -195,6 +219,7 @@ export function printSong(
   const helpers = [
     "song",
     ...TIME_HELPERS.filter((name) => time.used.has(name)),
+    ...(score.style ? ["style"] : []),
   ];
   const lines: string[] = [`import { ${helpers.join(", ")} } from "dawg";`];
   for (const track of score.tracks)
@@ -225,6 +250,7 @@ export function printSong(
     )}`,
   );
   if (score.master) entries.push(printMaster(score.master));
+  if (score.style) entries.push(`style: ${printStyle(score.style)}`);
   // Song sections and form (0.5): printed only when the song has them.
   if (score.sections.length > 0)
     entries.push(
@@ -239,6 +265,7 @@ export function printSong(
     entries.push(`form: ${printForm(score.form, INDENT)}`);
   if (score.loopSection !== undefined)
     entries.push(`loopSection: ${str(score.loopSection)}`);
+  if (score.calibration) entries.push(`calibration: ${num(score.calibration)}`);
   lines.push("export default song({");
   for (const entry of entries) lines.push(`${INDENT}${entry},`);
   lines.push("});", "");
@@ -255,7 +282,8 @@ function printTime(score: TrackScore): {
 } {
   const marks: string[] = [];
   const used = new Set<string>();
-  const time = score.time;
+  // Marks past the final barline are never heard and the SDK refuses them.
+  const time = timeWithinSong(score);
   if (!time) return { marks, used };
   const beat = (tick: number) => num(tick / score.ticksPerBeat);
   type Mark = { tick: number; order: number; text: string };
@@ -414,6 +442,25 @@ export function printTrack(score: TrackScore, track: Track): string {
       ? printModal(track.modal, INDENT)
       : undefined;
   if (modalCall?.startsWith("modal(")) used.add("modal");
+  const windCall =
+    track.instrument === WIND_INSTRUMENT && track.wind
+      ? printWind(track.wind, INDENT)
+      : undefined;
+  if (windCall?.startsWith("wind(")) used.add("wind");
+  const singCall =
+    track.instrument === SING_INSTRUMENT && track.sing
+      ? printSing(track.sing, INDENT)
+      : undefined;
+  if (singCall?.startsWith("sing(")) used.add("sing");
+  const vocoderCall = track.vocoder
+    ? printVocoder(
+        track.vocoder,
+        vocoderSrcText(score, track.vocoder.src),
+        track.instrument === VOCODER_INSTRUMENT ? "instrument: " : "vocoder: ",
+        INDENT,
+      )
+    : undefined;
+  if (vocoderCall?.startsWith("vocoder(")) used.add("vocoder");
 
   const entries: string[] = [
     `id: ${str(track.id)}`,
@@ -432,8 +479,21 @@ export function printTrack(score: TrackScore, track: Track): string {
     entries.push(`instrument: ${printStringed(track.string!, INDENT)}`);
   } else if (modalCall) {
     entries.push(`instrument: ${modalCall}`);
+  } else if (windCall) {
+    entries.push(`instrument: ${windCall}`);
+  } else if (singCall) {
+    entries.push(`instrument: ${singCall}`);
+  } else if (vocoderCall && track.instrument === VOCODER_INSTRUMENT) {
+    entries.push(`instrument: ${vocoderCall}`);
   } else entries.push(`instrument: ${str(track.instrument)}`);
+  if (vocoderCall && track.instrument !== VOCODER_INSTRUMENT)
+    entries.push(`vocoder: ${vocoderCall}`);
   if (track.kit) entries.push(`kit: ${str(track.kit)}`);
+  // The table a track keeps after leaving the wavetable instrument.
+  if (track.wavetable && !wavetable) {
+    used.add("wavetable");
+    entries.push(`wavetable: ${printWavetable(track.wavetable, INDENT)}`);
+  }
   if (track.granular && !grained)
     entries.push(
       `granular: ${obj(
@@ -586,6 +646,11 @@ export function printTrack(score: TrackScore, track: Track): string {
     );
   }
   entries.push(...performanceEntries(score, track));
+  if (track.autotune) {
+    const call = printAutotune(track.autotune, INDENT);
+    if (call.startsWith("autotune(")) used.add("autotune");
+    entries.push(`autotune: ${call}`);
+  }
   const lanes: [string, readonly AutomationPoint[] | undefined][] = [
     ["volume", track.volumeAutomation],
     ["pan", track.panAutomation],
@@ -644,6 +709,20 @@ export function printTrack(score: TrackScore, track: Track): string {
   }
   if (rows.length === 0 || printed.length > 0)
     entries.push(`notes: ${list(printed, INDENT, "notes: ".length, 1)}`);
+  if (track.takes && track.takes.length > 0) {
+    used.add("take");
+    const items = track.takes.map((t) => printTake(score, t, INDENT + INDENT));
+    entries.push(`takes: ${list(items, INDENT, "takes: ".length, 1, true)}`);
+  }
+  if (track.clips && track.clips.length > 0) {
+    used.add("audio");
+    const items = track.clips.map((clip, index) =>
+      printClip(score, clip, index, INDENT + INDENT),
+    );
+    entries.push(
+      `clips: ${list(items, INDENT, "clips: ".length, 1, items.length > 1)}`,
+    );
+  }
 
   const names = [
     "track",
@@ -658,8 +737,14 @@ export function printTrack(score: TrackScore, track: Track): string {
     "rig",
     "granular",
     "modal",
+    "wind",
+    "sing",
+    "vocoder",
+    "autotune",
     "euclid",
     "grid",
+    "audio",
+    "take",
   ]
     .filter((name) => used.has(name))
     .join(", ");
@@ -768,6 +853,9 @@ function expressionEntries(
       ),
     ]);
   }
+  if (note.vowel) entries.push(["vowel", str(note.vowel)]);
+  if (note.lyric !== undefined) entries.push(["lyric", str(note.lyric)]);
+  if (note.drift !== undefined) entries.push(["drift", num(note.drift)]);
   return entries.length === 0 ? undefined : entries;
 }
 
@@ -791,6 +879,66 @@ function call(
   return `${name}(${[...args, "{"].join(", ")}\n${body}\n${indent}})`;
 }
 
+/** Seconds at 4 decimals (sources.md 6). */
+function secs(value: number): string {
+  return num(Math.round(value * 1e4) / 1e4);
+}
+
+/**
+ * `audio(src, { at, offset, dur, gain, fadeInTime, fadeTime, rev, take,
+ * mute, text, say, sha256 })` (SDK 1.32.0); defaults omitted, an id printed
+ * only when it differs from the positional default.
+ */
+function printClip(
+  score: TrackScore,
+  clip: AudioClip,
+  index: number,
+  indent: string,
+): string {
+  const how: [string, string][] = [];
+  if (clip.id !== defaultClipId(index)) how.push(["id", str(clip.id)]);
+  if (clip.startTick !== 0)
+    how.push(["at", num(clip.startTick / score.ticksPerBeat)]);
+  if (clip.offset) how.push(["offset", secs(clip.offset)]);
+  if (clip.dur !== undefined) how.push(["dur", secs(clip.dur)]);
+  // Gain is linear in the file; a comment shows the dB the commands speak.
+  if (clip.gain !== undefined && clip.gain !== 1)
+    how.push([
+      "gain",
+      `${num(clip.gain)} /* ${
+        clip.gain > 0 ? (20 * Math.log10(clip.gain)).toFixed(1) : "-inf"
+      } dB */`,
+    ]);
+  if (clip.fadeInTime !== undefined)
+    how.push(["fadeInTime", secs(clip.fadeInTime)]);
+  if (clip.fadeTime !== undefined) how.push(["fadeTime", secs(clip.fadeTime)]);
+  if (clip.rev) how.push(["rev", "true"]);
+  if (clip.take !== undefined) how.push(["take", str(clip.take)]);
+  if (clip.mute) how.push(["mute", "true"]);
+  if (clip.text !== undefined) how.push(["text", str(clip.text)]);
+  if (clip.say !== undefined) how.push(["say", JSON.stringify(clip.say)]);
+  how.push(["sha256", str(clip.sha256)]);
+  return call("audio", [str(clip.src)], how, indent);
+}
+
+/** `take(name, src, { at, in, out, ... })` (SDK 1.32.0). */
+function printTake(score: TrackScore, t: Take, indent: string): string {
+  const beatsAt = (tick: number) => num(tick / score.ticksPerBeat);
+  const how: [string, string][] = [];
+  if (t.startTick !== 0) how.push(["at", beatsAt(t.startTick)]);
+  how.push(["in", beatsAt(t.inTick)], ["out", beatsAt(t.outTick)]);
+  if (t.offset) how.push(["offset", secs(t.offset)]);
+  if (t.latency) how.push(["latency", secs(t.latency)]);
+  if (t.latencyAssumed) how.push(["latencyAssumed", "true"]);
+  if (t.ppm !== undefined)
+    how.push(["ppm", num(Math.round(t.ppm * 100) / 100)]);
+  if (t.fit !== undefined) how.push(["fit", num(t.fit)]);
+  if (t.warn !== undefined) how.push(["warn", str(t.warn)]);
+  if (t.nudge !== undefined) how.push(["nudge", num(t.nudge)]);
+  how.push(["sha256", str(t.sha256)]);
+  return call("take", [str(t.name), str(t.src)], how, indent);
+}
+
 /** A track's performance fields (SDK 1.15.0) as `key: literal` entries. */
 function performanceEntries(score: TrackScore, track: Track): string[] {
   const entries: string[] = [];
@@ -808,13 +956,15 @@ function performanceEntries(score: TrackScore, track: Track): string[] {
             1,
           )}`,
     );
-  if (track.pedal) {
-    const events = track.pedal.map(
+  for (const key of ["pedal", "softPedal", "sostenuto"] as const) {
+    const lane = track[key];
+    if (!lane) continue;
+    const events = lane.map(
       (event) =>
         `[${num(event.tick / score.ticksPerBeat)}, ${str(event.state)}]`,
     );
     entries.push(
-      `pedal: ${list(events, INDENT, "pedal: ".length, 1, events.length > 1)}`,
+      `${key}: ${list(events, INDENT, `${key}: `.length, 1, events.length > 1)}`,
     );
   }
   if (track.velocityCurve)
@@ -851,6 +1001,20 @@ function performanceEntries(score: TrackScore, track: Track): string[] {
       )}`,
     );
   }
+  if (track.guitar) {
+    const { tune, capo, hand, ring, position } = track.guitar;
+    const fields: [string, string][] = [];
+    if (tune !== undefined)
+      fields.push([
+        "tune",
+        typeof tune === "string" ? str(tune) : `[${tune.map(num).join(", ")}]`,
+      ]);
+    if (capo !== undefined) fields.push(["capo", num(capo)]);
+    if (hand !== undefined) fields.push(["hand", num(hand)]);
+    if (ring !== undefined) fields.push(["ring", num(ring)]);
+    if (position !== undefined) fields.push(["position", num(position)]);
+    entries.push(`guitar: ${obj(fields, INDENT, "guitar: ".length, 1)}`);
+  }
   return entries;
 }
 
@@ -1000,6 +1164,7 @@ function printModal(settings: TrackModal, indent: string): string {
     if (value === undefined) continue;
     params.push([key, typeof value === "number" ? num(value) : str(value)]);
   }
+  if (settings.pair !== undefined) params.push(["pair", str(settings.pair)]);
   const preset = settings.preset;
   if (params.length === 0 && preset && preset !== "marimba") return str(preset);
   const head = preset ? str(preset) : "";
@@ -1012,6 +1177,164 @@ function printModal(settings: TrackModal, indent: string): string {
   return `modal(${lead}{\n${params.map(([k, v]) => `${inner}${k}: ${v},`).join("\n")}\n${indent}})`;
 }
 
+/**
+ * A wind track's instrument: the preset word alone (`"flute"`) when there
+ * are no overrides, else `wind("sax", { breath: 0.8 })` with keys in
+ * `WIND_PARAMS` order. Every wind preset word is also an instrument word.
+ */
+function printWind(settings: TrackWind, indent: string): string {
+  const params: [string, string][] = [];
+  for (const key of Object.keys(WIND_PARAMS)) {
+    const value = (settings as Record<string, unknown>)[key];
+    if (value === undefined) continue;
+    params.push([
+      key,
+      typeof value === "number"
+        ? num(value)
+        : typeof value === "boolean"
+          ? String(value)
+          : str(String(value)),
+    ]);
+  }
+  const preset = settings.preset;
+  if (params.length === 0 && preset) return str(preset);
+  const head = preset ? str(preset) : "";
+  if (params.length === 0) return `wind(${head})`;
+  const lead = head ? `${head}, ` : "";
+  const inline = `wind(${lead}{ ${params.map(([k, v]) => `${k}: ${v}`).join(", ")} })`;
+  if (indent.length + "instrument: ".length + inline.length + 1 <= WIDTH)
+    return inline;
+  const inner = indent + INDENT;
+  return `wind(${lead}{\n${params.map(([k, v]) => `${inner}${k}: ${v},`).join("\n")}\n${indent}})`;
+}
+
+/**
+ * A sing track's instrument: the preset word alone (`"choir"`) when there
+ * are no overrides and the preset is an instrument word, else
+ * `sing("khoomei", { drone: "D3" })` with keys in `SING_KEY_ORDER`; the
+ * drone prints as a note name.
+ */
+function printSing(settings: TrackSing, indent: string): string {
+  const params: [string, string][] = [];
+  for (const key of SING_KEY_ORDER) {
+    const value = (settings as Record<string, unknown>)[key];
+    if (value === undefined) continue;
+    params.push([
+      key,
+      key === "drone"
+        ? str(singNoteName(value as number))
+        : Array.isArray(value)
+          ? `[${value.map((v) => num(v as number)).join(", ")}]`
+          : typeof value === "number"
+            ? num(value)
+            : str(String(value)),
+    ]);
+  }
+  const preset = settings.preset;
+  if (params.length === 0 && preset && SING_BARE_WORDS.has(preset))
+    return str(preset);
+  if (params.length === 0 && !preset) return str(SING_INSTRUMENT);
+  const head = preset ? str(preset) : "";
+  if (params.length === 0) return `sing(${head})`;
+  const lead = head ? `${head}, ` : "";
+  const inline = `sing(${lead}{ ${params.map(([k, v]) => `${k}: ${v}`).join(", ")} })`;
+  if (indent.length + "instrument: ".length + inline.length + 1 <= WIDTH)
+    return inline;
+  const inner = indent + INDENT;
+  return `sing(${lead}{\n${params.map(([k, v]) => `${inner}${k}: ${v},`).join("\n")}\n${indent}})`;
+}
+
+/** Sing presets that are also instrument words (`"choir"`). */
+const SING_BARE_WORDS: ReadonlySet<string> = new Set([
+  "aah",
+  "ooh",
+  "choir",
+  "chorale",
+  "khoomei",
+  "sygyt",
+  "kargyraa",
+]);
+
+/**
+ * A vocoder's `src` as the SDK reads it back: the track's name slug when it
+ * names exactly that track (no other slug or id collides), else the id.
+ */
+function vocoderSrcText(
+  score: TrackScore,
+  src: string | undefined,
+): string | undefined {
+  if (src === undefined) return undefined;
+  const target = score.tracks.find((track) => track.id === src);
+  if (!target) return src;
+  const slug = trackSlug(target.name);
+  const clash = score.tracks.some(
+    (track) =>
+      track.id !== target.id &&
+      (track.id === slug || trackSlug(track.name) === slug),
+  );
+  return clash ? src : slug;
+}
+
+/**
+ * A vocoder: the bare word `"vocoder"` for a built-in carrier with nothing
+ * set, else `vocoder("talkbox", { src: "vox", formant: 2 })` with `src`
+ * first and the rest in `VOCODER_PARAMS` order.
+ */
+function printVocoder(
+  settings: TrackVocoder,
+  src: string | undefined,
+  prefix: string,
+  indent: string,
+): string {
+  const params: [string, string][] = [];
+  if (src !== undefined) params.push(["src", str(src)]);
+  for (const key of Object.keys(VOCODER_PARAMS)) {
+    const value = (settings as Record<string, unknown>)[key];
+    if (value === undefined) continue;
+    params.push([
+      key,
+      typeof value === "number"
+        ? num(value)
+        : typeof value === "boolean"
+          ? String(value)
+          : str(String(value)),
+    ]);
+  }
+  const preset = settings.preset;
+  if (params.length === 0 && !preset && prefix === "instrument: ")
+    return str(VOCODER_INSTRUMENT);
+  const head = preset ? str(preset) : "";
+  if (params.length === 0) return `vocoder(${head})`;
+  const lead = head ? `${head}, ` : "";
+  const inline = `vocoder(${lead}{ ${params.map(([k, v]) => `${k}: ${v}`).join(", ")} })`;
+  if (indent.length + prefix.length + inline.length + 1 <= WIDTH) return inline;
+  const inner = indent + INDENT;
+  return `vocoder(${lead}{\n${params.map(([k, v]) => `${inner}${k}: ${v},`).join("\n")}\n${indent}})`;
+}
+
+/**
+ * A track's autotune: the preset word alone (`"hard"`) when nothing
+ * overrides it, else `autotune("pop", { speed: 40 })` with keys in
+ * `AUTOTUNE_FIELDS` order.
+ */
+function printAutotune(settings: TrackAutotune, indent: string): string {
+  const params: [string, string][] = [];
+  for (const key of AUTOTUNE_FIELDS) {
+    if (key === "preset") continue;
+    const value = settings[key];
+    if (value === undefined) continue;
+    params.push([key, typeof value === "number" ? num(value) : str(value)]);
+  }
+  const preset = settings.preset;
+  if (params.length === 0 && preset) return str(preset);
+  const lead = preset ? `${str(preset)}, ` : "";
+  const inline = `autotune(${lead}{ ${params.map(([k, v]) => `${k}: ${v}`).join(", ")} })`;
+  if (indent.length + "autotune: ".length + inline.length + 1 <= WIDTH)
+    return inline;
+  const inner = indent + INDENT;
+  return `autotune(${lead}{\n${params.map(([k, v]) => `${inner}${k}: ${v},`).join("\n")}\n${indent}})`;
+}
+
 /** `wavetable("basic", { wt: 0.5 })`; pack tables keep their pin. */
 function printWavetable(settings: TrackWavetable, indent: string): string {
   const src = settings.table.src;
@@ -1071,6 +1394,23 @@ function printSample(ref: SampleRef, indent: string, prefix: number): string {
   if (ref.bpm !== undefined) entries.push(["bpm", num(ref.bpm)]);
   if (ref.fitmode !== undefined) entries.push(["fitmode", str(ref.fitmode)]);
   if (ref.len !== undefined) entries.push(["len", num(ref.len)]);
+  if (ref.shift !== undefined) entries.push(["shift", num(ref.shift)]);
+  if (ref.formant !== undefined) entries.push(["formant", num(ref.formant)]);
+  if (ref.fadeInTime !== undefined)
+    entries.push(["fadeInTime", num(ref.fadeInTime)]);
+  if (ref.fadeTime !== undefined) entries.push(["fadeTime", num(ref.fadeTime)]);
+  if (ref.from !== undefined) {
+    const from = ref.from;
+    const parts: [string, string][] = [["source", str(from.source)]];
+    if (from.section !== undefined) parts.push(["section", str(from.section)]);
+    if (from.bars !== undefined)
+      parts.push(["bars", `[${num(from.bars[0])}, ${num(from.bars[1])}]`]);
+    parts.push(["score", str(from.score)]);
+    entries.push(["from", obj(parts, indent + INDENT, "from: ".length, 1)]);
+  }
+  if (ref.vel !== undefined)
+    entries.push(["vel", `[${num(ref.vel[0])}, ${num(ref.vel[1])}]`]);
+  if (ref.rr !== undefined) entries.push(["rr", str(ref.rr)]);
   if (entries.length === 1) return str(ref.src);
   return obj(entries, indent, prefix, 1);
 }
@@ -1138,6 +1478,14 @@ function fill(
   return `[\n${lines.join("\n")}\n${indent}]`;
 }
 
+/** `style("id", { seed, bars, blend })`: provenance, seed and bars always written. */
+function printStyle(value: SongStyle): string {
+  const options = [`seed: ${num(value.seed)}`, `bars: ${num(value.bars)}`];
+  if (value.blend)
+    options.push(`blend: [${str(value.blend.id)}, ${num(value.blend.weight)}]`);
+  return `style(${str(value.id)}, { ${options.join(", ")} })`;
+}
+
 /** `master: { … }`, always expanded like `fx`; units in chain order. */
 function printMaster(master: SongMaster): string {
   const inner = INDENT + INDENT;

package/core/sdk/sync-lyrics.ts

@@ -0,0 +1,49 @@
+/**
+ * The SDK is one vendored file with no imports, so `core/sdk/v1.ts` carries
+ * a copy of the lyric grammar (`core/lyrics.ts`) between two marker lines.
+ * `bun core/sdk/sync-lyrics.ts` rewrites it and `sync-lyrics.test.ts` fails
+ * when it is stale. Same scheme as `sync-instruments.ts`.
+ */
+
+import { readFile, writeFile } from "node:fs/promises";
+import { join } from "node:path";
+import { format } from "prettier";
+
+export const BEGIN_MARKER =
+  "// BEGIN lyrics: generated from core/lyrics.ts by core/sdk/sync-lyrics.ts";
+export const END_MARKER = "// END lyrics";
+
+const ROOT = join(import.meta.dir, "..", "..");
+export const LYRICS_PATH = join(ROOT, "core", "lyrics.ts");
+export const SDK_PATH = join(ROOT, "core", "sdk", "v1.ts");
+
+/** The lyric block (markers included) for a `core/lyrics.ts` source. */
+export function lyricBlock(source: string): string {
+  const start = source.indexOf("// ---- lyrics");
+  if (start < 0) throw new Error("core/lyrics.ts layout changed");
+  const body = source
+    .slice(source.indexOf("\n", start) + 1)
+    .replace(/^export /gm, "")
+    .trim();
+  return `${BEGIN_MARKER}\n${body}\n${END_MARKER}`;
+}
+
+/** `sdk` with its lyric block replaced, formatted like the repo. */
+export async function syncedSdk(sdk: string, lyrics: string): Promise<string> {
+  const from = sdk.indexOf(BEGIN_MARKER);
+  const to = sdk.indexOf(END_MARKER);
+  if (from < 0 || to < 0) throw new Error("v1.ts has no lyric markers");
+  const next =
+    sdk.slice(0, from) + lyricBlock(lyrics) + sdk.slice(to + END_MARKER.length);
+  return format(next, { parser: "typescript", filepath: SDK_PATH });
+}
+
+if (import.meta.main) {
+  const [sdk, lyrics] = await Promise.all([
+    readFile(SDK_PATH, "utf8"),
+    readFile(LYRICS_PATH, "utf8"),
+  ]);
+  const next = await syncedSdk(sdk, lyrics);
+  if (next !== sdk) await writeFile(SDK_PATH, next);
+  console.log(next === sdk ? "v1.ts lyrics up to date" : "v1.ts updated");
+}