@hraness/dawg 0.4.1 → 0.5.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.19.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"),
   });
 }
 
@@ -1458,6 +1677,21 @@ export type TrackInput = Readonly<{
    * 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;
   muted?: boolean;
@@ -1476,6 +1710,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 +1795,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";
@@ -1561,8 +1839,133 @@ export type TrackSpec = Readonly<{
   /** 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;
 }>;
 
+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,
@@ -1703,13 +2106,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`);
@@ -1834,9 +2232,74 @@ 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}`),
   });
 }
 
+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",
@@ -2018,19 +2481,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 +2585,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. */
@@ -2094,8 +2648,21 @@ 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[];
+  glide?: TrackSpec["glide"];
+  pedal?: readonly Readonly<{ tick: number; state: PedalState }>[];
+  velocityCurve?: TrackSpec["velocityCurve"];
+  humanize?: TrackSpec["humanize"];
 }>;
 
 /**
@@ -2111,10 +2678,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 +2851,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 +2867,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)
@@ -2202,6 +2932,36 @@ export function song(input: SongInput): Song {
         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.rhythm && t.rhythm.length > 0)
       stored.rhythm = Object.freeze(
         t.rhythm.map((row) => {
@@ -2228,10 +2988,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 +3032,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
 
@@ -2815,6 +4220,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 +4244,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 +4554,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 +4563,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. */