@hraness/dawg 0.6.1 → 0.7.0

package/core/score.ts

@@ -29,6 +29,21 @@ import {
   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,
@@ -43,6 +58,7 @@ import {
   normalizeTrackTime,
   TimeValidationError,
   type SongTime,
+  timeWithinSong,
   type TrackTime,
   withMeterChange,
 } from "./tempo.ts";
@@ -66,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({
@@ -90,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,
@@ -138,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. */
@@ -311,7 +373,8 @@ export class ScoreValidationError extends Error {
     | "invalid-track"
     | "duplicate-note"
     | "duplicate-track"
-    | "score-limit";
+    | "score-limit"
+    | "routing-cycle";
 
   constructor(
     message: string,
@@ -451,6 +514,29 @@ export type Track = Readonly<{
    * 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
@@ -849,6 +935,11 @@ export type TrackPatch = Readonly<
     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;
   }
 >;
 
@@ -871,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;
 
@@ -901,6 +996,11 @@ export type TrackInput = Readonly<
     | "sostenuto"
     | "guitar"
     | "wind"
+    | "sing"
+    | "clips"
+    | "takes"
+    | "vocoder"
+    | "autotune"
   > &
     Pick<Track, "id"> & {
       filter?: TrackFilter | null;
@@ -927,6 +1027,11 @@ export type TrackInput = Readonly<
       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;
     }
 >;
 
@@ -944,6 +1049,8 @@ export type NoteInput = Readonly<{
   pitch: number;
   velocity: number;
   cents?: number;
+  lyric?: string | null;
+  vowel?: string | null;
 }> &
   NoteExpressionPatch;
 
@@ -997,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. */
@@ -1006,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. */
@@ -1023,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;
@@ -1092,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 {
@@ -1102,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.
@@ -1124,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);
   }
 
@@ -1135,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 {
@@ -1161,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 {
@@ -1196,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,
@@ -1213,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 } : {}),
     };
   }
 }
@@ -1284,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(
@@ -1292,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) =>
@@ -1331,6 +1497,9 @@ export function updateTrack(
       // (`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 (
@@ -1339,6 +1508,15 @@ export function updateTrack(
         !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;
     }),
   );
@@ -1349,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);
@@ -1529,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[];
@@ -1551,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,
@@ -1576,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);
 }
 
@@ -1606,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);
@@ -1629,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[];
@@ -1637,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);
 }
 
@@ -1766,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[],
@@ -1827,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(
@@ -1837,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 {
@@ -1936,7 +2188,19 @@ function normalizeTrack(input: unknown): Track {
       `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`),
@@ -2055,6 +2319,11 @@ function normalizeTrack(input: unknown): Track {
     ...(sostenuto ? { sostenuto } : {}),
     ...(guitar ? { guitar } : {}),
     ...(wind ? { wind } : {}),
+    ...(sing ? { sing } : {}),
+    ...(clips ? { clips } : {}),
+    ...(takes ? { takes } : {}),
+    ...(vocoder ? { vocoder } : {}),
+    ...(autotune ? { autotune } : {}),
   });
 }
 
@@ -2984,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" ||
@@ -3022,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,
@@ -3031,6 +3311,8 @@ function normalizeNote(input: unknown): Note {
     velocity: input.velocity,
     ...expression,
     ...(cents !== undefined ? { cents } : {}),
+    ...(lyric !== undefined ? { lyric } : {}),
+    ...(vowel !== undefined ? { vowel } : {}),
   });
 }
 
@@ -3049,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,
@@ -3104,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;
+}