@hraness/dawg 0.5.0 → 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.19.0";
+export const SDK_VERSION = "1.25.0";
 /** Major of `SDK_VERSION`; `dawg.json` records it as `sdk`. */
 export const SDK_MAJOR = 1;
 
@@ -1277,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`. */
@@ -1317,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 });
 }
@@ -1433,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
@@ -1445,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;
@@ -1460,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`);
@@ -1483,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)
@@ -1532,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
 
@@ -1564,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
@@ -1585,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;
@@ -1668,9 +2222,26 @@ 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;
+  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"`).
+   */
+  granular?: GranularInput | null;
   /**
    * Synthesized drum kit for an `instrument: "kit"` track: `syn808`,
    * `syn909`, `acoustic`, `lofi`, `electro` or `trap`. Omit for the default
@@ -1694,6 +2265,17 @@ export type TrackInput = Readonly<{
   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;
@@ -1833,6 +2415,10 @@ 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[];
@@ -1855,6 +2441,10 @@ export type TrackSpec = Readonly<{
     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";
@@ -2056,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"))
@@ -2158,6 +2791,23 @@ export function track(input: TrackInput): TrackSpec {
       throw new DawgSdkError(
         `track ${name}: unknown automation lane "${key}" (${AUTOMATION_KEYS.join(" ")})`,
       );
+  // 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
@@ -2200,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,
@@ -2219,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"),
@@ -2235,9 +2905,100 @@ export function track(input: TrackInput): TrackSpec {
     ...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))
@@ -2348,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))
@@ -2433,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 } : {}),
@@ -2445,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;
@@ -2617,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. */
@@ -2640,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";
@@ -2659,6 +3474,12 @@ export type ScoreTrack = Readonly<{
   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"];
@@ -2926,6 +3747,7 @@ 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,
@@ -2962,6 +3784,9 @@ export function song(input: SongInput): Song {
     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) => {
@@ -3834,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