@hraness/dawg 0.4.1 → 0.6.0

package/core/score.ts

@@ -20,7 +20,45 @@ import {
   type FxLane,
   type TrackFx,
 } from "./fx.ts";
+import {
+  MODAL_INSTRUMENT,
+  normalizeModal,
+  type TrackModal,
+} from "./resonators.ts";
 import { normalizeSynth, type TrackSynth } from "./synth.ts";
+import { normalizeString, type TrackString } from "./strings.ts";
+import {
+  isGranularInstrument,
+  normalizeGranular,
+  type TrackGranular,
+} from "./granular.ts";
+import { normalizeKeys, type TrackKeys } from "./keys.ts";
+import {
+  checkSongTime,
+  normalizeSongTime,
+  normalizeTrackTime,
+  TimeValidationError,
+  type SongTime,
+  type TrackTime,
+  withMeterChange,
+} from "./tempo.ts";
+import {
+  ExpressionValidationError,
+  normalizeNoteExpression,
+  normalizeTrackPerformance,
+  type NoteExpression,
+  type NoteExpressionPatch,
+  type TrackPerformance,
+} from "./expression.ts";
+import {
+  normalizeNoteCents,
+  normalizeTuning,
+  TuningError,
+  type Tuning,
+} from "./tuning.ts";
+
+export type { Tuning } from "./tuning.ts";
+import { normalizeMaster, type SongMaster } from "./master.ts";
 
 export const SCORE_VERSION = 1 as const;
 export const DEFAULT_TICKS_PER_BEAT = 480 as const;
@@ -36,6 +74,13 @@ export const SCORE_LIMITS = Object.freeze({
   maxTempoBpm: 300,
   minTempoBpm: 20,
   maxBars: 256,
+  /** Song sections (0.5): named bar ranges and the form that orders them. */
+  maxSections: 64,
+  maxSectionNameLength: 32,
+  maxFormEntries: 128,
+  maxFormRepeat: 16,
+  maxSectionTranspose: 24,
+  maxSectionGain: 2,
   maxBeatsPerBar: 16,
   maxTicksPerBeat: 4096,
   maxTick: 1_000_000,
@@ -66,6 +111,11 @@ export const SCORE_LIMITS = Object.freeze({
   maxSampleAccelerate: 8,
   /** Sampler `squiz` ratio bound. */
   maxSampleSquiz: 32,
+  /** Sampler `bpm` (source tempo) bounds. */
+  minSampleBpm: 20,
+  maxSampleBpm: 400,
+  /** Sampler `len` (window length in beats) bound. */
+  maxSampleLenBeats: 1024,
   /** Per sample file, enforced by the decoder and the import tool. */
   maxSampleFileBytes: 50 * 1024 * 1024,
   maxSampleSeconds: 600,
@@ -328,7 +378,47 @@ export type Track = Readonly<{
    * `lofi`, … see `core/kits.ts`). Absent plays the default voices.
    */
   kit?: string;
-}>;
+  /**
+   * Track time against the song (`core/tempo.ts`): `rate` (tempo ratio),
+   * `phase` (ticks the pattern shifts later) and `cycle` (track ticks per
+   * repetition) for polytempo, polymeter and phasing. Absent follows the
+   * song.
+   */
+  time?: TrackTime;
+  /**
+   * Tuning for this track (`core/tuning.ts`): its own table, or just a
+   * `ref`/`root` over the song tuning. Absent follows the song tuning.
+   */
+  tuning?: Tuning;
+  /**
+   * String engine settings (`core/strings.ts`): a preset plus overrides.
+   * Played only when `instrument` is "string"; absent keeps today's voice.
+   */
+  string?: TrackString;
+  /**
+   * Granular instrument settings (0.6, `core/granular.ts`). Played when
+   * `instrument` is `"granular"`; kept when the instrument changes.
+   */
+  granular?: TrackGranular;
+  /**
+   * Optional (0.6): modelled piano settings (`core/keys.ts`), `{ preset?,
+   * ...overrides }`. The modelled piano plays only when `instrument` is a
+   * piano family (grand upright felt honkytonk prepared) and this is
+   * present; `{}` is the family's defaults.
+   */
+  keys?: TrackKeys;
+  /**
+   * Optional (0.6): modal percussion (`core/resonators.ts`), a preset plus
+   * overrides. Plays only when `instrument` is `"modal"`; any other
+   * instrument with this field is rejected. Absent keeps today's tone.
+   */
+  modal?: TrackModal;
+}> &
+  /**
+   * Performance (`core/expression.ts`): glide default, sustain pedal
+   * events, velocity curve and seeded humanize, all applied at render.
+   */
+  TrackPerformance;
 
 /**
  * A track's sample voices (Strudel-aligned). In `oneshot` mode every voice is
@@ -399,8 +489,35 @@ export type SampleRef = Readonly<{
    * (1 is off, up to 32).
    */
   squiz?: number;
+  /**
+   * Optional: the sample's own tempo (20..400). The window then follows
+   * the song's tempo map (ramps included): a 174 BPM break in a 128 BPM
+   * song plays 128/174 as fast. `fitmode` picks how.
+   */
+  bpm?: number;
+  /**
+   * Optional: how a fitted sample changes its time. `repitch` (default)
+   * changes speed and pitch together like tape; `beats` cuts the window at
+   * its onsets and places each slice on its new time, unstretched (drums,
+   * speech); `tones` time-stretches with a phase vocoder and keeps the
+   * pitch (pads, loops, vocals). Needs `bpm`, `len` or `fit`.
+   */
+  fitmode?: SampleFitMode;
+  /**
+   * Optional: the window's length in beats (0 < len ≤ 1024), followed
+   * through the song's tempo map. `fit` wins over `bpm`, `bpm` over `len`.
+   */
+  len?: number;
 }>;
 
+/** Sampler `fitmode`: how a fitted window changes its time. */
+export type SampleFitMode = "repitch" | "beats" | "tones";
+export const SAMPLE_FIT_MODES: readonly SampleFitMode[] = Object.freeze([
+  "repitch",
+  "beats",
+  "tones",
+]);
+
 /** Sample `unit`: rate, cycles (bars) or seconds. */
 export type SampleUnit = "r" | "c" | "s";
 export const SAMPLE_UNITS: readonly SampleUnit[] = Object.freeze([
@@ -627,6 +744,16 @@ export type TrackPatch = Readonly<
     fxAutomation?: Track["fxAutomation"] | null;
     synth?: TrackSynth | null;
     wavetable?: TrackWavetable | null;
+    time?: TrackTime | null;
+    glide?: Track["glide"] | null;
+    pedal?: Track["pedal"] | null;
+    velocityCurve?: Track["velocityCurve"] | null;
+    humanize?: Track["humanize"] | null;
+    tuning?: Tuning | null;
+    string?: TrackString | null;
+    granular?: TrackGranular | null;
+    keys?: TrackKeys | null;
+    modal?: TrackModal | null;
   }
 >;
 
@@ -635,7 +762,11 @@ export type AutomationPoint = Readonly<{
   value: number;
 }>;
 
-/** A note's start and duration are integer ticks, never floating-point beats. */
+/**
+ * A note's start and duration are integer ticks, never floating-point beats.
+ * Expression fields (`articulation`, `glide`, `bend`, `vibrato`, see
+ * `core/expression.ts`) are optional and absent when unused.
+ */
 export type Note = Readonly<{
   id: string;
   trackId: string;
@@ -643,7 +774,10 @@ export type Note = Readonly<{
   durationTicks: number;
   pitch: number;
   velocity: number;
-}>;
+  /** Static offset from the tuned pitch in cents (±1200); absent is 0. */
+  cents?: number;
+}> &
+  NoteExpression;
 
 export type TrackInput = Readonly<
   Omit<
@@ -658,6 +792,16 @@ export type TrackInput = Readonly<
     | "fxAutomation"
     | "synth"
     | "wavetable"
+    | "time"
+    | "glide"
+    | "pedal"
+    | "velocityCurve"
+    | "humanize"
+    | "tuning"
+    | "string"
+    | "granular"
+    | "keys"
+    | "modal"
   > &
     Pick<Track, "id"> & {
       filter?: TrackFilter | null;
@@ -670,6 +814,16 @@ export type TrackInput = Readonly<
       fxAutomation?: Track["fxAutomation"] | null;
       synth?: TrackSynth | null;
       wavetable?: TrackWavetable | null;
+      time?: TrackTime | null;
+      glide?: Track["glide"] | number | null;
+      pedal?: Track["pedal"] | null;
+      velocityCurve?: Track["velocityCurve"] | string | null;
+      humanize?: Track["humanize"] | null;
+      tuning?: Tuning | null;
+      string?: TrackString | null;
+      granular?: TrackGranular | null;
+      keys?: TrackKeys | null;
+      modal?: TrackModal | null;
     }
 >;
 
@@ -686,6 +840,41 @@ export type NoteInput = Readonly<{
   duration?: number;
   pitch: number;
   velocity: number;
+  cents?: number;
+}> &
+  NoteExpressionPatch;
+
+/** A per-track change inside a section: semitones and a velocity gain. */
+export type SectionVariation = Readonly<{
+  /** Semitones, -24..24; drum and one-shot sampler tracks ignore it. */
+  transpose?: number;
+  /** Velocity multiplier 0..2 (1 leaves it alone). */
+  gain?: number;
+}>;
+
+/**
+ * A named bar range of the song (0.5). Sections may overlap: two sections
+ * over the same bars with different mutes or variations are two versions
+ * of that music. `mute` and `vary` name track ids; unknown ids are ignored.
+ */
+export type Section = Readonly<{
+  /** Unique (ignoring case), 1..32 characters: `intro`, `chorus 2`, `A`. */
+  name: string;
+  /** First bar, 0-based. */
+  startBar: number;
+  /** Length in bars, at least 1. */
+  bars: number;
+  /** Tracks silent in this section. */
+  mute?: readonly string[];
+  /** Per-track variations in this section. */
+  vary?: Readonly<Record<string, SectionVariation>>;
+}>;
+
+/** One step of the song form: a section by name, played `repeat` times. */
+export type FormEntry = Readonly<{
+  section: string;
+  /** 1..16, default 1. */
+  repeat?: number;
 }>;
 
 export type TrackScoreData = Readonly<{
@@ -694,8 +883,26 @@ export type TrackScoreData = Readonly<{
   bars?: number;
   ticksPerBeat?: number;
   key?: string | null;
+  /**
+   * Tempo map, meter changes and fermatas (`core/tempo.ts`). Absent keeps
+   * `tempoBpm` and `beatsPerBar` for the whole song.
+   */
+  time?: SongTime | null;
+  /** Song tuning (`core/tuning.ts`); absent is 12-TET at A4 = 440 Hz. */
+  tuning?: Tuning | null;
   tracks?: readonly TrackInput[];
   notes?: readonly NoteInput[];
+  /** Song master chain and loudness target (core/master.ts); absent is off. */
+  master?: SongMaster | null;
+  /** Song sections (0.5); absent or empty means none. */
+  sections?: readonly Section[];
+  /** Song form (0.5): the order sections play in; absent plays the score straight through. */
+  form?: readonly FormEntry[];
+  /**
+   * The section playback loops (0.5), like a DAW's loop brace; absent plays
+   * the song (or its form). A name that matches no section is dropped.
+   */
+  loopSection?: string | null;
 }>;
 
 /** Canonical immutable score. Use `addNote`/`removeNote` to create a revision. */
@@ -706,8 +913,19 @@ export class TrackScore {
   readonly bars: number;
   readonly ticksPerBeat: number;
   readonly key: string | null;
+  /** Tempo map, meters and fermatas; absent when the song has none. */
+  declare readonly time?: SongTime;
+  readonly tuning: Tuning | undefined;
   readonly tracks: readonly Track[];
   readonly notes: readonly Note[];
+  /** Absent (not undefined-valued) without a master, so 0.4 scores are unchanged. */
+  declare readonly master?: SongMaster;
+  /** Song sections in bar order; empty when the song has none. */
+  readonly sections: readonly Section[];
+  /** Song form; empty plays the score straight through. */
+  readonly form: readonly FormEntry[];
+  /** The section playback loops; undefined plays the song. */
+  readonly loopSection: string | undefined;
 
   constructor(data: TrackScoreData = {}) {
     const tempoBpm = data.tempoBpm ?? 120;
@@ -760,15 +978,49 @@ export class TrackScore {
         "invalid-score",
       );
     }
+    const time = timeOrThrow(() => {
+      const normalized = normalizeSongTime(data.time);
+      checkSongTime(normalized, ticksPerBeat, { tempoBpm, beatsPerBar, bars });
+      return normalized;
+    });
+    const tuning = tuningOrThrow(
+      () => normalizeTuning(data.tuning, "song tuning"),
+      "invalid-score",
+    );
     const tracks = normalizeTracks(data.tracks ?? []);
     const notes = normalizeNotes(data.notes ?? []);
+    this.tuning = tuning;
+    let master: SongMaster | undefined;
+    try {
+      master = normalizeMaster(data.master);
+    } catch (error) {
+      if (error instanceof FxValidationError)
+        throw new ScoreValidationError(error.message, "invalid-score");
+      throw error;
+    }
+    if (master) this.master = master;
+    const sections = normalizeSections(data.sections ?? []);
+    const form = normalizeForm(data.form ?? [], sections);
+    // Sections count bars in one meter; meter changes would move them.
+    if (
+      sections.length > 0 &&
+      time?.meter?.some((change, index) => index > 0 || change.bar > 0)
+    )
+      throw new ScoreValidationError(
+        "sections need one meter: remove the meter changes (time.meter) or the sections",
+        "invalid-score",
+      );
     this.tempoBpm = tempoBpm;
     this.beatsPerBar = beatsPerBar;
     this.bars = bars;
     this.ticksPerBeat = ticksPerBeat;
     this.key = key;
+    if (time) this.time = time;
     this.tracks = freezeArray(tracks);
     this.notes = freezeArray(notes);
+    this.sections = freezeArray(sections);
+    this.form = freezeArray(form);
+    this.loopSection = normalizeLoopSection(data.loopSection, sections);
     Object.freeze(this);
   }
 
@@ -781,26 +1033,27 @@ export class TrackScore {
   }
 
   withTracks(tracks: readonly TrackInput[]): TrackScore {
-    return new TrackScore({
-      tempoBpm: this.tempoBpm,
-      beatsPerBar: this.beatsPerBar,
-      bars: this.bars,
-      ticksPerBeat: this.ticksPerBeat,
-      key: this.key,
-      tracks,
-      notes: this.notes,
-    });
+    return new TrackScore({ ...this.toJSON(), tracks });
   }
 
   withTempo(tempoBpm: number): TrackScore {
+    return new TrackScore({ ...this.toJSON(), tempoBpm });
+  }
+
+  /**
+   * Replace the sections and the form (both validated together). The loop
+   * section is kept while a section of that name remains.
+   */
+  withSections(
+    sections: readonly Section[],
+    form: readonly FormEntry[] = [],
+    loopSection: string | null | undefined = this.loopSection,
+  ): TrackScore {
     return new TrackScore({
-      tempoBpm,
-      beatsPerBar: this.beatsPerBar,
-      bars: this.bars,
-      ticksPerBeat: this.ticksPerBeat,
-      key: this.key,
-      tracks: this.tracks,
-      notes: this.notes,
+      ...this.toJSON(),
+      sections,
+      form,
+      loopSection: loopSection ?? null,
     });
   }
 
@@ -813,9 +1066,35 @@ export class TrackScore {
     return new TrackScore({ ...this.toJSON(), key });
   }
 
-  /** Change the meter; ticks are per beat, so notes keep their positions. */
+  /** Set or clear (null) the song tuning. */
+  withTuning(tuning: Tuning | null): TrackScore {
+    return new TrackScore({ ...this.toJSON(), tuning });
+  }
+
+  /**
+   * Change the meter; ticks are per beat, so notes keep their positions.
+   * Beats per bar is the song meter, so a meter change at bar 1
+   * (`time.meter` bar 0) is dropped rather than left overriding it.
+   */
   withMeter(beatsPerBar: number): TrackScore {
-    return new TrackScore({ ...this.toJSON(), beatsPerBar });
+    const time = this.time?.meter?.some((change) => change.bar === 0)
+      ? withMeterChange(this.time, 0, null)
+      : this.time;
+    return new TrackScore({
+      ...this.toJSON(),
+      beatsPerBar,
+      time: time ?? null,
+    });
+  }
+
+  /** Replace the tempo map, meter changes and fermatas; null clears them. */
+  withTime(time: SongTime | null | undefined): TrackScore {
+    return new TrackScore({ ...this.toJSON(), time: time ?? null });
+  }
+
+  /** Replace the song master; `null` removes it (bypass). */
+  withMaster(master: SongMaster | null): TrackScore {
+    return new TrackScore({ ...this.toJSON(), master });
   }
 
   toJSON(): TrackScoreData & { version: typeof SCORE_VERSION } {
@@ -826,8 +1105,16 @@ export class TrackScore {
       bars: this.bars,
       ticksPerBeat: this.ticksPerBeat,
       key: this.key,
+      ...(this.time ? { time: this.time } : {}),
+      ...(this.tuning ? { tuning: this.tuning } : {}),
       tracks: this.tracks,
       notes: this.notes,
+      ...(this.master ? { master: this.master } : {}),
+      ...(this.sections.length > 0 ? { sections: this.sections } : {}),
+      ...(this.form.length > 0 ? { form: this.form } : {}),
+      ...(this.loopSection === undefined
+        ? {}
+        : { loopSection: this.loopSection }),
     };
   }
 }
@@ -862,15 +1149,7 @@ export function addNote(score: TrackScore, input: NoteInput): TrackScore {
       "score-limit",
     );
   }
-  return new TrackScore({
-    tempoBpm: score.tempoBpm,
-    beatsPerBar: score.beatsPerBar,
-    bars: score.bars,
-    ticksPerBeat: score.ticksPerBeat,
-    key: score.key,
-    tracks: score.tracks,
-    notes: [...score.notes, note],
-  });
+  return new TrackScore({ ...score.toJSON(), notes: [...score.notes, note] });
 }
 
 export function removeNote(score: TrackScore, noteId: string): TrackScore {
@@ -888,32 +1167,31 @@ export function removeNote(score: TrackScore, noteId: string): TrackScore {
   }
   if (!score.notes.some((note) => note.id === noteId)) return score;
   return new TrackScore({
-    tempoBpm: score.tempoBpm,
-    beatsPerBar: score.beatsPerBar,
-    bars: score.bars,
-    ticksPerBeat: score.ticksPerBeat,
-    key: score.key,
-    tracks: score.tracks,
+    ...score.toJSON(),
     notes: score.notes.filter((note) => note.id !== noteId),
   });
 }
 
+/**
+ * A note edit: timing, pitch and velocity, plus the expression fields
+ * (`null` clears one).
+ */
+export type NotePatch = Readonly<
+  Partial<
+    Pick<Note, "startTick" | "durationTicks" | "pitch" | "velocity" | "cents">
+  >
+> &
+  NoteExpressionPatch;
+
 export function updateNote(
   score: TrackScore,
   noteId: string,
-  patch: Readonly<
-    Partial<Pick<Note, "startTick" | "durationTicks" | "pitch" | "velocity">>
-  >,
+  patch: NotePatch,
 ): TrackScore {
   const current = score.notes.find((note) => note.id === noteId);
   if (!current) return score;
   return new TrackScore({
-    tempoBpm: score.tempoBpm,
-    beatsPerBar: score.beatsPerBar,
-    bars: score.bars,
-    ticksPerBeat: score.ticksPerBeat,
-    key: score.key,
-    tracks: score.tracks,
+    ...score.toJSON(),
     notes: score.notes.map((note) =>
       note.id === noteId ? { ...note, ...patch } : note,
     ),
@@ -923,12 +1201,7 @@ export function updateNote(
 export function clearTrack(score: TrackScore, trackId: string): TrackScore {
   if (!score.notes.some((note) => note.trackId === trackId)) return score;
   return new TrackScore({
-    tempoBpm: score.tempoBpm,
-    beatsPerBar: score.beatsPerBar,
-    bars: score.bars,
-    ticksPerBeat: score.ticksPerBeat,
-    key: score.key,
-    tracks: score.tracks,
+    ...score.toJSON(),
     notes: score.notes.filter((note) => note.trackId !== trackId),
   });
 }
@@ -940,9 +1213,19 @@ export function updateTrack(
 ): TrackScore {
   if (!score.tracks.some((track) => track.id === trackId)) return score;
   return score.withTracks(
-    score.tracks.map((track) =>
-      track.id === trackId ? { ...track, ...patch } : track,
-    ),
+    score.tracks.map((track) => {
+      if (track.id !== trackId) return track;
+      const next: Record<string, unknown> = { ...track, ...patch };
+      // A modal field only belongs to a modal track: switching the
+      // instrument away drops it unless the patch sets it too.
+      if (
+        patch.instrument !== undefined &&
+        patch.modal === undefined &&
+        patch.instrument !== MODAL_INSTRUMENT
+      )
+        delete next.modal;
+      return next as Track;
+    }),
   );
 }
 
@@ -1076,11 +1359,7 @@ export type ScoreOperation =
   | Readonly<{
       type: "updateNote";
       noteId: string;
-      patch: Readonly<
-        Partial<
-          Pick<Note, "startTick" | "durationTicks" | "pitch" | "velocity">
-        >
-      >;
+      patch: NotePatch;
     }>
   | Readonly<{
       type: "setTempo";
@@ -1121,6 +1400,26 @@ export type ScoreOperation =
   | Readonly<{
       type: "setMeter";
       beatsPerBar: number;
+    }>
+  | Readonly<{
+      /** Replaces the song's tempo map, meter changes and fermatas. */
+      type: "setTime";
+      time: SongTime | null;
+    }>
+  | Readonly<{
+      type: "setTuning";
+      tuning: Tuning | null;
+    }>
+  | Readonly<{
+      type: "setMaster";
+      master: SongMaster | null;
+    }>
+  | Readonly<{
+      type: "setSections";
+      sections: readonly Section[];
+      form: readonly FormEntry[];
+      /** The looped section; absent or null plays the song. */
+      loopSection?: string | null;
     }>;
 
 export function applyScoreOperation(
@@ -1134,6 +1433,15 @@ export function applyScoreOperation(
   if (operation.type === "setKey") return score.withKey(operation.key);
   if (operation.type === "setMeter")
     return score.withMeter(operation.beatsPerBar);
+  if (operation.type === "setTime") return score.withTime(operation.time);
+  if (operation.type === "setTuning") return score.withTuning(operation.tuning);
+  if (operation.type === "setMaster") return score.withMaster(operation.master);
+  if (operation.type === "setSections")
+    return score.withSections(
+      operation.sections,
+      operation.form,
+      operation.loopSection ?? null,
+    );
   if (operation.type === "addTrack") return addTrack(score, operation.track);
   if (operation.type === "addNote") return addNote(score, operation.note);
   if (operation.type === "removeNote")
@@ -1178,8 +1486,14 @@ export function scoreFromJSON(value: unknown): TrackScore {
     bars?: number;
     ticksPerBeat?: number;
     key?: string | null;
+    time?: SongTime | null;
+    tuning?: Tuning | null;
     tracks: readonly TrackInput[];
     notes: readonly NoteInput[];
+    master?: SongMaster;
+    sections?: readonly Section[];
+    form?: readonly FormEntry[];
+    loopSection?: string | null;
   } = {
     tracks: optionalArray(value.tracks).map(parseTrack),
     notes: optionalArray(value.notes).map(parseNote),
@@ -1194,9 +1508,202 @@ export function scoreFromJSON(value: unknown): TrackScore {
   if (bars !== undefined) data.bars = bars;
   if (ticksPerBeat !== undefined) data.ticksPerBeat = ticksPerBeat;
   if (key !== undefined) data.key = key;
+  if (value.time !== undefined && value.time !== null)
+    data.time = value.time as SongTime;
+  if (value.tuning !== undefined) data.tuning = value.tuning as Tuning | null;
+  // Validated by the constructor (core/master.ts normalizeMaster).
+  if (value.master !== undefined && value.master !== null)
+    data.master = value.master as SongMaster;
+  // Shapes are checked by the constructor (normalizeSections, normalizeForm).
+  if (value.sections !== undefined)
+    data.sections = optionalArray(value.sections) as readonly Section[];
+  if (value.form !== undefined)
+    data.form = optionalArray(value.form) as readonly FormEntry[];
+  // The constructor checks the type and drops a name matching no section.
+  if (value.loopSection !== undefined)
+    data.loopSection = value.loopSection as string | null;
   return new TrackScore(data);
 }
 
+/** Section names: printable text without control characters, trimmed. */
+const SECTION_NAME = /^[^\u0000-\u001f\u007f]+$/u;
+
+function normalizeSections(inputs: readonly unknown[]): Section[] {
+  if (!Array.isArray(inputs) || inputs.length > SCORE_LIMITS.maxSections)
+    throw new ScoreValidationError(
+      `score cannot contain more than ${SCORE_LIMITS.maxSections} sections`,
+      "score-limit",
+    );
+  const seen = new Set<string>();
+  const sections = inputs.map((input, index): Section => {
+    if (!isRecord(input))
+      throw new ScoreValidationError(`section ${index} must be an object`);
+    const name =
+      typeof input.name === "string"
+        ? input.name.trim().replace(/\s+/gu, " ")
+        : "";
+    if (
+      name.length === 0 ||
+      name.length > SCORE_LIMITS.maxSectionNameLength ||
+      !SECTION_NAME.test(name)
+    )
+      throw new ScoreValidationError(
+        `section ${index} needs a name of 1..${SCORE_LIMITS.maxSectionNameLength} characters`,
+      );
+    const folded = name.toLowerCase();
+    if (seen.has(folded))
+      throw new ScoreValidationError(`duplicate section name: ${name}`);
+    seen.add(folded);
+    const startBar = input.startBar;
+    const bars = input.bars;
+    if (
+      typeof startBar !== "number" ||
+      !Number.isInteger(startBar) ||
+      startBar < 0 ||
+      startBar >= SCORE_LIMITS.maxBars
+    )
+      throw new ScoreValidationError(
+        `section ${name} startBar must be an integer 0..${SCORE_LIMITS.maxBars - 1}`,
+      );
+    if (
+      typeof bars !== "number" ||
+      !Number.isInteger(bars) ||
+      bars < 1 ||
+      startBar + bars > SCORE_LIMITS.maxBars
+    )
+      throw new ScoreValidationError(
+        `section ${name} bars must be an integer 1..${SCORE_LIMITS.maxBars - startBar}`,
+      );
+    const out: { -readonly [K in keyof Section]: Section[K] } = {
+      name,
+      startBar,
+      bars,
+    };
+    if (input.mute !== undefined) {
+      if (
+        !Array.isArray(input.mute) ||
+        input.mute.length > SCORE_LIMITS.maxTracks ||
+        input.mute.some((id) => typeof id !== "string" || id.length === 0)
+      )
+        throw new ScoreValidationError(
+          `section ${name} mute must be a list of track ids`,
+        );
+      const mute = [...new Set(input.mute as string[])];
+      if (mute.length > 0) out.mute = freezeArray(mute);
+    }
+    if (input.vary !== undefined) {
+      if (!isRecord(input.vary))
+        throw new ScoreValidationError(
+          `section ${name} vary must map track ids to variations`,
+        );
+      const entries = Object.entries(input.vary);
+      if (entries.length > SCORE_LIMITS.maxTracks)
+        throw new ScoreValidationError(
+          `section ${name} vary has too many tracks`,
+        );
+      const vary: Record<string, SectionVariation> = {};
+      for (const [trackId, raw] of entries.sort(([a], [b]) =>
+        a < b ? -1 : a > b ? 1 : 0,
+      )) {
+        if (!isRecord(raw) || trackId.length === 0)
+          throw new ScoreValidationError(
+            `section ${name} vary.${trackId} must be an object`,
+          );
+        const variation: { transpose?: number; gain?: number } = {};
+        if (raw.transpose !== undefined) {
+          const t = raw.transpose;
+          if (
+            typeof t !== "number" ||
+            !Number.isInteger(t) ||
+            Math.abs(t) > SCORE_LIMITS.maxSectionTranspose
+          )
+            throw new ScoreValidationError(
+              `section ${name} vary.${trackId}.transpose must be an integer -${SCORE_LIMITS.maxSectionTranspose}..${SCORE_LIMITS.maxSectionTranspose}`,
+            );
+          if (t !== 0) variation.transpose = t;
+        }
+        if (raw.gain !== undefined) {
+          const g = raw.gain;
+          if (
+            typeof g !== "number" ||
+            !Number.isFinite(g) ||
+            g < 0 ||
+            g > SCORE_LIMITS.maxSectionGain
+          )
+            throw new ScoreValidationError(
+              `section ${name} vary.${trackId}.gain must be 0..${SCORE_LIMITS.maxSectionGain}`,
+            );
+          if (g !== 1) variation.gain = g;
+        }
+        if (Object.keys(variation).length > 0)
+          vary[trackId] = Object.freeze(variation);
+      }
+      if (Object.keys(vary).length > 0) out.vary = Object.freeze(vary);
+    }
+    return Object.freeze(out);
+  });
+  // Bar order; sections that start together keep the order they were given.
+  return sections
+    .map((section, index) => ({ section, index }))
+    .sort(
+      (a, b) => a.section.startBar - b.section.startBar || a.index - b.index,
+    )
+    .map(({ section }) => section);
+}
+
+function normalizeLoopSection(
+  value: unknown,
+  sections: readonly Section[],
+): string | undefined {
+  if (value === undefined || value === null) return undefined;
+  if (typeof value !== "string")
+    throw new ScoreValidationError(
+      "loopSection must be a section name or null",
+      "invalid-score",
+    );
+  const key = value.trim().replace(/\s+/gu, " ").toLowerCase();
+  return sections.find((section) => section.name.toLowerCase() === key)?.name;
+}
+
+function normalizeForm(
+  inputs: readonly unknown[],
+  sections: readonly Section[],
+): FormEntry[] {
+  if (!Array.isArray(inputs) || inputs.length > SCORE_LIMITS.maxFormEntries)
+    throw new ScoreValidationError(
+      `form cannot contain more than ${SCORE_LIMITS.maxFormEntries} entries`,
+      "score-limit",
+    );
+  const byName = new Map(
+    sections.map((section) => [section.name.toLowerCase(), section] as const),
+  );
+  return inputs.map((input, index): FormEntry => {
+    const record = typeof input === "string" ? { section: input } : input;
+    if (!isRecord(record) || typeof record.section !== "string")
+      throw new ScoreValidationError(`form entry ${index} must name a section`);
+    const section = byName.get(record.section.trim().toLowerCase());
+    if (!section)
+      throw new ScoreValidationError(
+        `form entry ${index} names an unknown section: ${record.section}`,
+      );
+    const repeat = record.repeat ?? 1;
+    if (
+      typeof repeat !== "number" ||
+      !Number.isInteger(repeat) ||
+      repeat < 1 ||
+      repeat > SCORE_LIMITS.maxFormRepeat
+    )
+      throw new ScoreValidationError(
+        `form entry ${index} repeat must be an integer 1..${SCORE_LIMITS.maxFormRepeat}`,
+      );
+    return Object.freeze(
+      repeat === 1
+        ? { section: section.name }
+        : { section: section.name, repeat },
+    );
+  });
+}
+
 function normalizeTracks(inputs: readonly unknown[]): Track[] {
   if (!Array.isArray(inputs) || inputs.length > SCORE_LIMITS.maxTracks) {
     throw new ScoreValidationError(
@@ -1299,9 +1806,44 @@ function normalizeTrack(input: unknown): Track {
   const fx = fxOrThrow(() => normalizeFx(input.fx));
   const fxAutomation = normalizeFxAutomation(input.fxAutomation);
   const synth = fxOrThrow(() => normalizeSynth(input.synth));
+  const keys = fxOrThrow(() => normalizeKeys(input.keys));
   const wavetable = normalizeWavetable(input.wavetable);
+  const modal = fxOrThrow(() => normalizeModal(input.modal));
+  if (modal && instrument !== MODAL_INSTRUMENT)
+    throw new ScoreValidationError(
+      `track ${id} has modal settings but its instrument is "${instrument}"`,
+      "invalid-track",
+    );
   const sampler = normalizeSampler(input.sampler);
   const rhythm = normalizeRhythm(input.rhythm, id);
+  const time = timeOrThrow(
+    () => normalizeTrackTime(input.time, `track ${id} time`),
+    "invalid-track",
+  );
+  let performance: TrackPerformance;
+  try {
+    performance = normalizeTrackPerformance(input, SCORE_LIMITS.maxTick);
+  } catch (error) {
+    if (error instanceof ExpressionValidationError)
+      throw new ScoreValidationError(
+        `track ${id} ${error.message}`,
+        "invalid-track",
+      );
+    throw error;
+  }
+  const tuning = tuningOrThrow(
+    () => normalizeTuning(input.tuning, `track ${id} tuning`),
+    "invalid-track",
+  );
+  const string = fxOrThrow(() => normalizeString(input.string));
+  // A bare `granular` instrument (set_instrument, `instrument granular`)
+  // gets an empty object, so the engine plays its defaults.
+  const granular =
+    fxOrThrow(() =>
+      normalizeGranular(input.granular, (ref) =>
+        normalizeSampleRef(ref, "granular src"),
+      ),
+    ) ?? (isGranularInstrument(instrument) ? Object.freeze({}) : undefined);
   let kit: string | undefined;
   if (input.kit !== undefined && input.kit !== null) {
     const found =
@@ -1323,7 +1865,12 @@ function normalizeTrack(input: unknown): Track {
       `track ${id} instrument "sampler" needs a sampler`,
       "invalid-track",
     );
-  if (sampler && !isSamplerInstrument(instrument))
+  // A granular track keeps the sampler it grains (`grain off` goes back).
+  if (
+    sampler &&
+    !isSamplerInstrument(instrument) &&
+    !isGranularInstrument(instrument)
+  )
     throw new ScoreValidationError(
       `track ${id} has a sampler but its instrument is "${instrument}"`,
       "invalid-track",
@@ -1353,6 +1900,13 @@ function normalizeTrack(input: unknown): Track {
     ...(sampler ? { sampler } : {}),
     ...(rhythm ? { rhythm } : {}),
     ...(kit ? { kit } : {}),
+    ...(time ? { time } : {}),
+    ...performance,
+    ...(tuning ? { tuning } : {}),
+    ...(string ? { string } : {}),
+    ...(granular ? { granular } : {}),
+    ...(keys ? { keys } : {}),
+    ...(modal ? { modal } : {}),
   });
 }
 
@@ -1386,6 +1940,29 @@ export function normalizeRhythm(
   return Object.freeze(rows);
 }
 
+function timeOrThrow<T>(
+  run: () => T,
+  code: ScoreValidationError["code"] = "invalid-score",
+): T {
+  try {
+    return run();
+  } catch (error) {
+    if (error instanceof TimeValidationError)
+      throw new ScoreValidationError(error.message, code);
+    throw error;
+  }
+}
+
+function tuningOrThrow<T>(run: () => T, code: ScoreValidationError["code"]): T {
+  try {
+    return run();
+  } catch (error) {
+    if (error instanceof TuningError)
+      throw new ScoreValidationError(error.message, code);
+    throw error;
+  }
+}
+
 function fxOrThrow<T>(run: () => T): T {
   try {
     return run();
@@ -1537,6 +2114,9 @@ export function normalizeSampleRef(input: unknown, name: string): SampleRef {
     fit?: boolean;
     accelerate?: number;
     squiz?: number;
+    bpm?: number;
+    fitmode?: SampleFitMode;
+    len?: number;
   } = { src };
   if (input.sha256 !== undefined) {
     if (typeof input.sha256 !== "string" || !SHA256_HEX.test(input.sha256))
@@ -1700,6 +2280,46 @@ export function normalizeSampleRef(input: unknown, name: string): SampleRef {
       1,
       SCORE_LIMITS.maxSampleSquiz,
     );
+  if (input.bpm !== undefined)
+    ref.bpm = boundedNumber(
+      input.bpm,
+      `${label} bpm`,
+      SCORE_LIMITS.minSampleBpm,
+      SCORE_LIMITS.maxSampleBpm,
+    );
+  if (input.fitmode !== undefined) {
+    if (!SAMPLE_FIT_MODES.includes(input.fitmode as SampleFitMode))
+      throw new ScoreValidationError(
+        `${label} fitmode must be "repitch", "beats" or "tones"`,
+        "invalid-track",
+      );
+    ref.fitmode = input.fitmode as SampleFitMode;
+  }
+  if (input.len !== undefined) {
+    const len = boundedNumber(
+      input.len,
+      `${label} len`,
+      0,
+      SCORE_LIMITS.maxSampleLenBeats,
+    );
+    if (len === 0)
+      throw new ScoreValidationError(
+        `${label} len must be greater than 0`,
+        "invalid-track",
+      );
+    ref.len = len;
+  }
+  if (
+    ref.fitmode !== undefined &&
+    ref.fitmode !== "repitch" &&
+    ref.bpm === undefined &&
+    ref.len === undefined &&
+    ref.fit !== true
+  )
+    throw new ScoreValidationError(
+      `${label} fitmode ${ref.fitmode} needs bpm, len or fit`,
+      "invalid-track",
+    );
   return Object.freeze(ref);
 }
 
@@ -1940,10 +2560,28 @@ function normalizeAutomation(
   return freezeArray(points);
 }
 
+/** The note cap `normalizeNotes` enforces; see `withNoteCap`. */
+let noteCap: number = SCORE_LIMITS.maxNotes;
+
+/**
+ * Runs `fn` with the note cap raised to `cap`. Stored scores keep
+ * SCORE_LIMITS.maxNotes; the arranged renderer bakes timed tracks (cycle,
+ * rate) into plain notes and may hold more than a stored score allows.
+ */
+export function withNoteCap<T>(cap: number, fn: () => T): T {
+  const previous = noteCap;
+  noteCap = Math.max(previous, cap);
+  try {
+    return fn();
+  } finally {
+    noteCap = previous;
+  }
+}
+
 function normalizeNotes(inputs: readonly unknown[]): Note[] {
-  if (!Array.isArray(inputs) || inputs.length > SCORE_LIMITS.maxNotes) {
+  if (!Array.isArray(inputs) || inputs.length > noteCap) {
     throw new ScoreValidationError(
-      `score cannot contain more than ${SCORE_LIMITS.maxNotes} notes`,
+      `score cannot contain more than ${noteCap} notes`,
       "score-limit",
     );
   }
@@ -2023,6 +2661,21 @@ function normalizeNote(input: unknown): Note {
       "invalid-note",
     );
   }
+  let expression: NoteExpression;
+  try {
+    expression = normalizeNoteExpression(input);
+  } catch (error) {
+    if (error instanceof ExpressionValidationError)
+      throw new ScoreValidationError(
+        `note ${id} ${error.message}`,
+        "invalid-note",
+      );
+    throw error;
+  }
+  const cents = tuningOrThrow(
+    () => normalizeNoteCents(input.cents, `note ${id}`),
+    "invalid-note",
+  );
   return Object.freeze({
     id,
     trackId,
@@ -2030,6 +2683,8 @@ function normalizeNote(input: unknown): Note {
     durationTicks,
     pitch,
     velocity: input.velocity,
+    ...expression,
+    ...(cents !== undefined ? { cents } : {}),
   });
 }