@hraness/dawg 0.6.0 → 0.7.0

package/core/score.ts

@@ -23,30 +23,53 @@ import {
 import {
   MODAL_INSTRUMENT,
   normalizeModal,
+  normalizeWind,
+  WIND_INSTRUMENT,
   type TrackModal,
+  type TrackWind,
 } from "./resonators.ts";
 import { normalizeSynth, type TrackSynth } from "./synth.ts";
+import {
+  normalizeSing,
+  normalizeVowel,
+  SING_INSTRUMENT,
+  type TrackSing,
+} from "./sing.ts";
+import {
+  normalizeVocoder,
+  vocoderScoreError,
+  VOCODER_INSTRUMENT,
+  type TrackVocoder,
+} from "./vocoder.ts";
+import { normalizeAutotune, type TrackAutotune } from "./autotune.ts";
+// Registers cross-track reference fields (autotune.from, vocoder.src).
+import "./routing.ts";
 import { normalizeString, type TrackString } from "./strings.ts";
 import {
   isGranularInstrument,
   normalizeGranular,
   type TrackGranular,
 } from "./granular.ts";
-import { normalizeKeys, type TrackKeys } from "./keys.ts";
+import { isKeysFamily, normalizeKeys, type TrackKeys } from "./keys.ts";
+import { GUITAR_TUNING_NAMES } from "./chords.ts";
 import {
   checkSongTime,
   normalizeSongTime,
   normalizeTrackTime,
   TimeValidationError,
   type SongTime,
+  timeWithinSong,
   type TrackTime,
   withMeterChange,
 } from "./tempo.ts";
 import {
   ExpressionValidationError,
   normalizeNoteExpression,
+  normalizePedal,
   normalizeTrackPerformance,
+  SOSTENUTO_STATES,
   type NoteExpression,
+  type PedalEvent,
   type NoteExpressionPatch,
   type TrackPerformance,
 } from "./expression.ts";
@@ -59,8 +82,22 @@ import {
 
 export type { Tuning } from "./tuning.ts";
 import { normalizeMaster, type SongMaster } from "./master.ts";
+import {
+  normalizeSongStyle,
+  SongStyleError,
+  type SongStyle,
+} from "./style-provenance.ts";
 
 export const SCORE_VERSION = 1 as const;
+
+/**
+ * Sound calibration (0.7): which revision of the released engines' level,
+ * pitch and voice fixes a song renders with. Absent (0) keeps every 0.4 to
+ * 0.6.1 project byte-identical; new songs start at the latest. Revision 1
+ * chokes the open hat, key-tracks toms, adds crash, ride and cowbell,
+ * band-limits hat metal, levels keys presets and steadies lip brass.
+ */
+export const CALIBRATION_LATEST = 1 as const;
 export const DEFAULT_TICKS_PER_BEAT = 480 as const;
 
 export const SCORE_LIMITS = Object.freeze({
@@ -83,7 +120,11 @@ export const SCORE_LIMITS = Object.freeze({
   maxSectionGain: 2,
   maxBeatsPerBar: 16,
   maxTicksPerBeat: 4096,
-  maxTick: 1_000_000,
+  /**
+   * Latest tick anything may sit at or reach: the longest valid song,
+   * 256 bars of 16/1 at 4096 ticks per beat (2^26).
+   */
+  maxTick: 67_108_864,
   minFilterCutoff: 20,
   maxFilterCutoff: 20_000,
   maxFilterResonance: 1,
@@ -116,6 +157,12 @@ export const SCORE_LIMITS = Object.freeze({
   maxSampleBpm: 400,
   /** Sampler `len` (window length in beats) bound. */
   maxSampleLenBeats: 1024,
+  /** Sampler `shift` and `formant` bound in semitones (0.6.1). */
+  maxSampleShift: 24,
+  /** Sampler `fadeTime`/`fadeInTime` bound in seconds (0.6.1). */
+  maxSampleFadeSeconds: 2,
+  /** Longest `resample` render in seconds (0.6.1). */
+  maxResampleSeconds: 600,
   /** Per sample file, enforced by the decoder and the import tool. */
   maxSampleFileBytes: 50 * 1024 * 1024,
   maxSampleSeconds: 600,
@@ -125,6 +172,34 @@ export const SCORE_LIMITS = Object.freeze({
    * `DAWG_ASSETS_CACHE_MAX` / `DAWG_PACKS_CACHE_MAX`.
    */
   maxSampleCacheBytes: 512 * 1024 * 1024,
+  /** Audio clips, takes and lyrics (0.7, shapes in the contract). */
+  maxClipsPerTrack: 256,
+  maxTakesPerTrack: 64,
+  maxClipGain: 4,
+  maxClipFadeSeconds: 2,
+  maxClipSeconds: 520,
+  maxClipTextLength: 2000,
+  maxLyricLength: 32,
+  maxTakeNudgeMs: 250,
+  maxTtsVoiceLength: 64,
+  /** Singers per note in a `sing` ensemble (0.7). */
+  singVoices: 8,
+  /** Ensemble members one `sing` track sounds at once (0.7). */
+  singVoicesPerTrack: 48,
+  maxSayCuts: 512,
+  maxTakePpm: 1000,
+  /** Vocoder (0.7): channel bands, formant shift (st), tracks per song. */
+  minVocoderBands: 4,
+  maxVocoderBands: 40,
+  maxVocoderFormant: 24,
+  maxVocoderTracks: 8,
+  /** Track.autotune (0.7). */
+  maxAutotuneSpeedMs: 400,
+  maxAutotuneHoldMs: 1000,
+  maxAutotuneGlideSeconds: 0.5,
+  maxAutotuneVibHz: 12,
+  /** Per-frame correction cap in semitones. */
+  maxAutotuneShift: 12,
 } as const);
 
 /** Instrument name that selects a track's `wavetable` oscillator. */
@@ -298,7 +373,8 @@ export class ScoreValidationError extends Error {
     | "invalid-track"
     | "duplicate-note"
     | "duplicate-track"
-    | "score-limit";
+    | "score-limit"
+    | "routing-cycle";
 
   constructor(
     message: string,
@@ -413,6 +489,54 @@ export type Track = Readonly<{
    * instrument with this field is rejected. Absent keeps today's tone.
    */
   modal?: TrackModal;
+  /**
+   * Optional (0.6.1): una corda (soft pedal) events, same shape as `pedal`.
+   * Modelled pianos read it at each onset (half is half the shift); other
+   * instruments ignore it.
+   */
+  softPedal?: readonly PedalEvent[];
+  /**
+   * Optional (0.6.1): sostenuto pedal events (down and up only). Keys held
+   * when it goes down ring until it lifts; later keys damp as usual.
+   */
+  sostenuto?: readonly PedalEvent[];
+  /**
+   * Optional (0.6.1): how the track is fretted when chords are strummed
+   * (`strum`, perform mode `guitar`): tuning, capo, hand stretch, how much
+   * open strings ring and a preferred position. Notes only; never read at
+   * render, so it changes no sound by itself.
+   */
+  guitar?: TrackGuitar;
+  /**
+   * Optional (0.6.1): a blown waveguide (`core/winds.ts`), a preset plus
+   * overrides. Plays only when `instrument` is `"wind"`; without it the
+   * legacy `wind` tone plays unchanged. Any other instrument with this
+   * field is rejected.
+   */
+  wind?: TrackWind;
+  /**
+   * Optional (0.7): the built-in singing voice (`core/sing.ts`), a preset
+   * plus overrides. Plays only when `instrument` is `"sing"`; any other
+   * instrument with this field is rejected.
+   */
+  sing?: TrackSing;
+  /**
+   * Optional (0.7): audio clips placed on the timeline. Shapes only in the
+   * contract; the renderer ignores them until the clips lane.
+   */
+  clips?: readonly AudioClip[];
+  /** Optional (0.7): recorded or imported takes that clips may reference. */
+  takes?: readonly Take[];
+  /**
+   * Optional (0.7): vocoder on this track (`core/vocoder.ts`); `src` names
+   * the modulator track. Absent: today's sound.
+   */
+  vocoder?: TrackVocoder;
+  /**
+   * Optional (0.7): pitch correction of every clip and sampler voice on the
+   * track (`core/autotune.ts`). Absent keeps the sound untouched.
+   */
+  autotune?: TrackAutotune;
 }> &
   /**
    * Performance (`core/expression.ts`): glide default, sustain pedal
@@ -508,6 +632,51 @@ export type SampleRef = Readonly<{
    * through the song's tempo map. `fit` wins over `bpm`, `bpm` over `len`.
    */
   len?: number;
+  /**
+   * Optional (0.6.1): pitch shift in semitones (−24..24) at constant
+   * length, a cached phase-vocoder preprocess (`src/audio/dsp/shift.ts`).
+   * Applied after any fit, so it follows `fitmode`.
+   */
+  shift?: number;
+  /**
+   * Optional (0.6.1, with `shift`): formant shift in semitones (−24..24).
+   * Absent: formants follow the pitch (chipmunk); 0 keeps them in place.
+   */
+  formant?: number;
+  /** Optional (0.6.1, Strudel `fadeTime`): release fade in seconds (0..2). */
+  fadeTime?: number;
+  /** Optional (0.6.1, Strudel `fadeInTime`): attack fade in seconds (0..2). */
+  fadeInTime?: number;
+  /**
+   * Optional (0.6.1): where `resample` rendered this file from; kept for
+   * reference only (never read by the renderer).
+   */
+  from?: SampleProvenance;
+  /**
+   * Optional (0.6.1, SFZ `lovel`/`hivel`): the MIDI velocity range
+   * [lo, hi] (0..127, lo ≤ hi) this voice plays. Keyed voices with the same
+   * root are velocity layers; a one-shot voice outside its range is silent
+   * unless its `rr` group has a voice for that velocity.
+   */
+  vel?: readonly [number, number];
+  /**
+   * Optional (0.6.1, SFZ `seq_length`): round-robin group name. One-shot
+   * voices in a group are one sound (any member's slot plays it); voices
+   * that match a note's velocity take turns, A B A B, in note order.
+   */
+  rr?: string;
+}>;
+
+/** `SampleRef.from`: the source of a resampled file (0.6.1). */
+export type SampleProvenance = Readonly<{
+  /** `track:<id>`, `orbit:<n>` or `master`. */
+  source: string;
+  /** Section name the render covered. */
+  section?: string;
+  /** Bars a..b (1-based, inclusive) the render covered. */
+  bars?: readonly [number, number];
+  /** sha256 of the canonical score JSON the file was rendered from. */
+  score: string;
 }>;
 
 /** Sampler `fitmode`: how a fitted window changes its time. */
@@ -541,14 +710,22 @@ export type TrackReverb = Readonly<{
   predelay?: number;
   /**
    * Optional (Strudel `iresponse`/`ir`): convolve with this impulse instead
-   * of the algorithmic tail. `builtin:room|hall|plate`, a pinned pack sound
+   * of the algorithmic tail. `builtin:room|hall|plate|reverse|gate|spring`, a pinned pack sound
    * or a project file; `size`, `fade` and `dim` then do nothing.
    */
   ir?: SampleRef;
 }>;
 
 /** Generated impulse responses `reverb.ir` can name as `builtin:<name>`. */
-export const REVERB_IR_BUILTINS = Object.freeze(["room", "hall", "plate"]);
+export const REVERB_IR_BUILTINS = Object.freeze([
+  "room",
+  "hall",
+  "plate",
+  // 0.6.1: a reverse (rising) wash, a gated tail, a spring tank.
+  "reverse",
+  "gate",
+  "spring",
+]);
 
 /**
  * Validates `reverb.ir`: a string or `{ src, … }`. Bare built-in names and
@@ -754,6 +931,15 @@ export type TrackPatch = Readonly<
     granular?: TrackGranular | null;
     keys?: TrackKeys | null;
     modal?: TrackModal | null;
+    softPedal?: Track["softPedal"] | null;
+    sostenuto?: Track["sostenuto"] | null;
+    guitar?: TrackGuitar | null;
+    wind?: TrackWind | null;
+    sing?: TrackSing | null;
+    clips?: readonly AudioClip[] | null;
+    takes?: readonly Take[] | null;
+    vocoder?: TrackVocoder | null;
+    autotune?: TrackAutotune | null;
   }
 >;
 
@@ -776,6 +962,10 @@ export type Note = Readonly<{
   velocity: number;
   /** Static offset from the tuned pitch in cents (±1200); absent is 0. */
   cents?: number;
+  /** Optional (0.7): one sung syllable, no whitespace (≤ 32 characters). */
+  lyric?: string;
+  /** Optional (0.7): the sung vowel, `"a"` or a morph `"a>u"` (sing). */
+  vowel?: string;
 }> &
   NoteExpression;
 
@@ -802,6 +992,15 @@ export type TrackInput = Readonly<
     | "granular"
     | "keys"
     | "modal"
+    | "softPedal"
+    | "sostenuto"
+    | "guitar"
+    | "wind"
+    | "sing"
+    | "clips"
+    | "takes"
+    | "vocoder"
+    | "autotune"
   > &
     Pick<Track, "id"> & {
       filter?: TrackFilter | null;
@@ -824,6 +1023,15 @@ export type TrackInput = Readonly<
       granular?: TrackGranular | null;
       keys?: TrackKeys | null;
       modal?: TrackModal | null;
+      softPedal?: Track["softPedal"] | null;
+      sostenuto?: Track["sostenuto"] | null;
+      guitar?: TrackGuitar | null;
+      wind?: TrackWind | null;
+      sing?: TrackSing | null;
+      clips?: readonly AudioClip[] | null;
+      takes?: readonly Take[] | null;
+      vocoder?: TrackVocoder | null;
+      autotune?: TrackAutotune | null;
     }
 >;
 
@@ -841,6 +1049,8 @@ export type NoteInput = Readonly<{
   pitch: number;
   velocity: number;
   cents?: number;
+  lyric?: string | null;
+  vowel?: string | null;
 }> &
   NoteExpressionPatch;
 
@@ -894,6 +1104,8 @@ export type TrackScoreData = Readonly<{
   notes?: readonly NoteInput[];
   /** Song master chain and loudness target (core/master.ts); absent is off. */
   master?: SongMaster | null;
+  /** Which style and seed made the song (core/style-provenance.ts); absent is none. */
+  style?: SongStyle | 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. */
@@ -903,6 +1115,8 @@ export type TrackScoreData = Readonly<{
    * the song (or its form). A name that matches no section is dropped.
    */
   loopSection?: string | null;
+  /** Sound calibration (0.7), 0..CALIBRATION_LATEST; absent or 0 is legacy. */
+  calibration?: number | null;
 }>;
 
 /** Canonical immutable score. Use `addNote`/`removeNote` to create a revision. */
@@ -920,12 +1134,16 @@ export class TrackScore {
   readonly notes: readonly Note[];
   /** Absent (not undefined-valued) without a master, so 0.4 scores are unchanged. */
   declare readonly master?: SongMaster;
+  /** Absent without a style, so older scores are unchanged. */
+  declare readonly style?: SongStyle;
   /** 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;
+  /** Sound calibration revision; absent is 0 (legacy engines). */
+  declare readonly calibration?: number;
 
   constructor(data: TrackScoreData = {}) {
     const tempoBpm = data.tempoBpm ?? 120;
@@ -989,6 +1207,13 @@ export class TrackScore {
     );
     const tracks = normalizeTracks(data.tracks ?? []);
     const notes = normalizeNotes(data.notes ?? []);
+    const trackIds = new Set(tracks.map((track) => track.id));
+    const orphan = notes.find((note) => !trackIds.has(note.trackId));
+    if (orphan)
+      throw new ScoreValidationError(
+        `note ${orphan.id} is on track ${orphan.trackId}, which does not exist`,
+        "invalid-note",
+      );
     this.tuning = tuning;
     let master: SongMaster | undefined;
     try {
@@ -999,6 +1224,15 @@ export class TrackScore {
       throw error;
     }
     if (master) this.master = master;
+    let style: SongStyle | undefined;
+    try {
+      style = normalizeSongStyle(data.style);
+    } catch (error) {
+      if (error instanceof SongStyleError)
+        throw new ScoreValidationError(error.message, "invalid-score");
+      throw error;
+    }
+    if (style) this.style = style;
     const sections = normalizeSections(data.sections ?? []);
     const form = normalizeForm(data.form ?? [], sections);
     // Sections count bars in one meter; meter changes would move them.
@@ -1021,6 +1255,8 @@ export class TrackScore {
     this.sections = freezeArray(sections);
     this.form = freezeArray(form);
     this.loopSection = normalizeLoopSection(data.loopSection, sections);
+    const calibration = normalizeCalibration(data.calibration);
+    if (calibration) this.calibration = calibration;
     Object.freeze(this);
   }
 
@@ -1032,8 +1268,14 @@ export class TrackScore {
     return removeNote(this, noteId);
   }
 
+  /** The song with `tracks`; notes on a track not listed go with it. */
   withTracks(tracks: readonly TrackInput[]): TrackScore {
-    return new TrackScore({ ...this.toJSON(), tracks });
+    const ids = new Set(tracks.map((track) => track.id));
+    return new TrackScore({
+      ...this.toJSON(),
+      tracks,
+      notes: this.notes.filter((note) => ids.has(note.trackId)),
+    });
   }
 
   withTempo(tempoBpm: number): TrackScore {
@@ -1058,8 +1300,19 @@ export class TrackScore {
   }
 
   /** Resize the loop without discarding notes or automation outside its bounds. */
+  /** A shorter song drops the time marks past its new end. */
   withBars(bars: number): TrackScore {
-    return new TrackScore({ ...this.toJSON(), bars });
+    const time =
+      bars < this.bars
+        ? timeWithinSong({
+            tempoBpm: this.tempoBpm,
+            beatsPerBar: this.beatsPerBar,
+            ticksPerBeat: this.ticksPerBeat,
+            bars,
+            ...(this.time ? { time: this.time } : {}),
+          })
+        : this.time;
+    return new TrackScore({ ...this.toJSON(), bars, time: time ?? null });
   }
 
   withKey(key: string | null): TrackScore {
@@ -1093,10 +1346,20 @@ export class TrackScore {
   }
 
   /** Replace the song master; `null` removes it (bypass). */
+  /** Set the sound calibration revision; 0 or null is legacy. */
+  withCalibration(calibration: number | null): TrackScore {
+    return new TrackScore({ ...this.toJSON(), calibration });
+  }
+
   withMaster(master: SongMaster | null): TrackScore {
     return new TrackScore({ ...this.toJSON(), master });
   }
 
+  /** Record (or clear, `null`) which style and seed made the song. */
+  withStyle(style: SongStyle | null): TrackScore {
+    return new TrackScore({ ...this.toJSON(), style });
+  }
+
   toJSON(): TrackScoreData & { version: typeof SCORE_VERSION } {
     return {
       version: SCORE_VERSION,
@@ -1110,11 +1373,13 @@ export class TrackScore {
       tracks: this.tracks,
       notes: this.notes,
       ...(this.master ? { master: this.master } : {}),
+      ...(this.style ? { style: this.style } : {}),
       ...(this.sections.length > 0 ? { sections: this.sections } : {}),
       ...(this.form.length > 0 ? { form: this.form } : {}),
       ...(this.loopSection === undefined
         ? {}
         : { loopSection: this.loopSection }),
+      ...(this.calibration ? { calibration: this.calibration } : {}),
     };
   }
 }
@@ -1181,6 +1446,7 @@ export type NotePatch = Readonly<
     Pick<Note, "startTick" | "durationTicks" | "pitch" | "velocity" | "cents">
   >
 > &
+  Readonly<{ lyric?: string | null; vowel?: string | null }> &
   NoteExpressionPatch;
 
 export function updateNote(
@@ -1189,7 +1455,10 @@ export function updateNote(
   patch: NotePatch,
 ): TrackScore {
   const current = score.notes.find((note) => note.id === noteId);
-  if (!current) return score;
+  // A patch for a missing note is a conflict (a stale or diverged score),
+  // never a silent no-op. removeNote stays idempotent: the note is gone.
+  if (!current)
+    throw new ScoreValidationError(`unknown note: ${noteId}`, "invalid-note");
   return new TrackScore({
     ...score.toJSON(),
     notes: score.notes.map((note) =>
@@ -1224,6 +1493,30 @@ export function updateTrack(
         patch.instrument !== MODAL_INSTRUMENT
       )
         delete next.modal;
+      // The legacy word `wind` is the legacy tone, so naming any instrument
+      // (`wind` included) without a wind field leaves the wind engine.
+      if (patch.instrument !== undefined && patch.wind === undefined)
+        delete next.wind;
+      // Likewise a sing field leaves with the singing instrument.
+      if (patch.instrument !== undefined && patch.sing === undefined)
+        delete next.sing;
+      // Keys settings only belong to a keys family (piano, electric, organ):
+      // switching to another instrument drops them unless the patch sets them.
+      if (
+        patch.instrument !== undefined &&
+        patch.keys === undefined &&
+        !isKeysFamily(patch.instrument)
+      )
+        delete next.keys;
+      // f07-vocoder: naming the `vocoder` instrument turns on its built-in
+      // carrier (an empty field keeps every default); a vocoder stage the
+      // track already has (its source) stays.
+      if (
+        patch.instrument === VOCODER_INSTRUMENT &&
+        patch.vocoder === undefined &&
+        next.vocoder === undefined
+      )
+        next.vocoder = Object.freeze({});
       return next as Track;
     }),
   );
@@ -1234,24 +1527,31 @@ export function removeTrack(score: TrackScore, trackId: string): TrackScore {
   if (!score.tracks.some((track) => track.id === trackId)) return score;
   return new TrackScore({
     ...score.toJSON(),
-    tracks: score.tracks.filter((track) => track.id !== trackId),
+    tracks: score.tracks
+      .filter((track) => track.id !== trackId)
+      .map((track) => dropTrackRefs(track, trackId)),
     notes: score.notes.filter((note) => note.trackId !== trackId),
   });
 }
 
-/** Moves a track to position `index` (clamped) in score order. */
+/** Moves a track to position `index` (0 .. tracks - 1) in score order. */
 export function moveTrack(
   score: TrackScore,
   trackId: string,
   index: number,
 ): TrackScore {
   const from = score.tracks.findIndex((track) => track.id === trackId);
-  if (from < 0 || !Number.isInteger(index))
+  if (
+    from < 0 ||
+    !Number.isInteger(index) ||
+    index < 0 ||
+    index >= score.tracks.length
+  )
     throw new ScoreValidationError(
-      "moveTrack needs an existing track and an integer index",
+      `moveTrack needs an existing track and an index 0..${score.tracks.length - 1}`,
       "invalid-track",
     );
-  const to = Math.max(0, Math.min(score.tracks.length - 1, index));
+  const to = index;
   if (from === to) return score;
   const tracks = [...score.tracks];
   const [moved] = tracks.splice(from, 1);
@@ -1414,6 +1714,22 @@ export type ScoreOperation =
       type: "setMaster";
       master: SongMaster | null;
     }>
+  | Readonly<{
+      /** Sound calibration revision (0.7); 0 or null is legacy. */
+      type: "setCalibration";
+      calibration: number | null;
+    }>
+  | Readonly<{
+      /** Which style and seed made the song (quality-08); null clears it. */
+      type: "setStyle";
+      style: SongStyle | null;
+    }>
+  | Readonly<{
+      /** Replaces a track's audio clips (0.7); null clears them. */
+      type: "setClips";
+      trackId: string;
+      clips: readonly AudioClip[] | null;
+    }>
   | Readonly<{
       type: "setSections";
       sections: readonly Section[];
@@ -1436,6 +1752,9 @@ export function applyScoreOperation(
   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 === "setCalibration")
+    return score.withCalibration(operation.calibration);
+  if (operation.type === "setStyle") return score.withStyle(operation.style);
   if (operation.type === "setSections")
     return score.withSections(
       operation.sections,
@@ -1461,6 +1780,8 @@ export function applyScoreOperation(
     );
   if (operation.type === "clearTrack")
     return clearTrack(score, operation.trackId);
+  if (operation.type === "setClips")
+    return setClips(score, operation.trackId, operation.clips);
   return assertNever(operation);
 }
 
@@ -1491,13 +1812,22 @@ export function scoreFromJSON(value: unknown): TrackScore {
     tracks: readonly TrackInput[];
     notes: readonly NoteInput[];
     master?: SongMaster;
+    style?: SongStyle;
     sections?: readonly Section[];
     form?: readonly FormEntry[];
     loopSection?: string | null;
+    calibration?: number | null;
   } = {
     tracks: optionalArray(value.tracks).map(parseTrack),
     notes: optionalArray(value.notes).map(parseNote),
   };
+  // Files written before 0.7 could hold notes on a track that no longer
+  // exists. They never sounded and no edit could reach them, so they go.
+  // They are still checked like any note first.
+  const trackIds = new Set(data.tracks.map((track) => track.id));
+  data.notes = normalizeNotes(data.notes).filter((note) =>
+    trackIds.has(note.trackId),
+  );
   const tempoBpm = optionalNumber(value.tempoBpm);
   const beatsPerBar = optionalNumber(value.beatsPerBar);
   const bars = optionalNumber(value.bars);
@@ -1514,6 +1844,9 @@ export function scoreFromJSON(value: unknown): TrackScore {
   // Validated by the constructor (core/master.ts normalizeMaster).
   if (value.master !== undefined && value.master !== null)
     data.master = value.master as SongMaster;
+  // Checked by the constructor (core/style-provenance.ts).
+  if (value.style !== undefined && value.style !== null)
+    data.style = value.style as SongStyle;
   // Shapes are checked by the constructor (normalizeSections, normalizeForm).
   if (value.sections !== undefined)
     data.sections = optionalArray(value.sections) as readonly Section[];
@@ -1522,6 +1855,9 @@ export function scoreFromJSON(value: unknown): TrackScore {
   // The constructor checks the type and drops a name matching no section.
   if (value.loopSection !== undefined)
     data.loopSection = value.loopSection as string | null;
+  // The constructor checks the range.
+  if (value.calibration !== undefined)
+    data.calibration = value.calibration as number | null;
   return new TrackScore(data);
 }
 
@@ -1651,6 +1987,21 @@ function normalizeSections(inputs: readonly unknown[]): Section[] {
     .map(({ section }) => section);
 }
 
+function normalizeCalibration(value: unknown): number | undefined {
+  if (value === undefined || value === null || value === 0) return undefined;
+  if (
+    typeof value !== "number" ||
+    !Number.isInteger(value) ||
+    value < 0 ||
+    value > CALIBRATION_LATEST
+  )
+    throw new ScoreValidationError(
+      `calibration must be an integer 0..${CALIBRATION_LATEST}`,
+      "invalid-score",
+    );
+  return value;
+}
+
 function normalizeLoopSection(
   value: unknown,
   sections: readonly Section[],
@@ -1712,7 +2063,7 @@ function normalizeTracks(inputs: readonly unknown[]): Track[] {
     );
   }
   const seen = new Set<string>();
-  return inputs.map((input) => {
+  const tracks = inputs.map((input) => {
     const track = normalizeTrack(input);
     if (seen.has(track.id))
       throw new ScoreValidationError(
@@ -1722,6 +2073,22 @@ function normalizeTracks(inputs: readonly unknown[]): Track[] {
     seen.add(track.id);
     return track;
   });
+  const vocoderError = vocoderScoreError(tracks, SCORE_LIMITS.maxVocoderTracks);
+  if (vocoderError)
+    throw new ScoreValidationError(vocoderError, "invalid-track");
+  // Cross-track references (0.7): autotune.from names another track.
+  for (const track of tracks) {
+    const from = track.autotune?.from;
+    if (from === undefined) continue;
+    if (from === track.id || !seen.has(from))
+      throw new ScoreValidationError(
+        from === track.id
+          ? `track ${track.id} autotune.from cannot be the track itself`
+          : `track ${track.id} autotune.from: unknown track "${from}"`,
+        "invalid-track",
+      );
+  }
+  return tracks;
 }
 
 function normalizeTrack(input: unknown): Track {
@@ -1814,7 +2181,26 @@ function normalizeTrack(input: unknown): Track {
       `track ${id} has modal settings but its instrument is "${instrument}"`,
       "invalid-track",
     );
+  const guitar = normalizeGuitar(input.guitar);
+  const wind = fxOrThrow(() => normalizeWind(input.wind));
+  if (wind && instrument !== WIND_INSTRUMENT)
+    throw new ScoreValidationError(
+      `track ${id} has wind settings but its instrument is "${instrument}"`,
+      "invalid-track",
+    );
+  const sing = fxOrThrow(() => normalizeSing(input.sing));
+  if (sing && instrument !== SING_INSTRUMENT)
+    throw new ScoreValidationError(
+      `track ${id} has sing settings but its instrument is "${instrument}"`,
+      "invalid-track",
+    );
   const sampler = normalizeSampler(input.sampler);
+  const takes = normalizeTakes(input.takes, id);
+  const vocoder = fxOrThrow(() => normalizeVocoder(input.vocoder));
+  const clips = normalizeClips(input.clips, id, takes);
+  const autotune = fxOrThrow(() =>
+    normalizeAutotune(input.autotune, instrument),
+  );
   const rhythm = normalizeRhythm(input.rhythm, id);
   const time = timeOrThrow(
     () => normalizeTrackTime(input.time, `track ${id} time`),
@@ -1835,6 +2221,28 @@ function normalizeTrack(input: unknown): Track {
     () => normalizeTuning(input.tuning, `track ${id} tuning`),
     "invalid-track",
   );
+  let softPedal: readonly PedalEvent[] | undefined;
+  let sostenuto: readonly PedalEvent[] | undefined;
+  try {
+    softPedal = normalizePedal(
+      input.softPedal,
+      SCORE_LIMITS.maxTick,
+      "softPedal",
+    );
+    sostenuto = normalizePedal(
+      input.sostenuto,
+      SCORE_LIMITS.maxTick,
+      "sostenuto",
+      SOSTENUTO_STATES,
+    );
+  } catch (error) {
+    if (error instanceof ExpressionValidationError)
+      throw new ScoreValidationError(
+        `track ${id} ${error.message}`,
+        "invalid-track",
+      );
+    throw error;
+  }
   const string = fxOrThrow(() => normalizeString(input.string));
   // A bare `granular` instrument (set_instrument, `instrument granular`)
   // gets an empty object, so the engine plays its defaults.
@@ -1907,9 +2315,94 @@ function normalizeTrack(input: unknown): Track {
     ...(granular ? { granular } : {}),
     ...(keys ? { keys } : {}),
     ...(modal ? { modal } : {}),
+    ...(softPedal ? { softPedal } : {}),
+    ...(sostenuto ? { sostenuto } : {}),
+    ...(guitar ? { guitar } : {}),
+    ...(wind ? { wind } : {}),
+    ...(sing ? { sing } : {}),
+    ...(clips ? { clips } : {}),
+    ...(takes ? { takes } : {}),
+    ...(vocoder ? { vocoder } : {}),
+    ...(autotune ? { autotune } : {}),
   });
 }
 
+/** Track.guitar (0.6.1): a tuning name or open-string pitches plus fretting. */
+export type TrackGuitar = Readonly<{
+  /** A GUITAR_TUNINGS name or 3..12 open-string MIDI pitches, low to high. */
+  tune?: string | readonly number[];
+  /** Capo fret 0..12. */
+  capo?: number;
+  /** Hand stretch in frets 3..6 (default 4). */
+  hand?: number;
+  /** 0 closed shapes .. 1 ringing open strings (default 0.5). */
+  ring?: number;
+  /** Preferred fret position 0..12. */
+  position?: number;
+}>;
+
+/** Validates Track.guitar; `{}` and null normalize to absent. */
+export function normalizeGuitar(input: unknown): TrackGuitar | undefined {
+  if (input === undefined || input === null) return undefined;
+  const fail = (message: string): never => {
+    throw new ScoreValidationError(`track guitar ${message}`, "invalid-track");
+  };
+  if (typeof input !== "object" || Array.isArray(input))
+    fail("must be an object or null");
+  const out: Record<string, unknown> = {};
+  const record = input as Record<string, unknown>;
+  for (const key of Object.keys(record))
+    if (!["tune", "capo", "hand", "ring", "position"].includes(key))
+      fail(`has no field "${key.slice(0, 32)}"`);
+  const tune = record.tune;
+  if (tune !== undefined && tune !== null) {
+    if (typeof tune === "string") {
+      const name = tune.toLowerCase().replace(/[\s_-]/g, "");
+      if (!(GUITAR_TUNING_NAMES as readonly string[]).includes(name))
+        fail(
+          `tune must be one of ${GUITAR_TUNING_NAMES.join(", ")} or a list of pitches`,
+        );
+      out.tune = name;
+    } else if (
+      Array.isArray(tune) &&
+      tune.length >= 3 &&
+      tune.length <= 12 &&
+      tune.every((p) => Number.isInteger(p) && p >= 0 && p <= 127)
+    )
+      out.tune = Object.freeze([...(tune as number[])]);
+    else fail("tune must be a tuning name or 3..12 MIDI pitches");
+  }
+  const int = (key: string, min: number, max: number) => {
+    const value = record[key];
+    if (value === undefined || value === null) return;
+    if (
+      typeof value !== "number" ||
+      !Number.isInteger(value) ||
+      value < min ||
+      value > max
+    )
+      fail(`${key} must be an integer ${min}..${max}`);
+    out[key] = value;
+  };
+  int("capo", 0, 12);
+  int("hand", 3, 6);
+  const ring = record.ring;
+  if (ring !== undefined && ring !== null) {
+    if (
+      typeof ring !== "number" ||
+      !Number.isFinite(ring) ||
+      ring < 0 ||
+      ring > 1
+    )
+      fail("ring must be 0..1");
+    out.ring = Math.round((ring as number) * 1000) / 1000;
+  }
+  int("position", 0, 12);
+  return Object.keys(out).length > 0
+    ? (Object.freeze(out) as TrackGuitar)
+    : undefined;
+}
+
 export function normalizeRhythm(
   input: unknown,
   trackId: string,
@@ -2032,6 +2525,8 @@ function trackEffectExtras(
 }
 
 const VOICE_NAME = /^[A-Za-z][A-Za-z0-9_]*$/;
+/** A sampler round-robin group name (`SampleRef.rr`). */
+const SAMPLE_RR_GROUP = /^[A-Za-z0-9_]{1,32}$/;
 const SHA256_HEX = /^[0-9a-f]{64}$/;
 
 /** Validates a `Sampler` from unknown; `undefined`/`null` means none. */
@@ -2117,6 +2612,13 @@ export function normalizeSampleRef(input: unknown, name: string): SampleRef {
     bpm?: number;
     fitmode?: SampleFitMode;
     len?: number;
+    shift?: number;
+    formant?: number;
+    fadeTime?: number;
+    fadeInTime?: number;
+    from?: SampleProvenance;
+    vel?: readonly [number, number];
+    rr?: string;
   } = { src };
   if (input.sha256 !== undefined) {
     if (typeof input.sha256 !== "string" || !SHA256_HEX.test(input.sha256))
@@ -2309,6 +2811,28 @@ export function normalizeSampleRef(input: unknown, name: string): SampleRef {
       );
     ref.len = len;
   }
+  if (input.vel !== undefined) {
+    const vel = input.vel;
+    if (
+      !Array.isArray(vel) ||
+      vel.length !== 2 ||
+      !vel.every((v) => Number.isInteger(v) && v >= 0 && v <= 127) ||
+      vel[0] > vel[1]
+    )
+      throw new ScoreValidationError(
+        `${label} vel must be [lo, hi], MIDI velocities 0..127 with lo ≤ hi`,
+        "invalid-track",
+      );
+    ref.vel = Object.freeze([vel[0] as number, vel[1] as number] as const);
+  }
+  if (input.rr !== undefined) {
+    if (typeof input.rr !== "string" || !SAMPLE_RR_GROUP.test(input.rr))
+      throw new ScoreValidationError(
+        `${label} rr must be a round-robin group name (letters, digits, _; at most 32)`,
+        "invalid-track",
+      );
+    ref.rr = input.rr;
+  }
   if (
     ref.fitmode !== undefined &&
     ref.fitmode !== "repitch" &&
@@ -2320,9 +2844,100 @@ export function normalizeSampleRef(input: unknown, name: string): SampleRef {
       `${label} fitmode ${ref.fitmode} needs bpm, len or fit`,
       "invalid-track",
     );
+  if (input.shift !== undefined)
+    ref.shift = boundedNumber(
+      input.shift,
+      `${label} shift`,
+      -SCORE_LIMITS.maxSampleShift,
+      SCORE_LIMITS.maxSampleShift,
+    );
+  if (input.formant !== undefined)
+    ref.formant = boundedNumber(
+      input.formant,
+      `${label} formant`,
+      -SCORE_LIMITS.maxSampleShift,
+      SCORE_LIMITS.maxSampleShift,
+    );
+  if (input.fadeTime !== undefined)
+    ref.fadeTime = boundedNumber(
+      input.fadeTime,
+      `${label} fadeTime`,
+      0,
+      SCORE_LIMITS.maxSampleFadeSeconds,
+    );
+  if (input.fadeInTime !== undefined)
+    ref.fadeInTime = boundedNumber(
+      input.fadeInTime,
+      `${label} fadeInTime`,
+      0,
+      SCORE_LIMITS.maxSampleFadeSeconds,
+    );
+  if (input.from !== undefined)
+    ref.from = normalizeProvenance(input.from, `${label} from`);
   return Object.freeze(ref);
 }
 
+const PROVENANCE_SOURCE =
+  /^(?:track:[A-Za-z0-9_-]{1,64}|orbit:[0-9]{1,2}|master)$/;
+
+function normalizeProvenance(input: unknown, label: string): SampleProvenance {
+  if (
+    !isRecord(input) ||
+    typeof input.source !== "string" ||
+    !PROVENANCE_SOURCE.test(input.source) ||
+    typeof input.score !== "string" ||
+    !SHA256_HEX.test(input.score)
+  )
+    throw new ScoreValidationError(
+      `${label} must be { source: track:<id>|orbit:<n>|master, score: <sha256> }`,
+      "invalid-track",
+    );
+  const from: {
+    source: string;
+    section?: string;
+    bars?: [number, number];
+    score: string;
+  } = {
+    source: input.source,
+    score: input.score,
+  };
+  if (input.section !== undefined) {
+    if (
+      typeof input.section !== "string" ||
+      input.section.length === 0 ||
+      input.section.length > 64
+    )
+      throw new ScoreValidationError(
+        `${label} section must be a section name`,
+        "invalid-track",
+      );
+    from.section = input.section;
+  }
+  if (input.bars !== undefined) {
+    const bars = input.bars;
+    if (
+      !Array.isArray(bars) ||
+      bars.length !== 2 ||
+      !bars.every((b) => Number.isInteger(b) && b >= 1 && b <= 100_000) ||
+      bars[0] > bars[1]
+    )
+      throw new ScoreValidationError(
+        `${label} bars must be [a, b] with 1 ≤ a ≤ b`,
+        "invalid-track",
+      );
+    from.bars = [bars[0], bars[1]];
+  }
+  // Key order is fixed so the printed JSON is stable.
+  return Object.freeze({
+    source: from.source,
+    ...(from.section !== undefined ? { section: from.section } : {}),
+    ...(from.bars !== undefined
+      ? { bars: Object.freeze(from.bars) as readonly [number, number] }
+      : {}),
+    score: from.score,
+  });
+}
+
 /** Prefix of a pack sound reference in `SampleRef.src`. */
 export const PACK_PREFIX = "pack:";
 
@@ -2638,6 +3253,12 @@ function normalizeNote(input: unknown): Note {
       "invalid-note",
     );
   }
+  if (startTick + durationTicks > SCORE_LIMITS.maxTick) {
+    throw new ScoreValidationError(
+      `note ${id} must end by tick ${SCORE_LIMITS.maxTick}`,
+      "invalid-note",
+    );
+  }
   const pitch = input.pitch;
   if (
     typeof pitch !== "number" ||
@@ -2676,6 +3297,11 @@ function normalizeNote(input: unknown): Note {
     () => normalizeNoteCents(input.cents, `note ${id}`),
     "invalid-note",
   );
+  const lyric = normalizeLyric(input.lyric, id);
+  const vowel =
+    input.vowel === undefined || input.vowel === null
+      ? undefined
+      : vowelOrThrow(input.vowel, id);
   return Object.freeze({
     id,
     trackId,
@@ -2685,6 +3311,8 @@ function normalizeNote(input: unknown): Note {
     velocity: input.velocity,
     ...expression,
     ...(cents !== undefined ? { cents } : {}),
+    ...(lyric !== undefined ? { lyric } : {}),
+    ...(vowel !== undefined ? { vowel } : {}),
   });
 }
 
@@ -2703,12 +3331,49 @@ function parseNote(value: unknown): NoteInput {
 function compareNotes(a: Note, b: Note): number {
   return (
     a.startTick - b.startTick ||
-    a.trackId.localeCompare(b.trackId) ||
+    compareIds(a.trackId, b.trackId) ||
     a.pitch - b.pitch ||
-    a.id.localeCompare(b.id)
+    compareIds(a.id, b.id)
   );
 }
 
+/**
+ * Printable ASCII in the order ICU's root collation gives it (uppercase
+ * letters share their lowercase rank and sort after them on a tie).
+ */
+const ID_COLLATION =
+  " _-,;:!?.'\"()[]{}@*/\\&#%`^+<=>|~$0123456789abcdefghijklmnopqrstuvwxyz";
+const PRINTABLE_ASCII = /^[\x20-\x7e]*$/;
+
+/**
+ * Canonical id order, independent of locale and ICU version. Printable
+ * ASCII ids keep the order `localeCompare` gave them before 0.7 (so older
+ * projects print and render byte-identically); any other id sorts after
+ * them by UTF-16 code units, so canonically equivalent spellings stay
+ * distinct and the order is total.
+ */
+export function compareIds(a: string, b: string): number {
+  if (a === b) return 0;
+  const asciiA = PRINTABLE_ASCII.test(a);
+  const asciiB = PRINTABLE_ASCII.test(b);
+  if (asciiA !== asciiB) return asciiA ? -1 : 1;
+  if (!asciiA) return a < b ? -1 : 1;
+  const length = Math.min(a.length, b.length);
+  for (let i = 0; i < length; i += 1) {
+    const rank =
+      ID_COLLATION.indexOf(a[i]!.toLowerCase()) -
+      ID_COLLATION.indexOf(b[i]!.toLowerCase());
+    if (rank !== 0) return rank;
+  }
+  if (a.length !== b.length) return a.length - b.length;
+  for (let i = 0; i < length; i += 1) {
+    if (a[i] === b[i]) continue;
+    // Same letter, different case: lowercase first.
+    return a[i] === a[i]!.toLowerCase() ? -1 : 1;
+  }
+  return 0;
+}
+
 function boundedString(
   value: unknown,
   label: string,
@@ -2758,3 +3423,503 @@ function assertNever(value: never): never {
     `unsupported score operation: ${String(value)}`,
   );
 }
+
+// ---------------------------------------------------------------------------
+// 0.7 Voice contract: audio clips, takes and lyrics (shapes only). The
+// renderer ignores these fields until the clips lane wires them up.
+// ---------------------------------------------------------------------------
+
+/** How a text-to-speech clip was made and where its syllables fall (0.7.1). */
+export type ClipSay = Readonly<{
+  engine: "say" | "espeak-ng" | "piper";
+  /** Stock voice name, at most 64 characters. */
+  voice: string;
+  /** Words per minute 80..400 (default 180). */
+  rate?: number;
+  /** Licence of the voice output, recorded with the clip. */
+  license: string;
+  /** Syllable starts in seconds, strictly increasing. */
+  cuts: readonly number[];
+  /** Voicing onsets in seconds (= cuts for unvoiced syllables). */
+  vowels: readonly number[];
+  /** Indices of unvoiced syllables. */
+  unvoiced?: readonly number[];
+  /** Octave shift applied to targets, -3..3. */
+  oct?: number;
+  /** 0..1 share of the spoken contour kept. */
+  soft?: number;
+  /** The pinned sung buffer. */
+  sung?: Readonly<{ src: string; sha256: string; key: string }>;
+}>;
+
+/** An audio file placed on a track's timeline (0.7). Times in seconds. */
+export type AudioClip = Readonly<{
+  id: string;
+  src: string;
+  sha256: string;
+  startTick: number;
+  offset?: number;
+  dur?: number;
+  gain?: number;
+  fadeInTime?: number;
+  fadeTime?: number;
+  rev?: boolean;
+  /** Name of the track's take this clip plays from. */
+  take?: string;
+  mute?: boolean;
+  text?: string;
+  say?: ClipSay;
+}>;
+
+/** A recorded or imported take (0.7 shape; recording is 0.7.1). */
+export type Take = Readonly<{
+  name: string;
+  src: string;
+  sha256: string;
+  startTick: number;
+  /** Seconds into the file where the take starts. */
+  offset: number;
+  /** Round-trip latency compensated, in seconds. */
+  latency: number;
+  latencyAssumed?: boolean;
+  /** Clock drift in parts per million (±1000). */
+  ppm?: number;
+  /** 0..1 fit of the alignment. */
+  fit?: number;
+  warn?: string;
+  /** Manual nudge in milliseconds (±250). */
+  nudge?: number;
+  inTick: number;
+  outTick: number;
+}>;
+
+const MAX_CLIP_LABEL_LENGTH = 128;
+
+function clipError(message: string): ScoreValidationError {
+  return new ScoreValidationError(message, "invalid-track");
+}
+
+function clipNumber(
+  value: unknown,
+  label: string,
+  min: number,
+  max: number,
+): number | undefined {
+  if (value === undefined) return undefined;
+  if (
+    typeof value !== "number" ||
+    !Number.isFinite(value) ||
+    value < min ||
+    value > max
+  )
+    throw clipError(`${label} must be a number ${min}..${max}`);
+  return value;
+}
+
+function clipTick(value: unknown, label: string): number {
+  if (
+    typeof value !== "number" ||
+    !Number.isInteger(value) ||
+    value < 0 ||
+    value > SCORE_LIMITS.maxTick
+  )
+    throw clipError(
+      `${label} must be an integer tick 0..${SCORE_LIMITS.maxTick}`,
+    );
+  return value;
+}
+
+function clipString(
+  value: unknown,
+  label: string,
+  max: number,
+): string | undefined {
+  if (value === undefined) return undefined;
+  if (typeof value !== "string" || value.length === 0 || value.length > max)
+    throw clipError(`${label} must be 1..${max} characters`);
+  return value;
+}
+
+function clipBool(value: unknown, label: string): boolean | undefined {
+  if (value === undefined) return undefined;
+  if (typeof value !== "boolean") throw clipError(`${label} must be a boolean`);
+  return value || undefined;
+}
+
+function clipSrc(value: unknown, label: string): string {
+  const packRef = typeof value === "string" && value.startsWith(PACK_PREFIX);
+  if (
+    typeof value !== "string" ||
+    value.length === 0 ||
+    value.length > SCORE_LIMITS.maxSamplePathLength ||
+    (packRef ? !isPackRef(value) : !isSafeRelativePath(value))
+  )
+    throw clipError(
+      `${label} src must be a project-relative path without ".." or pack:<pack>/<sound>, at most ${SCORE_LIMITS.maxSamplePathLength} characters`,
+    );
+  return value;
+}
+
+function clipSha(value: unknown, label: string): string {
+  if (typeof value !== "string" || !SHA256_HEX.test(value))
+    throw clipError(`${label} sha256 must be 64 lowercase hex characters`);
+  return value;
+}
+
+function increasingTimes(value: unknown, label: string): number[] {
+  if (!Array.isArray(value) || value.length > SCORE_LIMITS.maxSayCuts)
+    throw clipError(
+      `${label} must be an array of at most ${SCORE_LIMITS.maxSayCuts} times`,
+    );
+  let previous = -Infinity;
+  return value.map((time: unknown, index) => {
+    if (
+      typeof time !== "number" ||
+      !Number.isFinite(time) ||
+      time < 0 ||
+      time > SCORE_LIMITS.maxClipSeconds
+    )
+      throw clipError(
+        `${label}[${index}] must be seconds 0..${SCORE_LIMITS.maxClipSeconds}`,
+      );
+    if (time <= previous)
+      throw clipError(`${label} must be strictly increasing`);
+    previous = time;
+    return time;
+  });
+}
+
+/** Validates ClipSay; absent stays absent. */
+export function normalizeClipSay(
+  input: unknown,
+  label: string,
+): ClipSay | undefined {
+  if (input === undefined || input === null) return undefined;
+  if (!isRecord(input)) throw clipError(`${label} say must be an object`);
+  const engine = input.engine;
+  if (engine !== "say" && engine !== "espeak-ng" && engine !== "piper")
+    throw clipError(`${label} say.engine must be say, espeak-ng or piper`);
+  const voice = clipString(
+    input.voice,
+    `${label} say.voice`,
+    SCORE_LIMITS.maxTtsVoiceLength,
+  );
+  if (voice === undefined) throw clipError(`${label} say.voice is required`);
+  const license = clipString(
+    input.license,
+    `${label} say.license`,
+    MAX_CLIP_LABEL_LENGTH,
+  );
+  if (license === undefined)
+    throw clipError(`${label} say.license is required`);
+  const rate = clipNumber(input.rate, `${label} say.rate`, 80, 400);
+  const cuts = increasingTimes(input.cuts, `${label} say.cuts`);
+  const vowels = increasingTimes(input.vowels, `${label} say.vowels`);
+  if (cuts.length !== vowels.length)
+    throw clipError(`${label} say.cuts and say.vowels must be the same length`);
+  cuts.forEach((cut, index) => {
+    if (cut > vowels[index]!)
+      throw clipError(
+        `${label} say.cuts[${index}] must be <= say.vowels[${index}]`,
+      );
+  });
+  let unvoiced: number[] | undefined;
+  if (input.unvoiced !== undefined) {
+    if (!Array.isArray(input.unvoiced))
+      throw clipError(`${label} say.unvoiced must be an array of indices`);
+    let previous = -1;
+    unvoiced = input.unvoiced.map((index: unknown) => {
+      if (
+        typeof index !== "number" ||
+        !Number.isInteger(index) ||
+        index <= previous ||
+        index >= cuts.length
+      )
+        throw clipError(
+          `${label} say.unvoiced must be increasing indices below ${cuts.length}`,
+        );
+      previous = index;
+      return index;
+    });
+  }
+  const oct = clipNumber(input.oct, `${label} say.oct`, -3, 3);
+  if (oct !== undefined && !Number.isInteger(oct))
+    throw clipError(`${label} say.oct must be an integer -3..3`);
+  const soft = clipNumber(input.soft, `${label} say.soft`, 0, 1);
+  let sung: ClipSay["sung"];
+  if (input.sung !== undefined) {
+    if (!isRecord(input.sung))
+      throw clipError(`${label} say.sung must be { src, sha256, key }`);
+    const key = clipString(
+      input.sung.key,
+      `${label} say.sung.key`,
+      MAX_CLIP_LABEL_LENGTH,
+    );
+    if (key === undefined) throw clipError(`${label} say.sung.key is required`);
+    sung = Object.freeze({
+      src: clipSrc(input.sung.src, `${label} say.sung`),
+      sha256: clipSha(input.sung.sha256, `${label} say.sung`),
+      key,
+    });
+  }
+  return Object.freeze({
+    engine,
+    voice,
+    ...(rate !== undefined ? { rate } : {}),
+    license,
+    cuts: Object.freeze(cuts),
+    vowels: Object.freeze(vowels),
+    ...(unvoiced && unvoiced.length > 0
+      ? { unvoiced: Object.freeze(unvoiced) }
+      : {}),
+    ...(oct !== undefined ? { oct } : {}),
+    ...(soft !== undefined ? { soft } : {}),
+    ...(sung ? { sung } : {}),
+  });
+}
+
+/**
+ * Validates Track.takes: unique names, sample path rules, inTick < outTick.
+ * Null, absent and `[]` normalize to absent.
+ */
+export function normalizeTakes(
+  input: unknown,
+  trackId: string,
+): readonly Take[] | undefined {
+  if (input === undefined || input === null) return undefined;
+  if (!Array.isArray(input))
+    throw clipError(`track ${trackId} takes must be an array`);
+  if (input.length > SCORE_LIMITS.maxTakesPerTrack)
+    throw new ScoreValidationError(
+      `track ${trackId} takes holds at most ${SCORE_LIMITS.maxTakesPerTrack} takes`,
+      "score-limit",
+    );
+  const names = new Set<string>();
+  const takes = input.map((value: unknown, index): Take => {
+    if (!isRecord(value))
+      throw clipError(`track ${trackId} takes[${index}] must be an object`);
+    const name = clipString(
+      value.name,
+      `track ${trackId} takes[${index}] name`,
+      SCORE_LIMITS.maxNameLength,
+    );
+    if (name === undefined)
+      throw clipError(`track ${trackId} takes[${index}] name is required`);
+    if (names.has(name))
+      throw clipError(`track ${trackId} take name ${name} is duplicated`);
+    names.add(name);
+    const label = `track ${trackId} take ${name}`;
+    const offset = clipNumber(
+      value.offset,
+      `${label} offset`,
+      0,
+      SCORE_LIMITS.maxClipSeconds,
+    );
+    if (offset === undefined) throw clipError(`${label} offset is required`);
+    const latency = clipNumber(value.latency, `${label} latency`, -1, 1);
+    if (latency === undefined) throw clipError(`${label} latency is required`);
+    const inTick = clipTick(value.inTick, `${label} inTick`);
+    const outTick = clipTick(value.outTick, `${label} outTick`);
+    if (inTick >= outTick)
+      throw clipError(`${label} inTick must be before outTick`);
+    const latencyAssumed = clipBool(
+      value.latencyAssumed,
+      `${label} latencyAssumed`,
+    );
+    const ppm = clipNumber(
+      value.ppm,
+      `${label} ppm`,
+      -SCORE_LIMITS.maxTakePpm,
+      SCORE_LIMITS.maxTakePpm,
+    );
+    const fit = clipNumber(value.fit, `${label} fit`, 0, 1);
+    const warn = clipString(value.warn, `${label} warn`, MAX_CLIP_LABEL_LENGTH);
+    const nudge = clipNumber(
+      value.nudge,
+      `${label} nudge`,
+      -SCORE_LIMITS.maxTakeNudgeMs,
+      SCORE_LIMITS.maxTakeNudgeMs,
+    );
+    return Object.freeze({
+      name,
+      src: clipSrc(value.src, label),
+      sha256: clipSha(value.sha256, label),
+      startTick: clipTick(value.startTick, `${label} startTick`),
+      offset,
+      latency,
+      ...(latencyAssumed ? { latencyAssumed } : {}),
+      ...(ppm !== undefined ? { ppm } : {}),
+      ...(fit !== undefined ? { fit } : {}),
+      ...(warn !== undefined ? { warn } : {}),
+      ...(nudge !== undefined ? { nudge } : {}),
+      inTick,
+      outTick,
+    });
+  });
+  return takes.length > 0 ? Object.freeze(takes) : undefined;
+}
+
+/**
+ * Validates Track.clips: unique ids, sample path rules, sha256 pins,
+ * offset + dur within maxClipSeconds, fades that fit the clip, and takes
+ * that exist on the track. Null, absent and `[]` normalize to absent.
+ */
+export function normalizeClips(
+  input: unknown,
+  trackId: string,
+  takes: readonly Take[] | undefined,
+): readonly AudioClip[] | undefined {
+  if (input === undefined || input === null) return undefined;
+  if (!Array.isArray(input))
+    throw clipError(`track ${trackId} clips must be an array`);
+  if (input.length > SCORE_LIMITS.maxClipsPerTrack)
+    throw new ScoreValidationError(
+      `track ${trackId} clips holds at most ${SCORE_LIMITS.maxClipsPerTrack} clips`,
+      "score-limit",
+    );
+  const takeNames = new Set((takes ?? []).map((take) => take.name));
+  const ids = new Set<string>();
+  const clips = input.map((value: unknown, index): AudioClip => {
+    if (!isRecord(value))
+      throw clipError(`track ${trackId} clips[${index}] must be an object`);
+    const id = clipString(
+      value.id,
+      `track ${trackId} clips[${index}] id`,
+      SCORE_LIMITS.maxIdLength,
+    );
+    if (id === undefined)
+      throw clipError(`track ${trackId} clips[${index}] id is required`);
+    if (ids.has(id))
+      throw clipError(`track ${trackId} clip id ${id} is duplicated`);
+    ids.add(id);
+    const label = `track ${trackId} clip ${id}`;
+    const max = SCORE_LIMITS.maxClipSeconds;
+    const offset = clipNumber(value.offset, `${label} offset`, 0, max);
+    const dur = clipNumber(value.dur, `${label} dur`, 0, max);
+    if (dur === 0) throw clipError(`${label} dur must be above 0`);
+    if ((offset ?? 0) + (dur ?? 0) > max)
+      throw clipError(`${label} offset + dur must be at most ${max} seconds`);
+    const gain = clipNumber(
+      value.gain,
+      `${label} gain`,
+      0,
+      SCORE_LIMITS.maxClipGain,
+    );
+    const fadeMax = SCORE_LIMITS.maxClipFadeSeconds;
+    const fadeInTime = clipNumber(
+      value.fadeInTime,
+      `${label} fadeInTime`,
+      0,
+      fadeMax,
+    );
+    const fadeTime = clipNumber(
+      value.fadeTime,
+      `${label} fadeTime`,
+      0,
+      fadeMax,
+    );
+    if (dur !== undefined && (fadeInTime ?? 0) + (fadeTime ?? 0) > dur)
+      throw clipError(`${label} fadeInTime + fadeTime must fit within dur`);
+    const rev = clipBool(value.rev, `${label} rev`);
+    const take = clipString(
+      value.take,
+      `${label} take`,
+      SCORE_LIMITS.maxNameLength,
+    );
+    if (take !== undefined && !takeNames.has(take))
+      throw clipError(`${label} take ${take} does not exist on the track`);
+    const mute = clipBool(value.mute, `${label} mute`);
+    const text = clipString(
+      value.text,
+      `${label} text`,
+      SCORE_LIMITS.maxClipTextLength,
+    );
+    const say = normalizeClipSay(value.say, label);
+    return Object.freeze({
+      id,
+      src: clipSrc(value.src, label),
+      sha256: clipSha(value.sha256, label),
+      startTick: clipTick(value.startTick, `${label} startTick`),
+      ...(offset !== undefined ? { offset } : {}),
+      ...(dur !== undefined ? { dur } : {}),
+      ...(gain !== undefined ? { gain } : {}),
+      ...(fadeInTime !== undefined ? { fadeInTime } : {}),
+      ...(fadeTime !== undefined ? { fadeTime } : {}),
+      ...(rev ? { rev } : {}),
+      ...(take !== undefined ? { take } : {}),
+      ...(mute ? { mute } : {}),
+      ...(text !== undefined ? { text } : {}),
+      ...(say ? { say } : {}),
+    });
+  });
+  return clips.length > 0 ? Object.freeze(clips) : undefined;
+}
+
+/** Validates Note.vowel: `"a"` or a morph `"a>u"`; null clears. */
+function vowelOrThrow(input: unknown, noteId: string): string {
+  try {
+    return normalizeVowel(input);
+  } catch (error) {
+    if (error instanceof FxValidationError)
+      throw new ScoreValidationError(
+        `note ${noteId} ${error.message}`,
+        "invalid-note",
+      );
+    throw error;
+  }
+}
+
+/** Validates Note.lyric: one syllable without whitespace; null clears. */
+export function normalizeLyric(
+  input: unknown,
+  noteId: string,
+): string | undefined {
+  if (input === undefined || input === null) return undefined;
+  if (
+    typeof input !== "string" ||
+    input.length === 0 ||
+    input.length > SCORE_LIMITS.maxLyricLength ||
+    /\s/.test(input)
+  )
+    throw new ScoreValidationError(
+      `note ${noteId} lyric must be 1..${SCORE_LIMITS.maxLyricLength} characters without whitespace`,
+      "invalid-note",
+    );
+  return input;
+}
+
+/** Replaces (or with null clears) a track's clips. */
+export function setClips(
+  score: TrackScore,
+  trackId: string,
+  clips: readonly AudioClip[] | null,
+): TrackScore {
+  return updateTrack(score, trackId, { clips });
+}
+
+/**
+ * Cross-track references (0.7): fields that name another track register a
+ * drop function here (through `registerTrackRefs` in core/routing.ts) so
+ * removing a track never leaves a dangling reference.
+ */
+// `var` and a lazily created map: core/routing.ts registers while this
+// module may still be evaluating (score.ts imports routing.ts for its
+// side effect), so the map must not sit in a temporal dead zone.
+// eslint-disable-next-line no-var
+var trackRefDrops:
+  Map<string, (track: Track, removedId: string) => Track> | undefined;
+
+/** Registers how `field` forgets a removed track. Used by core/routing.ts. */
+export function registerTrackRefDrop(
+  field: string,
+  drop: (track: Track, removedId: string) => Track,
+): void {
+  (trackRefDrops ??= new Map()).set(field, drop);
+}
+
+function dropTrackRefs(track: Track, removedId: string): Track {
+  let next = track;
+  for (const drop of trackRefDrops?.values() ?? [])
+    next = drop(next, removedId);
+  return next;
+}