@hraness/dawg 0.6.0 → 0.7.0

package/core/diff.ts

@@ -10,10 +10,6 @@
  * canonical order, so insertion order never matters).
  */
 
-import {
-  NOTE_EXPRESSION_FIELDS,
-  TRACK_PERFORMANCE_FIELDS,
-} from "./expression.ts";
 import {
   applyScoreOperation,
   TrackScore,
@@ -31,29 +27,109 @@ export class DiffError extends Error {
   }
 }
 
-const EFFECTS = [
-  "filter",
-  "delay",
-  "reverb",
-  "sampler",
-  "fx",
-  "fxAutomation",
-  "synth",
-  "wavetable",
-  "string",
-  "granular",
-  "keys",
-  "modal",
-] as const;
-const LANES = [
-  "volumeAutomation",
-  "panAutomation",
-  "filterAutomation",
-  "resonanceAutomation",
-  "delayFeedbackAutomation",
-  "delayMixAutomation",
-  "wtAutomation",
-] as const;
+/**
+ * How each field diffs: `same` is identity (never patched), `set` patches
+ * the new value, `clear` patches the new value or null, `zero` treats
+ * absent as 0, `flag` treats absent as false and `lane` treats absent as
+ * []. The records are keyed by every field of `Note` and `Track`, so a new
+ * field fails typechecking until it is classified here.
+ */
+type FieldRule = "same" | "set" | "clear" | "zero" | "flag" | "lane";
+
+const NOTE_FIELDS: { readonly [K in keyof Note]-?: FieldRule } = {
+  id: "same",
+  trackId: "same",
+  startTick: "set",
+  durationTicks: "set",
+  pitch: "set",
+  velocity: "set",
+  cents: "zero",
+  lyric: "clear",
+  vowel: "clear",
+  articulation: "clear",
+  glide: "clear",
+  bend: "clear",
+  vibrato: "clear",
+  humanize: "clear",
+  drift: "clear",
+};
+
+const TRACK_FIELDS: { readonly [K in keyof Track]-?: FieldRule } = {
+  id: "same",
+  name: "set",
+  instrument: "set",
+  muted: "set",
+  volume: "set",
+  pan: "set",
+  solo: "flag",
+  volumeAutomation: "lane",
+  panAutomation: "lane",
+  filterAutomation: "lane",
+  resonanceAutomation: "lane",
+  delayFeedbackAutomation: "lane",
+  delayMixAutomation: "lane",
+  wtAutomation: "lane",
+  filter: "clear",
+  delay: "clear",
+  reverb: "clear",
+  fx: "clear",
+  fxAutomation: "clear",
+  synth: "clear",
+  wavetable: "clear",
+  sampler: "clear",
+  rhythm: "clear",
+  kit: "clear",
+  time: "clear",
+  tuning: "clear",
+  string: "clear",
+  granular: "clear",
+  keys: "clear",
+  modal: "clear",
+  softPedal: "clear",
+  sostenuto: "clear",
+  guitar: "clear",
+  wind: "clear",
+  sing: "clear",
+  vocoder: "clear",
+  clips: "clear",
+  takes: "clear",
+  autotune: "clear",
+  glide: "clear",
+  pedal: "clear",
+  velocityCurve: "clear",
+  humanize: "clear",
+};
+
+/** Field names of `Note` and `Track`, for tests that check completeness. */
+export const NOTE_FIELD_NAMES = Object.freeze(
+  Object.keys(NOTE_FIELDS),
+) as readonly (keyof Note)[];
+export const TRACK_FIELD_NAMES = Object.freeze(
+  Object.keys(TRACK_FIELDS),
+) as readonly (keyof Track)[];
+
+function fieldPatch(
+  rules: Readonly<Record<string, FieldRule>>,
+  a: Readonly<Record<string, unknown>>,
+  b: Readonly<Record<string, unknown>>,
+): Record<string, unknown> | undefined {
+  const patch: Record<string, unknown> = {};
+  for (const [key, rule] of Object.entries(rules)) {
+    const before = a[key];
+    const after = b[key];
+    if (rule === "same") continue;
+    if (rule === "set") {
+      if (!deepEqual(before, after)) patch[key] = after;
+    } else if (rule === "zero") {
+      if (!deepEqual(before ?? 0, after ?? 0)) patch[key] = after ?? 0;
+    } else if (rule === "flag") {
+      if ((before ?? false) !== (after ?? false)) patch[key] = after ?? false;
+    } else if (rule === "lane") {
+      if (!deepEqual(before ?? [], after ?? [])) patch[key] = after ?? [];
+    } else if (!deepEqual(before, after)) patch[key] = after ?? null;
+  }
+  return Object.keys(patch).length > 0 ? patch : undefined;
+}
 
 /** Operations turning `a` into `b`; empty when they are equal. */
 export function diffScores(
@@ -64,31 +140,7 @@ export function diffScores(
     throw new DiffError(
       `ticksPerBeat differs (${a.ticksPerBeat} → ${b.ticksPerBeat}); the session resolution is fixed`,
     );
-  const ops: ScoreOperation[] = [];
-  if (a.beatsPerBar !== b.beatsPerBar)
-    ops.push({ type: "setMeter", beatsPerBar: b.beatsPerBar });
-  if (a.bars !== b.bars) ops.push({ type: "setBars", bars: b.bars });
-  if (a.tempoBpm !== b.tempoBpm)
-    ops.push({ type: "setTempo", tempoBpm: b.tempoBpm });
-  if (a.key !== b.key) ops.push({ type: "setKey", key: b.key });
-  if (!deepEqual(a.time, b.time))
-    ops.push({ type: "setTime", time: b.time ?? null });
-  if (!deepEqual(a.tuning, b.tuning))
-    ops.push({ type: "setTuning", tuning: b.tuning ?? null });
-  if (!deepEqual(a.master, b.master))
-    ops.push({ type: "setMaster", master: b.master ?? null });
-  if (
-    !deepEqual(a.sections, b.sections) ||
-    !deepEqual(a.form, b.form) ||
-    a.loopSection !== b.loopSection
-  )
-    ops.push({
-      type: "setSections",
-      sections: b.sections,
-      form: b.form,
-      ...(b.loopSection === undefined ? {} : { loopSection: b.loopSection }),
-    });
-
+  const ops: ScoreOperation[] = [...songOperations(a, b)];
   const aTracks = new Map(a.tracks.map((track) => [track.id, track]));
   const bTracks = new Map(b.tracks.map((track) => [track.id, track]));
   const aNotes = new Map(a.notes.map((note) => [note.id, note]));
@@ -96,32 +148,26 @@ export function diffScores(
 
   const updates: ScoreOperation[] = [];
   const additions: ScoreOperation[] = [];
+  // Notes that leave `a`: dropped with their track, or removed one by one
+  // (a note may name a track the score lacks, so check `a` too).
+  const gone = new Set<string>();
   for (const note of a.notes) {
-    if (!bTracks.has(note.trackId)) continue; // removed with its track
+    if (aTracks.has(note.trackId) && !bTracks.has(note.trackId)) {
+      gone.add(note.id); // removed with its track
+      continue;
+    }
     const next = bNotes.get(note.id);
     if (!next || next.trackId !== note.trackId) {
       ops.push({ type: "removeNote", noteId: note.id });
+      gone.add(note.id);
       continue;
     }
     const patch = notePatch(note, next);
     if (patch) updates.push({ type: "updateNote", noteId: note.id, patch });
   }
-  for (const note of b.notes) {
-    const previous = aNotes.get(note.id);
-    if (
-      previous &&
-      previous.trackId === note.trackId &&
-      bTracks.has(note.trackId)
-    )
-      continue;
-    if (
-      previous &&
-      previous.trackId === note.trackId &&
-      !aTracks.has(note.trackId)
-    )
-      continue;
-    additions.push({ type: "addNote", note });
-  }
+  for (const note of b.notes)
+    if (!aNotes.has(note.id) || gone.has(note.id))
+      additions.push({ type: "addNote", note });
 
   for (const track of a.tracks)
     if (!bTracks.has(track.id))
@@ -151,6 +197,69 @@ export function diffScores(
   return Object.freeze(ops);
 }
 
+/**
+ * Song settings, ordered so every step is valid on its own: constraints
+ * that go away are dropped first (sections before meter changes, fermatas
+ * before the tempo or meter that time them) and constraints that arrive
+ * are added last. Steps are checked on a copy without tracks or notes,
+ * because song settings never depend on them.
+ */
+function songOperations(a: TrackScore, b: TrackScore): ScoreOperation[] {
+  const ops: ScoreOperation[] = [];
+  let song = new TrackScore({ ...a.toJSON(), tracks: [], notes: [] });
+  const emit = (operation: ScoreOperation): void => {
+    song = applyScoreOperation(song, operation);
+    ops.push(operation);
+  };
+  const sectionsDiffer = (): boolean =>
+    !deepEqual(song.sections, b.sections) ||
+    !deepEqual(song.form, b.form) ||
+    song.loopSection !== b.loopSection;
+  const setSections = (): void =>
+    emit({
+      type: "setSections",
+      sections: b.sections,
+      form: b.form,
+      ...(b.loopSection === undefined ? {} : { loopSection: b.loopSection }),
+    });
+  if (b.sections.length === 0 && sectionsDiffer()) setSections();
+  const retimed =
+    song.beatsPerBar !== b.beatsPerBar ||
+    song.bars !== b.bars ||
+    song.tempoBpm !== b.tempoBpm;
+  if (retimed && song.time?.fermatas && !deepEqual(song.time, b.time)) {
+    const { fermatas: _fermatas, ...rest } = b.time ?? {};
+    const interim = Object.keys(rest).length > 0 ? rest : null;
+    if (!deepEqual(song.time, interim ?? undefined))
+      emit({ type: "setTime", time: interim });
+  } else if (retimed && song.time?.fermatas) {
+    // Same fermatas before and after, but timed by a new tempo or meter.
+    const { fermatas: _fermatas, ...rest } = song.time;
+    emit({
+      type: "setTime",
+      time: Object.keys(rest).length > 0 ? rest : null,
+    });
+  }
+  if (song.beatsPerBar !== b.beatsPerBar)
+    emit({ type: "setMeter", beatsPerBar: b.beatsPerBar });
+  if (song.bars !== b.bars) emit({ type: "setBars", bars: b.bars });
+  if (song.tempoBpm !== b.tempoBpm)
+    emit({ type: "setTempo", tempoBpm: b.tempoBpm });
+  if (song.key !== b.key) emit({ type: "setKey", key: b.key });
+  if (!deepEqual(song.time, b.time))
+    emit({ type: "setTime", time: b.time ?? null });
+  if (!deepEqual(song.tuning, b.tuning))
+    emit({ type: "setTuning", tuning: b.tuning ?? null });
+  if (!deepEqual(song.master, b.master))
+    emit({ type: "setMaster", master: b.master ?? null });
+  if ((song.calibration ?? 0) !== (b.calibration ?? 0))
+    emit({ type: "setCalibration", calibration: b.calibration ?? null });
+  if (!deepEqual(song.style, b.style))
+    emit({ type: "setStyle", style: b.style ?? null });
+  if (sectionsDiffer()) setSections();
+  return ops;
+}
+
 /** Applies operations in order; the inverse of `diffScores`. */
 export function applyScoreOperations(
   score: TrackScore,
@@ -160,43 +269,17 @@ export function applyScoreOperations(
 }
 
 function notePatch(a: Note, b: Note): NotePatch | undefined {
-  const patch: Record<string, unknown> = {};
-  for (const key of [
-    "startTick",
-    "durationTicks",
-    "pitch",
-    "velocity",
-  ] as const)
-    if (a[key] !== b[key]) patch[key] = b[key];
-  for (const key of NOTE_EXPRESSION_FIELDS)
-    if (!deepEqual(a[key], b[key])) patch[key] = b[key] ?? null;
-  if ((a.cents ?? 0) !== (b.cents ?? 0)) patch.cents = b.cents ?? 0;
-  return Object.keys(patch).length > 0 ? (patch as NotePatch) : undefined;
+  return fieldPatch(NOTE_FIELDS, a, b) as NotePatch | undefined;
 }
 
 function trackPatch(a: Track, b: Track): TrackPatch | undefined {
-  const patch: Record<string, unknown> = {};
-  for (const key of ["name", "instrument", "muted", "volume", "pan"] as const)
-    if (a[key] !== b[key]) patch[key] = b[key];
-  if ((a.solo ?? false) !== (b.solo ?? false)) patch.solo = b.solo ?? false;
-  for (const key of EFFECTS)
-    if (!deepEqual(a[key], b[key])) patch[key] = b[key] ?? null;
-  for (const key of [
-    "rhythm",
-    "kit",
-    "time",
-    "tuning",
-    ...TRACK_PERFORMANCE_FIELDS,
-  ] as const)
-    if (!deepEqual(a[key], b[key])) patch[key] = b[key] ?? null;
-  for (const key of LANES)
-    if (!deepEqual(a[key] ?? [], b[key] ?? [])) patch[key] = b[key] ?? [];
-  return Object.keys(patch).length > 0 ? (patch as TrackPatch) : undefined;
+  return fieldPatch(TRACK_FIELDS, a, b) as TrackPatch | undefined;
 }
 
 /** Structural equality for plain JSON-like data. */
 export function deepEqual(a: unknown, b: unknown): boolean {
-  if (Object.is(a, b)) return true;
+  // === so -0 equals 0: a printed song.ts reads -0 back as 0.
+  if (a === b) return true;
   if (
     typeof a !== "object" ||
     typeof b !== "object" ||

package/core/expression.ts

@@ -125,6 +125,11 @@ export type NoteExpression = Readonly<{
    * track's humanize seed, 1 when it has none). `{}` keeps the note exact.
    */
   humanize?: NoteHumanize;
+  /**
+   * Optional (0.7): on an autotune guide note, the share of slow pitch drift
+   * removed (0..1), overriding the track's `autotune.drift` for this note.
+   */
+  drift?: number;
 }>;
 
 /** Per-note humanize: amounts as in `Humanize`, absent ones 0. */
@@ -141,6 +146,7 @@ export type NoteExpressionPatch = Readonly<{
   bend?: readonly BendPoint[] | null;
   vibrato?: NoteVibrato | null;
   humanize?: NoteHumanize | null;
+  drift?: number | null;
 }>;
 
 export const NOTE_EXPRESSION_FIELDS = [
@@ -149,6 +155,7 @@ export const NOTE_EXPRESSION_FIELDS = [
   "bend",
   "vibrato",
   "humanize",
+  "drift",
 ] as const;
 
 export const GLIDE_MODES = ["legato", "mono", "poly"] as const;
@@ -167,6 +174,8 @@ export type TrackGlide = Readonly<{ time: number; mode: GlideMode }>;
 export const DEFAULT_GLIDE_SECONDS = 0.06;
 
 export const PEDAL_STATES = ["down", "half", "up"] as const;
+/** Sostenuto has no half position (0.6.1). */
+export const SOSTENUTO_STATES = ["down", "up"] as const;
 export type PedalState = (typeof PEDAL_STATES)[number];
 
 /** A sustain pedal (MIDI CC64) change at a tick. */
@@ -323,6 +332,12 @@ export function normalizeVibrato(value: unknown): NoteVibrato | undefined {
   return Object.freeze({ rate, depth, ...(delay > 0 ? { delay } : {}) });
 }
 
+/** A guide note's autotune drift share (0.7), 0..1. */
+export function normalizeNoteDrift(value: unknown): number | undefined {
+  if (value === undefined || value === null) return undefined;
+  return finite(value, "note drift", 0, 1);
+}
+
 /** Validates a note's expression fields; only the set ones are returned. */
 export function normalizeNoteExpression(
   input: Readonly<Record<string, unknown>>,
@@ -332,12 +347,14 @@ export function normalizeNoteExpression(
   const bend = normalizeBend(input.bend);
   const vibrato = normalizeVibrato(input.vibrato);
   const humanize = normalizeNoteHumanize(input.humanize);
+  const drift = normalizeNoteDrift(input.drift);
   return {
     ...(articulation ? { articulation } : {}),
     ...(glide !== undefined ? { glide } : {}),
     ...(bend ? { bend } : {}),
     ...(vibrato ? { vibrato } : {}),
     ...(humanize ? { humanize } : {}),
+    ...(drift !== undefined ? { drift } : {}),
   };
 }
 
@@ -386,16 +403,18 @@ export function normalizeTrackGlide(value: unknown): TrackGlide | undefined {
 export function normalizePedal(
   value: unknown,
   maxTick: number,
+  label = "pedal",
+  states: readonly PedalState[] = PEDAL_STATES,
 ): readonly PedalEvent[] | undefined {
   if (value === undefined || value === null) return undefined;
   if (!Array.isArray(value) || value.length > EXPRESSION_LIMITS.maxPedalEvents)
     throw new ExpressionValidationError(
-      `pedal must be an array of at most ${EXPRESSION_LIMITS.maxPedalEvents} events`,
+      `${label} must be an array of at most ${EXPRESSION_LIMITS.maxPedalEvents} events`,
     );
   const byTick = new Map<number, PedalEvent>();
   for (const item of value as unknown[]) {
-    const event = record(item, "pedal event");
-    onlyKeys(event, ["tick", "state"], "pedal event");
+    const event = record(item, `${label} event`);
+    onlyKeys(event, ["tick", "state"], `${label} event`);
     const tick = event.tick;
     if (
       typeof tick !== "number" ||
@@ -404,11 +423,11 @@ export function normalizePedal(
       tick > maxTick
     )
       throw new ExpressionValidationError(
-        `pedal tick must be an integer 0..${maxTick}`,
+        `${label} tick must be an integer 0..${maxTick}`,
       );
-    if (!PEDAL_STATES.includes(event.state as PedalState))
+    if (!states.includes(event.state as PedalState))
       throw new ExpressionValidationError(
-        `pedal state must be one of ${PEDAL_STATES.join(", ")}`,
+        `${label} state must be one of ${states.join(", ")}`,
       );
     // The last event at a tick wins.
     byTick.set(tick, Object.freeze({ tick, state: event.state as PedalState }));
@@ -551,6 +570,80 @@ export function pedalStateAt(
   return state;
 }
 
+/** A stretch of song ticks `[from, to)` placed at `offset` in a slice. */
+export type PedalPiece = Readonly<{ from: number; to: number; offset: number }>;
+
+/**
+ * Pedal events for a slice made of `pieces` (a render window, a section
+ * pass, an audition region): the state in force at each piece's start is
+ * restated at its offset (`carry`, for sustain and una corda; sostenuto
+ * passes false, since a pedal already down latches no key struck later),
+ * events inside the piece move by `offset - from`, and a pedal still down
+ * at the piece's end is lifted there. Undefined when nothing is left.
+ */
+export function slicePedal(
+  events: readonly PedalEvent[] | undefined,
+  pieces: readonly PedalPiece[],
+  carry = true,
+): readonly PedalEvent[] | undefined {
+  if (!events || events.length === 0) return events;
+  const byTick = new Map<number, PedalEvent>();
+  const put = (tick: number, state: PedalState) =>
+    byTick.set(tick, Object.freeze({ tick, state }));
+  for (const { from, to, offset } of pieces) {
+    let state: PedalState = "up";
+    if (carry)
+      for (const event of events) {
+        if (event.tick >= from) break;
+        state = event.state;
+      }
+    // Restate up too: the previous piece may have ended with it down.
+    if (state !== "up" || byTick.size > 0) put(offset, state);
+    for (const event of events) {
+      if (event.tick < from || event.tick >= to) continue;
+      put(event.tick - from + offset, event.state);
+      state = event.state;
+    }
+    if (state !== "up" && Number.isFinite(to)) put(offset + to - from, "up");
+  }
+  const out = [...byTick.values()].sort((a, b) => a.tick - b.tick);
+  // Drop events that restate the state already in force.
+  const kept: PedalEvent[] = [];
+  let last: PedalState = "up";
+  for (const event of out)
+    if (event.state !== last) {
+      kept.push(event);
+      last = event.state;
+    }
+  return kept.length > 0 ? Object.freeze(kept) : undefined;
+}
+
+/** The track with its three pedal lanes cut to `pieces` (see slicePedal). */
+export function slicePedals<T extends PedalTrack>(
+  track: T,
+  pieces: readonly PedalPiece[],
+): T {
+  if (!track.pedal && !track.softPedal && !track.sostenuto) return track;
+  const out: Record<string, unknown> = { ...track };
+  for (const [field, carry] of [
+    ["pedal", true],
+    ["softPedal", true],
+    ["sostenuto", false],
+  ] as const) {
+    if (!track[field]) continue;
+    const next = slicePedal(track[field], pieces, carry);
+    if (next) out[field] = next;
+    else delete out[field];
+  }
+  return out as T;
+}
+
+type PedalTrack = Readonly<{
+  pedal?: readonly PedalEvent[];
+  softPedal?: readonly PedalEvent[];
+  sostenuto?: readonly PedalEvent[];
+}>;
+
 // ---------------------------------------------------------------------------
 // Performance
 
@@ -674,6 +767,7 @@ export function hasTrackPerformance(track: Track | undefined): boolean {
     track !== undefined &&
     (track.glide !== undefined ||
       track.pedal !== undefined ||
+      track.sostenuto !== undefined ||
       track.velocityCurve !== undefined ||
       track.humanize !== undefined)
   );
@@ -869,6 +963,64 @@ export function performNotes(
       };
     });
   }
+  // 3b. Sostenuto (0.6.1): a key held (written length after articulation)
+  // when the sostenuto goes down keeps its damper up until the sostenuto
+  // lifts; keys struck later damp at their own release (or the sustain
+  // pedal's). The rod keeps a caught damper raised, so the same pitch
+  // struck again while that sostenuto is down rings to the lift too; the
+  // earlier instance stops at the restrike so voices do not pile up. A key
+  // still held through a lift and a new press is caught again.
+  const sostenuto = track?.sostenuto;
+  if (sostenuto) {
+    const spans: { down: number; lift: number; pitches: Set<number> }[] = [];
+    let open: number | undefined;
+    for (const event of sostenuto) {
+      if (event.state === "down" && open === undefined) open = event.tick;
+      else if (event.state === "up" && open !== undefined) {
+        spans.push({ down: open, lift: event.tick, pitches: new Set() });
+        open = undefined;
+      }
+    }
+    if (open !== undefined)
+      spans.push({ down: open, lift: timing.endTick, pitches: new Set() });
+    const caughtBy = working.map((item) => {
+      const keyUp = item.start + item.bendLength;
+      return spans.filter((span) => {
+        const held = item.start <= span.down && span.down < keyUp;
+        if (held) span.pitches.add(item.note.pitch);
+        return held;
+      });
+    });
+    working = working.map((item, index) => {
+      const keyUp = item.start + item.bendLength;
+      let lift = -Infinity;
+      for (const span of caughtBy[index]!) lift = Math.max(lift, span.lift);
+      for (const span of spans)
+        if (
+          span.pitches.has(item.note.pitch) &&
+          span.down < item.start &&
+          item.start < span.lift
+        )
+          lift = Math.max(lift, span.lift);
+      if (lift === -Infinity) return item;
+      const current = item.start + item.duration;
+      let end = Math.max(current, Math.min(lift, timing.endTick));
+      if (end <= current) return item;
+      const restrike = working.find(
+        (other) =>
+          other !== item &&
+          other.note.pitch === item.note.pitch &&
+          other.start > item.start &&
+          other.start < end,
+      );
+      if (restrike) end = Math.max(current, restrike.start);
+      return {
+        ...item,
+        duration: end - item.start,
+        pedalled: end > keyUp || item.pedalled === true,
+      };
+    });
+  }
   // 4. Glide and monophony (on the written timing).
   let performed = glideAndMono(
     track,