@hraness/dawg 0.6.0 → 0.7.0

package/src/render.ts

@@ -36,6 +36,7 @@ import {
   sectionCues,
 } from "./audio/arrange.ts";
 import { SampleLibrary, hasSamplerTracks } from "./audio/samples.ts";
+import { withClipLengths } from "./audio/clips.ts";
 import {
   PackStore,
   creditsLine,
@@ -118,6 +119,14 @@ export async function runRenderCommand(
       );
       return 1;
     }
+    // Clips crossing the section's edges are cut against their files' real
+    // ends, so read their lengths first (load problems are reported below).
+    if (score.tracks.some((track) => track.clips)) {
+      const bank = await new SampleLibrary({ projectRoot: workspace }).load(
+        score,
+      );
+      score = withClipLengths(score, bank);
+    }
     // One section as it plays when looped: its mutes and variations, no form.
     score = withNoteCap(BAKED_NOTE_CAP, () =>
       sectionScore(bakeTrackTime(score), section),
@@ -226,9 +235,28 @@ export async function runRenderCommand(
   const sha = createHash("sha256").update(wav).digest("hex");
   const seconds = audio.frames / audio.sampleRate;
   stdout.write(
-    `rendered · ${target} · ${seconds.toFixed(2)} s · ${wav.byteLength} bytes · ${sha}\n`,
+    `rendered · ${target} · ${seconds.toFixed(2)} s · ${audio.sampleRate} Hz${
+      // A plain song keeps 0.4's 22.05 kHz (byte-identical renders); say
+      // so, since its ceiling is 11 kHz and cymbal air is lost.
+      rateArg === undefined && !score.master
+        ? " (--rate 48000 for full band)"
+        : ""
+    } · ${wav.byteLength} bytes · ${sha}\n`,
   );
   if (credits) stdout.write(`credits · ${credits}\n`);
+  const clipped = clippedSamples(audio.pcm);
+  if (clipped > 0)
+    stderr.write(
+      `warning · ${clipped} ${clipped === 1 ? "sample clips" : "samples clip"} at full scale · ${
+        audio.master
+          ? "add master limiter or lower the master gain"
+          : "lower track volumes or add a master with a limiter (master streaming, or master: { limiter: {} } in song.ts)"
+      }\n`,
+    );
+  if (audio.nonFinite)
+    stderr.write(
+      `warning · ${audio.nonFinite.samples} non-finite ${audio.nonFinite.samples === 1 ? "sample" : "samples"} zeroed · from ${audio.nonFinite.tracks.join(", ")} · an effect or voice setting is unstable\n`,
+    );
   if (options.has("--measure"))
     stdout.write(
       `loudness · ${measurementLine(measureRendered(audio, false).mix, audio.master)}\n`,
@@ -238,6 +266,13 @@ export async function runRenderCommand(
   return 0;
 }
 
+/** Samples at or past 16-bit full scale: the mix bus hit the rails. */
+export function clippedSamples(pcm: Int16Array): number {
+  let count = 0;
+  for (const value of pcm) if (value >= 32_767 || value <= -32_768) count += 1;
+  return count;
+}
+
 async function loadScore(
   workspace: string,
   options: ReadonlyMap<string, string>,

package/src/session/daemon.ts

@@ -704,7 +704,10 @@ const OPERATION_TYPES = new Set([
   "setTime",
   "setTuning",
   "setMaster",
+  "setCalibration",
+  "setStyle",
   "setSections",
+  "setClips",
 ]);
 
 /** Shape gate before the reducer, which validates every field it reads. */

package/src/session/meta.ts

@@ -30,6 +30,11 @@ export type SessionMeta = {
   namedFingerprint?: string;
   /** Track-and-instrument-set hash at the last auto name. */
   namedStructure?: string;
+  /**
+   * Optional (0.7): the song's loop has wrapped once, so the one-shot
+   * `↻ first loop` moment never repeats. Session state, never the score.
+   */
+  heardLoop?: true;
 };
 
 /** Fields a client may change. `null` clears an optional field. */
@@ -38,6 +43,8 @@ export type MetaPatch = {
   nameSource?: NameSource;
   namedFingerprint?: string | null;
   namedStructure?: string | null;
+  /** Only ever set; the first loop is heard once. */
+  heardLoop?: true;
 };
 
 /** A conditional write applies only when every given field still matches. */
@@ -125,6 +132,7 @@ export function parseSessionMeta(
   if (fingerprint) result.namedFingerprint = fingerprint;
   const structure = optionalFingerprint(meta.namedStructure);
   if (structure) result.namedStructure = structure;
+  if (meta.heardLoop === true) result.heardLoop = true;
   return result;
 }
 
@@ -144,6 +152,11 @@ export function parseMetaPatch(value: unknown): MetaPatch {
     if (raw[key] === undefined) continue;
     patch[key] = raw[key] === null ? null : requireFingerprint(raw[key]);
   }
+  if (raw.heardLoop !== undefined) {
+    if (raw.heardLoop !== true)
+      throw new MetaValidationError("heardLoop is invalid");
+    patch.heardLoop = true;
+  }
   if (Object.keys(patch).length === 0)
     throw new MetaValidationError("meta patch is empty");
   return patch;
@@ -184,6 +197,7 @@ export function applyMetaPatch(
   };
   if (patch.name !== undefined) next.name = patch.name;
   if (patch.nameSource !== undefined) next.nameSource = patch.nameSource;
+  if (patch.heardLoop) next.heardLoop = true;
   for (const key of ["namedFingerprint", "namedStructure"] as const) {
     if (patch[key] === null) delete next[key];
     else if (patch[key] !== undefined) next[key] = patch[key];

package/src/session/origin.ts

@@ -0,0 +1,154 @@
+import { WRITTEN_REVISION, type SessionPort } from "./port.ts";
+import type { SessionEvent, SessionRecord } from "./store.ts";
+
+/**
+ * Remembers the events this window wrote, so the "synced" card shows only
+ * for revisions that came from another client (design C12). Session events
+ * carry no writer id, so the tracker records the id of the event each of
+ * this window's appends produced, and holds a decision while a write is in
+ * flight (a watcher update can land before the append resolves).
+ */
+export class OwnWrites {
+  private readonly ids = new Set<string>();
+  private inflight = 0;
+  private waiters: (() => void)[] = [];
+
+  /** Wraps one append: records the event it produced. */
+  public async track<T>(
+    write: Promise<SessionRecord<T>>,
+  ): Promise<SessionRecord<T>> {
+    this.inflight++;
+    try {
+      const record = await write;
+      const revision = WRITTEN_REVISION.get(record);
+      const own =
+        revision === undefined
+          ? record.events[record.events.length - 1]
+          : record.events.find((event) => event.revision === revision);
+      if (own) this.remember(own.id);
+      return record;
+    } finally {
+      this.inflight--;
+      if (this.inflight === 0) {
+        const waiters = this.waiters;
+        this.waiters = [];
+        for (const wake of waiters) wake();
+      }
+    }
+  }
+
+  public remember(id: string): void {
+    this.ids.add(id);
+    // Bounded: only recent ids matter for the next watcher update.
+    if (this.ids.size > 512) {
+      const oldest = this.ids.values().next().value;
+      if (oldest !== undefined) this.ids.delete(oldest);
+    }
+  }
+
+  public isOwn(id: string): boolean {
+    return this.ids.has(id);
+  }
+
+  /** Resolves once no append from this window is in flight. */
+  public settled(): Promise<void> {
+    if (this.inflight === 0) return Promise.resolve();
+    return new Promise((resolve) => this.waiters.push(resolve));
+  }
+
+  /**
+   * Patches a port's append methods in place so every write it commits is
+   * tracked. Idempotent per port.
+   */
+  public attach<T>(port: SessionPort<T>): void {
+    const marked = port as SessionPort<T> & { [TRACKED]?: true };
+    if (marked[TRACKED]) return;
+    marked[TRACKED] = true;
+    const append = port.append.bind(port);
+    const appendOperations = port.appendOperations.bind(port);
+    port.append = (...args) => this.track(append(...args));
+    port.appendOperations = (...args) => this.track(appendOperations(...args));
+  }
+}
+
+const TRACKED = Symbol("dawg.ownWrites");
+
+/** Events in `latest` past `fromRevision` that this window did not write. */
+export function foreignEvents(
+  latest: Pick<SessionRecord<unknown>, "events">,
+  fromRevision: number,
+  own: Pick<OwnWrites, "isOwn">,
+): SessionEvent[] {
+  return latest.events.filter(
+    (event) => event.revision > fromRevision && !own.isOwn(event.id),
+  );
+}
+
+/**
+ * Names the other window for the sync card by the track it has open, the
+ * word that window's own header shows (`synced · lead window`), never by a
+ * number taken from the presence list's order. With several other windows
+ * the one whose track the edit touched is named; before presence arrives
+ * the edited track names it. Otherwise `another window`.
+ */
+export function otherWindowName(
+  clients: readonly { clientId: string; focusedTrackId?: string | null }[],
+  selfId: string,
+  options: {
+    /** The one track the foreign revision changed, when exactly one. */
+    editedTrackId?: string | undefined;
+    /** Display name for a track id. */
+    trackName?: (trackId: string) => string;
+  } = {},
+): string {
+  const name = options.trackName ?? ((trackId: string) => trackId);
+  const others = clients.filter(
+    (client) => client.clientId !== selfId && client.focusedTrackId,
+  );
+  const edited = options.editedTrackId;
+  const owner =
+    (edited && others.find((client) => client.focusedTrackId === edited)) ||
+    (others.length === 1 ? others[0] : undefined);
+  if (owner?.focusedTrackId) return `${name(owner.focusedTrackId)} window`;
+  if (edited) return `${name(edited)} window`;
+  return "another window";
+}
+
+/** The single track whose notes or settings differ, or undefined. */
+export function editedTrack(
+  before: {
+    tracks: readonly { id: string }[];
+    notes: readonly { trackId: string }[];
+  },
+  after: {
+    tracks: readonly { id: string }[];
+    notes: readonly { trackId: string }[];
+  },
+): string | undefined {
+  const changed = new Set<string>();
+  const byTrack = (value: typeof before) => {
+    const map = new Map<string, string[]>();
+    for (const note of value.notes) {
+      const list = map.get(note.trackId) ?? [];
+      list.push(JSON.stringify(note));
+      map.set(note.trackId, list);
+    }
+    return map;
+  };
+  const left = byTrack(before);
+  const right = byTrack(after);
+  const ids = new Set([
+    ...before.tracks.map((track) => track.id),
+    ...after.tracks.map((track) => track.id),
+  ]);
+  for (const id of ids) {
+    const a = before.tracks.find((track) => track.id === id);
+    const b = after.tracks.find((track) => track.id === id);
+    if (
+      JSON.stringify(a) !== JSON.stringify(b) ||
+      (left.get(id) ?? []).join("\n") !== (right.get(id) ?? []).join("\n")
+    )
+      changed.add(id);
+  }
+  return changed.size === 1 ? [...changed][0] : undefined;
+}

package/src/session/port.ts

@@ -129,6 +129,11 @@ export type OpenPortOptions = {
   /** Set false for one-shot commands (demo, export) that must not spawn dawgd. */
   daemon?: boolean;
   daemonArgs?: string[];
+  /**
+   * File sessions: the backstop poll while fs.watch is live (default 1 s).
+   * Tests raise it to prove a change arrived through the watcher.
+   */
+  watchedPollMs?: number;
 };
 
 /** Connects to (or starts) dawgd, falling back to the file-lock path. */
@@ -225,7 +230,11 @@ class DaemonPort<T> implements SessionPort<T> {
     }
     if (result.status === "accepted" || result.status === "duplicate") {
       this.setSync("synced");
-      return this.record();
+      // The client's record can already hold a later write from another
+      // window; mark which revision is this one's (OwnWrites reads it).
+      const record = { ...this.record() };
+      WRITTEN_REVISION.set(record, result.revision);
+      return record;
     }
     if (result.status === "rebase") {
       this.setSync("conflict");
@@ -308,6 +317,12 @@ class DaemonPort<T> implements SessionPort<T> {
   }
 }
 
+/**
+ * The revision an append produced, for records whose last event may be a
+ * newer write from elsewhere (a daemon window's record follows the log).
+ */
+export const WRITTEN_REVISION = new WeakMap<object, number>();
+
 class FilePort<T> implements SessionPort<T> {
   public readonly mode = "file" as const;
   public readonly clientId = randomUUID();
@@ -408,10 +423,10 @@ class FilePort<T> implements SessionPort<T> {
     };
     const recordName = basename(this.options.paths.record);
     // macOS coalesces the temp write and the rename into events named after
-    // the temp file (`<record>.<pid>.tmp`), so match that too, but not the
+    // the temp file (`<record>.<pid>.<n>.tmp`), so match that too, but not the
     // sibling `.audio.lock` / `.daemon.log` files that share the prefix.
     const recordFile = new RegExp(
-      `^${recordName.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")}(?:\\.\\d+\\.tmp)?$`,
+      `^${recordName.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")}(?:(?:\\.\\d+)+\\.tmp)?$`,
     );
     let watcher: FSWatcher | undefined;
     try {
@@ -429,7 +444,10 @@ class FilePort<T> implements SessionPort<T> {
     } catch {
       watcher = undefined;
     }
-    const timer = setInterval(check, watcher ? WATCHED_POLL_MS : POLL_MS);
+    const timer = setInterval(
+      check,
+      watcher ? (this.options.watchedPollMs ?? WATCHED_POLL_MS) : POLL_MS,
+    );
     this.statusListeners.add(listener);
     check();
     return () => {

package/src/session/presence.ts

@@ -4,6 +4,7 @@ import {
   readFile,
   rename,
   rm,
+  stat,
   writeFile,
 } from "node:fs/promises";
 import { join } from "node:path";
@@ -32,6 +33,9 @@ export class FilePresence {
   private readonly lock: string;
   private entry: PresenceEntry;
   private timer: ReturnType<typeof setInterval> | undefined;
+  private writing: Promise<void> = Promise.resolve();
+  private writes = 0;
+  private stopped = false;
 
   public constructor(paths: SessionPaths, entry: PresenceEntry) {
     this.dir = `${paths.record}.presence`;
@@ -40,6 +44,7 @@ export class FilePresence {
   }
 
   public async start(): Promise<void> {
+    this.stopped = false;
     await this.write();
     this.timer = setInterval(
       () => void this.write().catch(() => {}),
@@ -49,14 +54,19 @@ export class FilePresence {
   }
 
   public async stop(): Promise<void> {
+    // A heartbeat already queued would otherwise rename its file back after
+    // the removal and leave a ghost entry.
+    this.stopped = true;
     if (this.timer) clearInterval(this.timer);
     this.timer = undefined;
+    await this.writing;
     await rm(this.file(), { force: true });
   }
 
   public async focus(trackId: string | null): Promise<void> {
     this.entry = { ...this.entry, focusedTrackId: trackId };
-    await this.write();
+    // Presence is advisory: a failed heartbeat write never refuses a focus change.
+    await this.write().catch(() => undefined);
   }
 
   public async claim(
@@ -98,14 +108,17 @@ export class FilePresence {
 
   /** Live entries; stale or dead-process heartbeats are removed. */
   public async list(now = Date.now()): Promise<PresenceEntry[]> {
-    let names: string[];
+    let all: string[];
     try {
-      names = (await readdir(this.dir)).filter((name) =>
-        name.endsWith(".json"),
-      );
+      all = await readdir(this.dir);
     } catch {
       return [];
     }
+    // A writer that crashed between write and rename leaves its temp file.
+    for (const name of all.slice(0, MAX_PRESENCE_FILES))
+      if (name.endsWith(".tmp"))
+        await sweepTemporary(join(this.dir, name), now);
+    const names = all.filter((name) => name.endsWith(".json"));
     const entries: PresenceEntry[] = [];
     for (const name of names.slice(0, MAX_PRESENCE_FILES)) {
       const path = join(this.dir, name);
@@ -133,18 +146,48 @@ export class FilePresence {
     return join(this.dir, `${this.entry.clientId}.json`);
   }
 
-  private async write(): Promise<void> {
+  /** Writes are serialized so the heartbeat and focus() never share a rename. */
+  private write(): Promise<void> {
+    const next = this.writing.then(
+      () => this.writeNow(),
+      () => this.writeNow(),
+    );
+    this.writing = next.catch(() => undefined);
+    return next;
+  }
+
+  private async writeNow(): Promise<void> {
+    if (this.stopped) return;
     await mkdir(this.dir, { recursive: true });
-    const temporary = `${this.file()}.${process.pid}.tmp`;
+    const temporary = `${this.file()}.${process.pid}.${++this.writes}.tmp`;
     await writeFile(
       temporary,
       JSON.stringify({ ...this.entry, at: Date.now() }),
       "utf8",
     );
+    if (this.stopped) {
+      await rm(temporary, { force: true });
+      return;
+    }
     await rename(temporary, this.file());
   }
 }
 
+/** Removes a temp file left by a dead writer, or one older than the stale window. */
+async function sweepTemporary(path: string, now: number): Promise<void> {
+  const pid = Number(/\.(\d+)\.\d+\.tmp$/.exec(path)?.[1]);
+  try {
+    const { mtimeMs } = await stat(path);
+    if (
+      now - mtimeMs > PRESENCE_STALE_MS ||
+      (Number.isSafeInteger(pid) && pid > 0 && !alive(pid))
+    )
+      await rm(path, { force: true });
+  } catch {
+    // Already renamed or removed by its writer.
+  }
+}
+
 function alive(pid: number): boolean {
   try {
     process.kill(pid, 0);

package/src/session/protocol.ts

@@ -551,7 +551,11 @@ function requireRecord(value: unknown): SessionRecord<unknown> {
     !Number.isSafeInteger(record.revision) ||
     typeof record.updatedAt !== "string" ||
     !Array.isArray(record.events) ||
-    record.events.length !== record.revision ||
+    (record.folded !== undefined &&
+      (!Number.isSafeInteger(record.folded) ||
+        (record.folded as number) < 1)) ||
+    record.events.length + ((record.folded as number | undefined) ?? 0) !==
+      record.revision ||
     record.composition === undefined
   )
     throw new ProtocolError("invalid", "record is invalid");

package/src/session/rebase.ts

@@ -84,6 +84,7 @@ export function rebaseOperations(
         break;
       }
       case "updateTrack":
+      case "setClips":
       case "setAutomation": {
         if (added.tracks.has(operation.trackId)) break;
         if (!settingsUnchanged(operation.trackId))
@@ -123,10 +124,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) ||
@@ -177,13 +186,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);
 }