@hraness/dawg 0.7.0 → 0.8.0

package/src/audio/engine.ts

@@ -14,6 +14,12 @@ import { measureLoudness, pcmChannels } from "./loudness.ts";
 import type { MasterReport } from "./master.ts";
 import { levelOf, type SoundLevel } from "./preview.ts";
 import { DEFAULT_SAMPLE_RATE, RENDER_CHANNELS } from "./wav.ts";
+import { statSync } from "node:fs";
+import {
+  audioChoicePath,
+  readAudioChoice,
+  resolveOutputDevice,
+} from "./devices.ts";
 import { playbackTime } from "./arrange.ts";
 import { transportMapFor, type TransportMap } from "./clock.ts";
 import {
@@ -67,6 +73,15 @@ export type DetectOptions = Readonly<{
 }>;
 
 let cachedProbe: NativeProbe | undefined;
+
+/**
+ * Replace the process's native probe (a test preload's fake sink, so a PTY
+ * run can list and switch devices without hardware).
+ */
+export function setNativeProbe(probe: NativeProbe | undefined): void {
+  cachedProbe = probe;
+}
+
 /** The real probe, once per process (dlopen is not repeated). */
 function defaultNativeProbe(): NativeProbe {
   cachedProbe ??= probeNativeSink();
@@ -293,20 +308,49 @@ export type AudioEngineOptions = Readonly<{
   onStatus?: (status: AudioStatus) => void;
   /** Play-mode lead (default 60 ms; 15 ms on the native sink). */
   playLeadMs?: number;
-  /** Native sink output device name (default: system default). */
-  device?: string;
+  /**
+   * Output device name (native sink; sox via AUDIODEV). Default:
+   * DAWG_AUDIO_DEVICE, then the saved choice (src/audio/devices.ts), then
+   * the system default. `null` forces the system default.
+   */
+  device?: string | null;
+  /**
+   * The saved choice to follow (`<config>/audio.json`): checked about once
+   * a second while playing and before each player starts, so a choice made
+   * in another window or the daemon's client moves playback. Defaults to
+   * the real file when the backend is auto-detected (no `info`, no
+   * `spawn`, no `device`); `false` never follows one.
+   */
+  choicePath?: string | false;
   /** Native sink device buffer frames (default 128; 0 = device default). */
   bufferFrames?: number;
 }>;
 
 export type AudioStatus = Readonly<{
-  /** `restarting`: the player died and is being respawned; `stopped`: gave up. */
-  state: "restarting" | "stopped";
+  /**
+   * `restarting`: the player died and is being respawned; `stopped`: gave
+   * up; `device`: the chosen output is gone, playback moved to the default.
+   */
+  state: "restarting" | "stopped" | "device";
   message: string;
 }>;
 
 /** Respawns of a dying player before playback is declared stopped. */
 const MAX_RESPAWNS = 3;
+/** How often a playing engine checks the saved device choice. */
+const CHOICE_CHECK_MS = 1000;
+
+function fileMtime(path: string): number {
+  try {
+    return statSync(path).mtimeMs;
+  } catch {
+    return 0;
+  }
+}
+
+function cleanEnvDevice(): string | undefined {
+  return resolveOutputDevice(process.env, {});
+}
 /** A player that ran this long before dying resets the respawn budget. */
 const RESPAWN_RESET_MS = 10_000;
 /**
@@ -430,7 +474,14 @@ export class AudioEngine {
   public readonly playLeadMs: number;
   private readonly now: () => number;
   private readonly useTimer: boolean;
-  private readonly spawnPlayer: (command: readonly string[]) => PlayerProcess;
+  private readonly customSpawn:
+    ((command: readonly string[]) => PlayerProcess) | undefined;
+  private readonly bufferFrames: number;
+  /** The output device the next player opens (undefined: system default). */
+  private outputDevice: string | undefined;
+  private readonly choicePath: string | false;
+  private choiceMtime: number;
+  private choiceCheckedMs = Number.NEGATIVE_INFINITY;
   private readonly renderer: LoopRenderer;
   private readonly respawnMs: number;
   private readonly onStatus: ((status: AudioStatus) => void) | undefined;
@@ -494,21 +545,24 @@ export class AudioEngine {
       (native ? NATIVE_PLAY_LEAD_MS : 60);
     this.now = options.now ?? (() => performance.now());
     this.useTimer = options.timer ?? true;
-    const device = options.device ?? process.env.DAWG_AUDIO_DEVICE?.trim();
-    const bufferFrames =
+    this.choicePath =
+      options.choicePath ??
+      (options.info === undefined &&
+      options.spawn === undefined &&
+      options.device === undefined
+        ? audioChoicePath()
+        : false);
+    this.outputDevice =
+      options.device === null
+        ? undefined
+        : ((options.device?.trim() || undefined) ??
+          (this.choicePath
+            ? resolveOutputDevice(process.env, readAudioChoice(this.choicePath))
+            : cleanEnvDevice()));
+    this.choiceMtime = this.choicePath ? fileMtime(this.choicePath) : 0;
+    this.bufferFrames =
       options.bufferFrames ?? envNumber(process.env.DAWG_AUDIO_BUFFER) ?? 128;
-    this.spawnPlayer =
-      options.spawn ??
-      (native
-        ? () =>
-            openNativePlayer(native, {
-              rate: this.sampleRate,
-              channels: RENDER_CHANNELS,
-              ...(device ? { device } : {}),
-              bufferFrames,
-              now: this.now,
-            })
-        : spawnStdinPlayer);
+    this.customSpawn = options.spawn;
     this.respawnMs = options.respawnMs ?? 250;
     this.onStatus = options.onStatus;
     this.renderer = new LoopRenderer({
@@ -900,6 +954,7 @@ export class AudioEngine {
     const child = this.child;
     const loop = this.loop;
     if (!child || (!loop && !this.monitoring)) return;
+    if (this.followChoice()) return;
     let remaining: number;
     if (child.clock) {
       // Device-clocked: top the ring up to the lead. Frames the device
@@ -1103,6 +1158,134 @@ export class AudioEngine {
     this.loop = next;
   }
 
+  /** The output device players open; undefined is the system default. */
+  public get device(): string | undefined {
+    return this.outputDevice;
+  }
+
+  /** Whether this backend can play on a chosen output. */
+  public get choosesDevice(): boolean {
+    return (
+      this.customSpawn === undefined &&
+      (this.info.backend === "native" || this.info.backend === "sox")
+    );
+  }
+
+  /**
+   * Move playback to `device` (undefined: the system default). A running
+   * player is replaced at the frame being heard, so the song carries on.
+   */
+  public setDevice(device: string | undefined): void {
+    const next = device?.trim() || undefined;
+    if (next === this.outputDevice) return;
+    this.outputDevice = next;
+    const child = this.child;
+    if (!child || !this.choosesDevice) return;
+    const loop = this.loop;
+    const heard = this.heardFrame(loop);
+    const at = this.now();
+    const generation = this.generation;
+    this.child = undefined;
+    this.loop = undefined;
+    if (this.timer) clearInterval(this.timer);
+    this.timer = undefined;
+    child.kill();
+    this.starting = child.exited
+      .catch(() => undefined)
+      .then(() => this.lock.release())
+      .then(async () => {
+        if (generation !== this.generation || this.child) return;
+        if (!loop && !this.monitoring) return;
+        const frame = heard + ((this.now() - at) * this.sampleRate) / 1000;
+        await this.start(loop, loop ? beatOfFrame(loop, frame) : 0);
+      })
+      .finally(() => {
+        this.starting = undefined;
+      });
+  }
+
+  /**
+   * Follow the saved choice when its file changed (at most once a second).
+   * Returns true when that moved playback to another device.
+   */
+  private followChoice(force = false): boolean {
+    if (!this.choicePath) return false;
+    const now = this.now();
+    if (!force && now - this.choiceCheckedMs < CHOICE_CHECK_MS) return false;
+    this.choiceCheckedMs = now;
+    const mtime = fileMtime(this.choicePath);
+    if (mtime === this.choiceMtime) return false;
+    this.choiceMtime = mtime;
+    const next = resolveOutputDevice(
+      process.env,
+      readAudioChoice(this.choicePath),
+    );
+    if (next === this.outputDevice) return false;
+    this.setDevice(next);
+    return true;
+  }
+
+  private heardFrame(loop: Loop | undefined): number {
+    return loop
+      ? (((this.cursor - this.queuedFrames()) % loop.frames) + loop.frames) %
+          loop.frames
+      : 0;
+  }
+
+  /** Open a player on the chosen output, or the default when it is gone. */
+  private spawnPlayer(command: readonly string[]): PlayerProcess {
+    if (this.customSpawn) return this.customSpawn(command);
+    this.followChoice(true);
+    const native =
+      this.info.backend === "native" ? this.info.native : undefined;
+    const device = this.outputDevice;
+    if (native) {
+      const open = (name: string | undefined) =>
+        openNativePlayer(native, {
+          rate: this.sampleRate,
+          channels: RENDER_CHANNELS,
+          ...(name ? { device: name } : {}),
+          bufferFrames: this.bufferFrames,
+          now: this.now,
+        });
+      if (!device) return open(undefined);
+      try {
+        return open(device);
+      } catch (error) {
+        const player = open(undefined);
+        this.deviceLost(device, error);
+        return player;
+      }
+    }
+    return spawnStdinPlayer(
+      command,
+      this.info.backend === "sox" && device ? { AUDIODEV: device } : undefined,
+    );
+  }
+
+  /** The chosen output is gone: play on the default and say so once. */
+  private deviceLost(device: string, _error?: unknown): void {
+    if (this.outputDevice !== device) return;
+    this.outputDevice = undefined;
+    this.onStatus?.({
+      state: "device",
+      message: `audio output "${device}" is unavailable · playing on the system default`,
+    });
+  }
+
+  /** After a player died: is its chosen output still there? */
+  private deviceGone(): string | undefined {
+    const device = this.outputDevice;
+    if (!device || !this.choosesDevice) return undefined;
+    if (this.info.backend === "sox") return device;
+    try {
+      const names = this.info.native?.devices(false) ?? [];
+      return names.some((entry) => entry.name === device) ? undefined : device;
+    } catch {
+      return undefined;
+    }
+  }
+
   private async start(loop: Loop | undefined, beat: number): Promise<void> {
     const generation = this.generation;
     if (!(await this.lock.acquire())) return;
@@ -1142,11 +1325,9 @@ export class AudioEngine {
     const loop = this.loop;
     const ranMs = this.now() - this.startMs;
     // Frame the device was playing when the stream ended.
-    const heard = loop
-      ? (((this.cursor - this.queuedFrames()) % loop.frames) + loop.frames) %
-        loop.frames
-      : 0;
+    const heard = this.heardFrame(loop);
     const diedAt = this.now();
+    const lost = this.deviceGone();
     this.child = undefined;
     this.loop = undefined;
     if (this.timer) clearInterval(this.timer);
@@ -1163,10 +1344,13 @@ export class AudioEngine {
       }
       this.respawns += 1;
       const delay = this.respawnMs * 2 ** (this.respawns - 1);
-      this.onStatus?.({
-        state: "restarting",
-        message: `audio player exited; restarting (${this.respawns}/${MAX_RESPAWNS})`,
-      });
+      // An unplugged output: one notice, then the default device.
+      if (lost) this.deviceLost(lost);
+      else
+        this.onStatus?.({
+          state: "restarting",
+          message: `audio player exited; restarting (${this.respawns}/${MAX_RESPAWNS})`,
+        });
       this.respawnTimer = setTimeout(() => {
         this.respawnTimer = undefined;
         if (generation !== this.generation || this.child || this.starting)
@@ -1181,9 +1365,13 @@ export class AudioEngine {
   }
 }
 
-function spawnStdinPlayer(command: readonly string[]): PlayerProcess {
+function spawnStdinPlayer(
+  command: readonly string[],
+  env?: Readonly<Record<string, string>>,
+): PlayerProcess {
   if (command.length === 0) throw new Error("no player command");
   const child = Bun.spawn([...command], {
+    ...(env ? { env: { ...process.env, ...env } } : {}),
     stdin: "pipe",
     stdout: "ignore",
     stderr: "ignore",

package/src/commands/arrange.ts

@@ -37,6 +37,8 @@ import {
   arrangedStartBar,
   deleteSection,
   duplicateSection,
+  joinSection,
+  splitSection,
   DROP_CUT_MIN,
   FILL_STYLES,
   findSection,
@@ -96,6 +98,8 @@ export type SectionCommand =
   | { type: "section-reset"; name: string }
   | { type: "section-loop"; name?: string }
   | { type: "section-jump"; name: string }
+  | { type: "section-split"; name: string; atBar: number }
+  | { type: "section-join"; name: string; force: boolean }
   | { type: "form-show" }
   | { type: "form-set"; text: string }
   | { type: "form-bake" }
@@ -134,6 +138,8 @@ const SUBCOMMANDS = new Set([
   "loop",
   "jump",
   "go",
+  "split",
+  "join",
 ]);
 
 /** `3-6` or `3..6` or `3` → 0-based start and length (1-based inclusive in). */
@@ -370,6 +376,22 @@ function parseSub(
       };
     case "vary":
       return parseVary(lead.name, lead.rest);
+    case "split": {
+      // section split verse at 5 (1-based bar)
+      const where = tail[0] === "at" ? tail.slice(1) : tail;
+      if (where.length === 2 && where[0] === "bar") where.shift();
+      if (where.length !== 1 || !/^\d{1,4}$/u.test(where[0]!)) return undefined;
+      const bar = Number(where[0]);
+      return bar >= 1
+        ? { type: "section-split", name: lead.name, atBar: bar - 1 }
+        : undefined;
+    }
+    case "join":
+      if (tail.length === 0)
+        return { type: "section-join", name: lead.name, force: false };
+      return tail.length === 1 && tail[0] === "force"
+        ? { type: "section-join", name: lead.name, force: true }
+        : undefined;
     default:
       return undefined;
   }
@@ -424,7 +446,10 @@ function parseFormWords(
   lower: readonly string[],
 ): SectionCommand | undefined {
   if (words.length === 0) return { type: "form-show" };
-  if (lower.length === 1 && (lower[0] === "bake" || lower[0] === "flatten"))
+  if (
+    lower.length === 1 &&
+    (lower[0] === "bake" || lower[0] === "flatten" || lower[0] === "print")
+  )
     return { type: "form-bake" };
   if (lower.length === 1 && (lower[0] === "off" || lower[0] === "none"))
     return { type: "form-set", text: "" };
@@ -713,6 +738,27 @@ function applyUnchecked(
         `section · added ${section.name} ${barsLabel(section)}${next.bars > score.bars ? ` · song now ${next.bars} bars` : ""}`,
       );
     }
+    case "section-split": {
+      const next = splitSection(score, command.name, command.atBar);
+      const half = next.sections.find(
+        (candidate) => !findSection(score, candidate.name),
+      );
+      return changed(
+        score,
+        next,
+        `section · ${command.name} split at bar ${command.atBar + 1}${half ? ` · ${half.name} ${barsLabel(half)}` : ""}`,
+      );
+    }
+    case "section-join": {
+      const section = findSection(score, command.name)!;
+      const next = joinSection(score, command.name, { force: command.force });
+      const joined = findSection(next, section.name);
+      return changed(
+        score,
+        next,
+        `section · joined into ${section.name}${joined ? ` ${barsLabel(joined)}` : ""}`,
+      );
+    }
     case "section-dup": {
       const next = duplicateSection(score, command.name, {
         ...(command.as ? { as: command.as } : {}),
@@ -882,10 +928,10 @@ function applyUnchecked(
       if (score.form.length === 0)
         return {
           ok: false,
-          message: "form · no form to bake · form verse chorus verse",
+          message: "form · no form to print · form verse chorus verse",
         };
       const next = flattenForm(score);
-      return changed(score, next, `form · baked into ${next.bars} bars`);
+      return changed(score, next, `printed form to tape · ${next.bars} bars`);
     }
     case "build": {
       const result = generateBuild(score, command.options);
@@ -926,39 +972,28 @@ function describeVary(vary: { transpose?: number; gain?: number }): string {
 }
 
 /**
- * `loop 2-3` when no section spans those bars: mark the section named
- * `loop` over them (moving it if it exists) and loop it, as one next score.
+ * `loop 2-3`: the loop range (score.loop, op1-ux §4), never a section. A
+ * range past the song's end is refused; a looped section stops looping.
  */
 export function loopSpan(
   score: TrackScore,
-  trackId: string,
   from: number,
   to: number,
 ):
-  | Readonly<{ ok: true; next: TrackScore; name: string; message: string }>
+  | Readonly<{ ok: true; next: TrackScore; message: string }>
   | Readonly<{ ok: false; message: string }> {
   const bars = from === to ? `${from}` : `${from}-${to}`;
-  const name = "loop";
   if (!Number.isInteger(from) || !Number.isInteger(to) || from < 1 || to < from)
     return { ok: false, message: `loop ${bars} · bars run low-high from 1` };
-  const marked = applySectionCommand(score, trackId, {
-    type: "section-mark",
-    name,
-    startBar: from - 1,
-    bars: to - from + 1,
-  });
-  if (!marked.ok || !marked.next)
-    return { ok: false, message: `loop ${bars} · ${marked.message}` };
-  const looped = applySectionCommand(marked.next, trackId, {
-    type: "section-loop",
-    name,
-  });
-  if (!looped.ok || !looped.next)
-    return { ok: false, message: `loop ${bars} · ${looped.message}` };
+  if (to > score.bars)
+    return {
+      ok: false,
+      message: `loop ${bars} · the song has ${score.bars} bars · bars ${to} lengthens it`,
+    };
+  const next = score.withLoop({ startBar: from - 1, bars: to - from + 1 });
   return {
     ok: true,
-    next: looped.next,
-    name,
-    message: `loop · bars ${from === to ? from : `${from}–${to}`} · section ${name} · loop off plays the song`,
+    next,
+    message: `loop · bars ${from === to ? from : `${from}–${to}`} · loop off plays the song`,
   };
 }

package/src/commands/grammar.ts

@@ -217,7 +217,7 @@ export type LoopCommand =
   | Readonly<{ type: "loop-show" }>;
 
 export const LOOP_USAGE =
-  "loop <a>-<b> | <section> | off · loop 1-4 · loop chorus · loop off";
+  "loop <a>-<b> | <section> | next | prev | off · loop 1-4 · loop chorus · loop next · loop off";
 
 /**
  * `loop 1-4` (bars, 1-based inclusive), `loop 1 4`, `loop chorus`, `loop
@@ -315,6 +315,7 @@ export const WINDOW_VERBS: ReadonlySet<string> = new Set([
   "theme",
   "motion",
   "showme",
+  "audio",
   "model",
   "sessions",
   "logout",
@@ -333,6 +334,7 @@ export const WINDOW_VERBS: ReadonlySet<string> = new Set([
   "len",
   "fitmode",
   "euclid",
+  "tape",
   "style",
   "styles",
   "calibration",