@hraness/dawg 0.6.1 → 0.8.0

package/src/session/rebase.ts

@@ -2,17 +2,20 @@
  * Server-side rebase of agent operation intents.
  *
  * An agent validates its operations against the score at `base`. When other
- * windows committed in the meantime, dawgd replays the operations on the
+ * panes committed in the meantime, dawgd replays the operations on the
  * current score instead of rejecting, but only when nothing they touch
- * changed since `base`: the notes they update or remove, the tracks whose
- * settings or contents they rewrite, the tracks they add notes to, and the
+ * changed since `base`: the notes they update or remove, the track
+ * properties they patch (per track and field, so two panes can set
+ * different properties of one track), the tracks whose contents they clear, the tracks they add notes to, and the
  * tempo or length they set. Anything else is a conflict and the caller gets
  * the usual `rebase` reply. The reducer still validates every operation.
  */
 import {
   applyScoreOperation,
+  automationPoints,
   scoreFromJSON,
   type ScoreOperation,
+  type Track,
   type TrackScore,
 } from "../../core/score.ts";
 import { rewindComposition, type Rewind } from "./delta.ts";
@@ -83,11 +86,43 @@ export function rebaseOperations(
           return { ok: false, reason: `note ${operation.noteId} changed` };
         break;
       }
-      case "updateTrack":
+      // Track settings conflict per (track, property): another pane's
+      // volume change never blocks this pane's pan, only its volume.
+      case "updateTrack": {
+        const id = operation.trackId;
+        if (added.tracks.has(id)) break;
+        const before = trackSettings(base, id);
+        const now = trackSettings(current, id);
+        if (!now) return { ok: false, reason: `track ${id} was removed` };
+        for (const field of Object.keys(operation.patch) as (keyof Track)[])
+          if (!same(before?.[field] ?? null, now[field] ?? null))
+            return { ok: false, reason: `${id} ${String(field)} changed` };
+        break;
+      }
+      case "setClips": {
+        const id = operation.trackId;
+        if (added.tracks.has(id)) break;
+        const now = trackSettings(current, id);
+        if (!now) return { ok: false, reason: `track ${id} was removed` };
+        if (!same(trackSettings(base, id)?.clips ?? null, now.clips ?? null))
+          return { ok: false, reason: `${id} clips changed` };
+        break;
+      }
       case "setAutomation": {
-        if (added.tracks.has(operation.trackId)) break;
-        if (!settingsUnchanged(operation.trackId))
-          return { ok: false, reason: `track ${operation.trackId} changed` };
+        const id = operation.trackId;
+        if (added.tracks.has(id)) break;
+        const now = trackSettings(current, id);
+        if (!now) return { ok: false, reason: `track ${id} was removed` };
+        if (
+          !same(
+            automationPoints(trackSettings(base, id), operation.parameter),
+            automationPoints(now, operation.parameter),
+          )
+        )
+          return {
+            ok: false,
+            reason: `${id} ${operation.parameter} automation changed`,
+          };
         break;
       }
       case "clearTrack": {
@@ -123,10 +158,18 @@ export function rebaseOperations(
         if (!same(base.tuning ?? null, current.tuning ?? null))
           return { ok: false, reason: "tuning changed" };
         break;
+      case "setCalibration":
+        if ((base.calibration ?? 0) !== (current.calibration ?? 0))
+          return { ok: false, reason: "calibration changed" };
+        break;
       case "setMaster":
         if (!deepEqual(base.master, current.master))
           return { ok: false, reason: "master changed" };
         break;
+      case "setStyle":
+        if (!deepEqual(base.style, current.style))
+          return { ok: false, reason: "style changed" };
+        break;
       case "setSections":
         if (
           JSON.stringify(base.sections) !== JSON.stringify(current.sections) ||
@@ -135,6 +178,10 @@ export function rebaseOperations(
         )
           return { ok: false, reason: "sections changed" };
         break;
+      case "setLoop":
+        if (!deepEqual(base.loop, current.loop))
+          return { ok: false, reason: "loop changed" };
+        break;
       case "removeTrack": {
         if (added.tracks.has(operation.trackId)) break;
         if (
@@ -177,13 +224,17 @@ export function compositionAt(
   record: {
     composition: unknown;
     events: readonly { revision: number; rewind?: Rewind | undefined }[];
+    /** Events folded out of the front of the log (see `SessionRecord`). */
+    folded?: number | undefined;
   },
   revision: number,
 ): unknown {
   const { events } = record;
-  if (!Number.isSafeInteger(revision) || revision < 0) return undefined;
-  if (revision >= events.length) return undefined;
-  for (let index = revision; index < events.length; index += 1)
-    if (events[index]!.revision !== index + 1) return undefined;
-  return rewindComposition(record.composition, events, revision);
+  const base = record.folded ?? 0;
+  if (!Number.isSafeInteger(revision) || revision < base) return undefined;
+  const start = revision - base;
+  if (start >= events.length) return undefined;
+  for (let index = start; index < events.length; index += 1)
+    if (events[index]!.revision !== base + index + 1) return undefined;
+  return rewindComposition(record.composition, events, start);
 }

package/src/session/receipt.ts

@@ -0,0 +1,265 @@
+/**
+ * Musical receipts: one line that says what changed in the song, built from
+ * the score operations a change applied (`diffScores(before, after)`).
+ *
+ *   ◆ 96 BPM · +2 notes on bass (C4 E4) · reverb 0.4
+ *
+ * Receipts name tempo in BPM, notes by pitch, and track settings by their
+ * musical value; revision numbers and validator counts stay in the ctrl-o
+ * log. The builder is pure, so the agent turn, undo and redo share it.
+ */
+import { diffScores } from "../../core/diff.ts";
+import { drumVoiceForPitch, isDrumInstrument } from "../../core/drums.ts";
+import { midiToPitch } from "../../core/pitch.ts";
+import type { ScoreOperation, TrackScore } from "../../core/score.ts";
+
+/** Parts kept before the rest collapse to `+N more`. */
+const MAX_PARTS = 5;
+/** Pitch names listed after a note count. */
+const MAX_PITCHES = 4;
+
+function plural(count: number, word: string): string {
+  return `${count} ${word}${count === 1 ? "" : "s"}`;
+}
+
+function round(value: number, places = 2): string {
+  const scale = 10 ** places;
+  return String(Math.round(value * scale) / scale);
+}
+
+function noteName(pitch: number, drum: boolean): string {
+  return drum ? drumVoiceForPitch(pitch) : midiToPitch(pitch);
+}
+
+type NoteTally = { added: number[]; removed: number[]; changed: number };
+
+/** One field of a track patch as a musical phrase, or undefined to skip. */
+function trackField(field: string, value: unknown): string | undefined {
+  if (value === null || value === undefined) {
+    if (field === "volumeAutomation" || field.endsWith("Automation"))
+      return `${field.replace(/Automation$/, "")} automation off`;
+    return `${field} off`;
+  }
+  switch (field) {
+    case "volume":
+      return typeof value === "number" ? `volume ${round(value)}` : undefined;
+    case "pan":
+      return typeof value === "number" ? `pan ${round(value)}` : undefined;
+    case "muted":
+      return value === true ? "muted" : "unmuted";
+    case "solo":
+      return value === true ? "solo" : "solo off";
+    case "instrument":
+      return typeof value === "string" ? `→ ${value}` : undefined;
+    case "name":
+      return typeof value === "string" ? `renamed ${value}` : undefined;
+    case "reverb":
+    case "delay": {
+      const mix = (value as { mix?: unknown }).mix;
+      return typeof mix === "number" ? `${field} ${round(mix)}` : field;
+    }
+    case "filter": {
+      const cutoff = (value as { cutoff?: unknown }).cutoff;
+      return typeof cutoff === "number"
+        ? `filter ${Math.round(cutoff)} Hz`
+        : "filter";
+    }
+    case "fx": {
+      const names = Object.keys(value as Record<string, unknown>);
+      return names.length ? `fx ${names.join(" ")}` : "fx off";
+    }
+    default:
+      if (Array.isArray(value) && field.endsWith("Automation"))
+        return value.length === 0
+          ? `${field.replace(/Automation$/, "")} automation off`
+          : `${field.replace(/Automation$/, "")} automation`;
+      return field;
+  }
+}
+
+/**
+ * The receipt parts for `operations` applied to `before`. Tracks are named
+ * only when the song has more than one, so a single-track edit reads
+ * `reverb 0.4` and a band edit `bass reverb 0.4`.
+ */
+export function receiptParts(
+  before: TrackScore,
+  operations: readonly ScoreOperation[],
+): string[] {
+  const parts: string[] = [];
+  // Track settings follow the notes: what you hear first reads first.
+  const settings: string[] = [];
+  const instruments = new Map(
+    before.tracks.map((track) => [track.id, track.instrument]),
+  );
+  const noteTrack = new Map(
+    before.notes.map((note) => [note.id, note.trackId]),
+  );
+  const notePitch = new Map(
+    before.notes.map((note) => [
+      note.id,
+      typeof note.pitch === "number" ? note.pitch : Number.NaN,
+    ]),
+  );
+  const tallies = new Map<string, NoteTally>();
+  const tally = (trackId: string): NoteTally => {
+    let found = tallies.get(trackId);
+    if (!found) {
+      found = { added: [], removed: [], changed: 0 };
+      tallies.set(trackId, found);
+    }
+    return found;
+  };
+  const added = new Set<string>();
+  const removed = new Set<string>();
+  const trackCount = new Set([
+    ...before.tracks.map((track) => track.id),
+    ...operations.flatMap((op) =>
+      op.type === "addTrack" ? [op.track.id ?? "track"] : [],
+    ),
+  ]).size;
+  const prefix = (trackId: string) => (trackCount > 1 ? `${trackId} ` : "");
+  // Notes are summarised per track after the song-level parts.
+  for (const op of operations) {
+    switch (op.type) {
+      case "setTempo":
+        parts.push(`${round(op.tempoBpm, 1)} BPM`);
+        break;
+      case "setKey":
+        parts.push(op.key ? `key ${op.key}` : "no key");
+        break;
+      case "setBars":
+        parts.push(plural(op.bars, "bar"));
+        break;
+      case "setMeter":
+        parts.push(`${op.beatsPerBar} beats a bar`);
+        break;
+      case "setTime":
+        parts.push(op.time ? "tempo map" : "steady tempo");
+        break;
+      case "setTuning":
+        parts.push(
+          op.tuning ? `tuning ${op.tuning.name ?? ""}`.trim() : "12-TET",
+        );
+        break;
+      case "setMaster":
+        parts.push(op.master ? "master" : "master off");
+        break;
+      case "setStyle":
+        if (op.style) parts.push(op.style.id);
+        break;
+      case "setSections":
+        parts.push(plural(op.sections.length, "section"));
+        break;
+      case "setLoop":
+        parts.push(
+          op.loop
+            ? `loop ${op.loop.startBar + 1}–${op.loop.startBar + op.loop.bars}`
+            : "loop off",
+        );
+        break;
+      case "setCalibration":
+        break;
+      case "addTrack": {
+        const id = op.track.id ?? "track";
+        const instrument = op.track.instrument;
+        added.add(id);
+        instruments.set(id, instrument ?? "");
+        parts.push(
+          `+${id}${instrument && instrument !== id ? ` (${instrument})` : ""}`,
+        );
+        break;
+      }
+      case "removeTrack":
+        removed.add(op.trackId);
+        parts.push(`−${op.trackId}`);
+        break;
+      case "moveTrack":
+        parts.push(`moved ${op.trackId}`);
+        break;
+      case "clearTrack":
+        parts.push(`cleared ${op.trackId}`);
+        break;
+      case "setClips":
+        settings.push(
+          `${prefix(op.trackId)}${op.clips && op.clips.length ? plural(op.clips.length, "clip") : "no clips"}`,
+        );
+        break;
+      case "setAutomation":
+        settings.push(`${prefix(op.trackId)}${op.parameter} automation`);
+        break;
+      case "updateTrack": {
+        if (added.has(op.trackId)) break;
+        const fields = Object.entries(op.patch)
+          .map(([field, value]) => trackField(field, value))
+          .filter((text): text is string => text !== undefined);
+        if (fields.length === 0) break;
+        const name = op.patch.name;
+        const label =
+          typeof name === "string" ? op.trackId : prefix(op.trackId).trim();
+        const text = fields.slice(0, 2).join(" ");
+        settings.push(label ? `${label} ${text}` : text);
+        break;
+      }
+      case "addNote": {
+        const entry = tally(op.note.trackId);
+        entry.added.push(
+          typeof op.note.pitch === "number" ? op.note.pitch : Number.NaN,
+        );
+        break;
+      }
+      case "removeNote": {
+        const trackId = noteTrack.get(op.noteId);
+        if (trackId && !removed.has(trackId))
+          tally(trackId).removed.push(notePitch.get(op.noteId) ?? Number.NaN);
+        break;
+      }
+      case "updateNote": {
+        const trackId = noteTrack.get(op.noteId);
+        if (trackId) tally(trackId).changed += 1;
+        break;
+      }
+    }
+  }
+  for (const [trackId, entry] of tallies) {
+    const drum = isDrumInstrument(instruments.get(trackId));
+    const listed = (pitches: readonly number[]): string => {
+      const names = pitches
+        .filter((pitch) => Number.isFinite(pitch))
+        .slice(0, MAX_PITCHES)
+        .map((pitch) => noteName(pitch, drum));
+      const more = pitches.length > MAX_PITCHES ? " …" : "";
+      return names.length ? ` (${names.join(" ")}${more})` : "";
+    };
+    if (entry.added.length > 0)
+      parts.push(
+        `+${plural(entry.added.length, "note")} on ${trackId}${listed(entry.added)}`,
+      );
+    if (entry.removed.length > 0)
+      parts.push(
+        `−${plural(entry.removed.length, "note")} on ${trackId}${listed(entry.removed)}`,
+      );
+    if (entry.changed > 0)
+      parts.push(`${plural(entry.changed, "note")} edited on ${trackId}`);
+  }
+  parts.push(...settings);
+  if (parts.length > MAX_PARTS)
+    return [
+      ...parts.slice(0, MAX_PARTS - 1),
+      `+${parts.length - (MAX_PARTS - 1)} more`,
+    ];
+  return parts;
+}
+
+/** `96 BPM · +2 notes on bass (C4 E4) · reverb 0.4`, or "" for no change. */
+export function musicalReceipt(before: TrackScore, after: TrackScore): string {
+  if (before === after) return "";
+  let operations: readonly ScoreOperation[];
+  try {
+    operations = diffScores(before, after);
+  } catch {
+    // A resolution change cannot diff: say the song changed.
+    return "song changed";
+  }
+  return receiptParts(before, operations).join(" · ");
+}

package/src/session/shared-live.ts

@@ -0,0 +1,131 @@
+/**
+ * A pane's handle on the machine's one live engine (design §12.3). It looks
+ * like the local `LiveEngine` to play mode, but notes go to dawgd as note
+ * events (`remoteNote`) and the click as a structured request
+ * (`remoteClick`): no audio crosses the socket. dawgd renders each voice
+ * from the score it holds and mixes every pane into one stream and one
+ * click.
+ *
+ * Times cross the seam on the authority's clock: local monotonic ms plus
+ * `performance.timeOrigin` plus the port's clock offset (0 on one machine).
+ */
+import type { ClickBus } from "../audio/engine.ts";
+import type { LiveNotePcm } from "../audio/live.ts";
+import type { LiveClick, LiveMessage, LiveStatus } from "./protocol.ts";
+
+/** What the shared engine needs from the session connection. */
+export interface LiveLink {
+  liveMonitor(on: boolean): Promise<LiveStatus>;
+  live(message: Exclude<LiveMessage, { action: "monitor" }>): void;
+  /** Authority clock minus this machine's, in ms. */
+  readonly clockOffsetMs: number;
+}
+
+/** A played note as play mode hands it to a shared engine. */
+export type RemoteNote = Readonly<{
+  trackId: string;
+  pitch: number;
+  /** 0..1. */
+  velocity: number;
+  seconds: number;
+  /** Transport beat of the press (unwrapped). */
+  beat: number;
+  /** Monotonic ms of the press. */
+  atMs: number;
+}>;
+
+/** A structured click request (a shared engine cannot take closures). */
+export type RemoteClick = Readonly<{
+  on: boolean;
+  volume: number;
+  countIn?: Readonly<{
+    /** Monotonic ms the count-in starts. */
+    startMs: number;
+    startBeat: number;
+    beats: number;
+    barBeats: number;
+    clickBeats: number;
+    bpm: number;
+  }>;
+}>;
+
+export class SharedLiveEngine {
+  public sampleRate = 48_000;
+  public canMonitor = true;
+  public leadMs = 15;
+  public playLeadMs: number | undefined;
+  public audioNote: string | undefined = "shared engine";
+  /** Notes sent (tests and the status line read it). */
+  public sent = 0;
+
+  public constructor(private readonly link: LiveLink) {}
+
+  public async monitor(on: boolean): Promise<void> {
+    try {
+      const status = await this.link.liveMonitor(on);
+      this.sampleRate = status.sampleRate;
+      this.canMonitor = status.canMonitor;
+      this.leadMs = status.leadMs;
+      this.playLeadMs = status.leadMs;
+      this.audioNote = status.note ?? "shared engine";
+    } catch {
+      // dawgd is reconnecting; the link resends monitor once it is back.
+    }
+  }
+
+  /** The lead is dawgd's: a pane never retimes the shared engine. */
+  public setLeadMs(_ms: number | undefined): void {}
+
+  /** Local PCM never reaches a shared engine; play mode uses `remoteNote`. */
+  public noteOn(_id: number, _note: LiveNotePcm): number {
+    return performance.now() + this.leadMs;
+  }
+
+  public remoteNote(id: number, note: RemoteNote): number {
+    this.sent += 1;
+    this.link.live({
+      v: 1,
+      type: "live",
+      action: "on",
+      voice: id,
+      trackId: note.trackId,
+      pitch: note.pitch,
+      velocity: Math.max(0, Math.min(1, note.velocity)),
+      seconds: Math.max(0, Math.min(600, note.seconds)),
+      beat: note.beat,
+      atMs: this.authority(note.atMs),
+    });
+    return performance.now() + this.leadMs;
+  }
+
+  public noteOff(id: number): void {
+    this.link.live({
+      v: 1,
+      type: "live",
+      action: "off",
+      voice: id,
+      atMs: this.authority(performance.now()),
+    });
+  }
+
+  /** A pane cannot hand dawgd a click closure; see `remoteClick`. */
+  public setClick(click: ClickBus | undefined): void {
+    if (!click) this.remoteClick({ on: false, volume: 0 });
+  }
+
+  public remoteClick(click: RemoteClick): void {
+    const message: LiveClick = {
+      on: click.on,
+      volume: Math.max(0, Math.min(1, click.volume)),
+    };
+    if (click.countIn) {
+      const { startMs, ...rest } = click.countIn;
+      message.countIn = { ...rest, startAtMs: this.authority(startMs) };
+    }
+    this.link.live({ v: 1, type: "live", action: "click", ...message });
+  }
+
+  private authority(monotonicMs: number): number {
+    return performance.timeOrigin + monotonicMs + this.link.clockOffsetMs;
+  }
+}