@hraness/dawg 0.2.0 → 0.4.0

package/core/score.ts

@@ -6,6 +6,22 @@
  * without rewriting the score.
  */
 
+import { normalizeRhythmRow, RHYTHM_LIMITS, type RhythmRow } from "./euclid.ts";
+import { isDrumInstrument } from "./drums.ts";
+import { synthKit, SYNTH_KIT_NAMES } from "./kits.ts";
+
+export type { RhythmRow } from "./euclid.ts";
+import {
+  FX_LANES,
+  FxValidationError,
+  normalizeFx,
+  normalizeParams,
+  TRACK_EFFECT_SPECS,
+  type FxLane,
+  type TrackFx,
+} from "./fx.ts";
+import { normalizeSynth, type TrackSynth } from "./synth.ts";
+
 export const SCORE_VERSION = 1 as const;
 export const DEFAULT_TICKS_PER_BEAT = 480 as const;
 
@@ -33,8 +49,198 @@ export const SCORE_LIMITS = Object.freeze({
   maxReverbMix: 1,
   minReverbSize: 0,
   maxReverbSize: 1,
+  /** Automation lanes kept in `fxAutomation` per track. */
+  maxFxLanes: 64,
+  /** Sampler voices per track (score v2, `sampler` field). */
+  maxSamplerVoices: 64,
+  maxSamplerVoiceNameLength: 32,
+  maxSamplePathLength: 256,
+  maxSampleUrlLength: 1024,
+  maxSampleGain: 2,
+  /** |speed| bound; negative speeds play in reverse. */
+  maxSampleSpeed: 8,
+  maxChokeGroupLength: 32,
+  /** Sampler `clip`/`legato` factor bound. */
+  maxSampleClip: 16,
+  /** |accelerate| bound. */
+  maxSampleAccelerate: 8,
+  /** Sampler `squiz` ratio bound. */
+  maxSampleSquiz: 32,
+  /** Per sample file, enforced by the decoder and the import tool. */
+  maxSampleFileBytes: 50 * 1024 * 1024,
+  maxSampleSeconds: 600,
+  /**
+   * In-memory decoded-sample budget. The disk caps (`.dawg/assets`, pack
+   * downloads) live in `src/audio/cache.ts` and follow
+   * `DAWG_ASSETS_CACHE_MAX` / `DAWG_PACKS_CACHE_MAX`.
+   */
+  maxSampleCacheBytes: 512 * 1024 * 1024,
 } as const);
 
+/** Instrument name that selects a track's `wavetable` oscillator. */
+export const WAVETABLE_INSTRUMENT = "wavetable" as const;
+
+/**
+ * Warp modes (Strudel's documented `warpmode` names). Each bends the read
+ * phase of the table; see `src/audio/wavetable.ts` for the exact maps.
+ */
+export const WARP_MODES = Object.freeze([
+  "none",
+  "asym",
+  "bendp",
+  "bendm",
+  "bendmp",
+  "sync",
+  "quant",
+] as const);
+export type WarpMode = (typeof WARP_MODES)[number];
+
+/** Prefix of a table generated in code (`builtin:basic`). */
+export const BUILTIN_TABLE_PREFIX = "builtin:" as const;
+
+/**
+ * A track's wavetable oscillator, with Strudel's parameter names. Every
+ * field but `table` is omitted at its default.
+ */
+export type TrackWavetable = Readonly<{
+  /**
+   * `builtin:<name>`, a pinned pack sound (`pack:uzu-wavetables/wt_digital:1`)
+   * or a project WAV (`tracks/<slug>/wavetables/vox.wav`, sha256-pinned).
+   */
+  table: SampleRef;
+  /** Position in the table, 0..1 (default 0). */
+  wt?: number;
+  /** Position envelope amount, -1..1 (default 0 = off). */
+  wtenv?: number;
+  /** Position envelope times in seconds and sustain level 0..1. */
+  wtattack?: number;
+  wtdecay?: number;
+  wtsustain?: number;
+  wtrelease?: number;
+  /** Position LFO rate in Hz (0..50) and depth 0..1 (default 0 = off). */
+  wtrate?: number;
+  wtdepth?: number;
+  /** Warp amount 0..1 and mode (default none). */
+  warp?: number;
+  warpmode?: WarpMode;
+  /** Randomness of each note's start phase, 0..1 (seeded by the note). */
+  wtphaserand?: number;
+}>;
+
+/** Strudel parameter name → [min, max, default] for wavetable numbers. */
+export const WAVETABLE_PARAMS = Object.freeze({
+  wt: [0, 1, 0],
+  wtenv: [-1, 1, 0],
+  wtattack: [0, 10, 0.01],
+  wtdecay: [0, 10, 0.1],
+  wtsustain: [0, 1, 1],
+  wtrelease: [0, 10, 0.1],
+  wtrate: [0, 50, 0],
+  wtdepth: [0, 1, 0],
+  warp: [0, 1, 0],
+  wtphaserand: [0, 1, 0],
+} as const satisfies Record<string, readonly [number, number, number]>);
+export type WavetableParam = keyof typeof WAVETABLE_PARAMS;
+
+const BUILTIN_TABLE = /^builtin:[a-z][a-z0-9_-]{0,31}$/;
+
+/**
+ * A project wavetable file: a project-relative `.wav` path (dawg writes them
+ * to `tracks/<slug>/wavetables/<name>.wav`).
+ */
+export function isLocalTableSrc(src: string): boolean {
+  return (
+    !src.startsWith(PACK_PREFIX) &&
+    !src.startsWith(BUILTIN_TABLE_PREFIX) &&
+    /\.wav$/i.test(src) &&
+    isSafeRelativePath(src)
+  );
+}
+
+export function isWavetableInstrument(instrument: string | undefined): boolean {
+  return (
+    typeof instrument === "string" &&
+    instrument.trim().toLowerCase() === WAVETABLE_INSTRUMENT
+  );
+}
+
+/** The table a wavetable track plays: its own, else the built-in `basic`. */
+export function wavetableOf(track: Track): TrackWavetable {
+  return track.wavetable ?? DEFAULT_WAVETABLE;
+}
+
+export const DEFAULT_WAVETABLE: TrackWavetable = Object.freeze({
+  table: Object.freeze({ src: `${BUILTIN_TABLE_PREFIX}basic` }),
+});
+
+export function normalizeWavetable(input: unknown): TrackWavetable | undefined {
+  if (input === undefined || input === null) return undefined;
+  if (!isRecord(input))
+    throw new ScoreValidationError(
+      "track wavetable must be an object or null",
+      "invalid-track",
+    );
+  const table = input.table;
+  let ref: SampleRef;
+  if (
+    isRecord(table) &&
+    typeof table.src === "string" &&
+    table.src.startsWith(BUILTIN_TABLE_PREFIX)
+  ) {
+    if (!BUILTIN_TABLE.test(table.src) || Object.keys(table).length !== 1)
+      throw new ScoreValidationError(
+        "wavetable table builtin:<name> takes no other fields",
+        "invalid-track",
+      );
+    ref = Object.freeze({ src: table.src });
+  } else {
+    ref = normalizeSampleRef(table, "wavetable table");
+    if (!isPackRef(ref.src) && !isLocalTableSrc(ref.src))
+      throw new ScoreValidationError(
+        "wavetable table must be builtin:<name>, pack:<pack>/<sound>[:<n>] or a project .wav path",
+        "invalid-track",
+      );
+  }
+  const out: Record<string, unknown> = { table: ref };
+  for (const name of Object.keys(WAVETABLE_PARAMS) as WavetableParam[]) {
+    const value = input[name];
+    if (value === undefined) continue;
+    const [min, max, fallback] = WAVETABLE_PARAMS[name];
+    if (typeof value !== "number" || !Number.isFinite(value))
+      throw new ScoreValidationError(
+        `wavetable ${name} must be a number ${min}..${max}`,
+        "invalid-track",
+      );
+    const clamped = Math.max(min, Math.min(max, value));
+    if (clamped !== fallback) out[name] = clamped;
+  }
+  if (input.warpmode !== undefined) {
+    if (!WARP_MODES.includes(input.warpmode as WarpMode))
+      throw new ScoreValidationError(
+        `wavetable warpmode must be one of ${WARP_MODES.join(", ")}`,
+        "invalid-track",
+      );
+    if (input.warpmode !== "none") out.warpmode = input.warpmode;
+  }
+  for (const key of Object.keys(input))
+    if (
+      key !== "table" &&
+      key !== "warpmode" &&
+      !Object.prototype.hasOwnProperty.call(WAVETABLE_PARAMS, key)
+    )
+      throw new ScoreValidationError(
+        `wavetable has an unknown field ${key.slice(0, 32)}`,
+        "invalid-track",
+      );
+  return Object.freeze(out) as TrackWavetable;
+}
+
+/** Instrument name that selects a track's `sampler`. */
+export const SAMPLER_INSTRUMENT = "sampler" as const;
+
+/** First pitch slot assigned to one-shot sampler voices (GM kick). */
+export const SAMPLER_FIRST_SLOT = 36;
+
 export class ScoreValidationError extends Error {
   readonly code:
     | "invalid-score"
@@ -85,20 +291,179 @@ export type Track = Readonly<{
   delayMixAutomation?: readonly AutomationPoint[];
   /** Algorithmic stereo reverb send, mixed after the delay. */
   reverb?: TrackReverb;
+  /**
+   * Optional: insert effects by name (`core/fx.ts`), each with every
+   * parameter stored. Rendered in `FX_CHAIN` order.
+   */
+  fx?: TrackFx;
+  /** Optional: automation for `fx` parameters, keyed `<effect>-<param>`. */
+  fxAutomation?: Readonly<Partial<Record<FxLane, readonly AutomationPoint[]>>>;
+  /**
+   * Optional: synth voice parameters (`core/synth.ts`), Strudel names.
+   * Only the parameters a document sets are stored; lanes are
+   * `fxAutomation["synth-<param>"]`, read at note onsets.
+   */
+  synth?: TrackSynth;
+  /**
+   * Wavetable oscillator settings (Strudel names). Used when `instrument`
+   * is `"wavetable"`; kept when the instrument changes so switching back
+   * restores them. Absent means the built-in `basic` table at position 0.
+   */
+  wavetable?: TrackWavetable;
+  /** Wavetable position (`wt`, 0..1) control points; overrides the static `wt`. */
+  wtAutomation?: readonly AutomationPoint[];
+  /**
+   * Score v2: sample voices; present exactly when `instrument` is
+   * `"sampler"`. Documents without it decode unchanged.
+   */
+  sampler?: Sampler;
+  /**
+   * Generated drum rows (Euclidean or grid, see `core/euclid.ts`). The notes
+   * they generate are stored as ordinary notes; the rows are the editable
+   * source for those voices. Absent when empty.
+   */
+  rhythm?: readonly RhythmRow[];
+  /**
+   * Synthesized drum kit for an `instrument: "kit"` track (`syn808`,
+   * `lofi`, … see `core/kits.ts`). Absent plays the default voices.
+   */
+  kit?: string;
+}>;
+
+/**
+ * A track's sample voices (Strudel-aligned). In `oneshot` mode every voice is
+ * a drum-like hit addressed by the pitch slot `samplerVoiceSlots` assigns
+ * (36, 37, … in voice-name order); in `keyed` mode notes are ordinary pitches
+ * and a voice is resampled from its `root`.
+ */
+export type Sampler = Readonly<{
+  voices: Readonly<Record<string, SampleRef>>;
+  mode: "oneshot" | "keyed";
+}>;
+
+export type SampleRef = Readonly<{
+  /**
+   * Project-relative path, normally `tracks/<slug>/samples/<file>`, or a
+   * pack sound `pack:<pack>/<sound>[:<n>]` (`pack:tidal-drum-machines/RolandTR909_bd:0`).
+   */
+  src: string;
+  /** Content hash (64 hex) when known; the decoded cache is keyed by it. */
+  sha256?: string;
+  /** Pack sounds: the pinned HTTPS file the sound resolved to. */
+  url?: string;
+  /** Pack sounds: the pack's license (SPDX id or `none stated`). */
+  license?: string;
+  /** MIDI note the file plays at in keyed mode, default 60. */
+  root?: number;
+  /** Start fraction 0..1 of the file. */
+  begin?: number;
+  /** End fraction 0..1 of the file, greater than `begin`. */
+  end?: number;
+  /** Linear gain 0..2. */
+  gain?: number;
+  /** Playback rate; negative reverses. |speed| ≤ 8, never 0. */
+  speed?: number;
+  /** Sustain by looping begin..end. */
+  loop?: boolean;
+  /** Choke group: a new hit in the group stops the previous one. */
+  choke?: string;
+  /**
+   * Optional (Strudel `loopBegin`/`loopb`, `loopEnd`/`loope`): the looped
+   * part of the window, fractions of the file with
+   * begin ≤ loopBegin < loopEnd ≤ end. Playback starts at `begin`.
+   */
+  loopBegin?: number;
+  loopEnd?: number;
+  /**
+   * Optional (Strudel `clip`/`legato`): the voice lasts the note's length
+   * times this, cutting the sample off; a oneshot voice otherwise plays
+   * the whole window. 0 < clip ≤ 16.
+   */
+  clip?: number;
+  /**
+   * Optional (Strudel/Tidal `unit`): how `speed` reads. `r` (default) is a
+   * rate; `c`: the window lasts 1/|speed| cycles (a cycle is one bar);
+   * `s`: the window lasts |speed| seconds. Negative still reverses.
+   */
+  unit?: SampleUnit;
+  /** Optional (Strudel `fit`): the window lasts exactly the note's length. */
+  fit?: boolean;
+  /**
+   * Optional (Tidal/Strudel `accelerate`): the rate ramps linearly by this
+   * many times the starting rate over the voice (−8..8; −1 slows to a stop).
+   */
+  accelerate?: number;
+  /**
+   * Optional (Tidal/Strudel `squiz`): raise the pitch by this ratio inside
+   * each zero-crossing cycle, repeating the cycle to keep the length
+   * (1 is off, up to 32).
+   */
+  squiz?: number;
 }>;
 
+/** Sample `unit`: rate, cycles (bars) or seconds. */
+export type SampleUnit = "r" | "c" | "s";
+export const SAMPLE_UNITS: readonly SampleUnit[] = Object.freeze([
+  "r",
+  "c",
+  "s",
+]);
+
 export type TrackReverb = Readonly<{
   /** Wet level added to the dry signal, 0..1. */
   mix: number;
   /** Room size 0..1: longer comb feedback and a darker, longer tail. */
   size: number;
+  /** Optional: decay time to -60 dB in seconds; overrides the size-derived decay. */
+  fade?: number;
+  /** Optional: low-pass on the reverb input, Hz. */
+  lowpass?: number;
+  /** Optional: the tail darkens toward this frequency (Hz) as it decays. */
+  dim?: number;
+  /** Optional: seconds before the tail starts. */
+  predelay?: number;
+  /**
+   * Optional (Strudel `iresponse`/`ir`): convolve with this impulse instead
+   * of the algorithmic tail. `builtin:room|hall|plate`, 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"]);
+
+/**
+ * Validates `reverb.ir`: a string or `{ src, … }`. Bare built-in names and
+ * `builtin:<name>` become `{ src: "builtin:<name>" }`; anything else is a
+ * sample reference (pack sound or project-relative file).
+ */
+export function normalizeReverbIr(input: unknown): SampleRef {
+  const ref = typeof input === "string" ? { src: input } : input;
+  if (isRecord(ref) && typeof ref.src === "string") {
+    const bare = REVERB_IR_BUILTINS.includes(ref.src);
+    if (bare || ref.src.startsWith(BUILTIN_TABLE_PREFIX)) {
+      const name = bare ? ref.src : ref.src.slice(BUILTIN_TABLE_PREFIX.length);
+      if (!REVERB_IR_BUILTINS.includes(name) || Object.keys(ref).length !== 1)
+        throw new ScoreValidationError(
+          `track reverb ir builtin must be one of ${REVERB_IR_BUILTINS.map((n) => `builtin:${n}`).join(", ")} with no other fields`,
+          "invalid-track",
+        );
+      return Object.freeze({ src: `${BUILTIN_TABLE_PREFIX}${name}` });
+    }
+  }
+  return normalizeSampleRef(ref, "reverb ir");
+}
+
 export type TrackFilter = Readonly<{
   /** Cutoff frequency in Hz, 20..20000. */
   cutoff: number;
   /** Resonance 0..1, mapped to a bounded biquad Q. */
   resonance: number;
+  /** Optional: filter type; absent is the original low-pass. */
+  type?: "lpf" | "hpf" | "bpf";
+  /** Optional: slope; absent is the original 12 dB/oct biquad. */
+  ftype?: "12db" | "24db" | "ladder";
 }>;
 
 export type TrackDelay = Readonly<{
@@ -108,15 +473,31 @@ export type TrackDelay = Readonly<{
   feedback: number;
   /** Wet level added to the dry signal, 0..1. */
   mix: number;
+  /** Optional: delay time in seconds; 0/absent follows `beats`. */
+  time?: number;
+  /** Optional: repeats alternate left/right; absent is the original cross-fed stereo. */
+  pingpong?: boolean;
+  /** Optional: low-pass (Hz) inside the feedback loop. */
+  highcut?: number;
 }>;
 
-export type AutomationParameter =
-  "volume" | "pan" | "filter" | "resonance" | "delay-feedback" | "delay-mix";
+/** The lanes stored in their own track fields (`AUTOMATION_LANES`). */
+export type TrackAutomationParameter =
+  | "volume"
+  | "pan"
+  | "filter"
+  | "resonance"
+  | "delay-feedback"
+  | "delay-mix"
+  | "wt";
+
+/** Every automation lane: the track-field lanes plus `fx` lanes. */
+export type AutomationParameter = TrackAutomationParameter | FxLane;
 
 /** Track field and value range for every automation lane. */
 export const AUTOMATION_LANES: Readonly<
   Record<
-    AutomationParameter,
+    TrackAutomationParameter,
     Readonly<{
       field:
         | "volumeAutomation"
@@ -124,7 +505,8 @@ export const AUTOMATION_LANES: Readonly<
         | "filterAutomation"
         | "resonanceAutomation"
         | "delayFeedbackAutomation"
-        | "delayMixAutomation";
+        | "delayMixAutomation"
+        | "wtAutomation";
       min: number;
       max: number;
     }>
@@ -152,17 +534,69 @@ export const AUTOMATION_LANES: Readonly<
     min: 0,
     max: SCORE_LIMITS.maxDelayMix,
   },
+  wt: { field: "wtAutomation", min: 0, max: 1 },
 });
 
-export function isAutomationParameter(
+const FX_LANE_RANGES: ReadonlyMap<
+  string,
+  Readonly<{ min: number; max: number }>
+> = new Map(
+  FX_LANES.map(({ lane, spec }) => [lane, { min: spec.min, max: spec.max }]),
+);
+
+export function isTrackAutomationParameter(
   value: unknown,
-): value is AutomationParameter {
+): value is TrackAutomationParameter {
   return (
     typeof value === "string" &&
     Object.prototype.hasOwnProperty.call(AUTOMATION_LANES, value)
   );
 }
 
+export function isAutomationParameter(
+  value: unknown,
+): value is AutomationParameter {
+  return (
+    isTrackAutomationParameter(value) ||
+    (typeof value === "string" && FX_LANE_RANGES.has(value))
+  );
+}
+
+/** Every automation lane name, track-field lanes first. */
+export const AUTOMATION_PARAMETERS: readonly AutomationParameter[] =
+  Object.freeze([
+    ...(Object.keys(AUTOMATION_LANES) as TrackAutomationParameter[]),
+    ...FX_LANES.map(({ lane }) => lane),
+  ]);
+
+/** Value range of any lane. */
+export function automationRange(
+  parameter: AutomationParameter,
+): Readonly<{ min: number; max: number }> {
+  if (isTrackAutomationParameter(parameter)) {
+    const { min, max } = AUTOMATION_LANES[parameter];
+    return { min, max };
+  }
+  const range = FX_LANE_RANGES.get(parameter);
+  if (!range)
+    throw new ScoreValidationError(
+      `unknown automation parameter: ${String(parameter)}`,
+      "invalid-track",
+    );
+  return range;
+}
+
+/** A track's points on any lane (empty when it has none). */
+export function automationPoints(
+  track: Track | undefined,
+  parameter: AutomationParameter,
+): readonly AutomationPoint[] {
+  if (!track) return [];
+  if (isTrackAutomationParameter(parameter))
+    return track[AUTOMATION_LANES[parameter].field] ?? [];
+  return track.fxAutomation?.[parameter as FxLane] ?? [];
+}
+
 /** Track fields that score operations may patch; `null` clears an effect. */
 export type TrackPatch = Readonly<
   Partial<
@@ -180,11 +614,19 @@ export type TrackPatch = Readonly<
       | "resonanceAutomation"
       | "delayFeedbackAutomation"
       | "delayMixAutomation"
+      | "wtAutomation"
     >
   > & {
     filter?: TrackFilter | null;
     delay?: TrackDelay | null;
     reverb?: TrackReverb | null;
+    sampler?: Sampler | null;
+    rhythm?: readonly RhythmRow[] | null;
+    kit?: string | null;
+    fx?: TrackFx | null;
+    fxAutomation?: Track["fxAutomation"] | null;
+    synth?: TrackSynth | null;
+    wavetable?: TrackWavetable | null;
   }
 >;
 
@@ -204,11 +646,30 @@ export type Note = Readonly<{
 }>;
 
 export type TrackInput = Readonly<
-  Omit<Partial<Track>, "filter" | "delay" | "reverb"> &
+  Omit<
+    Partial<Track>,
+    | "filter"
+    | "delay"
+    | "reverb"
+    | "sampler"
+    | "rhythm"
+    | "kit"
+    | "fx"
+    | "fxAutomation"
+    | "synth"
+    | "wavetable"
+  > &
     Pick<Track, "id"> & {
       filter?: TrackFilter | null;
       delay?: TrackDelay | null;
       reverb?: TrackReverb | null;
+      sampler?: Sampler | null;
+      rhythm?: readonly RhythmRow[] | null;
+      kit?: string | null;
+      fx?: TrackFx | null;
+      fxAutomation?: Track["fxAutomation"] | null;
+      synth?: TrackSynth | null;
+      wavetable?: TrackWavetable | null;
     }
 >;
 
@@ -348,6 +809,15 @@ export class TrackScore {
     return new TrackScore({ ...this.toJSON(), bars });
   }
 
+  withKey(key: string | null): TrackScore {
+    return new TrackScore({ ...this.toJSON(), key });
+  }
+
+  /** Change the meter; ticks are per beat, so notes keep their positions. */
+  withMeter(beatsPerBar: number): TrackScore {
+    return new TrackScore({ ...this.toJSON(), beatsPerBar });
+  }
+
   toJSON(): TrackScoreData & { version: typeof SCORE_VERSION } {
     return {
       version: SCORE_VERSION,
@@ -476,6 +946,62 @@ export function updateTrack(
   );
 }
 
+/** Removes a track and every note on it; unknown ids are a no-op. */
+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),
+    notes: score.notes.filter((note) => note.trackId !== trackId),
+  });
+}
+
+/** Moves a track to position `index` (clamped) 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))
+    throw new ScoreValidationError(
+      "moveTrack needs an existing track and an integer index",
+      "invalid-track",
+    );
+  const to = Math.max(0, Math.min(score.tracks.length - 1, index));
+  if (from === to) return score;
+  const tracks = [...score.tracks];
+  const [moved] = tracks.splice(from, 1);
+  tracks.splice(to, 0, moved!);
+  return score.withTracks(tracks);
+}
+
+export function isSamplerInstrument(instrument: string | undefined): boolean {
+  return (
+    typeof instrument === "string" &&
+    instrument.trim().toLowerCase() === SAMPLER_INSTRUMENT
+  );
+}
+
+/**
+ * One-shot voices are addressed by pitch slots so the drum-lane projection
+ * and note tools keep working: voice names sorted by code point, slots from
+ * `SAMPLER_FIRST_SLOT` upward. Keyed samplers have no slots.
+ */
+export function samplerVoiceSlots(
+  sampler: Sampler,
+): ReadonlyMap<string, number> {
+  const slots = new Map<string, number>();
+  if (sampler.mode !== "oneshot") return slots;
+  const names = Object.keys(sampler.voices).sort(compareCodePoints);
+  names.forEach((name, index) => slots.set(name, SAMPLER_FIRST_SLOT + index));
+  return slots;
+}
+
+function compareCodePoints(a: string, b: string): number {
+  return a < b ? -1 : a > b ? 1 : 0;
+}
+
 export function setVolumeAutomation(
   score: TrackScore,
   trackId: string,
@@ -512,9 +1038,18 @@ export function setTrackAutomation(
       `unknown automation parameter: ${String(parameter)}`,
       "invalid-track",
     );
-  return updateTrack(score, trackId, {
-    [AUTOMATION_LANES[parameter].field]: points,
-  });
+  if (isTrackAutomationParameter(parameter))
+    return updateTrack(score, trackId, {
+      [AUTOMATION_LANES[parameter].field]: points,
+    });
+  const track = score.tracks.find((candidate) => candidate.id === trackId);
+  if (!track) return score;
+  const lanes: Partial<Record<FxLane, readonly AutomationPoint[]>> = {
+    ...track.fxAutomation,
+  };
+  if (points.length > 0) lanes[parameter] = points;
+  else delete lanes[parameter];
+  return updateTrack(score, trackId, { fxAutomation: lanes });
 }
 
 /** Mute always silences a track; any solo silences every unsoloed track. */
@@ -569,12 +1104,36 @@ export type ScoreOperation =
   | Readonly<{
       type: "clearTrack";
       trackId: string;
+    }>
+  | Readonly<{
+      type: "removeTrack";
+      trackId: string;
+    }>
+  | Readonly<{
+      type: "moveTrack";
+      trackId: string;
+      index: number;
+    }>
+  | Readonly<{
+      type: "setKey";
+      key: string | null;
+    }>
+  | Readonly<{
+      type: "setMeter";
+      beatsPerBar: number;
     }>;
 
 export function applyScoreOperation(
   score: TrackScore,
   operation: ScoreOperation,
 ): TrackScore {
+  if (operation.type === "removeTrack")
+    return removeTrack(score, operation.trackId);
+  if (operation.type === "moveTrack")
+    return moveTrack(score, operation.trackId, operation.index);
+  if (operation.type === "setKey") return score.withKey(operation.key);
+  if (operation.type === "setMeter")
+    return score.withMeter(operation.beatsPerBar);
   if (operation.type === "addTrack") return addTrack(score, operation.track);
   if (operation.type === "addNote") return addNote(score, operation.note);
   if (operation.type === "removeNote")
@@ -728,14 +1287,47 @@ function normalizeTrack(input: unknown): Track {
     SCORE_LIMITS.minFilterCutoff,
     SCORE_LIMITS.maxFilterCutoff,
   );
-  const lane = (parameter: AutomationParameter) => {
+  const lane = (parameter: TrackAutomationParameter) => {
     const { field, min, max } = AUTOMATION_LANES[parameter];
     return normalizeAutomation(input[field], field, min, max);
   };
   const resonanceAutomation = lane("resonance");
   const delayFeedbackAutomation = lane("delay-feedback");
   const delayMixAutomation = lane("delay-mix");
+  const wtAutomation = lane("wt");
   const reverb = normalizeReverb(input.reverb);
+  const fx = fxOrThrow(() => normalizeFx(input.fx));
+  const fxAutomation = normalizeFxAutomation(input.fxAutomation);
+  const synth = fxOrThrow(() => normalizeSynth(input.synth));
+  const wavetable = normalizeWavetable(input.wavetable);
+  const sampler = normalizeSampler(input.sampler);
+  const rhythm = normalizeRhythm(input.rhythm, id);
+  let kit: string | undefined;
+  if (input.kit !== undefined && input.kit !== null) {
+    const found =
+      typeof input.kit === "string" ? synthKit(input.kit) : undefined;
+    if (!found)
+      throw new ScoreValidationError(
+        `track ${id} kit must be one of ${SYNTH_KIT_NAMES.join(", ")}`,
+        "invalid-track",
+      );
+    if (!isDrumInstrument(instrument))
+      throw new ScoreValidationError(
+        `track ${id} has a kit but its instrument is "${instrument}"`,
+        "invalid-track",
+      );
+    kit = found.name;
+  }
+  if (isSamplerInstrument(instrument) && !sampler)
+    throw new ScoreValidationError(
+      `track ${id} instrument "sampler" needs a sampler`,
+      "invalid-track",
+    );
+  if (sampler && !isSamplerInstrument(instrument))
+    throw new ScoreValidationError(
+      `track ${id} has a sampler but its instrument is "${instrument}"`,
+      "invalid-track",
+    );
   return Object.freeze({
     id,
     name,
@@ -753,9 +1345,436 @@ function normalizeTrack(input: unknown): Track {
     ...(delayFeedbackAutomation.length > 0 ? { delayFeedbackAutomation } : {}),
     ...(delayMixAutomation.length > 0 ? { delayMixAutomation } : {}),
     ...(reverb ? { reverb } : {}),
+    ...(fx ? { fx } : {}),
+    ...(fxAutomation ? { fxAutomation } : {}),
+    ...(synth ? { synth } : {}),
+    ...(wavetable ? { wavetable } : {}),
+    ...(wtAutomation.length > 0 ? { wtAutomation } : {}),
+    ...(sampler ? { sampler } : {}),
+    ...(rhythm ? { rhythm } : {}),
+    ...(kit ? { kit } : {}),
   });
 }
 
+export function normalizeRhythm(
+  input: unknown,
+  trackId: string,
+): readonly RhythmRow[] | undefined {
+  if (input === undefined || input === null) return undefined;
+  if (!Array.isArray(input) || input.length > RHYTHM_LIMITS.maxRows)
+    throw new ScoreValidationError(
+      `track ${trackId} rhythm must be an array of at most ${RHYTHM_LIMITS.maxRows} rows`,
+      "invalid-track",
+    );
+  if (input.length === 0) return undefined;
+  const rows = input.map((row: unknown, index) => {
+    try {
+      return normalizeRhythmRow(row, `track ${trackId} rhythm[${index}]`);
+    } catch (error) {
+      throw new ScoreValidationError(
+        error instanceof Error ? error.message : String(error),
+        "invalid-track",
+      );
+    }
+  });
+  const voices = new Set(rows.map((row) => row.voice));
+  if (voices.size !== rows.length)
+    throw new ScoreValidationError(
+      `track ${trackId} rhythm has two rows for one voice`,
+      "invalid-track",
+    );
+  return Object.freeze(rows);
+}
+
+function fxOrThrow<T>(run: () => T): T {
+  try {
+    return run();
+  } catch (error) {
+    if (error instanceof FxValidationError)
+      throw new ScoreValidationError(error.message, "invalid-track");
+    throw error;
+  }
+}
+
+/** Validates `fxAutomation`; empty lanes are dropped, keys in lane order. */
+function normalizeFxAutomation(
+  input: unknown,
+): Track["fxAutomation"] | undefined {
+  if (input === undefined || input === null) return undefined;
+  if (!isRecord(input))
+    throw new ScoreValidationError(
+      "track fxAutomation must be an object",
+      "invalid-track",
+    );
+  const keys = Object.keys(input);
+  if (keys.length > SCORE_LIMITS.maxFxLanes)
+    throw new ScoreValidationError(
+      `track fxAutomation holds at most ${SCORE_LIMITS.maxFxLanes} lanes`,
+      "score-limit",
+    );
+  for (const key of keys)
+    if (!FX_LANE_RANGES.has(key))
+      throw new ScoreValidationError(
+        `unknown fx automation lane "${key}"`,
+        "invalid-track",
+      );
+  const out: Partial<Record<FxLane, readonly AutomationPoint[]>> = {};
+  for (const { lane, spec } of FX_LANES) {
+    if (input[lane] === undefined) continue;
+    const points = normalizeAutomation(
+      input[lane],
+      `fxAutomation ${lane}`,
+      spec.min,
+      spec.max,
+    );
+    if (points.length > 0) out[lane] = points;
+  }
+  return Object.keys(out).length > 0 ? Object.freeze(out) : undefined;
+}
+
+/** The optional parameters of a track effect; absent keys stay absent. */
+function trackEffectExtras(
+  name: keyof typeof TRACK_EFFECT_SPECS,
+  input: Record<string, unknown>,
+  keys: readonly string[],
+): Record<string, unknown> {
+  const params = TRACK_EFFECT_SPECS[name].params as Record<
+    string,
+    Parameters<typeof normalizeParams>[0][string]
+  >;
+  const subset: Record<string, Parameters<typeof normalizeParams>[0][string]> =
+    {};
+  const values: Record<string, unknown> = {};
+  for (const key of keys) {
+    subset[key] = params[key]!;
+    if (input[key] !== undefined) values[key] = input[key];
+  }
+  return {
+    ...fxOrThrow(() => normalizeParams(subset, values, `track ${name}`)),
+  };
+}
+
+const VOICE_NAME = /^[A-Za-z][A-Za-z0-9_]*$/;
+const SHA256_HEX = /^[0-9a-f]{64}$/;
+
+/** Validates a `Sampler` from unknown; `undefined`/`null` means none. */
+export function normalizeSampler(input: unknown): Sampler | undefined {
+  if (input === undefined || input === null) return undefined;
+  if (!isRecord(input))
+    throw new ScoreValidationError(
+      "track sampler must be an object or null",
+      "invalid-track",
+    );
+  const mode = input.mode ?? "oneshot";
+  if (mode !== "oneshot" && mode !== "keyed")
+    throw new ScoreValidationError(
+      'sampler mode must be "oneshot" or "keyed"',
+      "invalid-track",
+    );
+  if (!isRecord(input.voices))
+    throw new ScoreValidationError(
+      "sampler voices must be an object of name → sample",
+      "invalid-track",
+    );
+  const names = Object.keys(input.voices);
+  if (names.length === 0 || names.length > SCORE_LIMITS.maxSamplerVoices)
+    throw new ScoreValidationError(
+      `sampler must have between 1 and ${SCORE_LIMITS.maxSamplerVoices} voices`,
+      "score-limit",
+    );
+  const voices: Record<string, SampleRef> = {};
+  for (const name of names.sort(compareCodePoints)) {
+    if (
+      name.length > SCORE_LIMITS.maxSamplerVoiceNameLength ||
+      !VOICE_NAME.test(name)
+    )
+      throw new ScoreValidationError(
+        `sampler voice name "${name.slice(0, 40)}" must match ${VOICE_NAME.source} and be at most ${SCORE_LIMITS.maxSamplerVoiceNameLength} characters`,
+        "invalid-track",
+      );
+    voices[name] = normalizeSampleRef(input.voices[name], name);
+  }
+  return Object.freeze({ voices: Object.freeze(voices), mode });
+}
+
+export function normalizeSampleRef(input: unknown, name: string): SampleRef {
+  const label = `sampler voice ${name}`;
+  if (!isRecord(input))
+    throw new ScoreValidationError(
+      `${label} must be an object`,
+      "invalid-track",
+    );
+  const src = input.src;
+  const packRef = typeof src === "string" && src.startsWith(PACK_PREFIX);
+  if (
+    typeof src !== "string" ||
+    src.length === 0 ||
+    src.length > SCORE_LIMITS.maxSamplePathLength ||
+    (packRef ? !isPackRef(src) : !isSafeRelativePath(src))
+  )
+    throw new ScoreValidationError(
+      packRef
+        ? `${label} src must be pack:<pack>/<sound>[:<n>], at most ${SCORE_LIMITS.maxSamplePathLength} characters`
+        : `${label} src must be a project-relative path without "..", at most ${SCORE_LIMITS.maxSamplePathLength} characters`,
+      "invalid-track",
+    );
+  const ref: {
+    src: string;
+    sha256?: string;
+    url?: string;
+    license?: string;
+    root?: number;
+    begin?: number;
+    end?: number;
+    gain?: number;
+    speed?: number;
+    loop?: boolean;
+    choke?: string;
+    loopBegin?: number;
+    loopEnd?: number;
+    clip?: number;
+    unit?: SampleUnit;
+    fit?: boolean;
+    accelerate?: number;
+    squiz?: number;
+  } = { src };
+  if (input.sha256 !== undefined) {
+    if (typeof input.sha256 !== "string" || !SHA256_HEX.test(input.sha256))
+      throw new ScoreValidationError(
+        `${label} sha256 must be 64 lowercase hex characters`,
+        "invalid-track",
+      );
+    ref.sha256 = input.sha256;
+  }
+  if (input.url !== undefined) {
+    if (!packRef || !isPinnedSampleUrl(input.url))
+      throw new ScoreValidationError(
+        `${label} url must be an https URL without credentials, at most ${SCORE_LIMITS.maxSampleUrlLength} characters, on a pack: sound`,
+        "invalid-track",
+      );
+    ref.url = input.url;
+  }
+  if (input.license !== undefined) {
+    if (
+      typeof input.license !== "string" ||
+      !/^[\x20-\x7e]{1,64}$/.test(input.license)
+    )
+      throw new ScoreValidationError(
+        `${label} license must be a short label such as CC0-1.0`,
+        "invalid-track",
+      );
+    ref.license = input.license;
+  }
+  if (input.root !== undefined) {
+    if (
+      typeof input.root !== "number" ||
+      !Number.isInteger(input.root) ||
+      input.root < 0 ||
+      input.root > 127
+    )
+      throw new ScoreValidationError(
+        `${label} root must be a MIDI integer between 0 and 127`,
+        "invalid-track",
+      );
+    ref.root = input.root;
+  }
+  const begin = input.begin === undefined ? 0 : input.begin;
+  const end = input.end === undefined ? 1 : input.end;
+  if (
+    typeof begin !== "number" ||
+    typeof end !== "number" ||
+    !Number.isFinite(begin) ||
+    !Number.isFinite(end) ||
+    begin < 0 ||
+    end > 1 ||
+    begin >= end
+  )
+    throw new ScoreValidationError(
+      `${label} begin/end must be fractions with 0 ≤ begin < end ≤ 1`,
+      "invalid-track",
+    );
+  if (input.begin !== undefined) ref.begin = begin;
+  if (input.end !== undefined) ref.end = end;
+  if (input.gain !== undefined)
+    ref.gain = boundedNumber(
+      input.gain,
+      `${label} gain`,
+      0,
+      SCORE_LIMITS.maxSampleGain,
+    );
+  if (input.speed !== undefined) {
+    const speed = boundedNumber(
+      input.speed,
+      `${label} speed`,
+      -SCORE_LIMITS.maxSampleSpeed,
+      SCORE_LIMITS.maxSampleSpeed,
+    );
+    if (speed === 0)
+      throw new ScoreValidationError(
+        `${label} speed cannot be 0`,
+        "invalid-track",
+      );
+    ref.speed = speed;
+  }
+  if (input.loop !== undefined) {
+    if (typeof input.loop !== "boolean")
+      throw new ScoreValidationError(
+        `${label} loop must be boolean`,
+        "invalid-track",
+      );
+    ref.loop = input.loop;
+  }
+  if (input.choke !== undefined) {
+    if (
+      typeof input.choke !== "string" ||
+      input.choke.length === 0 ||
+      input.choke.length > SCORE_LIMITS.maxChokeGroupLength ||
+      !VOICE_NAME.test(input.choke)
+    )
+      throw new ScoreValidationError(
+        `${label} choke must be a short group name`,
+        "invalid-track",
+      );
+    ref.choke = input.choke;
+  }
+  if (input.loopBegin !== undefined || input.loopEnd !== undefined) {
+    const loopBegin = input.loopBegin === undefined ? begin : input.loopBegin;
+    const loopEnd = input.loopEnd === undefined ? end : input.loopEnd;
+    if (
+      typeof loopBegin !== "number" ||
+      typeof loopEnd !== "number" ||
+      !Number.isFinite(loopBegin) ||
+      !Number.isFinite(loopEnd) ||
+      loopBegin < begin ||
+      loopEnd > end ||
+      loopBegin >= loopEnd
+    )
+      throw new ScoreValidationError(
+        `${label} loopBegin/loopEnd must be fractions with begin ≤ loopBegin < loopEnd ≤ end`,
+        "invalid-track",
+      );
+    if (input.loopBegin !== undefined) ref.loopBegin = loopBegin;
+    if (input.loopEnd !== undefined) ref.loopEnd = loopEnd;
+  }
+  if (input.clip !== undefined) {
+    const clip = boundedNumber(
+      input.clip,
+      `${label} clip`,
+      0,
+      SCORE_LIMITS.maxSampleClip,
+    );
+    if (clip === 0)
+      throw new ScoreValidationError(
+        `${label} clip must be greater than 0`,
+        "invalid-track",
+      );
+    ref.clip = clip;
+  }
+  if (input.unit !== undefined) {
+    if (!SAMPLE_UNITS.includes(input.unit as SampleUnit))
+      throw new ScoreValidationError(
+        `${label} unit must be "r", "c" or "s"`,
+        "invalid-track",
+      );
+    ref.unit = input.unit as SampleUnit;
+  }
+  if (input.fit !== undefined) {
+    if (typeof input.fit !== "boolean")
+      throw new ScoreValidationError(
+        `${label} fit must be boolean`,
+        "invalid-track",
+      );
+    ref.fit = input.fit;
+  }
+  if (input.accelerate !== undefined)
+    ref.accelerate = boundedNumber(
+      input.accelerate,
+      `${label} accelerate`,
+      -SCORE_LIMITS.maxSampleAccelerate,
+      SCORE_LIMITS.maxSampleAccelerate,
+    );
+  if (input.squiz !== undefined)
+    ref.squiz = boundedNumber(
+      input.squiz,
+      `${label} squiz`,
+      1,
+      SCORE_LIMITS.maxSampleSquiz,
+    );
+  return Object.freeze(ref);
+}
+
+/** Prefix of a pack sound reference in `SampleRef.src`. */
+export const PACK_PREFIX = "pack:";
+
+/**
+ * `pack:<pack>/<sound>[:<n>]`: pack is a lowercase slug, sound a manifest
+ * key, `n` an index (wrapping, like Strudel `s("bd:3")`) or a note name for
+ * pitched packs (`pack:gm/gm_piano:C4`).
+ */
+const PACK_REF =
+  /^pack:([a-z0-9][a-z0-9._-]{0,63})\/([A-Za-z0-9][A-Za-z0-9_.~+-]{0,127})(?::([0-9]{1,4}|[A-Ga-g](?:#|s|b)?-?[0-9]))?$/;
+
+export type PackRef = Readonly<{
+  pack: string;
+  sound: string;
+  /** Index into the sound's files (wraps), or a note-zone name. */
+  n: number | string;
+}>;
+
+export function isPackRef(src: string): boolean {
+  return PACK_REF.test(src);
+}
+
+/** Splits `pack:<pack>/<sound>[:<n>]`; undefined for anything else. */
+export function parsePackRef(src: string): PackRef | undefined {
+  const match = PACK_REF.exec(src);
+  if (!match) return undefined;
+  const n = match[3];
+  return Object.freeze({
+    pack: match[1]!,
+    sound: match[2]!,
+    n: n === undefined ? 0 : /^[0-9]+$/.test(n) ? Number(n) : n,
+  });
+}
+
+export function formatPackRef(ref: PackRef): string {
+  return `${PACK_PREFIX}${ref.pack}/${ref.sound}${ref.n === 0 ? "" : `:${ref.n}`}`;
+}
+
+/** HTTPS (or loopback HTTP), no credentials, bounded: the URLs a score may pin. */
+export function isPinnedSampleUrl(value: unknown): value is string {
+  if (
+    typeof value !== "string" ||
+    value.length === 0 ||
+    value.length > SCORE_LIMITS.maxSampleUrlLength ||
+    /[\u0000-\u0020]/.test(value)
+  )
+    return false;
+  let url: URL;
+  try {
+    url = new URL(value);
+  } catch {
+    return false;
+  }
+  if (url.username !== "" || url.password !== "") return false;
+  // Plain HTTP only to loopback (local fixture servers); fetches still refuse
+  // it unless the pack store allows loopback.
+  return (
+    url.protocol === "https:" ||
+    (url.protocol === "http:" &&
+      ["127.0.0.1", "localhost", "[::1]"].includes(url.hostname))
+  );
+}
+
+/** Relative, forward-slash, no empty/dot segments, no control characters. */
+function isSafeRelativePath(path: string): boolean {
+  if (path.startsWith("/") || /[\\\u0000-\u001f]/.test(path)) return false;
+  if (/^[A-Za-z]:/.test(path)) return false;
+  return path
+    .split("/")
+    .every((segment) => segment !== "" && segment !== "." && segment !== "..");
+}
+
 export function normalizeReverb(input: unknown): TrackReverb | undefined {
   if (input === undefined || input === null) return undefined;
   if (!isRecord(input))
@@ -775,7 +1794,17 @@ export function normalizeReverb(input: unknown): TrackReverb | undefined {
     SCORE_LIMITS.minReverbSize,
     SCORE_LIMITS.maxReverbSize,
   );
-  return Object.freeze({ mix, size });
+  const extras = trackEffectExtras("reverb", input, [
+    "fade",
+    "lowpass",
+    "dim",
+    "predelay",
+  ]);
+  const ir =
+    input.ir === undefined || input.ir === null
+      ? undefined
+      : normalizeReverbIr(input.ir);
+  return Object.freeze({ mix, size, ...extras, ...(ir ? { ir } : {}) });
 }
 
 export function normalizeFilter(input: unknown): TrackFilter | undefined {
@@ -797,7 +1826,12 @@ export function normalizeFilter(input: unknown): TrackFilter | undefined {
     0,
     SCORE_LIMITS.maxFilterResonance,
   );
-  return Object.freeze({ cutoff, resonance });
+  const extras = trackEffectExtras("filter", input, ["type", "ftype"]);
+  if (extras.ftype === "12db") delete extras.ftype;
+  // `lpf` is the original filter; store it as absent so v1 documents and
+  // explicit `lpf` encode the same.
+  if (extras.type === "lpf") delete extras.type;
+  return Object.freeze({ cutoff, resonance, ...extras });
 }
 
 export function normalizeDelay(input: unknown): TrackDelay | undefined {
@@ -825,7 +1859,13 @@ export function normalizeDelay(input: unknown): TrackDelay | undefined {
     0,
     SCORE_LIMITS.maxDelayMix,
   );
-  return Object.freeze({ beats, feedback, mix });
+  const extras = trackEffectExtras("delay", input, [
+    "time",
+    "pingpong",
+    "highcut",
+  ]);
+  if (extras.time === 0) delete extras.time;
+  return Object.freeze({ beats, feedback, mix, ...extras });
 }
 
 function boundedNumber(