@hraness/dawg 0.4.1 → 0.6.0

package/core/sdk/print.ts

@@ -8,9 +8,25 @@
  */
 
 import { DRUM_VOICES, isDrumInstrument } from "../drums.ts";
+import type { TrackGranular } from "../granular.ts";
+import { DEFAULT_FIXED_VELOCITY } from "../expression.ts";
 import type { RhythmRow } from "../euclid.ts";
-import { FX_LANES, fxSpec, type FxName, type FxValues } from "../fx.ts";
+import {
+  FX_LANES,
+  RIG_STAGES,
+  fxSpec,
+  rigPresetKeys,
+  rigPresetOf,
+  type FxName,
+  type FxValues,
+} from "../fx.ts";
+import { MASTER_SPECS, MASTER_UNITS, type SongMaster } from "../master.ts";
 import { midiToPitch } from "../pitch.ts";
+import {
+  MODAL_INSTRUMENT,
+  MODAL_PARAMS,
+  type TrackModal,
+} from "../resonators.ts";
 import { rhythmVoicePitch, rowInSync } from "../rhythm.ts";
 import {
   BUILTIN_TABLE_PREFIX,
@@ -23,12 +39,17 @@ import {
   type WavetableParam,
   TrackScore,
   type AutomationPoint,
+  type FormEntry,
   type Note,
   type SampleRef,
   type Sampler,
+  type Section,
   type Track,
 } from "../score.ts";
 import { trackSlug } from "../slug.ts";
+import { barStartTick } 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";
 
 const WIDTH = 80;
@@ -131,6 +152,9 @@ const RESERVED = new Set([
   "every",
   "sampler",
   "wavetable",
+  "rig",
+  "granular",
+  "modal",
   "slices",
   "euclid",
   "euclidRot",
@@ -147,7 +171,12 @@ export function trackIdentifiers(
   const out = new Map<string, string>();
   for (const track of score.tracks) {
     let base = dirs.get(track.id)!.replace(/-/g, "_");
-    if (!/^[a-z_]/.test(base) || RESERVED.has(base)) base = `track_${base}`;
+    if (
+      !/^[a-z_]/.test(base) ||
+      RESERVED.has(base) ||
+      (score.time && TIME_HELPERS.includes(base))
+    )
+      base = `track_${base}`;
     let name = base;
     for (let n = 2; used.has(name); n += 1) name = `${base}_${n}`;
     used.add(name);
@@ -162,7 +191,12 @@ export function printSong(
   dirs: ReadonlyMap<string, string> = trackDirectories(score),
 ): string {
   const ids = trackIdentifiers(score, dirs);
-  const lines: string[] = ['import { song } from "dawg";'];
+  const time = printTime(score);
+  const helpers = [
+    "song",
+    ...TIME_HELPERS.filter((name) => time.used.has(name)),
+  ];
+  const lines: string[] = [`import { ${helpers.join(", ")} } from "dawg";`];
   for (const track of score.tracks)
     lines.push(
       `import ${ids.get(track.id)!} from "./tracks/${dirs.get(track.id)!}/track.ts";`,
@@ -174,8 +208,14 @@ export function printSong(
     `bars: ${num(score.bars)}`,
   ];
   if (score.key !== null) entries.push(`key: ${str(score.key)}`);
+  if (score.tuning)
+    entries.push(
+      `tuning: ${printTuning(score.tuning, INDENT, "tuning: ".length)}`,
+    );
   if (score.ticksPerBeat !== 480)
     entries.push(`ticksPerBeat: ${num(score.ticksPerBeat)}`);
+  if (time.marks.length > 0)
+    entries.push(`time: ${list(time.marks, INDENT, "time: ".length, 1)}`);
   entries.push(
     `tracks: ${list(
       score.tracks.map((track) => ids.get(track.id)!),
@@ -184,12 +224,150 @@ export function printSong(
       1,
     )}`,
   );
+  if (score.master) entries.push(printMaster(score.master));
+  // Song sections and form (0.5): printed only when the song has them.
+  if (score.sections.length > 0)
+    entries.push(
+      `sections: ${list(
+        score.sections.map((section) => printSection(section, INDENT + INDENT)),
+        INDENT,
+        "sections: ".length,
+        1,
+      )}`,
+    );
+  if (score.form.length > 0)
+    entries.push(`form: ${printForm(score.form, INDENT)}`);
+  if (score.loopSection !== undefined)
+    entries.push(`loopSection: ${str(score.loopSection)}`);
   lines.push("export default song({");
   for (const entry of entries) lines.push(`${INDENT}${entry},`);
   lines.push("});", "");
   return lines.join("\n");
 }
 
+/** SDK time helpers `song.ts` may import, in import order. */
+const TIME_HELPERS: readonly string[] = ["tempo", "ramp", "meter", "fermata"];
+
+/** `song({ time })` marks for a score's tempo map, meters and fermatas. */
+function printTime(score: TrackScore): {
+  marks: string[];
+  used: Set<string>;
+} {
+  const marks: string[] = [];
+  const used = new Set<string>();
+  const time = score.time;
+  if (!time) return { marks, used };
+  const beat = (tick: number) => num(tick / score.ticksPerBeat);
+  type Mark = { tick: number; order: number; text: string };
+  const all: Mark[] = [];
+  for (const event of time.tempo ?? []) {
+    if (event.ramp) {
+      used.add("ramp");
+      const curve = event.ramp === "exp" ? ', "exp"' : "";
+      all.push({
+        tick: event.tick,
+        order: 1,
+        text: `ramp(${beat(event.tick)}, ${num(event.bpm)}${curve})`,
+      });
+    } else {
+      used.add("tempo");
+      all.push({
+        tick: event.tick,
+        order: 1,
+        text: `tempo(${beat(event.tick)}, ${num(event.bpm)})`,
+      });
+    }
+  }
+  for (const change of time.meter ?? []) {
+    used.add("meter");
+    const tick = barStartTick(score, change.bar);
+    const unit = change.beatUnit ?? 4;
+    const value =
+      unit === 4
+        ? num(change.beatsPerBar)
+        : `[${num(change.beatsPerBar)}, ${num(unit)}]`;
+    all.push({ tick, order: 0, text: `meter(${beat(tick)}, ${value})` });
+  }
+  for (const hold of time.fermatas ?? []) {
+    used.add("fermata");
+    all.push({
+      tick: hold.tick,
+      order: 2,
+      text: `fermata(${beat(hold.tick)}, ${num(hold.beats)})`,
+    });
+  }
+  all.sort((a, b) => a.tick - b.tick || a.order - b.order);
+  for (const mark of all) marks.push(mark.text);
+  return { marks, used };
+}
+
+/**
+ * One `sections` item: `{ name: "verse", startBar: 0, bars: 8 }`. `indent`
+ * is the item's own line; expanded fields sit one level deeper.
+ */
+function printSection(section: Section, indent: string): string {
+  const inner = indent + INDENT;
+  const entries: (readonly [string, string])[] = [
+    ["name", str(section.name)],
+    ["startBar", num(section.startBar)],
+    ["bars", num(section.bars)],
+  ];
+  if (section.mute && section.mute.length > 0)
+    entries.push([
+      "mute",
+      list(section.mute.map(str), inner, "mute: ".length, 1),
+    ]);
+  if (section.vary) {
+    const vary = Object.entries(section.vary).map(([id, change]) => {
+      const key = /^[A-Za-z_$][A-Za-z0-9_$]*$/.test(id) ? id : str(id);
+      const fields: (readonly [string, string])[] = [];
+      if (change.transpose !== undefined)
+        fields.push(["transpose", num(change.transpose)]);
+      if (change.gain !== undefined) fields.push(["gain", num(change.gain)]);
+      return [key, obj(fields, inner + INDENT, `${key}: `.length, 1)] as const;
+    });
+    if (vary.length > 0)
+      entries.push(["vary", obj(vary, inner, "vary: ".length, 1)]);
+  }
+  return obj(entries, indent, 0, 1);
+}
+
+/**
+ * The form as a string when every name is plain (`"intro verse chorus*2"`),
+ * else as a list of entries.
+ */
+function printForm(form: readonly FormEntry[], indent: string): string {
+  // Word characters only, so the string reads back as the same entries.
+  const plain = form.every((entry) => /^\w+$/u.test(entry.section));
+  if (plain) {
+    const text = form
+      .map(
+        (entry) =>
+          `${entry.section}${(entry.repeat ?? 1) > 1 ? `*${entry.repeat}` : ""}`,
+      )
+      .join(" ");
+    return str(text);
+  }
+  return list(
+    form.map((entry) =>
+      (entry.repeat ?? 1) > 1
+        ? obj(
+            [
+              ["section", str(entry.section)],
+              ["repeat", num(entry.repeat!)],
+            ],
+            indent + INDENT,
+            0,
+            1,
+          )
+        : str(entry.section),
+    ),
+    indent,
+    "form: ".length,
+    1,
+  );
+}
+
 /** `tracks/<slug>/track.ts` for one track of a score. */
 export function printTrack(score: TrackScore, track: Track): string {
   // Rows whose lane still matches their expansion print as generators and
@@ -213,30 +391,85 @@ export function printTrack(score: TrackScore, track: Track): string {
   if (slots) for (const [voice, slot] of slots) voiceFor.set(slot, voice);
   const used = new Set<string>(["track"]);
   const printed = notes.map((note) => {
-    const voice = voiceFor.get(note.pitch);
+    const voice = note.cents ? undefined : voiceFor.get(note.pitch);
     if (voice !== undefined) {
       used.add("hit");
-      return printHit(score, note, voice);
+      return printHit(score, note, voice, INDENT + INDENT);
     }
     used.add("note");
-    return printNote(score, note, !kit && !slots);
+    return printNote(score, note, !kit && !slots, INDENT + INDENT);
   });
+  const grained =
+    track.instrument === "granular" && track.granular !== undefined;
+  if (grained) used.add("granular");
   if (track.sampler) used.add("sampler");
   const wavetable = isWavetableInstrument(track.instrument)
     ? wavetableOf(track)
     : undefined;
   if (wavetable) used.add("wavetable");
+  const stringed = track.instrument === "string" && track.string !== undefined;
+  if (stringed) used.add("stringed");
+  const modalCall =
+    track.instrument === MODAL_INSTRUMENT && track.modal
+      ? printModal(track.modal, INDENT)
+      : undefined;
+  if (modalCall?.startsWith("modal(")) used.add("modal");
 
   const entries: string[] = [
     `id: ${str(track.id)}`,
     `name: ${str(track.name)}`,
   ];
-  if (track.sampler) {
+  if (grained) {
+    entries.push(`instrument: ${printGranular(track.granular!, INDENT)}`);
+    // The sampler a granular track keeps for `grain off`.
+    if (track.sampler)
+      entries.push(`sampler: ${printSampler(track.sampler, INDENT)}`);
+  } else if (track.sampler) {
     entries.push(`instrument: ${printSampler(track.sampler, INDENT)}`);
   } else if (wavetable) {
     entries.push(`instrument: ${printWavetable(wavetable, INDENT)}`);
+  } else if (stringed) {
+    entries.push(`instrument: ${printStringed(track.string!, INDENT)}`);
+  } else if (modalCall) {
+    entries.push(`instrument: ${modalCall}`);
   } else entries.push(`instrument: ${str(track.instrument)}`);
   if (track.kit) entries.push(`kit: ${str(track.kit)}`);
+  if (track.granular && !grained)
+    entries.push(
+      `granular: ${obj(
+        [
+          ...(track.granular.preset
+            ? [["preset", str(track.granular.preset)] as const]
+            : []),
+          ...granularEntries(track.granular, INDENT),
+        ],
+        INDENT,
+        "granular: ".length,
+        1,
+      )}`,
+    );
+  if (track.time) {
+    const beats = (ticks: number) => num(ticks / score.ticksPerBeat);
+    const fields: (readonly [string, string])[] = [];
+    if (track.time.rate !== undefined)
+      fields.push(["rate", num(track.time.rate)]);
+    if (track.time.phase !== undefined)
+      fields.push(["phase", beats(track.time.phase)]);
+    if (track.time.cycle !== undefined)
+      fields.push(["cycle", beats(track.time.cycle)]);
+    if (track.time.steps) {
+      const { shift, hold, drift } = track.time.steps;
+      fields.push([
+        "steps",
+        `{ shift: ${beats(shift)}, hold: ${num(hold)}, drift: ${num(drift)} }`,
+      ]);
+    }
+    entries.push(`time: ${obj(fields, INDENT, "time: ".length, 1)}`);
+  }
+  if (track.tuning)
+    entries.push(
+      `tuning: ${printTuning(track.tuning, INDENT, "tuning: ".length)}`,
+    );
   if (track.muted) entries.push("muted: true");
   if (track.solo) entries.push("solo: true");
   if (track.volume !== 1) entries.push(`volume: ${num(track.volume)}`);
@@ -298,18 +531,31 @@ export function printTrack(score: TrackScore, track: Track): string {
       )}`,
     );
   if (track.fx) {
-    const effects = Object.entries(track.fx) as [FxName, FxValues][];
+    // A whole rig preset prints as `...rig("crunch")` (SDK 1.22.0).
+    const rigName = rigPresetOf(track.fx);
+    if (rigName) used.add("rig");
+    const effects = (Object.entries(track.fx) as [FxName, FxValues][]).filter(
+      ([effect]) =>
+        !rigName ||
+        !(
+          (RIG_STAGES as readonly string[]).includes(effect) ||
+          rigPresetKeys(rigName).includes(effect)
+        ),
+    );
     const inner = INDENT + INDENT;
-    const body = effects.map(([effect, values]) => {
-      // Only values that differ from the default: decoding fills the rest.
-      const params = Object.entries(fxSpec(effect).params)
-        .filter(
-          ([key, spec]) =>
-            values[key] !== undefined && values[key] !== spec.default,
-        )
-        .map(([key]) => [key, value(values[key]!)] as const);
-      return `${inner}${effect}: ${params.length === 0 ? "{}" : obj(params, inner, `${effect}: `.length, 1)},`;
-    });
+    const rigLine = rigName ? [`${inner}...rig(${str(rigName)}),`] : [];
+    const body = rigLine.concat(
+      effects.map(([effect, values]) => {
+        // Only values that differ from the default: decoding fills the rest.
+        const params = Object.entries(fxSpec(effect).params)
+          .filter(
+            ([key, spec]) =>
+              values[key] !== undefined && values[key] !== spec.default,
+          )
+          .map(([key]) => [key, value(values[key]!)] as const);
+        return `${inner}${effect}: ${params.length === 0 ? "{}" : obj(params, inner, `${effect}: `.length, 1)},`;
+      }),
+    );
     entries.push(`fx: {\n${body.join("\n")}\n${INDENT}}`);
   }
   if (track.synth) {
@@ -324,6 +570,22 @@ export function printTrack(score: TrackScore, track: Track): string {
     );
     entries.push(`synth: ${obj(params, INDENT, "synth: ".length, 1)}`);
   }
+  if (track.string && !stringed) {
+    const params = Object.entries(track.string).map(
+      ([key, v]) => [key, value(v!)] as const,
+    );
+    entries.push(`string: ${obj(params, INDENT, "string: ".length, 1)}`);
+  }
+  if (track.keys) {
+    // `{}` is meaningful: it turns the modelled piano on.
+    const params = Object.entries(track.keys).map(
+      ([key, v]) => [key, value(v)] as const,
+    );
+    entries.push(
+      `keys: ${params.length === 0 ? "{}" : obj(params, INDENT, "keys: ".length, 1)}`,
+    );
+  }
+  entries.push(...performanceEntries(score, track));
   const lanes: [string, readonly AutomationPoint[] | undefined][] = [
     ["volume", track.volumeAutomation],
     ["pan", track.panAutomation],
@@ -392,6 +654,10 @@ export function printTrack(score: TrackScore, track: Track): string {
     "every",
     "sampler",
     "wavetable",
+    "stringed",
+    "rig",
+    "granular",
+    "modal",
     "euclid",
     "grid",
   ]
@@ -407,23 +673,185 @@ export function printTrack(score: TrackScore, track: Track): string {
   return lines.join("\n");
 }
 
-function printNote(score: TrackScore, note: Note, named: boolean): string {
-  const pitch = named ? str(midiToPitch(note.pitch)) : num(note.pitch);
+function printNote(
+  score: TrackScore,
+  note: Note,
+  named: boolean,
+  indent: string,
+): string {
+  // A detuned note always prints by name: `"E4-14c"`.
+  const pitch = note.cents
+    ? str(
+        `${midiToPitch(note.pitch)}${note.cents > 0 ? "+" : ""}${num(note.cents)}c`,
+      )
+    : named
+      ? str(midiToPitch(note.pitch))
+      : num(note.pitch);
   const args = [pitch, num(note.startTick / score.ticksPerBeat)];
   const length = note.durationTicks / score.ticksPerBeat;
-  if (length !== 1 || note.velocity !== DEFAULT_VELOCITY)
+  const how = expressionEntries(note, indent + INDENT);
+  if (length !== 1 || note.velocity !== DEFAULT_VELOCITY || how)
     args.push(num(length));
-  if (note.velocity !== DEFAULT_VELOCITY) args.push(num(note.velocity));
-  return `note(${args.join(", ")})`;
+  if (note.velocity !== DEFAULT_VELOCITY || how) args.push(num(note.velocity));
+  return call("note", args, how, indent);
 }
 
-function printHit(score: TrackScore, note: Note, voice: string): string {
+function printHit(
+  score: TrackScore,
+  note: Note,
+  voice: string,
+  indent: string,
+): string {
   const args = [str(voice), num(note.startTick / score.ticksPerBeat)];
   const length = note.durationTicks / score.ticksPerBeat;
-  if (note.velocity !== DEFAULT_VELOCITY || length !== DEFAULT_HIT_LENGTH)
+  const how = expressionEntries(note, indent + INDENT);
+  if (
+    note.velocity !== DEFAULT_VELOCITY ||
+    length !== DEFAULT_HIT_LENGTH ||
+    how
+  )
     args.push(num(note.velocity));
-  if (length !== DEFAULT_HIT_LENGTH) args.push(num(length));
-  return `hit(${args.join(", ")})`;
+  if (length !== DEFAULT_HIT_LENGTH || how) args.push(num(length));
+  return call("hit", args, how, indent);
+}
+
+/**
+ * A note's expression as the fields of its `how` argument, values laid out
+ * for property lines at `indent`; undefined when it has none.
+ */
+function expressionEntries(
+  note: Note,
+  indent: string,
+): (readonly [string, string])[] | undefined {
+  const entries: (readonly [string, string])[] = [];
+  if (note.articulation) entries.push(["art", str(note.articulation)]);
+  if (note.glide !== undefined) entries.push(["glide", num(note.glide)]);
+  if (note.bend) {
+    const points = note.bend.map((p) => `[${num(p.at)}, ${num(p.cents)}]`);
+    // Prettier forces a break on arrays of 2+ arrays that each hold 2+ items.
+    entries.push([
+      "bend",
+      list(points, indent, "bend: ".length, 1, points.length > 1),
+    ]);
+  }
+  if (note.vibrato)
+    entries.push([
+      "vibrato",
+      obj(
+        [
+          ["rate", num(note.vibrato.rate)],
+          ["depth", num(note.vibrato.depth)],
+          ...(note.vibrato.delay !== undefined
+            ? ([["delay", num(note.vibrato.delay)]] as const)
+            : []),
+        ],
+        indent,
+        "vibrato: ".length,
+        1,
+      ),
+    ]);
+  if (note.humanize) {
+    const { timing, velocity, length } = note.humanize;
+    entries.push([
+      "humanize",
+      obj(
+        [
+          ...(timing !== undefined ? ([["timing", num(timing)]] as const) : []),
+          ...(velocity !== undefined
+            ? ([["velocity", num(velocity)]] as const)
+            : []),
+          ...(length !== undefined ? ([["length", num(length)]] as const) : []),
+        ],
+        indent,
+        "humanize: ".length,
+        1,
+      ),
+    ]);
+  }
+  return entries.length === 0 ? undefined : entries;
+}
+
+/**
+ * `name(args, how)` as a list item at `indent`: on one line when it fits,
+ * otherwise with the trailing `how` object hugged and broken one field per
+ * line, the way prettier prints a last object argument.
+ */
+function call(
+  name: string,
+  args: readonly string[],
+  how: readonly (readonly [string, string])[] | undefined,
+  indent: string,
+): string {
+  if (!how) return `${name}(${args.join(", ")})`;
+  const inline = `${name}(${[...args, `{ ${how.map(([k, v]) => `${k}: ${v}`).join(", ")} }`].join(", ")})`;
+  if (!inline.includes("\n") && indent.length + inline.length + 1 <= WIDTH)
+    return inline;
+  const inner = indent + INDENT;
+  const body = how.map(([k, v]) => property(k, v, inner)).join("\n");
+  return `${name}(${[...args, "{"].join(", ")}\n${body}\n${indent}})`;
+}
+
+/** A track's performance fields (SDK 1.15.0) as `key: literal` entries. */
+function performanceEntries(score: TrackScore, track: Track): string[] {
+  const entries: string[] = [];
+  if (track.glide)
+    entries.push(
+      track.glide.mode === "legato"
+        ? `glide: ${num(track.glide.time)}`
+        : `glide: ${obj(
+            [
+              ["time", num(track.glide.time)],
+              ["mode", str(track.glide.mode)],
+            ],
+            INDENT,
+            "glide: ".length,
+            1,
+          )}`,
+    );
+  if (track.pedal) {
+    const events = track.pedal.map(
+      (event) =>
+        `[${num(event.tick / score.ticksPerBeat)}, ${str(event.state)}]`,
+    );
+    entries.push(
+      `pedal: ${list(events, INDENT, "pedal: ".length, 1, events.length > 1)}`,
+    );
+  }
+  if (track.velocityCurve)
+    entries.push(
+      track.velocityCurve.curve !== "fixed" ||
+        (track.velocityCurve.fixed ?? DEFAULT_FIXED_VELOCITY) ===
+          DEFAULT_FIXED_VELOCITY
+        ? `velocityCurve: ${str(track.velocityCurve.curve)}`
+        : `velocityCurve: ${obj(
+            [
+              ["curve", str(track.velocityCurve.curve)],
+              ["fixed", num(track.velocityCurve.fixed!)],
+            ],
+            INDENT,
+            "velocityCurve: ".length,
+            1,
+          )}`,
+    );
+  if (track.humanize) {
+    const { timing, velocity, length, seed } = track.humanize;
+    entries.push(
+      `humanize: ${obj(
+        [
+          ...(timing !== undefined ? ([["timing", num(timing)]] as const) : []),
+          ...(velocity !== undefined
+            ? ([["velocity", num(velocity)]] as const)
+            : []),
+          ...(length !== undefined ? ([["length", num(length)]] as const) : []),
+          ["seed", num(seed)],
+        ],
+        INDENT,
+        "humanize: ".length,
+        1,
+      )}`,
+    );
+  }
+  return entries;
 }
 
 /** `euclid("hat", 7, 16, 2, { velocity: 0.5 })` or `grid("sd", "....x...")`. */
@@ -514,6 +942,76 @@ function printSampler(sampler: Sampler, indent: string): string {
   return `sampler(\n${inner}${shifted},\n${inner}{ mode: ${str(sampler.mode)} },\n${indent})`;
 }
 
+/** `stringed("sitar", { buzz: 0.8 })`: the preset, then its overrides. */
+function printStringed(settings: TrackString, indent: string): string {
+  const name = str(settings.preset ?? DEFAULT_STRING_PRESET);
+  const params = Object.entries(settings)
+    .filter(([key]) => key !== "preset")
+    .map(([key, v]) => [key, value(v!)] as const);
+  if (params.length === 0) return `stringed(${name})`;
+  const inline = `stringed(${name}, { ${params.map(([k, v]) => `${k}: ${v}`).join(", ")} })`;
+  if (indent.length + "instrument: ".length + inline.length + 1 <= WIDTH)
+    return inline;
+  const inner = indent + INDENT;
+  return `stringed(${name}, {\n${params.map(([k, v]) => `${inner}${k}: ${v},`).join("\n")}\n${indent}})`;
+}
+
+/** `[key, literal]` for each stored granular field but the preset. */
+function granularEntries(
+  settings: TrackGranular,
+  indent: string,
+): (readonly [string, string])[] {
+  return Object.entries(settings)
+    .filter(([key]) => key !== "preset")
+    .map(([key, v]) => [
+      key,
+      typeof v === "object"
+        ? printSample(v as SampleRef, indent + INDENT, `${key}: `.length)
+        : value(v as number | string | boolean),
+    ]);
+}
+
+/** `granular("cloud", { scan: 0.1 })`: the preset, then its overrides. */
+function printGranular(settings: TrackGranular, indent: string): string {
+  const inner = indent + INDENT;
+  const params = granularEntries(settings, indent);
+  const name = settings.preset ? str(settings.preset) : undefined;
+  if (params.length === 0) return name ? `granular(${name})` : "granular()";
+  const head = name ? `granular(${name}, ` : "granular(";
+  const inline = `${head}{ ${params.map(([k, v]) => `${k}: ${v}`).join(", ")} })`;
+  if (
+    !inline.includes("\n") &&
+    indent.length + "instrument: ".length + inline.length + 1 <= WIDTH
+  )
+    return inline;
+  return `${head}{\n${params.map(([k, v]) => property(k, v, inner)).join("\n")}\n${indent}})`;
+}
+
+/**
+ * A modal track's instrument: the preset word alone (`"vibes"`) when there
+ * are no overrides, else `modal("vibes", { motor: 4 })` with keys in
+ * `MODAL_PARAMS` order. `marimba` is a legacy word, so the modal marimba
+ * always prints as `modal("marimba")`.
+ */
+function printModal(settings: TrackModal, indent: string): string {
+  const params: [string, string][] = [];
+  for (const key of Object.keys(MODAL_PARAMS) as (keyof TrackModal)[]) {
+    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 && preset !== "marimba") return str(preset);
+  const head = preset ? str(preset) : "";
+  if (params.length === 0) return `modal(${head})`;
+  const lead = head ? `${head}, ` : "";
+  const inline = `modal(${lead}{ ${params.map(([k, v]) => `${k}: ${v}`).join(", ")} })`;
+  if (indent.length + "instrument: ".length + inline.length + 1 <= WIDTH)
+    return inline;
+  const inner = indent + INDENT;
+  return `modal(${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;
@@ -570,10 +1068,99 @@ function printSample(ref: SampleRef, indent: string, prefix: number): string {
   if (ref.accelerate !== undefined)
     entries.push(["accelerate", num(ref.accelerate)]);
   if (ref.squiz !== undefined) entries.push(["squiz", num(ref.squiz)]);
+  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 (entries.length === 1) return str(ref.src);
   return obj(entries, indent, prefix, 1);
 }
 
+/**
+ * A song or track tuning: a bare library name, or an object without the
+ * fields dawg resolved from Scala files (the table of an `scl`, the keymap
+ * of a `kbm`).
+ */
+function printTuning(tuning: Tuning, indent: string, prefix: number): string {
+  const entries: [string, string][] = [];
+  if (tuning.name !== undefined) entries.push(["name", str(tuning.name)]);
+  if (tuning.scl === undefined) {
+    const inner = indent + INDENT;
+    if (tuning.edo !== undefined) entries.push(["edo", num(tuning.edo)]);
+    if (tuning.ratios)
+      entries.push([
+        "ratios",
+        list(tuning.ratios.map(str), inner, "ratios: ".length, 1),
+      ]);
+    if (tuning.cents)
+      entries.push([
+        "cents",
+        fill(tuning.cents.map(num), inner, "cents: ".length, 1),
+      ]);
+  } else entries.push(["scl", str(tuning.scl)]);
+  if (tuning.kbm !== undefined) entries.push(["kbm", str(tuning.kbm)]);
+  if (tuning.ref !== undefined) entries.push(["ref", num(tuning.ref)]);
+  if (tuning.root !== undefined)
+    entries.push(["root", str(midiToPitch(tuning.root))]);
+  if (tuning.map !== undefined) entries.push(["map", str(tuning.map)]);
+  if (entries.length === 1 && entries[0]![0] === "name") return entries[0]![1];
+  return obj(entries, indent, prefix, 1);
+}
+
+/**
+ * Number array the way prettier prints one: inline when it fits, else
+ * filled (as many per line as fit, each followed by a comma).
+ */
+function fill(
+  items: readonly string[],
+  indent: string,
+  prefix: number,
+  trailing: number,
+): string {
+  const inline = `[${items.join(", ")}]`;
+  if (
+    items.length < 2 ||
+    indent.length + prefix + inline.length + trailing <= WIDTH
+  )
+    return inline;
+  const inner = indent + INDENT;
+  const lines: string[] = [];
+  let line = "";
+  for (const item of items) {
+    const next = `${item},`;
+    if (line !== "" && inner.length + line.length + 1 + next.length <= WIDTH)
+      line += ` ${next}`;
+    else {
+      if (line !== "") lines.push(inner + line);
+      line = next;
+    }
+  }
+  lines.push(inner + line);
+  return `[\n${lines.join("\n")}\n${indent}]`;
+}
+
+/** `master: { … }`, always expanded like `fx`; units in chain order. */
+function printMaster(master: SongMaster): string {
+  const inner = INDENT + INDENT;
+  const body: string[] = [];
+  for (const unit of MASTER_UNITS) {
+    const values = master[unit];
+    if (!values) continue;
+    // Only values that differ from the default: loading fills the rest.
+    const params = Object.entries(MASTER_SPECS[unit].params)
+      .filter(
+        ([key, spec]) =>
+          values[key] !== undefined && values[key] !== spec.default,
+      )
+      .map(([key]) => [key, value(values[key]!)] as const);
+    body.push(
+      `${inner}${unit}: ${params.length === 0 ? "{}" : obj(params, inner, `${unit}: `.length, 1)},`,
+    );
+  }
+  if (master.target !== undefined)
+    body.push(`${inner}target: ${num(master.target)},`);
+  return `master: {\n${body.join("\n")}\n${INDENT}}`;
+}
+
 /** Object literal: inline when the line fits, expanded otherwise (prettier keeps both). */
 function obj(
   entries: readonly (readonly [string, string])[],