@hraness/dawg 0.4.1 → 0.6.0

package/core/sdk/v1.ts

@@ -27,7 +27,7 @@
  */
 
 /** SDK release; dawg refreshes the vendored copy when its own is newer. */
-export const SDK_VERSION = "1.13.0";
+export const SDK_VERSION = "1.25.0";
 /** Major of `SDK_VERSION`; `dawg.json` records it as `sdk`. */
 export const SDK_MAJOR = 1;
 
@@ -90,6 +90,26 @@ export function midi(pitch: Pitch): number {
   return value;
 }
 
+/**
+ * A pitch with an optional cents suffix (SDK 1.16.0): `"E4-14c"` is E4
+ * fourteen cents flat, `"A3+50c"` a quarter tone sharp. The offset is
+ * static and sits on top of the song or track tuning; ±1200 at most.
+ */
+export function pitchCents(pitch: Pitch): Readonly<{
+  pitch: number;
+  cents: number;
+}> {
+  const match =
+    typeof pitch === "string"
+      ? pitch.trim().match(/^(.+?)([+-]\d+(?:\.\d+)?)c$/)
+      : null;
+  if (!match) return { pitch: midi(pitch), cents: 0 };
+  const cents = Number(match[2]);
+  if (!(Math.abs(cents) <= 1200))
+    throw new DawgSdkError(`pitch cents must be within ±1200: ${pitch}`);
+  return { pitch: midi(match[1]!), cents };
+}
+
 // ---------------------------------------------------------------------------
 // Drum voices (General MIDI numbers, same table as dawg's `kit`)
 
@@ -161,7 +181,10 @@ export type NoteSpec = Readonly<{
   length: number;
   /** 0..1. */
   velocity: number;
-}>;
+  /** Static offset in cents from a `"E4-14c"` pitch (SDK 1.16.0); absent is 0. */
+  cents?: number;
+}> &
+  NoteExpressionSpec;
 
 /** A drum or sampler hit addressed by voice name; resolved to a pitch slot by `track()`. */
 export type HitSpec = Readonly<{
@@ -170,15 +193,205 @@ export type HitSpec = Readonly<{
   start: number;
   length: number;
   velocity: number;
+}> &
+  NoteExpressionSpec;
+
+/** How a note is articulated (SDK 1.15.0). */
+export type Articulation =
+  "staccato" | "legato" | "accent" | "tenuto" | "marcato" | "ghost";
+
+export const ARTICULATIONS: readonly Articulation[] = Object.freeze([
+  "staccato",
+  "legato",
+  "accent",
+  "tenuto",
+  "marcato",
+  "ghost",
+]);
+
+/** A pitch-bend point: `[at, cents]`, `at` 0..1 through the note. */
+export type BendPoint = readonly [number, number];
+
+/**
+ * How one note is played (SDK 1.15.0). Every field is optional.
+ *
+ * ```ts
+ * note("C4", 0, 1, 0.8, { art: "staccato" })
+ * note("E4", 1, 2, 0.8, { glide: 0.1, vibrato: { depth: 30, delay: 0.3 } })
+ * note("G4", 3, 1, 0.8, { bend: [[0, -200], [0.25, 0]] }) // scoop up a tone
+ * ```
+ */
+export type Expression = Readonly<{
+  /**
+   * `staccato` (half length), `legato` (held into the next note),
+   * `accent` (louder), `tenuto` (full length, a little louder), `marcato`
+   * (two-thirds length, much louder) or `ghost` (half length, much softer).
+   */
+  articulation?: Articulation;
+  /** Short alias of `articulation`. */
+  art?: Articulation;
+  /** Portamento into this note from the track's previous pitch, seconds (0..10). */
+  glide?: number;
+  /** Pitch curve in cents as `[at, cents]` points, `at` 0..1 through the note; linear between points. */
+  bend?: readonly BendPoint[];
+  /** Vibrato: `rate` Hz (default 5.5), `depth` cents either side (default 20), `delay` seconds before it fades in. */
+  vibrato?: Readonly<{ rate?: number; depth?: number; delay?: number }>;
+  /**
+   * This note's humanize (SDK 1.15.0), replacing the track's amounts:
+   * `{ timing ms, velocity %, length % }`; `{}` keeps the note exact.
+   * Humanize just bars 5-8 with `expr({ humanize: { timing: 10 } }, ...)`.
+   */
+  humanize?: Readonly<{ timing?: number; velocity?: number; length?: number }>;
+}>;
+
+/** The expression a built note carries; fields are present only when set. */
+export type NoteExpressionSpec = Readonly<{
+  articulation?: Articulation;
+  glide?: number;
+  bend?: readonly BendPoint[];
+  vibrato?: Readonly<{ rate: number; depth: number; delay?: number }>;
+  humanize?: Readonly<{ timing?: number; velocity?: number; length?: number }>;
 }>;
 
+const DEFAULT_VIBRATO_RATE = 5.5;
+const DEFAULT_VIBRATO_DEPTH = 20;
+
+function expression(
+  input: Expression | undefined,
+  label: string,
+): NoteExpressionSpec {
+  if (input === undefined) return {};
+  if (!isRecord(input))
+    throw new DawgSdkError(`${label} expression must be an object`);
+  for (const key of Object.keys(input))
+    if (
+      !["articulation", "art", "glide", "bend", "vibrato", "humanize"].includes(
+        key,
+      )
+    )
+      throw new DawgSdkError(
+        `${label} expression has an unknown field "${key.slice(0, 32)}" (articulation glide bend vibrato humanize)`,
+      );
+  const out: {
+    articulation?: Articulation;
+    glide?: number;
+    bend?: readonly BendPoint[];
+    vibrato?: Readonly<{ rate: number; depth: number; delay?: number }>;
+    humanize?: Readonly<{
+      timing?: number;
+      velocity?: number;
+      length?: number;
+    }>;
+  } = {};
+  const articulation = input.articulation ?? input.art;
+  if (articulation !== undefined) {
+    if (!ARTICULATIONS.includes(articulation))
+      throw new DawgSdkError(
+        `${label} articulation must be one of ${ARTICULATIONS.join(" ")}`,
+      );
+    out.articulation = articulation;
+  }
+  if (input.glide !== undefined) {
+    const glide = finite(input.glide, `${label} glide`);
+    if (glide < 0) throw new DawgSdkError(`${label} glide must be ≥ 0`);
+    out.glide = glide;
+  }
+  if (input.bend !== undefined) {
+    if (!Array.isArray(input.bend) || input.bend.length > 32)
+      throw new DawgSdkError(
+        `${label} bend must be at most 32 [at, cents] points`,
+      );
+    if (input.bend.length > 0)
+      out.bend = Object.freeze(
+        input.bend.map((point: unknown, index: number): BendPoint => {
+          if (!Array.isArray(point) || point.length !== 2)
+            throw new DawgSdkError(
+              `${label} bend[${index}] must be [at, cents]`,
+            );
+          return Object.freeze([
+            unit(point[0], `${label} bend[${index}] at`),
+            finite(point[1], `${label} bend[${index}] cents`),
+          ] as const);
+        }),
+      );
+  }
+  if (input.vibrato !== undefined) {
+    if (!isRecord(input.vibrato))
+      throw new DawgSdkError(`${label} vibrato must be { rate, depth, delay }`);
+    const delay =
+      input.vibrato.delay === undefined
+        ? 0
+        : finite(input.vibrato.delay, `${label} vibrato delay`);
+    out.vibrato = Object.freeze({
+      rate: finite(
+        input.vibrato.rate ?? DEFAULT_VIBRATO_RATE,
+        `${label} vibrato rate`,
+      ),
+      depth: finite(
+        input.vibrato.depth ?? DEFAULT_VIBRATO_DEPTH,
+        `${label} vibrato depth`,
+      ),
+      ...(delay !== 0 ? { delay } : {}),
+    });
+  }
+  if (input.humanize !== undefined) {
+    if (!isRecord(input.humanize))
+      throw new DawgSdkError(
+        `${label} humanize must be { timing, velocity, length }`,
+      );
+    const amounts: Record<string, number> = {};
+    for (const key of Object.keys(input.humanize)) {
+      if (key !== "timing" && key !== "velocity" && key !== "length")
+        throw new DawgSdkError(
+          `${label} humanize has an unknown field "${key.slice(0, 32)}" (timing velocity length)`,
+        );
+      const value = finite(input.humanize[key], `${label} humanize ${key}`);
+      if (value < 0)
+        throw new DawgSdkError(`${label} humanize ${key} must be ≥ 0`);
+      if (value > 0) amounts[key] = value;
+    }
+    out.humanize = Object.freeze(amounts);
+  }
+  return out;
+}
+
+/**
+ * The same expression on many notes or hits (SDK 1.15.0); a note's own
+ * fields win.
+ *
+ * ```ts
+ * notes: expr(seq("C2 C2 Eb2 C3", { step: 0.25 }), { art: "staccato" })
+ * ```
+ */
+export function expr<T extends NoteSpec | HitSpec>(
+  notes: readonly T[],
+  expression_: Expression,
+): readonly T[] {
+  if (!Array.isArray(notes))
+    throw new DawgSdkError("expr needs an array of notes or hits");
+  const shared = expression(expression_, "expr");
+  return Object.freeze(
+    notes.map((item, index) => {
+      if (!isRecord(item) || (item.kind !== "note" && item.kind !== "hit"))
+        throw new DawgSdkError(
+          `expr notes[${index}] must come from note(), seq(), hit() or hits()`,
+        );
+      return Object.freeze({ ...shared, ...item }) as T;
+    }),
+  );
+}
+
 /**
  * One note. `pitch` is a name or MIDI number, `start` and `length` are
- * beats, `velocity` defaults to 0.8.
+ * beats, `velocity` defaults to 0.8, and `how` adds expression
+ * (articulation, glide, bend, vibrato; SDK 1.15.0). A cents suffix detunes
+ * one note (SDK 1.16.0): `"E4-14c"` (see `pitchCents`).
  *
  * ```ts
  * note("A1", 0, 1)          // A1 on the downbeat for one beat
  * note("A1", 1.5, 0.5, 0.6) // off-beat eighth, softer
+ * note("A1", 2, 1, 0.8, { art: "staccato" })
+ * note("E4-14c", 2)         // a just major third over C, 14 cents flat
  * ```
  */
 export function note(
@@ -186,13 +399,17 @@ export function note(
   start: number,
   length = 1,
   velocity = DEFAULT_VELOCITY,
+  how?: Expression,
 ): NoteSpec {
+  const tuned = pitchCents(pitch);
   return Object.freeze({
     kind: "note",
-    pitch: midi(pitch),
+    pitch: tuned.pitch,
     start: beat(start, "note start"),
     length: positive(length, "note length"),
     velocity: unit(velocity, "note velocity"),
+    ...expression(how, "note"),
+    ...(tuned.cents !== 0 ? { cents: tuned.cents } : {}),
   });
 }
 
@@ -245,13 +462,14 @@ export function seq(
  * One drum or sampler hit. On a `kit` track `voice` is `kick`, `snare`,
  * `clap`, `rim`, `tom`, `hat` or `openhat` (aliases `bd`, `sd`, `cp`, `hh`,
  * `oh` work); on a `sampler()` track it is a voice name. `length` defaults
- * to a sixteenth.
+ * to a sixteenth; `how` adds expression (`{ art: "ghost" }`, SDK 1.15.0).
  */
 export function hit(
   voice: string,
   start: number,
   velocity = DEFAULT_VELOCITY,
   length = DEFAULT_HIT_LENGTH,
+  how?: Expression,
 ): HitSpec {
   if (typeof voice !== "string" || voice.length === 0 || voice.length > 32)
     throw new DawgSdkError("hit voice must be a short name");
@@ -261,6 +479,7 @@ export function hit(
     start: beat(start, "hit start"),
     length: positive(length, "hit length"),
     velocity: unit(velocity, "hit velocity"),
+    ...expression(how, "hit"),
   });
 }
 
@@ -1058,6 +1277,12 @@ export type SampleSpec = Readonly<{
   accelerate?: number;
   /** Like Tidal `squiz`: pitch-raise ratio per zero-crossing cycle (1..32). */
   squiz?: number;
+  /** The file's own tempo (20..400, SDK 1.20.0): the window follows the song's tempo map. */
+  bpm?: number;
+  /** How a fitted window changes time (SDK 1.20.0): `"repitch"` (tape), `"beats"` (onset slices), `"tones"` (keeps pitch). */
+  fitmode?: "repitch" | "beats" | "tones";
+  /** Window length in beats (SDK 1.20.0); `fit` wins over `bpm`, `bpm` over `len`. */
+  len?: number;
 }>;
 
 /** Result of `sampler()`; pass it as a track's `instrument`. */
@@ -1098,7 +1323,7 @@ export function sampler(
       throw new DawgSdkError(
         `sampler voice "${name}" must be a short identifier`,
       );
-    out[name] = sample(voices[name]!, name);
+    out[name] = sampleSpec(voices[name]!, name);
   }
   return Object.freeze({ kind: "sampler", voices: Object.freeze(out), mode });
 }
@@ -1214,6 +1439,314 @@ export function wavetable(
   return Object.freeze(out) as WavetableSpec;
 }
 
+/** Instrument name of the 0.6 string engine (`Track.string`). */
+export const STRING_INSTRUMENT = "string";
+
+/**
+ * String engine settings (SDK 1.21.0): a `preset` (`nylon`, `steel`,
+ * `electric`, `jangle`, `ebass`, `slap`, `upright`, `sitar`, `tanpura`,
+ * `harpsichord`, `lute`, `oud`, `setar`, `tar`, `santur`, `dulcimer`, `koto`,
+ * `harp`, `banjo`, `tres`, `requinto`) plus any parameter to override
+ * (`ring`, `bright`, `damp`, `pos`, `mute`, `buzz`, `body`, `sym`, ...).
+ * dawg validates names and ranges; see **Strings** in DAWG.md.
+ */
+export type StringInput = Readonly<
+  { preset?: string } & Record<string, number | string | undefined>
+>;
+
+/** Result of `stringed()`; pass it as a track's `instrument`. */
+export type StringSpec = Readonly<{ kind: "string" } & StringInput>;
+
+/**
+ * A plucked string instrument (SDK 1.21.0): a preset and overrides.
+ *
+ * instrument: stringed("nylon")
+ * instrument: stringed("sitar", { buzz: 0.8, sym: 0.5 })
+ */
+export function stringed(
+  preset = "nylon",
+  params: Readonly<Record<string, number | string>> = {},
+): StringSpec {
+  if (typeof preset !== "string" || preset.length === 0)
+    throw new DawgSdkError("stringed needs a preset name");
+  if (!isRecord(params))
+    throw new DawgSdkError("stringed params must be an object");
+  const out: Record<string, number | string> = { kind: "string", preset };
+  for (const [key, value] of Object.entries(params)) {
+    if (value === undefined || key === "kind" || key === "preset") continue;
+    out[key] =
+      typeof value === "string" ? value : finite(value, `string ${key}`);
+  }
+  return Object.freeze(out) as StringSpec;
+}
+
+/** Instrument name of the 0.6 granular engine (`Track.granular`). */
+export const GRANULAR_INSTRUMENT = "granular";
+
+/**
+ * Granular settings (SDK 1.23.0). `src` is a sample (`sample(...)` shape,
+ * pinned like a sampler voice) or a built-in synth render
+ * `"synth:<preset>[@note]"` (default `synth:pad`, nothing to download);
+ * `preset` is `cloud`, `hold`, `sparkle`, `swarm`, `stutter`, `microloop`,
+ * `backwards` or `dust`; every other key overrides one parameter (`grain`
+ * seconds, `overlap`, `scan`, `pos`, `begin`, `end`, `spray`, `jitter`,
+ * `pitch`, `detune`, `shimmer`, `shimint`, `spread`, `window`, `reverse`,
+ * `freeze`, `repeat`, `hold`, `drift`, `drate`, `attack`, `release`,
+ * `veltone`, `gain`, `seed`, `root`). dawg validates names and ranges; see
+ * **Granular** in DAWG.md.
+ */
+export type GranularInput = Readonly<
+  {
+    src?: string | SampleSpec;
+    preset?: string;
+  } & Record<string, number | string | boolean | SampleSpec | undefined>
+>;
+
+/** Result of `granular()`; pass it as a track's `instrument`. */
+export type GranularSpec = Readonly<{ kind: "granular" } & GranularInput>;
+
+/**
+ * A granular instrument (SDK 1.23.0): an optional preset, then overrides.
+ *
+ * ```ts
+ * instrument: granular("cloud")
+ * instrument: granular("hold", { src: "samples/choir.wav", scan: 0 })
+ * instrument: granular({ src: "synth:bell@72", grain: 0.08, overlap: 6 })
+ * ```
+ */
+export function granular(
+  preset?: string | GranularInput,
+  params: GranularInput = {},
+): GranularSpec {
+  const fields =
+    typeof preset === "object" && preset !== null ? preset : params;
+  if (!isRecord(fields))
+    throw new DawgSdkError("granular params must be an object");
+  const out: Record<string, unknown> = { kind: "granular" };
+  if (typeof preset === "string") {
+    if (preset.length === 0)
+      throw new DawgSdkError("granular needs a preset name");
+    out.preset = preset;
+  } else if (preset !== undefined && (typeof preset !== "object" || !preset))
+    throw new DawgSdkError("granular takes a preset name or params");
+  for (const [key, value] of Object.entries(fields)) {
+    if (value === undefined || key === "kind") continue;
+    if (key === "src")
+      out.src =
+        typeof value === "string" && value.startsWith("synth:")
+          ? value
+          : sampleSpec(value as string | SampleSpec, "granular src");
+    else if (key === "preset" && typeof preset === "string") continue;
+    else if (key === "root" && typeof value === "string")
+      out.root = midi(value as Pitch);
+    else if (
+      typeof value === "number" ||
+      typeof value === "string" ||
+      typeof value === "boolean"
+    )
+      out[key] =
+        typeof value === "number" ? finite(value, `granular ${key}`) : value;
+    else throw new DawgSdkError(`granular ${key} must be a value`);
+  }
+  return Object.freeze(out) as GranularSpec;
+}
+
+/** Instrument name that selects the modal mallet-and-bell engine (SDK 1.25.0). */
+export const MODAL_INSTRUMENT = "modal";
+
+/** Modal presets (dawg's core/resonators.ts). */
+export type ModalPresetName =
+  | "marimba"
+  | "vibes"
+  | "xylophone"
+  | "glock"
+  | "celesta"
+  | "chimes"
+  | "kalimba"
+  | "mbira"
+  | "steelpan"
+  | "bowl"
+  | "gong"
+  | "timpani";
+
+/** Modal overrides; omitted means the preset's value. dawg validates ranges. */
+export type ModalParams = Readonly<{
+  /** `yarn` `cord` `rubber` `plastic` `brass`: sets hardness. */
+  mallet?: "yarn" | "cord" | "rubber" | "plastic" | "brass";
+  /** Mallet hardness 0..1: brighter, shorter contact. */
+  hardness?: number;
+  /** Strike position 0..1 (0.5 is the bar's centre). */
+  position?: number;
+  /** Fundamental ring time (T60 seconds). */
+  ring?: number;
+  /** How much faster upper modes die (octaves of decay per octave). */
+  tilt?: number;
+  /** Damping on note-off 0..1 (0 lets the bar ring). */
+  damp?: number;
+  /** Choke time after note-off, seconds. */
+  release?: number;
+  /** Vibraphone motor rate Hz and depth 0..1. */
+  motor?: number;
+  motordepth?: number;
+  /** Beat between paired gamelan modes, Hz. */
+  ombak?: number;
+  /** Mbira buzz 0..1 and mallet click 0..1. */
+  buzz?: number;
+  click?: number;
+  /** Strike pitch bend in semitones and its decay seconds (Strudel penv/pdecay). */
+  strikebend?: number;
+  strikedecay?: number;
+  /** Output level 0..2 (1 is the preset level). */
+  gain?: number;
+  /** Mode table override (`marimba`, `bell`, `gong`, …). */
+  body?: string;
+}>;
+
+const MODAL_KEYS = Object.freeze([
+  "mallet",
+  "hardness",
+  "position",
+  "ring",
+  "tilt",
+  "damp",
+  "release",
+  "motor",
+  "motordepth",
+  "ombak",
+  "buzz",
+  "click",
+  "strikebend",
+  "strikedecay",
+  "gain",
+  "body",
+] as const);
+
+/** Mallet words (core/resonators.ts MODAL_MALLETS). */
+const MODAL_MALLET_WORDS: readonly string[] = Object.freeze([
+  "yarn",
+  "cord",
+  "rubber",
+  "plastic",
+  "brass",
+]);
+
+/** Mode tables a `body` override may name (core/resonators.ts MODAL_BODIES). */
+const MODAL_BODY_WORDS: readonly string[] = Object.freeze([
+  "marimba",
+  "vibraphone",
+  "xylophone",
+  "glockenspiel",
+  "celesta",
+  "chimes",
+  "crotale",
+  "mbira",
+  "kalimba",
+  "musicbox",
+  "toypiano",
+  "saron",
+  "bonang",
+  "gender",
+  "kempul",
+  "gong",
+  "bell",
+  "steelpan",
+  "bowl",
+  "timpani",
+  "tabla",
+  "frame",
+]);
+
+/** Numeric ranges (core/resonators.ts MODAL_PARAMS min..max). */
+const MODAL_RANGES: Readonly<Record<string, readonly [number, number]>> =
+  Object.freeze({
+    hardness: [0, 1],
+    position: [0, 1],
+    ring: [0.05, 30],
+    tilt: [0, 2],
+    damp: [0, 1],
+    release: [0.005, 2],
+    motor: [0, 12],
+    motordepth: [0, 1],
+    ombak: [0, 12],
+    buzz: [0, 1],
+    click: [0, 1],
+    strikebend: [-24, 24],
+    strikedecay: [0.001, 2],
+    gain: [0, 2],
+  });
+
+const MODAL_PRESET_WORDS: readonly string[] = Object.freeze([
+  "marimba",
+  "vibes",
+  "xylophone",
+  "glock",
+  "celesta",
+  "chimes",
+  "kalimba",
+  "mbira",
+  "steelpan",
+  "bowl",
+  "gong",
+  "timpani",
+]);
+
+/** Result of `modal()`; pass it as a track's `instrument`. */
+export type ModalSpec = Readonly<
+  { kind: "modal"; preset?: ModalPresetName } & ModalParams
+>;
+
+/**
+ * Mallets and bells on the modal engine (SDK 1.25.0): a preset and
+ * optional overrides. A preset word alone (`instrument: "vibes"`) is the
+ * same as `modal("vibes")`, except `"marimba"`, which stays the legacy
+ * marimba voice; `modal("marimba")` is the modal one.
+ *
+ * ```ts
+ * instrument: modal("vibes", { motor: 4, hardness: 0.6 })
+ * instrument: modal("marimba", { mallet: "rubber" })
+ * instrument: modal({ ring: 2 }) // default preset (marimba)
+ * ```
+ */
+export function modal(
+  preset?: ModalPresetName | ModalParams,
+  params: ModalParams = {},
+): ModalSpec {
+  const overrides = isRecord(preset) ? preset : params;
+  const name = isRecord(preset) ? undefined : preset;
+  if (!isRecord(overrides))
+    throw new DawgSdkError("modal params must be an object");
+  const out: Record<string, unknown> = { kind: "modal" };
+  if (name !== undefined) {
+    if (typeof name !== "string" || !MODAL_PRESET_WORDS.includes(name))
+      throw new DawgSdkError(
+        `modal preset "${String(name).slice(0, 32)}" is not one of ${MODAL_PRESET_WORDS.join(" ")}`,
+      );
+    out.preset = name;
+  }
+  for (const key of Object.keys(overrides)) {
+    const value = (overrides as Record<string, unknown>)[key];
+    if (value === undefined) continue;
+    if (key === "mallet" || key === "body") {
+      const words = key === "mallet" ? MODAL_MALLET_WORDS : MODAL_BODY_WORDS;
+      if (typeof value !== "string" || !words.includes(value))
+        throw new DawgSdkError(
+          `modal ${key} "${String(value).slice(0, 32)}" is not one of ${words.join(" ")}`,
+        );
+      out[key] = value;
+    } else if ((MODAL_KEYS as readonly string[]).includes(key)) {
+      const number = finite(value, `modal ${key}`);
+      const [min, max] = MODAL_RANGES[key]!;
+      if (number < min || number > max)
+        throw new DawgSdkError(`modal ${key} must be ${min}..${max}`);
+      out[key] = number;
+    } else
+      throw new DawgSdkError(
+        `modal has no parameter "${key.slice(0, 32)}" (${MODAL_KEYS.join(" ")})`,
+      );
+  }
+  return Object.freeze(out) as ModalSpec;
+}
+
 /**
  * `count` equal slices of one file as voices `prefix0 … prefixN-1`, for
  * chopped breaks: `sampler(slices("samples/break.wav", 8, "brk"))`, then
@@ -1226,7 +1759,7 @@ export function slices(
 ): Record<string, SampleSpec> {
   if (!Number.isInteger(count) || count < 1 || count > 64)
     throw new DawgSdkError("slices count must be an integer 1..64");
-  const base = sample(src, prefix);
+  const base = sampleSpec(src, prefix);
   const begin = base.begin ?? 0;
   const end = base.end ?? 1;
   const span = (end - begin) / count;
@@ -1241,7 +1774,7 @@ export function slices(
   return voices;
 }
 
-function sample(value: string | SampleSpec, name: string): SampleSpec {
+function sampleSpec(value: string | SampleSpec, name: string): SampleSpec {
   const spec = typeof value === "string" ? { src: value } : value;
   if (!isRecord(spec) || typeof spec.src !== "string" || spec.src.length === 0)
     throw new DawgSdkError(`sampler voice ${name} needs a src path`);
@@ -1264,6 +1797,9 @@ function sample(value: string | SampleSpec, name: string): SampleSpec {
     fit?: boolean;
     accelerate?: number;
     squiz?: number;
+    bpm?: number;
+    fitmode?: "repitch" | "beats" | "tones";
+    len?: number;
   } = { src: spec.src };
   if (spec.src.startsWith("pack:")) {
     if (spec.sha256 !== undefined)
@@ -1313,9 +1849,36 @@ function sample(value: string | SampleSpec, name: string): SampleSpec {
   if (spec.accelerate !== undefined)
     out.accelerate = finite(spec.accelerate, `${name} accelerate`);
   if (spec.squiz !== undefined) out.squiz = finite(spec.squiz, `${name} squiz`);
+  if (spec.bpm !== undefined) out.bpm = finite(spec.bpm, `${name} bpm`);
+  if (spec.fitmode !== undefined) {
+    if (
+      spec.fitmode !== "repitch" &&
+      spec.fitmode !== "beats" &&
+      spec.fitmode !== "tones"
+    )
+      throw new DawgSdkError(
+        `${name} fitmode must be "repitch", "beats" or "tones"`,
+      );
+    out.fitmode = spec.fitmode;
+  }
+  if (spec.len !== undefined) out.len = finite(spec.len, `${name} len`);
   return Object.freeze(out);
 }
 
+/**
+ * One sample file with options (SDK 1.20.0), for `sampler({ brk: ... })`:
+ * `sample("samples/break.wav", { bpm: 174, fitmode: "beats" })` plays a
+ * 174 BPM break in time with the song, cut at its hits.
+ */
+export function sample(
+  src: string,
+  options: Omit<SampleSpec, "src"> = {},
+): SampleSpec {
+  if (typeof src !== "string" || src.length === 0)
+    throw new DawgSdkError("sample() needs a src path");
+  return Object.freeze({ ...options, src });
+}
+
 // ---------------------------------------------------------------------------
 // Tracks
 
@@ -1345,14 +1908,177 @@ export type AutomationInput = Readonly<{
   wt?: readonly Point[];
 }>;
 
+/**
+ * Every rig preset (SDK 1.22.0), kept equal to `RIG_PRESETS` in
+ * core/fx.ts by `print-rig.test.ts`: the stomp, head and cab stages plus
+ * the companion effects a few rigs need (funk's and wah's autofilter,
+ * bachata's chorus, jangle's compressor). `spring`'s short room is the
+ * track's `reverb`, not `fx`: give it as
+ * `reverb: { mix: 0.3, size: 0.35, fade: 1.5, predelay: 0, dim: 3500 }`.
+ */
+export const RIG_PRESETS: Readonly<
+  Record<
+    string,
+    Readonly<
+      Record<"stomp" | "head" | "cab", EffectParams | undefined> &
+        Readonly<Record<string, EffectParams | undefined>>
+    >
+  >
+> = Object.freeze({
+  clean: {
+    stomp: undefined,
+    head: { type: "clean", gain: 3, treble: 6 },
+    cab: { type: "1x12" },
+  },
+  crunch: {
+    stomp: undefined,
+    head: { type: "crunch", gain: 5 },
+    cab: { type: "4x12" },
+  },
+  punk: {
+    stomp: undefined,
+    head: { type: "crunch", gain: 7, mid: 6, master: 6 },
+    cab: { type: "4x12", mic: 0.2 },
+  },
+  ragged: {
+    stomp: { type: "face", gain: 6, tone: 0.6 },
+    head: { type: "chime", gain: 4 },
+    cab: { type: "2x12" },
+  },
+  lead: {
+    stomp: { type: "od", gain: 3, tone: 0.5, level: 3 },
+    head: { type: "lead", gain: 6, mid: 6 },
+    cab: { type: "4x12" },
+  },
+  metal: {
+    stomp: { type: "od", gain: 0, tone: 0.6, level: 6 },
+    head: { type: "high", gain: 7, bass: 6, mid: 3, treble: 7, gate: -55 },
+    cab: { type: "4x12", mic: 0.2 },
+  },
+  fuzz: {
+    stomp: { type: "fuzz", gain: 7, tone: 0.5 },
+    head: { type: "clean", gain: 4 },
+    cab: { type: "2x12" },
+  },
+  octave: {
+    stomp: { type: "octave", gain: 6, tone: 0.6, octave: 0.8 },
+    head: { type: "clean", gain: 3 },
+    cab: { type: "1x12" },
+  },
+  funk: {
+    stomp: undefined,
+    head: { type: "clean", gain: 2, treble: 7, presence: 6 },
+    cab: { type: "2x12" },
+    autofilter: {
+      type: "bpf",
+      sync: 0,
+      rate: 0.01,
+      depth: 0,
+      follow: 3,
+      cutoff: 500,
+      resonance: 0.6,
+    },
+  },
+  wah: {
+    stomp: undefined,
+    head: { type: "crunch", gain: 4 },
+    cab: { type: "2x12" },
+    autofilter: {
+      type: "bpf",
+      sync: 0.5,
+      depth: 2,
+      shape: "sine",
+      cutoff: 700,
+      resonance: 0.6,
+    },
+  },
+  bachata: {
+    stomp: undefined,
+    head: { type: "clean", gain: 2, mid: 6, treble: 7 },
+    cab: { type: "1x12", mic: 0.2 },
+    chorus: { rate: 0.8, depth: 0.25, mix: 0.3 },
+  },
+  spring: {
+    stomp: undefined,
+    head: { type: "clean", gain: 3, treble: 6 },
+    cab: { type: "open" },
+  },
+  bassdrive: {
+    stomp: { type: "od", gain: 4, tone: 0.5, mix: 0.6 },
+    head: { type: "bass", gain: 4 },
+    cab: { type: "8x10" },
+  },
+  reese: {
+    stomp: { type: "rat", gain: 3, tone: 0.3, mix: 0.5 },
+    head: { type: "bass", gain: 6, master: 6 },
+    cab: { type: "1x15" },
+  },
+  jangle: {
+    stomp: undefined,
+    head: { type: "chime", gain: 3, treble: 7 },
+    cab: { type: "2x12", mic: 0.2 },
+    compressor: { threshold: -20, ratio: 4, attack: 0.01, release: 0.15 },
+  },
+  alt: {
+    stomp: { type: "rat", gain: 6, tone: 0.4 },
+    head: { type: "crunch", gain: 4 },
+    cab: { type: "4x12" },
+  },
+});
+
+/**
+ * A guitar rig for a track's `fx` (SDK 1.22.0): the stomp → head → cab
+ * stages of rig preset `name` and its companion effects (as the `rig`
+ * command sets them), with optional per-stage overrides. Spread it
+ * into `fx` next to other effects:
+ *
+ * ```ts
+ * fx: { ...rig("crunch"), chorus: {} }
+ * fx: { ...rig("metal", { head: { gain: 9 } }) }
+ * ```
+ */
+export function rig(
+  name: string,
+  overrides: Readonly<
+    Partial<Record<"stomp" | "head" | "cab", EffectParams>>
+  > = {},
+): FxInput {
+  if (
+    typeof name !== "string" ||
+    !Object.prototype.hasOwnProperty.call(RIG_PRESETS, name)
+  )
+    throw new DawgSdkError(
+      `unknown rig "${String(name)}" (rigs: ${Object.keys(RIG_PRESETS).join(", ")})`,
+    );
+  if (!isRecord(overrides))
+    throw new DawgSdkError("rig overrides must be an object");
+  const out: Record<string, EffectParams> = {};
+  // Companion effects first, then the stages in chain order.
+  for (const [effect, values] of Object.entries(RIG_PRESETS[name]!))
+    if (values && effect !== "stomp" && effect !== "head" && effect !== "cab")
+      out[effect] = Object.freeze({ ...values });
+  for (const stage of ["stomp", "head", "cab"] as const) {
+    const base = RIG_PRESETS[name]![stage];
+    const extra = overrides[stage];
+    if (extra !== undefined && !isRecord(extra))
+      throw new DawgSdkError(`rig ${stage} overrides must be an object`);
+    if (base || extra)
+      out[stage] = Object.freeze({ ...(base ?? {}), ...(extra ?? {}) });
+  }
+  return Object.freeze(out);
+}
+
 /** One effect's parameters; omitted ones take dawg's defaults. */
 export type EffectParams = Readonly<Record<string, number | string | boolean>>;
 
 /**
  * Insert effects by name, rendered in the fixed chain order
- * filter → djf → autofilter → vowel → crush → distort → tremolo →
- * compressor → pan → phaser → chorus → leslie → postgain → delay → reverb.
- * Keys here: djf, autofilter, vowel, crush, distort, tremolo, compressor,
+ * filter → djf → autofilter → vowel → crush → distort → stomp → head →
+ * cab → tremolo → compressor → pan → phaser → chorus → leslie → postgain →
+ * delay → reverb. The guitar rig (stomp, head, cab; SDK 1.22.0) is easiest
+ * as `...rig("crunch")`.
+ * Keys here: djf, autofilter, vowel, crush, distort, stomp, head, cab,
+ * tremolo, compressor,
  * phaser, chorus, leslie, postgain, plus the mix-bus keys `orbit`
  * (`{ orbit: 2 }`, SDK 1.9.0) and `duck` (`{ orbit: 2, depth: 0.85 }`:
  * this track's onsets duck every other track on that orbit). See
@@ -1366,6 +2092,53 @@ export type FxInput = Readonly<Record<string, EffectParams>>;
  * `"synth-<param>"` (e.g. `"synth-lpf"`), read at each note's onset.
  * Every parameter, range and default: **Synth** in DAWG.md.
  */
+/**
+ * Modelled piano settings (SDK 1.24.0), for a track whose instrument is a
+ * piano family (`"grand"`, `"upright"`, `"felt"`, `"honkytonk"`,
+ * `"prepared"`; the words `"ballad"` and `"lofi"` pick presets). Every field
+ * is optional; `{}` is the family's own sound. Automate a parameter with
+ * `automation.fx["keys-<param>"]` (hardness, touch, decay, release, knock,
+ * noise, felt), read at each note's onset. Ranges: **Keys** in DAWG.md.
+ */
+export type KeysInput = Readonly<{
+  /** A named preset: grand ballad upright felt lofi honkytonk prepared. */
+  preset?: string;
+  /** Hammer hardness 0..1: brightness at a given velocity (0.5). */
+  hardness?: number;
+  /** Velocity sensitivity 0..1 (1). */
+  touch?: number;
+  /** Inharmonicity multiplier 0..4 (1 grand, 2.5 upright, 0 harmonic). */
+  inharm?: number;
+  /** Unison detune in cents 0..30 (0.7; honkytonk 16). */
+  unison?: number;
+  /** Sustain time multiplier 0.1..4 (1). */
+  decay?: number;
+  /** Damper time multiplier 0.1..4 (1). */
+  release?: number;
+  /** Hammer position along the string 0.04..0.3 (0.12). */
+  strike?: number;
+  /** Aftersound share 0..1 (0.3). */
+  after?: number;
+  /** Soundboard knock 0..1 (0.5). */
+  knock?: number;
+  /** Key and damper mechanics 0..1 (0.25). */
+  noise?: number;
+  /** Felt strip 0..1 (0; felt family 1). */
+  felt?: number;
+  /** Share of prepared keys 0..1 (0; prepared family 0.6). */
+  prep?: number;
+  /** Keyboard stereo width 0..1 (0.6). */
+  width?: number;
+  /** Octave stretch 0..1 (1); 0 keeps every key exactly on its tuning. */
+  stretch?: number;
+  /** Body EQ: grand upright felt honkytonk prepared (the family's own). */
+  body?: string;
+  /** Pitch wobble rate in Hz (tape wow), 0 off. */
+  vib?: number;
+  /** Pitch wobble depth in semitones (0.5). */
+  vibmod?: number;
+}>;
+
 export type SynthInput = Readonly<{
   attack?: number;
   decay?: number;
@@ -1449,17 +2222,60 @@ export type TrackInput = Readonly<{
    * `triangle`, and Strudel's `sawtooth`, `supersaw`, `pulse`, `user`,
    * `white`, `pink`, `brown`, `crackle`, and the ZzFX sounds `z_sine`,
    * `z_triangle`, `z_sawtooth`, `z_square`, `z_tan`, `z_noise`), `kit` for drums,
-   * `sampler(...)` or `wavetable(...)`. Default `sine`.
+   * `sampler(...)` or `wavetable(...)`, or a mallet or bell (`vibes`,
+   * `glock`, `gong`, … or `modal(...)`, SDK 1.25.0). Default `sine`.
+   */
+  instrument?:
+    | string
+    | SamplerSpec
+    | WavetableSpec
+    | StringSpec
+    | GranularSpec
+    | ModalSpec;
+  /**
+   * The sampler a `granular(...)` track keeps while it grains one of its
+   * voices (SDK 1.23.0); `grain off` plays it again.
+   */
+  sampler?: SamplerSpec | null;
+  /**
+   * Granular engine (SDK 1.23.0) for an `instrument: "granular"` track, or
+   * use `instrument: granular("cloud", {...})` or a word (`"cloud"`).
    */
-  instrument?: string | SamplerSpec | WavetableSpec;
+  granular?: GranularInput | null;
   /**
    * Synthesized drum kit for an `instrument: "kit"` track: `syn808`,
    * `syn909`, `acoustic`, `lofi`, `electro` or `trap`. Omit for the default
    * voices.
    */
   kit?: string;
+  /**
+   * The track's own clock against the song (SDK 1.14.0): `rate` 1.5 plays
+   * three beats in two, `phase` starts it that many beats later, `cycle`
+   * repeats its first `cycle` beats (a 3-beat cycle over 4/4 is polymeter).
+   * `{ cycle: 3, rate: 13 / 12 }` drifts against a twin and realigns, the
+   * tape phasing of Reich's Come Out; `phasing()` works the rate out for
+   * you, and `stepPhasing()` gives Piano Phase's shift and hold.
+   */
+  time?: TrackTimeInput;
+  /**
+   * This track's tuning over the song's (SDK 1.16.0): a library name such
+   * as `"pelog"` or `{ edo, ratios, cents, scl, kbm, ref, root, map }`.
+   * `{ ref: 432 }` alone keeps the song's table at another pitch.
+   */
+  tuning?: TuningInput | null;
   /** Synth voice parameters, Strudel names (`{ attack: 0.01, lpf: 800 }`). */
   synth?: SynthInput;
+  /**
+   * String engine (SDK 1.21.0) for an `instrument: "string"` track, or use
+   * `instrument: stringed("sitar", {...})` or a preset word (`"nylon"`).
+   */
+  string?: StringInput | null;
+  /**
+   * Modelled piano settings (SDK 1.24.0) for `instrument: "grand"` and the
+   * other piano families; `{}` is the family's sound. The word `"piano"`
+   * keeps the classic 0.4 tone; use `"grand"` for the modelled piano.
+   */
+  keys?: KeysInput;
   muted?: boolean;
   /** When any track is soloed only soloed tracks play. */
   solo?: boolean;
@@ -1476,6 +2292,34 @@ export type TrackInput = Readonly<{
   /** Insert effects by name (`{ distort: { drive: 3 }, chorus: {} }`). */
   fx?: FxInput;
   automation?: AutomationInput;
+  /**
+   * Glide between notes (SDK 1.15.0): seconds (`glide: 0.08`, TB-303 style
+   * legato) or `{ time, mode }`. Mode `legato` glides only into a note that
+   * overlaps the previous one and does not retrigger it; `mono` always
+   * glides and retriggers; `poly` glides every voice of a chord from the
+   * matching voice of the previous one.
+   */
+  glide?: number | Readonly<{ time?: number; mode?: GlideMode }>;
+  /** Sustain pedal changes as `[beat, "down" | "half" | "up"]` (SDK 1.15.0). */
+  pedal?: readonly (readonly [number, PedalState])[];
+  /**
+   * Velocity response (SDK 1.15.0): `soft` (quiet notes louder), `hard`
+   * (needs a firm touch), `fixed` (every note at 0.8, like an organ) or
+   * `{ curve: "fixed", fixed: 0.6 }`. Default `linear`.
+   */
+  velocityCurve?:
+    VelocityCurveName | Readonly<{ curve: VelocityCurveName; fixed?: number }>;
+  /**
+   * Seeded humanize applied when dawg renders, so the notes stay as written
+   * (SDK 1.15.0): `timing` ms either side, `velocity` and `length` in
+   * percent, `seed` (default 1) picks another take.
+   */
+  humanize?: Readonly<{
+    timing?: number;
+    velocity?: number;
+    length?: number;
+    seed?: number;
+  }>;
   /** `note()`/`seq()` for pitched tracks, `hit()`/`hits()` for kits and one-shot samplers. */
   notes?: readonly (NoteSpec | HitSpec)[];
   /**
@@ -1533,6 +2377,22 @@ export type ReverbInput = Readonly<{
       }>;
 }>;
 
+/** `track({ time })`: every field optional; absent follows the song. */
+export type TrackTimeInput = Readonly<{
+  /** Tempo ratio against the song, 0.125..8 (1 = in step). */
+  rate?: number;
+  /** Beats the track's pattern starts late (negative: early); it wraps. */
+  phase?: number;
+  /** Beats of the track that repeat, default the whole song loop. */
+  cycle?: number;
+  /**
+   * Stepped phasing (SDK 1.19.0), as in Reich's Piano Phase: hold `hold`
+   * cycles in step, then move `shift` beats ahead over `drift` cycles, and
+   * repeat. Needs `cycle`; replaces `rate`. `stepPhasing()` builds it.
+   */
+  steps?: Readonly<{ shift: number; hold: number; drift: number }>;
+}>;
+
 /** Frozen track built by `track()`; `song()` consumes it. Beats, not ticks. */
 export type TrackSpec = Readonly<{
   kind: "track";
@@ -1555,14 +2415,147 @@ export type TrackSpec = Readonly<{
   synth: SynthInput | null;
   sampler: SamplerSpec | null;
   wavetable: WavetableSpec | null;
+  /** String engine settings (SDK 1.21.0); present only when set. */
+  string?: StringInput;
+  /** Granular engine settings (SDK 1.23.0); null when not granular. */
+  granular?: GranularInput | null;
   automation: Readonly<Required<AutomationInput>>;
   /** Every hit resolved to its pitch slot. */
   notes: readonly NoteSpec[];
   /** Rhythm rows in order (voice names as written). */
   rhythm: readonly RhythmSpec[];
   kit: string | null;
+  /** Present only when `track({ time })` set something. */
+  time?: TrackTimeInput;
+  /** Performance (SDK 1.15.0); present only when set. */
+  glide?: Readonly<{ time: number; mode: GlideMode }>;
+  pedal?: readonly (readonly [number, PedalState])[];
+  velocityCurve?: Readonly<{
+    curve: Exclude<VelocityCurveName, "linear">;
+    fixed?: number;
+  }>;
+  humanize?: Readonly<{
+    timing?: number;
+    velocity?: number;
+    length?: number;
+    seed: number;
+  }>;
+  tuning: ScoreTuning | null;
+  /** Modelled piano settings (SDK 1.24.0); present only when set. */
+  keys?: KeysInput;
+  /** Modal settings (SDK 1.25.0); present only on a modal track. */
+  modal?: Readonly<{ preset?: ModalPresetName } & ModalParams>;
 }>;
 
+export type GlideMode = "legato" | "mono" | "poly";
+export type PedalState = "down" | "half" | "up";
+export type VelocityCurveName = "linear" | "soft" | "hard" | "fixed";
+
+const DEFAULT_GLIDE_SECONDS = 0.06;
+const DEFAULT_FIXED_VELOCITY = 0.8;
+
+/** Normalizes `track()` performance options; dawg validates the ranges. */
+function trackPerformance(
+  input: TrackInput,
+  name: string,
+): Partial<Pick<TrackSpec, "glide" | "pedal" | "velocityCurve" | "humanize">> {
+  const out: {
+    glide?: TrackSpec["glide"];
+    pedal?: TrackSpec["pedal"];
+    velocityCurve?: TrackSpec["velocityCurve"];
+    humanize?: TrackSpec["humanize"];
+  } = {};
+  if (input.glide !== undefined) {
+    const raw =
+      typeof input.glide === "number" ? { time: input.glide } : input.glide;
+    if (!isRecord(raw))
+      throw new DawgSdkError(
+        `track ${name}: glide must be seconds or { time, mode }`,
+      );
+    const mode = raw.mode ?? "legato";
+    if (!["legato", "mono", "poly"].includes(mode))
+      throw new DawgSdkError(
+        `track ${name}: glide mode must be legato, mono or poly`,
+      );
+    out.glide = Object.freeze({
+      time: finite(raw.time ?? DEFAULT_GLIDE_SECONDS, `${name} glide time`),
+      mode,
+    });
+  }
+  if (input.pedal !== undefined) {
+    if (!Array.isArray(input.pedal) || input.pedal.length > 1024)
+      throw new DawgSdkError(
+        `track ${name}: pedal must be at most 1024 [beat, "down" | "half" | "up"] events`,
+      );
+    if (input.pedal.length > 0)
+      out.pedal = Object.freeze(
+        input.pedal.map((event: unknown, index: number) => {
+          if (
+            !Array.isArray(event) ||
+            event.length !== 2 ||
+            !["down", "half", "up"].includes(event[1] as string)
+          )
+            throw new DawgSdkError(
+              `track ${name}: pedal[${index}] must be [beat, "down" | "half" | "up"]`,
+            );
+          return Object.freeze([
+            beat(event[0], `${name} pedal[${index}] beat`),
+            event[1] as PedalState,
+          ] as const);
+        }),
+      );
+  }
+  if (input.velocityCurve !== undefined) {
+    const raw =
+      typeof input.velocityCurve === "string"
+        ? { curve: input.velocityCurve }
+        : input.velocityCurve;
+    if (
+      !isRecord(raw) ||
+      !["linear", "soft", "hard", "fixed"].includes(raw.curve as string)
+    )
+      throw new DawgSdkError(
+        `track ${name}: velocityCurve must be linear, soft, hard or fixed`,
+      );
+    if (raw.curve === "fixed")
+      out.velocityCurve = Object.freeze({
+        curve: "fixed",
+        fixed: unit(
+          raw.fixed ?? DEFAULT_FIXED_VELOCITY,
+          `${name} velocityCurve fixed`,
+        ),
+      });
+    else if (raw.curve !== "linear")
+      out.velocityCurve = Object.freeze({ curve: raw.curve });
+  }
+  if (input.humanize !== undefined) {
+    if (!isRecord(input.humanize))
+      throw new DawgSdkError(
+        `track ${name}: humanize must be { timing, velocity, length, seed }`,
+      );
+    const amount = (key: "timing" | "velocity" | "length") => {
+      const value = input.humanize![key];
+      return value === undefined ? 0 : finite(value, `${name} humanize ${key}`);
+    };
+    const timing = amount("timing");
+    const velocity = amount("velocity");
+    const length = amount("length");
+    const seed = input.humanize.seed ?? 1;
+    if (!Number.isInteger(seed) || seed < 0)
+      throw new DawgSdkError(
+        `track ${name}: humanize seed must be an integer ≥ 0`,
+      );
+    if (timing !== 0 || velocity !== 0 || length !== 0)
+      out.humanize = Object.freeze({
+        ...(timing !== 0 ? { timing } : {}),
+        ...(velocity !== 0 ? { velocity } : {}),
+        ...(length !== 0 ? { length } : {}),
+        seed,
+      });
+  }
+  return out;
+}
+
 /**
  * A raw ZzFX parameter array (Strudel `zzfx([...])`, ZzFX's own layout:
  * volume, randomness, frequency, attack, sustain, release, shape,
@@ -1653,34 +2646,77 @@ export function track(input: TrackInput): TrackSpec {
   if (typeof id !== "string" || id.length === 0 || id.length > 64)
     throw new DawgSdkError(`track ${name}: id must be 1..64 characters`);
   const rawInstrument = input.instrument ?? "sine";
+  // A granular track may keep the sampler it grains (`grain off` goes back).
+  const keptSampler =
+    isRecord(input.sampler) &&
+    input.sampler.kind === "sampler" &&
+    isRecord(rawInstrument) &&
+    rawInstrument.kind === "granular"
+      ? localizeSampler(input.sampler as SamplerSpec, slug)
+      : null;
+  if (input.sampler !== undefined && input.sampler !== null && !keptSampler)
+    throw new DawgSdkError(
+      `track ${name}: sampler: is only for a granular(...) track; use instrument: sampler({...})`,
+    );
   const samplerSpec =
     isRecord(rawInstrument) && rawInstrument.kind === "sampler"
       ? localizeSampler(rawInstrument as SamplerSpec, slug)
-      : null;
+      : keptSampler;
   const wavetableSpec =
     isRecord(rawInstrument) && rawInstrument.kind === "wavetable"
       ? localizeWavetable(rawInstrument as WavetableSpec, slug)
       : null;
-  const instrument = samplerSpec
-    ? SAMPLER_INSTRUMENT
-    : wavetableSpec
-      ? WAVETABLE_INSTRUMENT
-      : typeof rawInstrument === "string"
-        ? rawInstrument
-        : undefined;
+  const stringFromInstrument =
+    isRecord(rawInstrument) && rawInstrument.kind === "string"
+      ? stringInput(rawInstrument, name)
+      : null;
+  const granularFromInstrument =
+    isRecord(rawInstrument) && rawInstrument.kind === "granular"
+      ? granularInput(rawInstrument, name, slug)
+      : null;
+  const word =
+    typeof rawInstrument === "string"
+      ? resolveInstrumentWord(rawInstrument)
+      : undefined;
+  const modalSpec = trackModal(rawInstrument);
+  const instrument = granularFromInstrument
+    ? GRANULAR_INSTRUMENT
+    : samplerSpec
+      ? SAMPLER_INSTRUMENT
+      : wavetableSpec
+        ? WAVETABLE_INSTRUMENT
+        : stringFromInstrument
+          ? STRING_INSTRUMENT
+          : modalSpec
+            ? MODAL_INSTRUMENT
+            : typeof rawInstrument === "string"
+              ? (word?.instrument ?? rawInstrument)
+              : undefined;
+  // A granular word (`"cloud"`) turns the engine on with its preset.
+  const granularSpec =
+    granularInput(input.granular, name, slug) ??
+    granularFromInstrument ??
+    (word?.field === "granular" && word.preset
+      ? Object.freeze({ preset: word.preset })
+      : instrument === GRANULAR_INSTRUMENT
+        ? Object.freeze({})
+        : null);
   if (
     instrument === undefined ||
     instrument.length === 0 ||
     instrument.length > 64
   )
     throw new DawgSdkError(
-      `track ${name}: instrument must be a voice name, "kit", sampler(...) or wavetable(...)`,
+      `track ${name}: instrument must be a voice name, "kit", sampler(...), wavetable(...), stringed(...), granular(...) or modal(...)`,
     );
   if (instrument === SAMPLER_INSTRUMENT && !samplerSpec)
     throw new DawgSdkError(
       `track ${name}: use instrument: sampler({...}) for a sampler track`,
     );
-  const slots = samplerSpec ? voiceSlots(samplerSpec) : undefined;
+  const slots =
+    samplerSpec && instrument === SAMPLER_INSTRUMENT
+      ? voiceSlots(samplerSpec)
+      : undefined;
   const kit = KIT_INSTRUMENTS.includes(instrument.trim().toLowerCase());
   const notes = (input.notes ?? []).map((item, index) => {
     if (!isRecord(item) || (item.kind !== "note" && item.kind !== "hit"))
@@ -1703,13 +2739,8 @@ export function track(input: TrackInput): TrackSpec {
             ? `track ${name}: unknown sampler voice "${spec.voice}" (${[...slots.keys()].join(" ")})`
             : `track ${name}: hit("${spec.voice}") needs instrument "kit" or sampler(...)`,
       );
-    return Object.freeze({
-      kind: "note" as const,
-      pitch,
-      start: spec.start,
-      length: spec.length,
-      velocity: spec.velocity,
-    });
+    const { kind: _kind, voice: _voice, ...rest } = spec;
+    return Object.freeze({ ...rest, kind: "note" as const, pitch });
   });
   if (notes.length > 4096)
     throw new DawgSdkError(`track ${name}: at most 4096 notes`);
@@ -1760,8 +2791,25 @@ export function track(input: TrackInput): TrackSpec {
       throw new DawgSdkError(
         `track ${name}: unknown automation lane "${key}" (${AUTOMATION_KEYS.join(" ")})`,
       );
-  const filter =
-    input.filter === undefined || input.filter === null
+  // A keys preset word (`"lofi"`, `"ballad"`) brings its preset's effects,
+  // as the prompt does; explicit filter, fx and reverb win.
+  const presetFx = keysPresetFx(input.keys, rawInstrument);
+  if (presetFx) {
+    input = {
+      ...input,
+      ...(input.filter === undefined && presetFx.filter
+        ? { filter: presetFx.filter }
+        : {}),
+      ...(input.reverb === undefined && presetFx.reverb
+        ? { reverb: presetFx.reverb }
+        : {}),
+      ...(presetFx.fx && input.fx !== null
+        ? { fx: { ...presetFx.fx, ...(isRecord(input.fx) ? input.fx : {}) } }
+        : {}),
+    };
+  }
+  const filter =
+    input.filter === undefined || input.filter === null
       ? null
       : Object.freeze({
           cutoff: finite(input.filter.cutoff, `${name} filter.cutoff`),
@@ -1802,8 +2850,26 @@ export function track(input: TrackInput): TrackSpec {
             ? {}
             : { ir: reverbIr(input.reverb.ir, name, slug) }),
         });
-  const fx = fxInput(input.fx, name);
+  // A guitar alias (`instrument: "jangle"`) also loads its rig; stages and
+  // effects the track's own `fx` names win.
+  const aliasRig =
+    typeof rawInstrument === "string"
+      ? resolveInstrumentWord(rawInstrument)?.fx
+      : undefined;
+  const fx = fxInput(
+    aliasRig === undefined
+      ? input.fx
+      : { ...rig(aliasRig), ...(isRecord(input.fx) ? input.fx : {}) },
+    name,
+  );
   const synth = synthInput(input.synth, name);
+  // A string preset word (`"nylon"`) turns the engine on with its preset.
+  const string =
+    stringInput(input.string, name) ??
+    stringFromInstrument ??
+    (word?.field === "string" && word.preset
+      ? Object.freeze({ preset: word.preset })
+      : null);
   return Object.freeze({
     kind: "track",
     id,
@@ -1821,6 +2887,8 @@ export function track(input: TrackInput): TrackSpec {
     synth,
     sampler: samplerSpec,
     wavetable: wavetableSpec,
+    ...(string ? { string } : {}),
+    ...(granularSpec ? { granular: granularSpec } : {}),
     automation: Object.freeze({
       volume: lane("volume"),
       pan: lane("pan"),
@@ -1834,9 +2902,165 @@ export function track(input: TrackInput): TrackSpec {
     notes: Object.freeze(notes),
     rhythm: Object.freeze([...rhythm]),
     kit: drumKit === null ? null : drumKit.trim(),
+    ...trackTime(input.time, name),
+    ...trackPerformance(input, name),
+    tuning: tuningSpec(input.tuning, `track ${name}`),
+    ...keysSpec(input.keys, rawInstrument, name),
+    ...(modalSpec ? { modal: modalSpec } : {}),
   });
 }
 
+/**
+ * Effects the keys presets set with the voice: a copy of `KEYS_PRESETS`
+ * filter, fx and reverb in core/keys.ts (core/keys.test.ts checks they
+ * match the prompt's `piano <preset>`).
+ */
+const KEYS_PRESET_FX: Readonly<
+  Record<
+    string,
+    Readonly<{
+      filter?: FilterInput;
+      fx?: FxInput;
+      reverb?: ReverbInput;
+    }>
+  >
+> = Object.freeze({
+  ballad: { reverb: { mix: 0.25, size: 0.7 } },
+  felt: { reverb: { mix: 0.2, size: 0.5 } },
+  lofi: {
+    filter: { cutoff: 3500, resonance: 0.1 },
+    fx: { crush: { bits: 10 } },
+  },
+});
+
+/**
+ * The preset effects an instrument word brings: a preset word that is not
+ * also its family (`"lofi"`, `"ballad"`), or any preset word without
+ * `keys` (`"felt"`). A printed track names its family and always prints
+ * `keys`, so print → eval never adds them twice.
+ */
+function keysPresetFx(
+  keys: unknown,
+  word: unknown,
+): (typeof KEYS_PRESET_FX)[string] | undefined {
+  if (typeof word !== "string") return undefined;
+  const meaning = resolveInstrumentWord(word);
+  if (meaning?.field !== "keys" || !meaning.preset) return undefined;
+  if (keys !== undefined && keys !== null && word === meaning.instrument)
+    return undefined;
+  return KEYS_PRESET_FX[meaning.preset];
+}
+
+/**
+ * `keys` for `track()`: the input as given, or `{ preset }` when the
+ * instrument word names a keys preset (`"grand"`, `"lofi"`), so the word
+ * alone plays the modelled piano. dawg validates the values.
+ */
+function keysSpec(
+  input: unknown,
+  word: unknown,
+  name: string,
+): { keys?: KeysInput } {
+  const meaning =
+    typeof word === "string" ? resolveInstrumentWord(word) : undefined;
+  const preset = meaning?.field === "keys" ? meaning.preset : undefined;
+  if (input === undefined || input === null)
+    return preset ? { keys: Object.freeze({ preset }) } : {};
+  if (!isRecord(input))
+    throw new DawgSdkError(`track ${name}: keys must be an object`);
+  const out: Record<string, EffectValue> = {};
+  // A preset word (`"lofi"`) keeps its preset under given overrides; a
+  // family word (`"upright"`) with `keys` is exactly the given keys.
+  if (preset && input.preset === undefined && word !== meaning?.instrument)
+    out.preset = preset;
+  for (const [key, value] of Object.entries(input)) {
+    if (value === undefined) continue;
+    out[key] = effectValue(value, `${name} keys.${key}`);
+  }
+  return { keys: Object.freeze(out) };
+}
+
+/**
+ * The modal field an instrument makes: `modal(...)`, or a modal preset
+ * word (`"vibes"`, `"glockenspiel"`). The bare words `"modal"` and
+ * `"marimba"` keep their pre-0.6 meaning and make none.
+ */
+function trackModal(
+  raw: unknown,
+): Readonly<{ preset?: ModalPresetName } & ModalParams> | undefined {
+  if (isRecord(raw) && raw.kind === "modal") {
+    const { kind: _kind, ...fields } = raw as ModalSpec;
+    return Object.freeze(fields);
+  }
+  if (typeof raw !== "string" || raw === MODAL_INSTRUMENT) return undefined;
+  const meaning = resolveInstrumentWord(raw);
+  if (meaning?.instrument !== MODAL_INSTRUMENT || !meaning.preset)
+    return undefined;
+  return Object.freeze({ preset: meaning.preset as ModalPresetName });
+}
+
+function trackTime(input: unknown, name: string): { time?: TrackTimeInput } {
+  if (input === undefined || input === null) return {};
+  if (!isRecord(input))
+    throw new DawgSdkError(`track ${name}: time must be an object`);
+  for (const key of Object.keys(input))
+    if (key !== "rate" && key !== "phase" && key !== "cycle" && key !== "steps")
+      throw new DawgSdkError(
+        `track ${name}: time takes rate, phase, cycle and steps, not ${key}`,
+      );
+  const out: {
+    rate?: number;
+    phase?: number;
+    cycle?: number;
+    steps?: { shift: number; hold: number; drift: number };
+  } = {};
+  if (input.rate !== undefined) {
+    const rate = finite(input.rate, `track ${name} time.rate`);
+    if (rate < 0.125 || rate > 8)
+      throw new DawgSdkError(`track ${name}: time.rate must be 0.125..8`);
+    if (rate !== 1) out.rate = rate;
+  }
+  if (input.phase !== undefined) {
+    const phase = finite(input.phase, `track ${name} time.phase`);
+    if (phase !== 0) out.phase = phase;
+  }
+  if (input.cycle !== undefined) {
+    const cycle = finite(input.cycle, `track ${name} time.cycle`);
+    if (cycle <= 0)
+      throw new DawgSdkError(`track ${name}: time.cycle must be > 0 beats`);
+    out.cycle = cycle;
+  }
+  if (input.steps !== undefined) {
+    if (!isRecord(input.steps))
+      throw new DawgSdkError(`track ${name}: time.steps must be an object`);
+    if (out.cycle === undefined)
+      throw new DawgSdkError(`track ${name}: time.steps needs a cycle`);
+    if (out.rate !== undefined)
+      throw new DawgSdkError(
+        `track ${name}: time takes rate or steps, not both`,
+      );
+    out.steps = phaseSteps(input.steps, out.cycle, `track ${name} time.steps`);
+  }
+  return Object.keys(out).length > 0 ? { time: Object.freeze(out) } : {};
+}
+
+function phaseSteps(
+  input: Record<string, unknown>,
+  cycle: number,
+  label: string,
+): Readonly<{ shift: number; hold: number; drift: number }> {
+  const shift = positive(input.shift, `${label}.shift`);
+  if (shift > cycle)
+    throw new DawgSdkError(`${label}.shift must be at most the cycle`);
+  const hold = finite(input.hold, `${label}.hold`);
+  if (!Number.isInteger(hold) || hold < 0 || hold > 64)
+    throw new DawgSdkError(`${label}.hold must be a whole 0..64 cycles`);
+  const drift = finite(input.drift, `${label}.drift`);
+  if (!Number.isInteger(drift) || drift < 1 || drift > 64)
+    throw new DawgSdkError(`${label}.drift must be a whole 1..64 cycles`);
+  return Object.freeze({ shift, hold, drift });
+}
+
 const AUTOMATION_KEYS: readonly (keyof AutomationInput)[] = Object.freeze([
   "volume",
   "pan",
@@ -1885,6 +3109,21 @@ function fxInput(input: unknown, name: string): FxInput | null {
   return Object.keys(out).length > 0 ? Object.freeze(out) : null;
 }
 
+function stringInput(input: unknown, name: string): StringInput | null {
+  if (input === undefined || input === null) return null;
+  if (!isRecord(input))
+    throw new DawgSdkError(`track ${name}: string must be an object`);
+  const out: Record<string, number | string> = {};
+  for (const [key, value] of Object.entries(input)) {
+    if (value === undefined || key === "kind") continue;
+    out[key] =
+      typeof value === "string"
+        ? value
+        : finite(value, `${name} string.${key}`);
+  }
+  return Object.freeze(out);
+}
+
 function synthInput(input: unknown, name: string): SynthInput | null {
   if (input === undefined || input === null) return null;
   if (!isRecord(input))
@@ -1970,7 +3209,7 @@ function reverbIr(
     throw new DawgSdkError(`track ${name}: reverb.ir needs a src`);
   const src = spec.src.trim().replace(/^\.\//, "");
   if (src.startsWith("pack:")) {
-    const ref = sample(spec as SampleSpec, `${name} reverb.ir`);
+    const ref = sampleSpec(spec as SampleSpec, `${name} reverb.ir`);
     return Object.freeze({
       src: ref.src,
       ...(ref.sha256 ? { sha256: ref.sha256 } : {}),
@@ -1982,6 +3221,41 @@ function reverbIr(
   return src.startsWith("tracks/") ? src : `tracks/${slug}/${src}`;
 }
 
+/** Validates `granular` input and localizes a sample source like a voice. */
+function granularInput(
+  input: unknown,
+  name: string,
+  slug: string,
+): GranularInput | null {
+  if (input === undefined || input === null) return null;
+  if (!isRecord(input))
+    throw new DawgSdkError(`track ${name}: granular must be an object`);
+  const out: Record<string, unknown> = {};
+  for (const [key, value] of Object.entries(input)) {
+    if (value === undefined || key === "kind") continue;
+    if (key === "src" && isRecord(value)) {
+      const ref = sampleSpec(value as SampleSpec, `${name} granular src`);
+      const src = ref.src.replace(/^\.\//, "");
+      out.src = Object.freeze({
+        ...ref,
+        src:
+          src.startsWith("tracks/") || src.startsWith("pack:")
+            ? src
+            : `tracks/${slug}/${src}`,
+      });
+    } else if (key === "src" && typeof value === "string")
+      out.src = value.startsWith("synth:")
+        ? value
+        : granularInput({ src: { src: value } }, name, slug)!.src;
+    else if (typeof value === "number")
+      out[key] = finite(value, `${name} granular.${key}`);
+    else if (typeof value === "string" || typeof value === "boolean")
+      out[key] = value;
+    else throw new DawgSdkError(`${name} granular.${key} must be a value`);
+  }
+  return Object.freeze(out) as GranularInput;
+}
+
 /** `./wavetables/x.wav` → `tracks/<slug>/wavetables/x.wav`, like sampler files. */
 function localizeWavetable(spec: WavetableSpec, slug: string): WavetableSpec {
   const src = spec.table.src;
@@ -2018,19 +3292,103 @@ function localizeSampler(spec: SamplerSpec, slug: string): SamplerSpec {
 export type SongInput = Readonly<{
   /** BPM 20..300, default 120. */
   tempo?: number;
-  /** `[beatsPerBar, noteValue]` or just `beatsPerBar`; default `[4, 4]`. Only the numerator is stored. */
+  /**
+   * `[beatsPerBar, noteValue]` or just `beatsPerBar`; default `[4, 4]`.
+   * A note value other than 4 is stored as a meter change at bar 1, so
+   * `[6, 8]` is six eighths (three quarter-note beats) per bar.
+   */
   meter?: readonly [number, number] | number;
   /** Loop length in bars, 1..256, default 4. */
   bars?: number;
-  /** Free text such as `"A minor"`, or null. */
+  /**
+   * Free text such as `"A minor"`, or null. A scale name after the tonic
+   * picks a scale: `"D dorian"`, `"E hijaz"`, `"C yaman"`, `"C messiaen-3"`.
+   */
   key?: string | null;
+  /**
+   * Song tuning (SDK 1.16.0), default 12-TET at A4 = 440 Hz: a library name
+   * (`"19-edo"`, `"just"`, `"pelog"`, `"yaman"`) or `{ edo, ratios, cents,
+   * scl, kbm, ref, root, map }`. See `TuningInput`.
+   */
+  tuning?: TuningInput | null;
   /** Integer ticks per beat, default 480. Leave it alone unless you know why. */
   ticksPerBeat?: number;
+  /**
+   * Tempo changes, meter changes and fermatas (SDK 1.14.0), in any order:
+   * `tempo()`, `ramp()`, `rit()`, `accel()`, `fermata()` and `meter()`.
+   * `tempo` above stays the opening tempo and `meter` the opening meter.
+   * `rit()` and `accel()` return two marks; list them as they come.
+   */
+  time?: readonly (TimeMark | readonly TimeMark[])[];
   /** Tracks in score order; each from `track()`. */
   tracks: readonly TrackSpec[];
+  /** Master chain and loudness target after every track and orbit bus (SDK 1.17.0); omit for none. */
+  master?: MasterInput;
+  /**
+   * Named bar ranges (SDK 1.18.0): `{ name: "chorus", startBar: 8, bars: 8 }`,
+   * optionally with `mute: ["pad"]` and `vary: { lead: { transpose: 12 } }`.
+   */
+  sections?: readonly SongSection[];
+  /**
+   * The order sections play, with repeats (SDK 1.18.0): `"intro verse
+   * chorus*2 outro"`, or `["intro", { section: "chorus", repeat: 2 }]`.
+   * Absent plays the bars straight through.
+   */
+  form?: string | readonly (string | SongFormEntry)[];
+  /** The section playback loops (SDK 1.18.0); export ignores it. */
+  loopSection?: string;
+}>;
+
+/** A song section (SDK 1.18.0); bars are 0-based like beats. */
+export type SongSection = Readonly<{
+  /** `intro`, `verse`, `chorus 2`, `A`: 1..32 characters, unique ignoring case. */
+  name: string;
+  /** First bar, 0-based. */
+  startBar: number;
+  /** Length in bars, at least 1. */
+  bars: number;
+  /** Track ids silent in this section. */
+  mute?: readonly string[];
+  /** Per-track changes in this section: semitones and a velocity multiplier. */
+  vary?: Readonly<
+    Record<string, Readonly<{ transpose?: number; gain?: number }>>
+  >;
+}>;
+
+/** One step of the song form (SDK 1.18.0). */
+export type SongFormEntry = Readonly<{ section: string; repeat?: number }>;
+
+/**
+ * The song master (SDK 1.17.0), processed in the fixed order
+ * eq → glue → tape → width → limiter after the tracks and orbit buses are
+ * summed. Each unit present is on; `{}` takes every default. `target` is
+ * an integrated loudness in LUFS (ITU-R BS.1770-4), -40..-3: renders drive
+ * the limiter (or, without one, a clean gain) to reach it. Streaming is
+ * -14, club -8, loud hyperpop or gabber -6, classical -20, broadcast -23.
+ * The SDK takes LUFS numbers only: a target name such as `master target
+ * club` in the prompt also sets a limiter preset, so write that unit out.
+ * DAWG.md "Master and loudness" lists every parameter with its range.
+ *
+ * ```ts
+ * master: { glue: { ratio: 2 }, limiter: { ceiling: -1 }, target: -14 }
+ * ```
+ */
+export type MasterInput = Readonly<{
+  /** `low`/`high` shelves and `bell1`/`bell2` gains in dB, with `…freq` and `…q`. */
+  eq?: EffectParams;
+  /** Bus compressor: threshold, ratio, attack, release (ms), knee, makeup, mix, hpf. */
+  glue?: EffectParams;
+  /** Saturation: drive (dB), bias, tone (Hz), mix. */
+  tape?: EffectParams;
+  /** Stereo width 0..2 (1 unchanged) and `mono` bass below this many Hz. */
+  width?: EffectParams;
+  /** True-peak limiter: ceiling (dBTP), gain, release, lookahead (ms), truepeak. */
+  limiter?: EffectParams;
+  /** Integrated loudness target in LUFS (a negative number, -40..-3). */
+  target?: number;
 }>;
 
-/** A stored note: integer ticks. */
+/** A stored note: integer ticks; expression fields only when set. */
 export type ScoreNote = Readonly<{
   id: string;
   trackId: string;
@@ -2038,6 +3396,13 @@ export type ScoreNote = Readonly<{
   durationTicks: number;
   pitch: number;
   velocity: number;
+  articulation?: Articulation;
+  glide?: number;
+  bend?: readonly Readonly<{ at: number; cents: number }>[];
+  vibrato?: Readonly<{ rate: number; depth: number; delay?: number }>;
+  humanize?: Readonly<{ timing?: number; velocity?: number; length?: number }>;
+  /** Static cents offset (SDK 1.16.0); absent is 0. */
+  cents?: number;
 }>;
 
 /** A stored automation point: integer tick. */
@@ -2063,6 +3428,9 @@ export type ScoreSampleRef = Readonly<{
   fit?: boolean;
   accelerate?: number;
   squiz?: number;
+  bpm?: number;
+  fitmode?: "repitch" | "beats" | "tones";
+  len?: number;
 }>;
 
 /** A stored track; optional fields are present only when set. */
@@ -2086,6 +3454,7 @@ export type ScoreTrack = Readonly<{
   fx?: FxInput;
   fxAutomation?: Readonly<Record<string, readonly ScorePoint[]>>;
   synth?: SynthInput;
+  keys?: KeysInput;
   sampler?: Readonly<{
     voices: Readonly<Record<string, ScoreSampleRef>>;
     mode: "oneshot" | "keyed";
@@ -2094,8 +3463,27 @@ export type ScoreTrack = Readonly<{
   rhythm?: readonly Readonly<Record<string, unknown>>[];
   /** Synth kit name; dawg validates it. */
   kit?: string;
+  /** `rate`, plus `phase` and `cycle` in ticks. */
+  time?: Readonly<{
+    rate?: number;
+    phase?: number;
+    cycle?: number;
+    steps?: Readonly<{ shift: number; hold: number; drift: number }>;
+  }>;
+  /** Track tuning; dawg validates it (SDK 1.16.0). */
+  tuning?: ScoreTuning;
   wavetable?: Readonly<{ table: ScoreSampleRef } & WavetableParams>;
   wtAutomation?: readonly ScorePoint[];
+  /** String engine settings; dawg validates them (SDK 1.21.0). */
+  string?: StringInput;
+  /** Granular settings (SDK 1.23.0); present only when set. */
+  granular?: GranularInput;
+  /** Modal settings (SDK 1.25.0). */
+  modal?: TrackSpec["modal"];
+  glide?: TrackSpec["glide"];
+  pedal?: readonly Readonly<{ tick: number; state: PedalState }>[];
+  velocityCurve?: TrackSpec["velocityCurve"];
+  humanize?: TrackSpec["humanize"];
 }>;
 
 /**
@@ -2111,10 +3499,167 @@ export type Song = Readonly<{
   bars: number;
   ticksPerBeat: number;
   key: string | null;
+  /** Present only when `song({ time })` has marks. */
+  time?: ScoreTime;
+  /** Present only when the song sets one (SDK 1.16.0). */
+  tuning?: ScoreTuning;
   tracks: readonly ScoreTrack[];
   notes: readonly ScoreNote[];
+  master?: MasterInput;
+  /** Present only when the song has sections (SDK 1.18.0). */
+  sections?: readonly SongSection[];
+  /** Present only when the song has a form (SDK 1.18.0). */
+  form?: readonly SongFormEntry[];
+  /** Present only when a section loops (SDK 1.18.0). */
+  loopSection?: string;
 }>;
 
+/** A stored song `time`: ticks, and 0-based bar indexes. */
+export type ScoreTime = Readonly<{
+  tempo?: readonly Readonly<{
+    tick: number;
+    bpm: number;
+    ramp?: "linear" | "exp";
+  }>[];
+  meter?: readonly Readonly<{
+    bar: number;
+    beatsPerBar: number;
+    beatUnit?: number;
+  }>[];
+  fermatas?: readonly Readonly<{ tick: number; beats: number }>[];
+}>;
+
+const MASTER_KEYS = ["eq", "glue", "tape", "width", "limiter", "target"];
+
+/** Shape checks only; dawg validates every value when it loads the song. */
+function masterData(input: unknown): MasterInput | undefined {
+  if (input === undefined || input === null) return undefined;
+  if (!isRecord(input)) throw new DawgSdkError("song master must be an object");
+  const out: Record<string, unknown> = {};
+  for (const [key, value] of Object.entries(input)) {
+    if (value === undefined) continue;
+    if (!MASTER_KEYS.includes(key))
+      throw new DawgSdkError(
+        `song master has no "${key}"; use ${MASTER_KEYS.join(", ")}`,
+      );
+    if (key === "target") {
+      if (typeof value === "string")
+        throw new DawgSdkError(
+          `song master target takes LUFS, e.g. target: -14 (streaming), -8 (club, with limiter: { release: 60, lookahead: 2 }), -6 (loud, with limiter: { release: 20, lookahead: 1 }); got "${value}"`,
+        );
+      out.target = finite(value as number, "song master target");
+      continue;
+    }
+    if (!isRecord(value))
+      throw new DawgSdkError(`song master ${key} must be an object`);
+    out[key] = Object.freeze({ ...value });
+  }
+  return Object.keys(out).length > 0
+    ? (Object.freeze(out) as MasterInput)
+    : undefined;
+}
+
+/** `"intro verse chorus*2"` (comma separated when a name has a space). */
+function parseSongForm(
+  form: NonNullable<SongInput["form"]>,
+): readonly SongFormEntry[] {
+  const items: (string | SongFormEntry)[] =
+    typeof form === "string"
+      ? (form.includes(",") ? form.split(",") : form.trim().split(/\s+/u))
+          .map((item) => item.trim())
+          .filter((item) => item !== "")
+      : Array.isArray(form)
+        ? [...form]
+        : (() => {
+            throw new DawgSdkError(
+              "song form must be a string or an array of section names",
+            );
+          })();
+  return Object.freeze(
+    items.map((item, index) => {
+      let entry: unknown = item;
+      if (typeof item === "string") {
+        const match = /^(.*?)\s*(?:\*|\bx|×)\s*(\d+)$/iu.exec(item);
+        entry =
+          match && match[1]!.length > 0
+            ? { section: match[1]!, repeat: Number(match[2]) }
+            : { section: item };
+      }
+      if (!isRecord(entry) || typeof entry.section !== "string")
+        throw new DawgSdkError(
+          `song form[${index}] must be a section name or { section, repeat }`,
+        );
+      const repeat = entry.repeat ?? 1;
+      if (
+        !Number.isInteger(repeat) ||
+        (repeat as number) < 1 ||
+        (repeat as number) > 16
+      )
+        throw new DawgSdkError(`song form[${index}] repeat must be 1..16`);
+      return Object.freeze(
+        repeat === 1
+          ? { section: entry.section }
+          : { section: entry.section, repeat: repeat as number },
+      );
+    }),
+  );
+}
+
+function songSections(
+  sections: NonNullable<SongInput["sections"]>,
+): readonly SongSection[] {
+  if (!Array.isArray(sections))
+    throw new DawgSdkError("song sections must be an array");
+  if (sections.length > 64) throw new DawgSdkError("song has over 64 sections");
+  return Object.freeze(
+    sections.map((section, index) => {
+      const where = `song sections[${index}]`;
+      if (!isRecord(section) || typeof section.name !== "string")
+        throw new DawgSdkError(`${where} needs a name`);
+      const stored: Record<string, unknown> = {
+        name: section.name,
+        startBar: finite(section.startBar, `${where}.startBar`),
+        bars: finite(section.bars, `${where}.bars`),
+      };
+      if (section.mute !== undefined) {
+        if (
+          !Array.isArray(section.mute) ||
+          section.mute.some((id) => typeof id !== "string")
+        )
+          throw new DawgSdkError(`${where}.mute must be track ids`);
+        if (section.mute.length > 0)
+          stored.mute = Object.freeze([...section.mute]);
+      }
+      if (section.vary !== undefined) {
+        if (!isRecord(section.vary))
+          throw new DawgSdkError(`${where}.vary must be an object`);
+        const vary = Object.entries(section.vary);
+        if (vary.length > 0)
+          stored.vary = Object.freeze(
+            Object.fromEntries(
+              vary.map(([id, change]) => {
+                if (!isRecord(change))
+                  throw new DawgSdkError(
+                    `${where}.vary.${id} must be an object`,
+                  );
+                const out: Record<string, number> = {};
+                if (change.transpose !== undefined)
+                  out.transpose = finite(
+                    change.transpose,
+                    `${where}.vary.${id}.transpose`,
+                  );
+                if (change.gain !== undefined)
+                  out.gain = finite(change.gain, `${where}.vary.${id}.gain`);
+                return [id, Object.freeze(out)];
+              }),
+            ),
+          );
+      }
+      return Object.freeze(stored) as SongSection;
+    }),
+  );
+}
+
 /**
  * Assemble the song. Beats become ticks (`Math.round(beat * ticksPerBeat)`,
  * lengths at least one tick), and every note gets a deterministic id from
@@ -2127,7 +3672,11 @@ export function song(input: SongInput): Song {
   const beatsPerBar = Array.isArray(meter)
     ? finite(meter[0], "song meter[0]")
     : finite(meter as number, "song meter");
-  if (Array.isArray(meter)) finite(meter[1], "song meter[1]");
+  const beatUnit = Array.isArray(meter) ? finite(meter[1], "song meter[1]") : 4;
+  if (![1, 2, 4, 8, 16, 32].includes(beatUnit))
+    throw new DawgSdkError(
+      "song meter note value must be 1, 2, 4, 8, 16 or 32",
+    );
   const bars = finite(input.bars ?? 4, "song bars");
   const ticksPerBeat = input.ticksPerBeat ?? DEFAULT_TICKS_PER_BEAT;
   if (
@@ -2139,6 +3688,8 @@ export function song(input: SongInput): Song {
   const key = input.key ?? null;
   if (key !== null && typeof key !== "string")
     throw new DawgSdkError("song key must be a string or null");
+  const songTuning = tuningSpec(input.tuning, "song");
+  const master = masterData(input.master);
   if (!Array.isArray(input.tracks))
     throw new DawgSdkError("song tracks must be an array of track()");
   if (input.tracks.length > 64)
@@ -2196,12 +3747,46 @@ export function song(input: SongInput): Song {
       stored.wavetable = Object.freeze(fields);
     }
     if (wtAutomation.length > 0) stored.wtAutomation = wtAutomation;
+    if (t.granular) stored.granular = t.granular;
     if (t.sampler)
       stored.sampler = Object.freeze({
         voices: t.sampler.voices,
         mode: t.sampler.mode,
       });
     if (t.kit) stored.kit = t.kit;
+    if (t.time) {
+      const time: Record<string, unknown> = {};
+      if (t.time.rate !== undefined) time.rate = t.time.rate;
+      if (t.time.phase !== undefined) {
+        const phase = ticks(t.time.phase);
+        if (phase !== 0) time.phase = phase;
+      }
+      if (t.time.cycle !== undefined)
+        time.cycle = Math.max(1, ticks(t.time.cycle));
+      if (t.time.steps)
+        time.steps = Object.freeze({
+          ...t.time.steps,
+          shift: Math.max(1, ticks(t.time.steps.shift)),
+        });
+      if (Object.keys(time).length > 0) stored.time = Object.freeze(time);
+    }
+    if (t.glide) stored.glide = t.glide;
+    if (t.pedal && t.pedal.length > 0) {
+      // One event per tick (the last wins), in tick order, as dawg stores it.
+      const byTick = new Map<number, PedalState>();
+      for (const [at, state] of t.pedal) byTick.set(ticks(at), state);
+      stored.pedal = Object.freeze(
+        [...byTick.entries()]
+          .sort((a, b) => a[0] - b[0])
+          .map(([tick, state]) => Object.freeze({ tick, state })),
+      );
+    }
+    if (t.velocityCurve) stored.velocityCurve = t.velocityCurve;
+    if (t.humanize) stored.humanize = t.humanize;
+    if (t.tuning) stored.tuning = t.tuning;
+    if (t.string) stored.string = t.string;
+    if (t.keys) stored.keys = t.keys;
+    if (t.modal) stored.modal = t.modal;
     if (t.rhythm && t.rhythm.length > 0)
       stored.rhythm = Object.freeze(
         t.rhythm.map((row) => {
@@ -2228,10 +3813,42 @@ export function song(input: SongInput): Song {
           durationTicks,
           pitch: n.pitch,
           velocity: n.velocity,
+          ...(n.articulation ? { articulation: n.articulation } : {}),
+          ...(n.glide !== undefined ? { glide: n.glide } : {}),
+          ...(n.bend
+            ? {
+                bend: Object.freeze(
+                  [...n.bend]
+                    .sort((a, b) => a[0] - b[0])
+                    .map(([at, cents]) => Object.freeze({ at, cents })),
+                ),
+              }
+            : {}),
+          ...(n.vibrato ? { vibrato: n.vibrato } : {}),
+          ...(n.humanize ? { humanize: n.humanize } : {}),
+          ...(n.cents ? { cents: n.cents } : {}),
         }),
       );
     }
   });
+  const arrangement: {
+    sections?: readonly SongSection[];
+    form?: readonly SongFormEntry[];
+    loopSection?: string;
+  } = {};
+  if (input.sections !== undefined) {
+    const sections = songSections(input.sections);
+    if (sections.length > 0) arrangement.sections = sections;
+  }
+  if (input.form !== undefined) {
+    const form = parseSongForm(input.form);
+    if (form.length > 0) arrangement.form = form;
+  }
+  if (input.loopSection !== undefined) {
+    if (typeof input.loopSection !== "string")
+      throw new DawgSdkError("song loopSection must be a section name");
+    arrangement.loopSection = input.loopSection;
+  }
   return Object.freeze({
     format: "track.loop/v1",
     version: 1,
@@ -2240,11 +3857,624 @@ export function song(input: SongInput): Song {
     bars,
     ticksPerBeat,
     key,
+    ...songTime(
+      input.time,
+      tempoBpm,
+      ticks,
+      beatsPerBar,
+      ticksPerBeat,
+      beatUnit,
+      bars,
+    ),
+    ...(songTuning ? { tuning: songTuning } : {}),
     tracks: Object.freeze(tracks),
     notes: Object.freeze(notes),
+    ...(master ? { master } : {}),
+    ...arrangement,
   });
 }
 
+// ---------------------------------------------------------------------------
+// Time (SDK 1.14.0)
+
+/** One entry of `song({ time })`; build them with the helpers below. */
+export type TimeMark =
+  | Readonly<{
+      kind: "tempo";
+      /** Beat the change lands on. */
+      at: number;
+      /** Absent: keep the tempo in effect there, so a ramp can start from it. */
+      bpm?: number;
+      /** Glide into `bpm` from the previous mark instead of stepping. */
+      ramp?: "linear" | "exp";
+      /** Set by `rit()`/`accel()`: the direction `song()` checks. */
+      gradual?: "rit" | "accel";
+      /**
+       * Set by `aTempo()` (the tempo before the last rit/accel) and
+       * `tempoPrimo()` (the song's opening tempo) instead of `bpm`.
+       */
+      back?: "a-tempo" | "primo";
+    }>
+  | Readonly<{
+      kind: "meter";
+      /** Beat of the bar line where the meter starts. */
+      at: number;
+      beatsPerBar: number;
+      beatUnit: number;
+    }>
+  | Readonly<{
+      kind: "fermata";
+      at: number;
+      /** Extra beats the held beat lasts. */
+      beats: number;
+    }>;
+
+/** `ramp()` curves: `linear` adds the same BPM each beat, `exp` the same ratio. */
+export type TempoCurve = "linear" | "exp";
+
+/**
+ * Tempo change at beat `at`: `tempo(32, 140)`. Omit `bpm` to pin the tempo
+ * in effect there, the start of a ramp.
+ */
+export function tempo(at: number, bpm?: number): TimeMark {
+  const start = beat(at, "tempo() at");
+  if (start <= 0)
+    throw new DawgSdkError("tempo() at must be > 0; song({ tempo }) is beat 0");
+  if (bpm === undefined) return Object.freeze({ kind: "tempo", at: start });
+  return Object.freeze({ kind: "tempo", at: start, bpm: songBpm(bpm) });
+}
+
+/**
+ * `a tempo` at beat `at` (SDK 1.19.0): step back to the tempo in effect
+ * before the last `rit()`/`accel()` (or ramp) ending before `at`.
+ */
+export function aTempo(at: number): TimeMark {
+  const start = beat(at, "aTempo() at");
+  if (start <= 0) throw new DawgSdkError("aTempo() at must be > 0");
+  return Object.freeze({ kind: "tempo", at: start, back: "a-tempo" });
+}
+
+/** `tempo primo` at beat `at` (SDK 1.19.0): step back to `song({ tempo })`. */
+export function tempoPrimo(at: number): TimeMark {
+  const start = beat(at, "tempoPrimo() at");
+  if (start <= 0) throw new DawgSdkError("tempoPrimo() at must be > 0");
+  return Object.freeze({ kind: "tempo", at: start, back: "primo" });
+}
+
+/**
+ * Glide from the previous tempo mark (or the song's opening tempo) to `bpm`
+ * at beat `at`: `ramp(64, 90)`. `exp` changes by the same ratio each beat.
+ */
+export function ramp(
+  at: number,
+  bpm: number,
+  curve: TempoCurve = "linear",
+): TimeMark {
+  const end = beat(at, "ramp() at");
+  if (end <= 0) throw new DawgSdkError("ramp() at must be > 0");
+  return Object.freeze({
+    kind: "tempo",
+    at: end,
+    bpm: songBpm(bpm),
+    ramp: tempoCurve(curve, "ramp()"),
+  });
+}
+
+/**
+ * Ritardando: slow from the tempo at beat `at` to `bpm` over `beats` beats,
+ * `rit(48, 16, 80)`. Same as `[tempo(at), ramp(at + beats, bpm, curve)]`.
+ */
+export function rit(
+  at: number,
+  beats: number,
+  bpm: number,
+  curve: TempoCurve = "linear",
+): readonly TimeMark[] {
+  return gradual("rit", at, beats, bpm, curve);
+}
+
+/** Accelerando: like `rit()`, toward a faster `bpm`. */
+export function accel(
+  at: number,
+  beats: number,
+  bpm: number,
+  curve: TempoCurve = "linear",
+): readonly TimeMark[] {
+  return gradual("accel", at, beats, bpm, curve);
+}
+
+function gradual(
+  direction: "rit" | "accel",
+  at: number,
+  beats: number,
+  bpm: number,
+  curve: TempoCurve,
+): readonly TimeMark[] {
+  const label = `${direction}()`;
+  const start = beat(at, `${label} at`);
+  const length = positive(beats, `${label} beats`);
+  const target = songBpm(bpm);
+  const shape = tempoCurve(curve, label);
+  const marks: TimeMark[] = [];
+  if (start > 0) marks.push(Object.freeze({ kind: "tempo", at: start }));
+  marks.push(
+    Object.freeze({
+      kind: "tempo",
+      at: start + length,
+      bpm: target,
+      ramp: shape,
+      gradual: direction,
+    }),
+  );
+  return Object.freeze(marks);
+}
+
+/** Fermata: the beat at `at` lasts `beats` extra beats (default 2). */
+export function fermata(at: number, beats = 2): TimeMark {
+  const hold = positive(beats, "fermata() beats");
+  if (hold > 64) throw new DawgSdkError("fermata() beats must be at most 64");
+  return Object.freeze({
+    kind: "fermata",
+    at: beat(at, "fermata() at"),
+    beats: hold,
+  });
+}
+
+/**
+ * Meter change on the bar line at beat `at`: `meter(16, [7, 8])` or
+ * `meter(16, 3)` (quarter-note beats). It lasts until the next one.
+ */
+export function meter(
+  at: number,
+  value: readonly [number, number] | number,
+): TimeMark {
+  const start = beat(at, "meter() at");
+  const [beatsPerBar, beatUnit] = Array.isArray(value)
+    ? [value[0], value[1]]
+    : [value as number, 4];
+  if (
+    typeof beatsPerBar !== "number" ||
+    !Number.isInteger(beatsPerBar) ||
+    beatsPerBar < 1 ||
+    beatsPerBar > 16
+  )
+    throw new DawgSdkError("meter() beats per bar must be an integer 1..16");
+  if (![1, 2, 4, 8, 16, 32].includes(beatUnit as number))
+    throw new DawgSdkError("meter() note value must be 1, 2, 4, 8, 16 or 32");
+  return Object.freeze({
+    kind: "meter",
+    at: start,
+    beatsPerBar,
+    beatUnit: beatUnit as number,
+  });
+}
+
+/**
+ * Track time for continuous phasing, the tape drift of Reich's It's Gonna
+ * Rain and Come Out: the track's first `cycle` beats repeat a little fast,
+ * gaining `cycles` whole cycles every `over` beats, so it drifts away from
+ * an identical track and lines up again. `over` should divide the song
+ * loop. `track({ ..., time: phasing(3, 48) })`. For Piano Phase's
+ * shift-and-hold, use `stepPhasing()`.
+ */
+export function phasing(
+  cycle: number,
+  over: number,
+  cycles = 1,
+): TrackTimeInput {
+  const length = positive(cycle, "phasing() cycle");
+  const span = positive(over, "phasing() over");
+  const gain = finite(cycles, "phasing() cycles");
+  const repeats = span / length;
+  const rate = (repeats + gain) / repeats;
+  if (!(rate >= 0.125 && rate <= 8))
+    throw new DawgSdkError("phasing() needs a rate between 0.125 and 8");
+  return Object.freeze({ cycle: length, rate });
+}
+
+/**
+ * Stepped phasing (SDK 1.19.0), as in Reich's Piano Phase: the track's first `cycle`
+ * beats hold in step with a twin for `hold` cycles, then move `shift`
+ * beats ahead over `drift` cycles, and repeat until a whole cycle ahead.
+ * `track({ ..., time: stepPhasing(3, { hold: 8 }) })`.
+ */
+export function stepPhasing(
+  cycle: number,
+  options: Readonly<{ shift?: number; hold?: number; drift?: number }> = {},
+): TrackTimeInput {
+  const length = positive(cycle, "stepPhasing() cycle");
+  const steps = phaseSteps(
+    { shift: 0.25, hold: 8, drift: 2, ...options },
+    length,
+    "stepPhasing()",
+  );
+  return Object.freeze({ cycle: length, steps });
+}
+
+function songBpm(value: unknown): number {
+  const bpm = finite(value, "tempo bpm");
+  if (bpm < 20 || bpm > 300)
+    throw new DawgSdkError("tempo bpm must be 20..300");
+  return bpm;
+}
+
+function tempoCurve(value: unknown, label: string): TempoCurve {
+  if (value !== "linear" && value !== "exp")
+    throw new DawgSdkError(`${label} curve must be "linear" or "exp"`);
+  return value;
+}
+
+/** Same as `TIME_LIMITS.maxFermataSeconds` in core/tempo.ts. */
+const MAX_FERMATA_SECONDS = 16.777;
+
+/** Tempo at `tick` through resolved tempo events (ramps glide into theirs). */
+function bpmAtTick(
+  tempo: readonly { tick: number; bpm: number; ramp?: TempoCurve }[],
+  start: number,
+  tick: number,
+): number {
+  let from = { tick: 0, bpm: start };
+  for (const event of tempo) {
+    if (event.tick <= tick) {
+      from = event;
+      continue;
+    }
+    if (!event.ramp) break;
+    const t = (tick - from.tick) / (event.tick - from.tick);
+    return event.ramp === "exp"
+      ? from.bpm * Math.pow(event.bpm / from.bpm, t)
+      : from.bpm + (event.bpm - from.bpm) * t;
+  }
+  return from.bpm;
+}
+
+/** Resolves `song({ time })` marks into the stored ticks and bar indexes. */
+function songTime(
+  input: unknown,
+  tempoBpm: number,
+  ticks: (beats: number) => number,
+  beatsPerBar: number,
+  ticksPerBeat: number,
+  beatUnit = 4,
+  bars = Infinity,
+): { time?: ScoreTime } {
+  if ((input === undefined || input === null) && beatUnit === 4) return {};
+  input ??= [];
+  if (!Array.isArray(input))
+    throw new DawgSdkError("song time must be an array of time marks");
+  const marks: TimeMark[] = [];
+  for (const [index, entry] of (input as unknown[]).entries()) {
+    for (const mark of Array.isArray(entry) ? entry : [entry]) {
+      if (
+        !isRecord(mark) ||
+        (mark.kind !== "tempo" &&
+          mark.kind !== "meter" &&
+          mark.kind !== "fermata")
+      )
+        throw new DawgSdkError(
+          `song time[${index}] must come from tempo(), ramp(), rit(), accel(), fermata() or meter()`,
+        );
+      marks.push(mark as TimeMark);
+    }
+  }
+  // Tempo: sort by tick, resolve pins against their neighbours.
+  type Event = {
+    tick: number;
+    bpm?: number;
+    ramp?: TempoCurve;
+    back?: "a-tempo" | "primo";
+  };
+  const byTick = new Map<number, Event>();
+  for (const mark of marks) {
+    if (mark.kind !== "tempo") continue;
+    const tick = ticks(mark.at);
+    const previous = byTick.get(tick);
+    const sets = (e: { bpm?: number; back?: unknown }) =>
+      e.bpm !== undefined || e.back !== undefined;
+    if (previous && sets(previous) && sets(mark)) {
+      // A rit or ramp ending where a tempo change starts (`rit(18, 6, 52)`
+      // with `aTempo(24)`): the ramp lands a tick early, then the step.
+      const ramped = previous.ramp ? previous : mark.ramp ? mark : undefined;
+      const other = ramped === previous ? mark : previous;
+      if (ramped && !other.ramp && tick > 1 && !byTick.has(tick - 1)) {
+        byTick.set(tick - 1, {
+          tick: tick - 1,
+          ...(ramped.bpm !== undefined ? { bpm: ramped.bpm } : {}),
+          ramp: ramped.ramp!,
+        });
+        byTick.set(tick, {
+          tick,
+          ...(other.bpm !== undefined ? { bpm: other.bpm } : {}),
+          ...(other.back ? { back: other.back } : {}),
+        });
+        continue;
+      }
+      throw new DawgSdkError(
+        `song time has two tempo changes at beat ${mark.at}; move one, or end a rit() where the next tempo starts`,
+      );
+    }
+    // A pin and a change on the same beat: the change wins.
+    if (previous && !sets(mark)) continue;
+    byTick.set(tick, {
+      tick,
+      ...(mark.bpm !== undefined ? { bpm: mark.bpm } : {}),
+      ...(mark.ramp ? { ramp: mark.ramp } : {}),
+      ...(mark.back ? { back: mark.back } : {}),
+    });
+  }
+  const events = [...byTick.values()].sort((a, b) => a.tick - b.tick);
+  const tempo: { tick: number; bpm: number; ramp?: TempoCurve }[] = [];
+  events.forEach((event, index) => {
+    if (event.back) {
+      let bpm = tempoBpm;
+      if (event.back === "a-tempo") {
+        let last = -1;
+        tempo.forEach((e, i) => {
+          if (e.ramp !== undefined) last = i;
+        });
+        if (last < 0)
+          throw new DawgSdkError(
+            `aTempo() at beat ${event.tick / ticksPerBeat} has no rit() or accel() before it`,
+          );
+        bpm = last > 0 ? tempo[last - 1]!.bpm : tempoBpm;
+      }
+      tempo.push(Object.freeze({ tick: event.tick, bpm }));
+      return;
+    }
+    if (event.bpm !== undefined) {
+      // rit() and accel() check their direction against the tempo they
+      // start from, as the prompt's `rit` and `accel` do.
+      const mark = marks.find(
+        (m) => m.kind === "tempo" && ticks(m.at) === event.tick && m.gradual,
+      ) as Extract<TimeMark, { kind: "tempo" }> | undefined;
+      if (mark?.gradual) {
+        const from = tempo[tempo.length - 1]?.bpm ?? tempoBpm;
+        if (mark.gradual === "rit" && event.bpm > from)
+          throw new DawgSdkError(
+            `rit() target ${event.bpm} BPM is faster than ${from}; use accel()`,
+          );
+        if (mark.gradual === "accel" && event.bpm < from)
+          throw new DawgSdkError(
+            `accel() target ${event.bpm} BPM is slower than ${from}; use rit()`,
+          );
+      }
+      tempo.push(
+        Object.freeze({
+          tick: event.tick,
+          bpm: event.bpm,
+          ...(event.ramp ? { ramp: event.ramp } : {}),
+        }),
+      );
+      return;
+    }
+    // A pin holds the tempo of the marks before it, and the next ramp
+    // starts from it. Without a ramp after it, it changes nothing.
+    const after = events
+      .slice(index + 1)
+      .find((e) => e.bpm !== undefined || e.back !== undefined);
+    if (!after?.ramp) return;
+    const before = tempo[tempo.length - 1]?.bpm ?? tempoBpm;
+    tempo.push(Object.freeze({ tick: event.tick, bpm: before }));
+  });
+  // Meter: beats to bar indexes, checking each lands on a bar line.
+  const meters = marks
+    .filter((mark) => mark.kind === "meter")
+    .sort((a, b) => a.at - b.at);
+  // `song({ meter: [6, 8] })`: the song meter's note value as a bar-1 change.
+  if (beatUnit !== 4 && !meters.some((mark) => ticks(mark.at) === 0))
+    meters.unshift({ kind: "meter", at: 0, beatsPerBar, beatUnit });
+  const meterOut: { bar: number; beatsPerBar: number; beatUnit?: number }[] =
+    [];
+  let barTick = 0;
+  let barIndex = 0;
+  let barLength = beatsPerBar * ticksPerBeat;
+  for (const mark of meters) {
+    const tick = ticks(mark.at);
+    const bars = (tick - barTick) / barLength;
+    if (!Number.isInteger(bars) || bars < 0)
+      throw new DawgSdkError(`meter() at beat ${mark.at} is not on a bar line`);
+    if (meterOut.length > 0 && bars === 0)
+      throw new DawgSdkError(`song time has two meters at beat ${mark.at}`);
+    barIndex += bars;
+    barTick = tick;
+    barLength = (mark.beatsPerBar * ticksPerBeat * 4) / mark.beatUnit;
+    meterOut.push(
+      Object.freeze({
+        bar: barIndex,
+        beatsPerBar: mark.beatsPerBar,
+        ...(mark.beatUnit !== 4 ? { beatUnit: mark.beatUnit } : {}),
+      }),
+    );
+  }
+  const fermatas = marks
+    .filter((mark) => mark.kind === "fermata")
+    .map((mark) => Object.freeze({ tick: ticks(mark.at), beats: mark.beats }))
+    .sort((a, b) => a.tick - b.tick);
+  for (let i = 1; i < fermatas.length; i += 1)
+    if (fermatas[i]!.tick === fermatas[i - 1]!.tick)
+      throw new DawgSdkError("song time has two fermatas on one beat");
+  // Marks past the song end are never heard; the prompt refuses them too.
+  if (Number.isFinite(bars)) {
+    let end = 0;
+    let fromBar = 0;
+    let length = beatsPerBar * ticksPerBeat;
+    for (const change of meterOut) {
+      if (change.bar >= bars) break;
+      end += (change.bar - fromBar) * length;
+      fromBar = change.bar;
+      length = (change.beatsPerBar * ticksPerBeat * 4) / (change.beatUnit ?? 4);
+    }
+    end += (bars - fromBar) * length;
+    const beatOf = (tick: number) => tick / ticksPerBeat;
+    // A ramp to the final barline (`rit()` over the last bars) lands on
+    // the last tick, the tempo the song ends at.
+    tempo.forEach((event, index) => {
+      if (
+        event.tick === end &&
+        event.ramp &&
+        end - 1 > (tempo[index - 1]?.tick ?? 0)
+      )
+        tempo[index] = Object.freeze({ ...event, tick: end - 1 });
+    });
+    for (const event of tempo)
+      if (event.tick >= end)
+        throw new DawgSdkError(
+          `tempo at beat ${beatOf(event.tick)} is past the song end (${beatOf(end)} beats); add bars`,
+        );
+    for (const change of meterOut)
+      if (change.bar >= bars)
+        throw new DawgSdkError(
+          `meter() at bar ${change.bar + 1} is past the song end (${bars} bars); add bars`,
+        );
+    for (const hold of fermatas)
+      if (hold.tick >= end)
+        throw new DawgSdkError(
+          `fermata() at beat ${beatOf(hold.tick)} is past the song end (${beatOf(end)} beats); add bars`,
+        );
+  }
+  // A fermata may hold its beat at most as long as a MIDI file can write.
+  // The held beat is the meter's felt beat (a dotted quarter in 6/8), as
+  // core/tempo.ts fermataSpan has it.
+  const feltBeats = (tick: number): number => {
+    let at = 0;
+    let fromBar = 0;
+    let meter = { beatsPerBar, beatUnit: 4 };
+    let length = beatsPerBar * ticksPerBeat;
+    for (const change of meterOut) {
+      const start = at + (change.bar - fromBar) * length;
+      if (start > tick) break;
+      at = start;
+      fromBar = change.bar;
+      meter = {
+        beatsPerBar: change.beatsPerBar,
+        beatUnit: change.beatUnit ?? 4,
+      };
+      length = (meter.beatsPerBar * ticksPerBeat * 4) / meter.beatUnit;
+    }
+    if (meterOut.length === 0) return 1;
+    const unit = 4 / meter.beatUnit;
+    const compound =
+      meter.beatUnit >= 8 &&
+      meter.beatsPerBar > 3 &&
+      meter.beatsPerBar % 3 === 0;
+    return Math.max(1, compound ? unit * 3 : unit);
+  };
+  for (const hold of fermatas) {
+    const bpm = bpmAtTick(tempo, tempoBpm, hold.tick);
+    const held = ((1 + hold.beats) * feltBeats(hold.tick) * 60) / bpm;
+    if (held > MAX_FERMATA_SECONDS + 1e-9)
+      throw new DawgSdkError(
+        `fermata() at beat ${hold.tick / ticksPerBeat} holds ${held.toFixed(1)} s; at most ${MAX_FERMATA_SECONDS} s (MIDI tempo limit), so use fewer beats or a faster tempo`,
+      );
+  }
+  const time: Record<string, unknown> = {};
+  if (tempo.length > 0) time.tempo = Object.freeze(tempo);
+  if (meterOut.length > 0) time.meter = Object.freeze(meterOut);
+  if (fermatas.length > 0) time.fermatas = Object.freeze(fermatas);
+  return Object.keys(time).length > 0
+    ? { time: Object.freeze(time) as ScoreTime }
+    : {};
+}
+
+// Tuning (SDK 1.16.0)
+
+/**
+ * A tuning for `song({ tuning })` or `track({ tuning })`: a library name or
+ * an object with at most one table source (`edo`, `ratios`, `cents` or
+ * `scl`). Library names: `12-tet`, `19-edo`, `24-edo`, `31-edo`,
+ * `pythagorean`, `just` (5-limit), `7-limit`, `well-tuned-piano`, `pelog`,
+ * `slendro`, `nyamaropa`, `shruti`, maqam and dastgah sets (`bayati`,
+ * `rast`, `saba`, `shur`, `homayoun`, `chahargah`) and raga intonations
+ * (`yaman`, `bhairav`, `kafi`, `todi`, …); `dawg` lists them with
+ * `/tuning list`. dawg checks every value when the song loads.
+ */
+export type TuningInput =
+  | string
+  | Readonly<{
+      /** A library tuning, or a label for the table given here. */
+      name?: string;
+      /** Equal divisions of the octave, 1..128. */
+      edo?: number;
+      /** Ratios for degrees 1..n, the last the period: `["9/8", "5/4", "2/1"]`. */
+      ratios?: readonly (string | number)[];
+      /** Cents for degrees 1..n, the last the period: `[240, 480, 720, 960, 1200]`. */
+      cents?: readonly number[];
+      /** A Scala `.scl` file in the project, e.g. `"tunings/slendro.scl"`. */
+      scl?: string;
+      /** A Scala `.kbm` keyboard mapping in the project; it sets its own root and A4. */
+      kbm?: string;
+      /** A4 in Hz, 220..880, default 440. */
+      ref?: number;
+      /** Key of degree 0, `"D4"` or 62; default the song key's tonic in octave 4. */
+      root?: Pitch;
+      /** `linear` (default): one key per step. `nearest`: every key plays the step nearest its 12-TET pitch. */
+      map?: "linear" | "nearest";
+    }>;
+
+/** A stored tuning: `root` is a MIDI number, `ratios` are strings. */
+export type ScoreTuning = Readonly<{
+  name?: string;
+  edo?: number;
+  ratios?: readonly string[];
+  cents?: readonly number[];
+  scl?: string;
+  kbm?: string;
+  ref?: number;
+  root?: number;
+  map?: "linear" | "nearest";
+}>;
+
+const TUNING_FIELDS: readonly string[] = Object.freeze([
+  "name",
+  "edo",
+  "ratios",
+  "cents",
+  "scl",
+  "kbm",
+  "ref",
+  "root",
+  "map",
+]);
+
+/** Checks a tuning's shape; dawg validates the values when the song loads. */
+function tuningSpec(
+  input: TuningInput | null | undefined,
+  where: string,
+): ScoreTuning | null {
+  if (input === undefined || input === null) return null;
+  if (typeof input === "string") {
+    if (input.trim() === "")
+      throw new DawgSdkError(`${where} tuning must be a name or an object`);
+    return Object.freeze({ name: input.trim() });
+  }
+  if (!isRecord(input))
+    throw new DawgSdkError(`${where} tuning must be a name or an object`);
+  const out: Record<string, unknown> = {};
+  for (const [field, value] of Object.entries(input)) {
+    if (!TUNING_FIELDS.includes(field))
+      throw new DawgSdkError(
+        `${where} tuning has an unknown field "${field}" (use ${TUNING_FIELDS.join(", ")})`,
+      );
+    if (value === undefined || value === null) continue;
+    if (field === "root") out.root = midi(value as Pitch);
+    else if (field === "ratios" || field === "cents") {
+      if (!Array.isArray(value))
+        throw new DawgSdkError(`${where} tuning ${field} must be a list`);
+      out[field] = Object.freeze(
+        field === "ratios" ? value.map((ratio) => String(ratio)) : [...value],
+      );
+    } else out[field] = value;
+  }
+  const sources = ["edo", "ratios", "cents", "scl"].filter(
+    (field) => out[field] !== undefined,
+  );
+  if (sources.length > 1)
+    throw new DawgSdkError(
+      `${where} tuning has ${sources.join(" and ")}; give one table`,
+    );
+  return Object.freeze(out as ScoreTuning);
+}
+
 // ---------------------------------------------------------------------------
 // Chords
 
@@ -2429,6 +4659,274 @@ export function progression(
   );
 }
 
+// BEGIN instrument words: generated from core/instruments.ts by core/sdk/sync-instruments.ts
+/** What an instrument word stores on a track. */
+type InstrumentWord = Readonly<{
+  /** The `Track.instrument` value. */
+  instrument: string;
+  /** The optional Track field the engine reads (created with defaults). */
+  field?: string;
+  /** A preset of that engine to apply. */
+  preset?: string;
+  /** An insert-effect preset to apply with it (rig aliases). */
+  fx?: string;
+}>;
+
+/** A word and what it means. */
+type InstrumentWordRow = Readonly<{
+  word: string;
+  /**
+   * Borrow the voice (instrument, field, preset) of this other word's row
+   * when it exists; `instrument` is the fallback when it does not.
+   */
+  voice?: string;
+}> &
+  InstrumentWord;
+
+/**
+ * Words that keep their pre-0.6 meaning forever: they resolve to
+ * themselves, whatever rows the lanes add.
+ */
+const LEGACY_WORDS: readonly string[] = Object.freeze([
+  "piano",
+  "pluck",
+  "bass",
+  "saw",
+  "square",
+  "triangle",
+  "marimba",
+  "wind",
+  "cello",
+  "contrabass",
+  "ebass",
+  "sitar",
+  "organ",
+  "strings",
+  "bell",
+  "keys",
+  "lead",
+]);
+
+/** 0.6 instrument words; each lane appends its own block. */
+const INSTRUMENT_WORDS: readonly InstrumentWordRow[] = Object.freeze([
+  // strings (f06-strings): plucked presets of the string engine. Legacy
+  // sitar/ebass keep today's voice (`string preset sitar` reaches the
+  // engine), jangle is the rig alias (the guitar lane maps its 12string to the
+  // preset; `string jangle` reaches it) and
+  // upright is the keys lane's piano (doublebass reaches the preset).
+  { word: "nylon", instrument: "string", field: "string", preset: "nylon" },
+  { word: "steel", instrument: "string", field: "string", preset: "steel" },
+  {
+    word: "electric",
+    instrument: "string",
+    field: "string",
+    preset: "electric",
+  },
+  { word: "slap", instrument: "string", field: "string", preset: "slap" },
+  { word: "motown", instrument: "string", field: "string", preset: "motown" },
+  { word: "tanpura", instrument: "string", field: "string", preset: "tanpura" },
+  {
+    word: "harpsichord",
+    instrument: "string",
+    field: "string",
+    preset: "harpsichord",
+  },
+  { word: "lute", instrument: "string", field: "string", preset: "lute" },
+  { word: "oud", instrument: "string", field: "string", preset: "oud" },
+  { word: "setar", instrument: "string", field: "string", preset: "setar" },
+  { word: "tar", instrument: "string", field: "string", preset: "tar" },
+  { word: "santur", instrument: "string", field: "string", preset: "santur" },
+  {
+    word: "dulcimer",
+    instrument: "string",
+    field: "string",
+    preset: "dulcimer",
+  },
+  { word: "koto", instrument: "string", field: "string", preset: "koto" },
+  { word: "harp", instrument: "string", field: "string", preset: "harp" },
+  { word: "banjo", instrument: "string", field: "string", preset: "banjo" },
+  { word: "tres", instrument: "string", field: "string", preset: "tres" },
+  {
+    word: "requinto",
+    instrument: "string",
+    field: "string",
+    preset: "requinto",
+  },
+  { word: "acoustic", instrument: "string", field: "string", preset: "steel" },
+  { word: "classical", instrument: "string", field: "string", preset: "nylon" },
+  {
+    word: "bassguitar",
+    instrument: "string",
+    field: "string",
+    preset: "ebass",
+  },
+  { word: "fender", instrument: "string", field: "string", preset: "ebass" },
+  {
+    word: "doublebass",
+    instrument: "string",
+    field: "string",
+    preset: "upright",
+  },
+  {
+    word: "cembalo",
+    instrument: "string",
+    field: "string",
+    preset: "harpsichord",
+  },
+  {
+    word: "hammered",
+    instrument: "string",
+    field: "string",
+    preset: "dulcimer",
+  },
+  { word: "sehtar", instrument: "string", field: "string", preset: "setar" },
+  // f06-rig: guitar track aliases, a guitar voice plus a whole rig. The
+  // voice is the strings lane's `electric` row (jangle: its 12-string
+  // `jangle` preset); the pluck only while that row is absent. Never `lead`
+  // or `bass`.
+  {
+    word: "jangle",
+    instrument: "string",
+    field: "string",
+    preset: "jangle",
+    fx: "jangle",
+  },
+  { word: "punk", instrument: "pluck", voice: "electric", fx: "punk" },
+  { word: "funk", instrument: "pluck", voice: "electric", fx: "funk" },
+  { word: "ragged", instrument: "pluck", voice: "electric", fx: "ragged" },
+  { word: "gtr-lead", instrument: "pluck", voice: "electric", fx: "lead" },
+  { word: "gtr-metal", instrument: "pluck", voice: "electric", fx: "metal" },
+  { word: "bachata", instrument: "pluck", voice: "electric", fx: "bachata" },
+  // granular (f06-granular): the instrument and its texture presets. Each
+  // starts from a built-in synth source, so nothing downloads.
+  {
+    word: "granular",
+    instrument: "granular",
+    field: "granular",
+    preset: "cloud",
+  },
+  {
+    word: "grains",
+    instrument: "granular",
+    field: "granular",
+    preset: "cloud",
+  },
+  { word: "cloud", instrument: "granular", field: "granular", preset: "cloud" },
+  {
+    word: "sparkle",
+    instrument: "granular",
+    field: "granular",
+    preset: "sparkle",
+  },
+  { word: "swarm", instrument: "granular", field: "granular", preset: "swarm" },
+  {
+    word: "microloop",
+    instrument: "granular",
+    field: "granular",
+    preset: "microloop",
+  },
+  // keys (f06-piano): modelled pianos. `piano` stays legacy here; the typed
+  // surfaces store a new `piano` as `grand` (core/keys.ts `pianoWrite`).
+  { word: "grand", instrument: "grand", field: "keys", preset: "grand" },
+  { word: "ballad", instrument: "grand", field: "keys", preset: "ballad" },
+  { word: "upright", instrument: "upright", field: "keys", preset: "upright" },
+  { word: "felt", instrument: "felt", field: "keys", preset: "felt" },
+  { word: "lofi", instrument: "felt", field: "keys", preset: "lofi" },
+  {
+    word: "honkytonk",
+    instrument: "honkytonk",
+    field: "keys",
+    preset: "honkytonk",
+  },
+  {
+    word: "prepared",
+    instrument: "prepared",
+    field: "keys",
+    preset: "prepared",
+  },
+  // f06-modal: mallets and bells (core/resonators.ts). `marimba` is legacy;
+  // `modal` alone gives the modal marimba.
+  { word: "modal", instrument: "modal", field: "modal", preset: "marimba" },
+  { word: "vibes", instrument: "modal", field: "modal", preset: "vibes" },
+  { word: "vibraphone", instrument: "modal", field: "modal", preset: "vibes" },
+  {
+    word: "xylophone",
+    instrument: "modal",
+    field: "modal",
+    preset: "xylophone",
+  },
+  { word: "glock", instrument: "modal", field: "modal", preset: "glock" },
+  {
+    word: "glockenspiel",
+    instrument: "modal",
+    field: "modal",
+    preset: "glock",
+  },
+  { word: "celesta", instrument: "modal", field: "modal", preset: "celesta" },
+  { word: "chimes", instrument: "modal", field: "modal", preset: "chimes" },
+  { word: "tubular", instrument: "modal", field: "modal", preset: "chimes" },
+  { word: "kalimba", instrument: "modal", field: "modal", preset: "kalimba" },
+  {
+    word: "thumbpiano",
+    instrument: "modal",
+    field: "modal",
+    preset: "kalimba",
+  },
+  { word: "mbira", instrument: "modal", field: "modal", preset: "mbira" },
+  { word: "steelpan", instrument: "modal", field: "modal", preset: "steelpan" },
+  { word: "bowl", instrument: "modal", field: "modal", preset: "bowl" },
+  { word: "gong", instrument: "modal", field: "modal", preset: "gong" },
+  { word: "gongageng", instrument: "modal", field: "modal", preset: "gong" },
+  { word: "timpani", instrument: "modal", field: "modal", preset: "timpani" },
+  {
+    word: "steeldrum",
+    instrument: "modal",
+    field: "modal",
+    preset: "steelpan",
+  },
+  { word: "singingbowl", instrument: "modal", field: "modal", preset: "bowl" },
+  {
+    word: "kettledrum",
+    instrument: "modal",
+    field: "modal",
+    preset: "timpani",
+  },
+  {
+    word: "tubularbells",
+    instrument: "modal",
+    field: "modal",
+    preset: "chimes",
+  },
+]);
+
+/**
+ * What an instrument word means: a legacy word is itself, a row word is its
+ * row, anything else is undefined (callers keep the word as typed).
+ */
+function resolveInstrumentWord(word: string): InstrumentWord | undefined {
+  if (LEGACY_WORDS.includes(word)) return Object.freeze({ instrument: word });
+  const row = INSTRUMENT_WORDS.find((entry) => entry.word === word);
+  if (!row) return undefined;
+  const { word: _word, voice, ...meaning } = row;
+  const borrowed =
+    voice === undefined
+      ? undefined
+      : INSTRUMENT_WORDS.find((entry) => entry.word === voice && !entry.voice);
+  if (!borrowed) return Object.freeze(meaning);
+  return Object.freeze({
+    instrument: borrowed.instrument,
+    ...(borrowed.field === undefined ? {} : { field: borrowed.field }),
+    ...(borrowed.preset === undefined ? {} : { preset: borrowed.preset }),
+    ...(meaning.fx === undefined ? {} : { fx: meaning.fx }),
+  });
+}
+
+/** The `Track.instrument` value a word stores (the word itself if unknown). */
+function instrumentForWord(word: string): string {
+  return resolveInstrumentWord(word)?.instrument ?? word;
+}
+// END instrument words
+
 // BEGIN chord engine: generated from core/chords.ts by core/sdk/sync-chords.ts
 // ---------------------------------------------------------------------------
 // Vocabulary
@@ -2815,6 +5313,8 @@ const MODES = Object.freeze({
   mixolydian: [0, 2, 4, 5, 7, 9, 10],
   locrian: [0, 1, 3, 5, 6, 8, 10],
   "harmonic-minor": [0, 2, 3, 5, 7, 8, 11],
+  "melodic-minor": [0, 2, 3, 5, 7, 9, 11],
+  "phrygian-dominant": [0, 1, 4, 5, 7, 8, 10],
 } as const);
 type ModeName = keyof typeof MODES;
 const MODE_NAMES = Object.keys(MODES) as ModeName[];
@@ -2837,25 +5337,302 @@ const MODE_ALIASES: Readonly<Record<string, ModeName>> = Object.freeze({
   "harmonic-minor": "harmonic-minor",
   "harmonic minor": "harmonic-minor",
   harmonic: "harmonic-minor",
+  "melodic-minor": "melodic-minor",
+  "melodic minor": "melodic-minor",
+  melodic: "melodic-minor",
+  "jazz minor": "melodic-minor",
+  "phrygian-dominant": "phrygian-dominant",
+  "phrygian dominant": "phrygian-dominant",
+  freygish: "phrygian-dominant",
+  spanish: "phrygian-dominant",
+  ajam: "major",
+  mahur: "major",
+  bilawal: "major",
 });
 
-type Key = Readonly<{ tonic: number; mode: ModeName }>;
+type ScaleFamily =
+  "pentatonic" | "blues" | "maqam" | "dastgah" | "raga" | "messiaen";
+
+/**
+ * Scales beyond the chord modes, for keys such as `D bayati`, `C yaman` or
+ * `C messiaen-3`. `steps` are semitones above the tonic and may be
+ * fractional (a quarter tone is .5); `mode` is the seven-note mode the
+ * chord engine harmonizes with (the closest one; see DAWG.md). A raga's
+ * `intonation` is each step's traditional just pitch in cents (shruti
+ * offsets), which its named tuning applies (`tuning yaman`): Pythagorean
+ * ati-komal re and dha for Bhairavi, Bhairav, Purvi and Todi, the high
+ * tivra ma (729/512) for Yaman, 9/5 komal ni for Kafi, after Daniélou and
+ * Jairazbhoy. Maqam and dastgah quarter tones follow the 24-tone convention;
+ * Segah and Sikah start on a half-flat note, so their tonic is the key.
+ */
+type ScaleInfo = Readonly<{
+  steps: readonly number[];
+  mode: ModeName;
+  family: ScaleFamily;
+  intonation?: readonly number[];
+  aliases?: readonly string[];
+}>;
+
+const SCALES = Object.freeze({
+  "major-pentatonic": {
+    steps: [0, 2, 4, 7, 9],
+    mode: "major",
+    family: "pentatonic",
+    aliases: ["pentatonic", "major pentatonic", "pent"],
+  },
+  "minor-pentatonic": {
+    steps: [0, 3, 5, 7, 10],
+    mode: "minor",
+    family: "pentatonic",
+    aliases: ["minor pentatonic", "m pentatonic", "min pentatonic"],
+  },
+  blues: {
+    steps: [0, 3, 5, 6, 7, 10],
+    mode: "minor",
+    family: "blues",
+    aliases: ["minor blues"],
+  },
+  "major-blues": {
+    steps: [0, 2, 3, 4, 7, 9],
+    mode: "major",
+    family: "blues",
+    aliases: ["major blues"],
+  },
+  hijaz: {
+    steps: [0, 1, 4, 5, 7, 8, 10],
+    mode: "phrygian-dominant",
+    family: "maqam",
+  },
+  bayati: {
+    steps: [0, 1.5, 3, 5, 7, 8, 10],
+    mode: "phrygian",
+    family: "maqam",
+  },
+  rast: { steps: [0, 2, 3.5, 5, 7, 9, 10.5], mode: "major", family: "maqam" },
+  saba: { steps: [0, 1.5, 3, 4, 7, 8, 10], mode: "phrygian", family: "maqam" },
+  kurd: { steps: [0, 1, 3, 5, 7, 8, 10], mode: "phrygian", family: "maqam" },
+  nahawand: {
+    steps: [0, 2, 3, 5, 7, 8, 11],
+    mode: "harmonic-minor",
+    family: "maqam",
+  },
+  sikah: {
+    steps: [0, 1.5, 3.5, 5.5, 7, 8.5, 10.5],
+    mode: "phrygian",
+    family: "maqam",
+    aliases: ["sika"],
+  },
+  huzam: {
+    steps: [0, 1.5, 3.5, 4.5, 7.5, 8.5, 10.5],
+    mode: "phrygian",
+    family: "maqam",
+    aliases: ["houzam"],
+  },
+  nikriz: { steps: [0, 2, 3, 6, 7, 9, 10], mode: "dorian", family: "maqam" },
+  shur: {
+    steps: [0, 1.5, 3, 5, 7, 8, 10],
+    mode: "phrygian",
+    family: "dastgah",
+  },
+  homayoun: {
+    steps: [0, 1.5, 4, 5, 7, 8, 10],
+    mode: "phrygian-dominant",
+    family: "dastgah",
+    aliases: ["homayun"],
+  },
+  chahargah: {
+    steps: [0, 1.5, 4, 5, 7, 8.5, 11],
+    mode: "phrygian-dominant",
+    family: "dastgah",
+    aliases: ["chahar-gah"],
+  },
+  segah: {
+    steps: [0, 1.5, 3.5, 5, 6.5, 8.5, 10.5],
+    mode: "phrygian",
+    family: "dastgah",
+    aliases: ["sehgah", "se-gah"],
+  },
+  nava: {
+    steps: [0, 2, 3.5, 5, 7, 8, 10],
+    mode: "minor",
+    family: "dastgah",
+  },
+  yaman: {
+    steps: [0, 2, 4, 6, 7, 9, 11],
+    mode: "lydian",
+    family: "raga",
+    intonation: [0, 203.91, 386.31, 611.73, 701.96, 884.36, 1088.27],
+    aliases: ["kalyan", "yaman kalyan"],
+  },
+  bhairav: {
+    steps: [0, 1, 4, 5, 7, 8, 11],
+    mode: "phrygian-dominant",
+    family: "raga",
+    intonation: [0, 90.22, 386.31, 498.04, 701.96, 792.18, 1088.27],
+  },
+  kafi: {
+    steps: [0, 2, 3, 5, 7, 9, 10],
+    mode: "dorian",
+    family: "raga",
+    intonation: [0, 203.91, 315.64, 498.04, 701.96, 884.36, 1017.6],
+  },
+  bhairavi: {
+    steps: [0, 1, 3, 5, 7, 8, 10],
+    mode: "phrygian",
+    family: "raga",
+    intonation: [0, 90.22, 294.13, 498.04, 701.96, 792.18, 996.09],
+  },
+  asavari: {
+    steps: [0, 2, 3, 5, 7, 8, 10],
+    mode: "minor",
+    family: "raga",
+    intonation: [0, 203.91, 315.64, 498.04, 701.96, 813.69, 996.09],
+  },
+  khamaj: {
+    steps: [0, 2, 4, 5, 7, 9, 10],
+    mode: "mixolydian",
+    family: "raga",
+    intonation: [0, 203.91, 386.31, 498.04, 701.96, 884.36, 996.09],
+  },
+  todi: {
+    steps: [0, 1, 3, 6, 7, 8, 11],
+    mode: "phrygian",
+    family: "raga",
+    intonation: [0, 95, 294, 606, 702, 792, 1107],
+  },
+  purvi: {
+    steps: [0, 1, 4, 6, 7, 8, 11],
+    mode: "phrygian-dominant",
+    family: "raga",
+    intonation: [0, 90.22, 386.31, 590.22, 701.96, 792.18, 1088.27],
+  },
+  marwa: {
+    steps: [0, 1, 4, 6, 9, 11],
+    mode: "lydian",
+    family: "raga",
+    intonation: [0, 111.73, 386.31, 590.22, 884.36, 1088.27],
+  },
+  darbari: {
+    steps: [0, 2, 3, 5, 7, 8, 10],
+    mode: "minor",
+    family: "raga",
+    intonation: [0, 203.91, 294.13, 498.04, 701.96, 792.18, 996.09],
+    aliases: ["darbari kanada"],
+  },
+  malkauns: {
+    steps: [0, 3, 5, 8, 10],
+    mode: "minor",
+    family: "raga",
+    intonation: [0, 315.64, 498.04, 813.69, 996.09],
+  },
+  bhupali: {
+    steps: [0, 2, 4, 7, 9],
+    mode: "major",
+    family: "raga",
+    intonation: [0, 203.91, 386.31, 701.96, 884.36],
+  },
+  durga: {
+    steps: [0, 2, 5, 7, 9],
+    mode: "major",
+    family: "raga",
+    intonation: [0, 203.91, 498.04, 701.96, 884.36],
+  },
+  "messiaen-1": {
+    steps: [0, 2, 4, 6, 8, 10],
+    mode: "lydian",
+    family: "messiaen",
+    aliases: ["whole-tone", "whole tone", "wholetone"],
+  },
+  "messiaen-2": {
+    steps: [0, 1, 3, 4, 6, 7, 9, 10],
+    mode: "mixolydian",
+    family: "messiaen",
+    aliases: ["octatonic", "diminished", "half-whole"],
+  },
+  "messiaen-3": {
+    steps: [0, 2, 3, 4, 6, 7, 8, 10, 11],
+    mode: "minor",
+    family: "messiaen",
+  },
+  "messiaen-4": {
+    steps: [0, 1, 2, 5, 6, 7, 8, 11],
+    mode: "harmonic-minor",
+    family: "messiaen",
+  },
+  "messiaen-5": {
+    steps: [0, 1, 5, 6, 7, 11],
+    mode: "lydian",
+    family: "messiaen",
+  },
+  "messiaen-6": {
+    steps: [0, 2, 4, 5, 6, 8, 10, 11],
+    mode: "major",
+    family: "messiaen",
+  },
+  "messiaen-7": {
+    steps: [0, 1, 2, 3, 5, 6, 7, 8, 9, 11],
+    mode: "harmonic-minor",
+    family: "messiaen",
+  },
+} as const satisfies Record<string, ScaleInfo>);
+type ScaleName = keyof typeof SCALES;
+const SCALE_NAMES = Object.keys(SCALES) as ScaleName[];
+
+const SCALE_ALIASES: Readonly<Record<string, ScaleName>> = (() => {
+  const aliases: Record<string, ScaleName> = {};
+  for (const name of SCALE_NAMES) {
+    const info: ScaleInfo = SCALES[name];
+    aliases[name] = name;
+    aliases[name.replace(/-/g, " ")] = name;
+    for (const alias of info.aliases ?? []) aliases[alias] = name;
+  }
+  return Object.freeze(aliases);
+})();
+
+/** The library scale named `text` (case and `-`/space insensitive). */
+function scaleNamed(text: string): ScaleName | undefined {
+  const word = text.trim().toLowerCase().replace(/\s+/g, " ");
+  return SCALE_ALIASES[word] ?? SCALE_ALIASES[word.replace(/ /g, "-")];
+}
+
+/**
+ * A key: a tonic and the seven-note `mode` the chord engine uses, plus the
+ * library `scale` when the key names one (`D bayati`, `C yaman`).
+ */
+type Key = Readonly<{
+  tonic: number;
+  mode: ModeName;
+  scale?: ScaleName;
+}>;
 
 /**
- * Parse a key: `C`, `c major`, `Am`, `a minor`, `F# dorian`, `Eb mixo`.
- * Accepts the `<note> <mode>` form `core/key.ts` writes.
+ * Parse a key: `C`, `c major`, `Am`, `a minor`, `F# dorian`, `Eb mixo`,
+ * `D bayati`, `C messiaen-3`. Accepts the `<note> <mode>` form
+ * `core/key.ts` writes.
  */
 function parseKey(text: string | null | undefined): Key | undefined {
   if (typeof text !== "string" || text.length > 40) return undefined;
   const match = text
     .trim()
-    .match(/^([a-gA-G])(#|b|♯|♭)?\s*(m(?![a-z])|[a-zA-Z][a-zA-Z -]*)?$/);
+    .match(/^([a-gA-G])(#|b|♯|♭)?\s*(m(?![a-z])|[a-zA-Z][a-zA-Z0-9 -]*)?$/);
   if (!match) return undefined;
   const tonic = parsePitchClass(`${match[1]}${match[2] ?? ""}`);
+  if (tonic === undefined) return undefined;
   const word = (match[3] ?? "").trim();
   const mode = MODE_ALIASES[word === "m" ? "m" : word.toLowerCase()];
-  if (tonic === undefined || mode === undefined) return undefined;
-  return Object.freeze({ tonic, mode });
+  if (mode !== undefined) return Object.freeze({ tonic, mode });
+  const scale = scaleNamed(word);
+  if (scale === undefined) return undefined;
+  return Object.freeze({ tonic, mode: SCALES[scale].mode, scale });
+}
+
+/**
+ * Steps of the key's whole scale in semitones above the tonic (fractional
+ * for quarter tones): the library scale when the key names one, else the
+ * mode.
+ */
+function scaleSteps(key: Key): number[] {
+  return [...(key.scale ? SCALES[key.scale].steps : MODES[key.mode])];
 }
 
 /** True when names in the key read better with flats (F, Bb, Eb, d minor…). */
@@ -2870,6 +5647,8 @@ function keyUsesFlats(key: Key): boolean {
     minor: 9,
     locrian: 11,
     "harmonic-minor": 9,
+    "melodic-minor": 9,
+    "phrygian-dominant": 4,
   };
   const parent = mod12(key.tonic - parentOffset[key.mode]);
   return [5, 10, 3, 8, 1].includes(parent);
@@ -2877,7 +5656,7 @@ function keyUsesFlats(key: Key): boolean {
 
 /** `C major`, `F# dorian`, `Bb minor`. */
 function keyName(key: Key): string {
-  return `${noteName(key.tonic, keyUsesFlats(key))} ${key.mode}`;
+  return `${noteName(key.tonic, keyUsesFlats(key))} ${key.scale ?? key.mode}`;
 }
 
 /** Pitch classes of the key's scale, tonic first. */