@hraness/dawg 0.6.1 → 0.8.0

package/src/audio/engine.ts

@@ -14,8 +14,22 @@ 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 {
+  openNativePlayer,
+  probeNativeSink,
+  type AudioTiming,
+  type NativeProbe,
+  type PlayerClock,
+  type SinkLibrary,
+} from "./native.ts";
 
 /**
  * How dawgd (or a file-mode window) makes sound.
@@ -30,7 +44,8 @@ import { transportMapFor, type TransportMap } from "./clock.ts";
  *   s16le from stdin; tests use it to record the exact byte stream.
  * - `none` makes no sound; the transport clock still runs.
  */
-export type AudioBackend = "ffplay" | "sox" | "afplay" | "command" | "none";
+export type AudioBackend =
+  "native" | "ffplay" | "sox" | "afplay" | "command" | "none";
 
 export type AudioBackendInfo = Readonly<{
   backend: AudioBackend;
@@ -40,6 +55,10 @@ export type AudioBackendInfo = Readonly<{
   command?: readonly string[];
   /** Human-readable reason the backend was chosen. */
   detail: string;
+  /** The loaded sink, for the `native` backend. */
+  native?: SinkLibrary;
+  /** Why the native sink is not in use, when another backend was picked. */
+  nativeUnavailable?: string;
 }>;
 
 type Which = (binary: string) => string | null;
@@ -49,8 +68,26 @@ export type DetectOptions = Readonly<{
   which?: Which;
   platform?: NodeJS.Platform;
   sampleRate?: number;
+  /** Native sink probe; `false` skips it (tests). Default: the real one. */
+  native?: (() => NativeProbe) | false;
 }>;
 
+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();
+  return cachedProbe;
+}
+
 /** Streaming argv for the known stdin players. */
 export function streamingCommand(
   backend: "ffplay" | "sox",
@@ -99,8 +136,9 @@ export function streamingCommand(
 
 /**
  * Pick the audio backend. Order: DAWG_AUDIO=0 (none), DAWG_AUDIO_PLAYER
- * (explicit stdin command), DAWG_AUDIO_BACKEND (forced name), then ffplay,
- * sox `play`, and afplay (macOS) in that order.
+ * (explicit stdin command), DAWG_AUDIO_BACKEND (forced name), then the
+ * native sink, ffplay, sox `play`, and afplay (macOS) in that order. When
+ * the native sink cannot load, the fallback's detail says why.
  */
 export function detectAudioBackend(
   options: DetectOptions = {},
@@ -128,13 +166,40 @@ export function detectAudioBackend(
   }
   const forced = env.DAWG_AUDIO_BACKEND?.trim().toLowerCase();
   const candidates: AudioBackend[] =
+    forced === "native" ||
     forced === "ffplay" ||
     forced === "sox" ||
     forced === "afplay" ||
     forced === "none"
       ? [forced]
-      : ["ffplay", "sox", "afplay"];
+      : ["native", "ffplay", "sox", "afplay"];
+  let unavailable: string | undefined;
+  const why = (info: AudioBackendInfo): AudioBackendInfo =>
+    unavailable
+      ? {
+          ...info,
+          detail: `${info.detail} · native sink unavailable: ${unavailable}`,
+          nativeUnavailable: unavailable,
+        }
+      : info;
   for (const candidate of candidates) {
+    if (candidate === "native") {
+      if (options.native === false) continue;
+      const probe = options.native
+        ? options.native()
+        : env === process.env && options.platform === undefined
+          ? defaultNativeProbe()
+          : probeNativeSink({ env, platform });
+      if (probe.ok)
+        return {
+          backend: "native",
+          streaming: true,
+          native: probe.library,
+          detail: `native sink ${probe.detail} (device callback)`,
+        };
+      unavailable = probe.reason;
+      continue;
+    }
     if (candidate === "none")
       return {
         backend: "none",
@@ -144,26 +209,26 @@ export function detectAudioBackend(
     if (candidate === "ffplay" || candidate === "sox") {
       const binary = which(candidate === "ffplay" ? "ffplay" : "play");
       if (!binary) continue;
-      return {
+      return why({
         backend: candidate,
         streaming: true,
         command: streamingCommand(candidate, binary, sampleRate),
         detail: `${binary} (gapless stream)`,
-      };
+      });
     }
     const binary = platform === "darwin" ? which("afplay") : null;
     if (binary)
-      return {
+      return why({
         backend: "afplay",
         streaming: false,
         detail: `${binary} (re-render on edit; install ffmpeg or sox for gapless playback)`,
-      };
+      });
   }
-  return {
+  return why({
     backend: "none",
     streaming: false,
     detail: "no player found (install ffmpeg or sox)",
-  };
+  });
 }
 
 /** One status line for `dawg auth status` and the header. */
@@ -205,8 +270,21 @@ type PlayerProcess = {
   readonly stdin: Sink;
   readonly exited: Promise<number>;
   kill(): void;
+  /** Device-clocked players (the native sink) pace the pump themselves. */
+  readonly clock?: PlayerClock;
 };
 
+/** Play-mode lead on the native sink: the ring only covers pump jitter. */
+export const NATIVE_PLAY_LEAD_MS = 15;
+/** Pump interval on the native sink. */
+export const NATIVE_TICK_MS = 5;
+
+function envNumber(value: string | undefined): number | undefined {
+  if (value === undefined || value.trim() === "") return undefined;
+  const number = Number(value);
+  return Number.isFinite(number) && number >= 0 ? number : undefined;
+}
+
 export type AudioEngineOptions = Readonly<{
   lockPath?: string;
   info?: AudioBackendInfo;
@@ -228,19 +306,60 @@ export type AudioEngineOptions = Readonly<{
   respawnMs?: number;
   /** Player lifecycle notices worth a status line. */
   onStatus?: (status: AudioStatus) => void;
+  /** Play-mode lead (default 60 ms; 15 ms on the native sink). */
+  playLeadMs?: number;
+  /**
+   * 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;
-/** Lead grows to this multiple of the last render time. */
+/**
+ * Default queue lead: the edit-to-audible floor while playing. 100 ms leaves
+ * 80 ms of slack over the 20 ms pump tick for main-thread stalls (a frame
+ * costs about 1 ms; play mode already runs at 60 ms).
+ */
+const DEFAULT_LEAD_MS = 100;
+/** Inline renders grow the lead to this multiple of the last render time. */
 const LEAD_RENDER_FACTOR = 1.5;
 
 type Loop = Readonly<{
@@ -334,8 +453,8 @@ type PlayRequest = {
  *
  * Timing: the engine is paced by the same monotonic clock as the transport.
  * Frame `n` of the stream belongs to wall time `start + n / rate`, and the
- * engine keeps a lead of audio queued ahead of now: at least `leadMs`, and
- * 1.5x the last render time when renders are slower than that. The device
+ * engine keeps a lead of audio queued ahead of now: `leadMs`, or 1.5x the
+ * last render time when renders run inline (no worker) and are slower. The device
  * plays the queue at its own rate, so what you hear trails the transport by
  * the player's fixed output latency and never accumulates drift from
  * re-renders. Renders run in a worker; an edit re-renders off-thread and
@@ -351,9 +470,18 @@ export class AudioEngine {
   private leadFrames: number;
   private readonly defaultLeadFrames: number;
   private readonly tickMs: number;
+  /** The lead play mode and auditions pin (see `setLeadMs`). */
+  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;
@@ -401,17 +529,40 @@ export class AudioEngine {
       options.info ?? detectAudioBackend({ sampleRate: this.sampleRate });
     this.lock = new PlaybackLock(options.lockPath);
     this.leadFrames = Math.round(
-      ((options.leadMs ?? 200) * this.sampleRate) / 1000,
+      ((options.leadMs ?? DEFAULT_LEAD_MS) * this.sampleRate) / 1000,
     );
     this.defaultLeadFrames = this.leadFrames;
     this.fadeFrames = Math.max(
       1,
       Math.round(SWAP_FADE_SECONDS * this.sampleRate),
     );
-    this.tickMs = options.tickMs ?? 20;
+    const native =
+      this.info.backend === "native" ? this.info.native : undefined;
+    this.tickMs = options.tickMs ?? (native ? NATIVE_TICK_MS : 20);
+    this.playLeadMs =
+      options.playLeadMs ??
+      envNumber(process.env.DAWG_PLAY_LEAD_MS) ??
+      (native ? NATIVE_PLAY_LEAD_MS : 60);
     this.now = options.now ?? (() => performance.now());
     this.useTimer = options.timer ?? true;
-    this.spawnPlayer = options.spawn ?? spawnStdinPlayer;
+    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.customSpawn = options.spawn;
     this.respawnMs = options.respawnMs ?? 250;
     this.onStatus = options.onStatus;
     this.renderer = new LoopRenderer({
@@ -452,6 +603,17 @@ export class AudioEngine {
         : Math.max(1, Math.round((ms * this.sampleRate) / 1000));
   }
 
+  /**
+   * A few words on how play mode sounds, for the play strip: the native
+   * sink, or the stdin player and why the sink is not in use.
+   */
+  public get audioNote(): string {
+    if (this.info.backend === "native") return "native sink";
+    return this.info.nativeUnavailable
+      ? `${this.info.backend} · no native sink`
+      : this.info.backend;
+  }
+
   /** Lead in milliseconds: how far ahead of now a new live voice sounds. */
   public get leadMs(): number {
     return (this.lead * 1000) / this.sampleRate;
@@ -619,14 +781,14 @@ export class AudioEngine {
 
   /** Frames kept queued ahead of the clock right now. */
   public get lead(): number {
-    // Play mode and auditions keep their short lead: renders run
-    // off-thread, so a slow render delays the swap, not the stream.
-    const adaptive =
-      (this.monitoring || this.leadPinned) && this.renderer.offThread
-        ? 0
-        : Math.round(
-            (LEAD_RENDER_FACTOR * this.lastRenderMs * this.sampleRate) / 1000,
-          );
+    // Off-thread renders never stall the pump: a slow render delays the
+    // swap, not the stream, so only inline renders grow the lead (every
+    // frame of lead is a frame of edit latency).
+    const adaptive = this.renderer.offThread
+      ? 0
+      : Math.round(
+          (LEAD_RENDER_FACTOR * this.lastRenderMs * this.sampleRate) / 1000,
+        );
     // The pump never queues more than a second, so the lead stays under it.
     return Math.min(
       Math.max(this.leadFrames, adaptive),
@@ -719,7 +881,18 @@ export class AudioEngine {
     );
   }
 
+  /**
+   * Stream timing on the native sink: the host time of the latest device
+   * callback, when a frame is heard, and the device latency. Undefined on
+   * the stdin players (their output latency is unknown).
+   */
+  public get timing(): AudioTiming | undefined {
+    return this.child?.clock?.timing();
+  }
+
   private queuedFrames(): number {
+    const clock = this.child?.clock;
+    if (clock) return clock.queuedFrames();
     const elapsed = Math.floor(
       ((this.now() - this.startMs) * this.sampleRate) / 1000,
     );
@@ -781,10 +954,22 @@ export class AudioEngine {
     const child = this.child;
     const loop = this.loop;
     if (!child || (!loop && !this.monitoring)) return;
-    const due =
-      Math.floor(((this.now() - this.startMs) * this.sampleRate) / 1000) +
-      this.lead;
-    let remaining = due - this.written;
+    if (this.followChoice()) return;
+    let remaining: number;
+    if (child.clock) {
+      // Device-clocked: top the ring up to the lead. Frames the device
+      // played as silence (an underrun) are skipped so the loop stays on
+      // the transport's beat.
+      const slip = child.clock.slipFrames();
+      if (slip > 0 && loop) this.cursor = (this.cursor + slip) % loop.frames;
+      if (slip > 0) this.endFades();
+      remaining = this.lead - child.clock.queuedFrames();
+    } else {
+      const due =
+        Math.floor(((this.now() - this.startMs) * this.sampleRate) / 1000) +
+        this.lead;
+      remaining = due - this.written;
+    }
     if (remaining <= 0) return;
     // Never queue more than one second at once, e.g. after a stalled loop.
     if (remaining > this.sampleRate) {
@@ -864,6 +1049,8 @@ export class AudioEngine {
 
   /** Wall time (monotonic ms) stream frame `frame` sounds at. */
   private frameMs(frame: number): number {
+    const clock = this.child?.clock;
+    if (clock) return clock.frameMs(frame);
     return this.startMs + (frame * 1000) / this.sampleRate;
   }
 
@@ -971,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;
@@ -1010,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);
@@ -1031,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)
@@ -1049,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/audio/fit.ts

@@ -53,7 +53,12 @@ const onsetCache = new Map<string, readonly number[]>();
 /** Background jobs by cache key, with the window they fit (one per window). */
 const pending = new Map<
   string,
-  { job: Generator<void, Float32Array>; window: string }
+  {
+    job: Generator<void, Float32Array>;
+    window: string;
+    /** Another stage's cache (0.7 autotune) takes the result instead. */
+    done?: (out: Float32Array) => void;
+  }
 >();
 let live = false;
 /** True when the current live render left a voice silent while fitting. */
@@ -191,6 +196,32 @@ export function shiftedBuffer(
   return out;
 }
 
+/** True inside `withLiveFit` (0.7: other stages defer long work too). */
+export function liveFitActive(): boolean {
+  return live;
+}
+
+/**
+ * Runs `job` between live blocks like a long fit and hands the result to
+ * `done` (the caller's own cache); `onFitReady` fires when it lands and
+ * the live render reports `fitting` until then (0.7 autotune).
+ */
+export function deferLiveJob<T>(
+  key: string,
+  job: () => Generator<void, T>,
+  done: (out: T) => void,
+): void {
+  missed = true;
+  if (pending.has(key)) return;
+  // The scheduler only steps the job and hands its value to `done`.
+  pending.set(key, {
+    job: job() as unknown as Generator<void, Float32Array>,
+    window: key,
+    done: done as unknown as (out: Float32Array) => void,
+  });
+  schedule();
+}
+
 function drain(job: Generator<void, Float32Array>): Float32Array {
   for (;;) {
     const step = job.next();
@@ -204,13 +235,14 @@ function schedule(): void {
     timer = undefined;
     const next = pending.entries().next();
     if (next.done) return;
-    const [key, { job }] = next.value;
+    const [key, { job, done }] = next.value;
     const until = performance.now() + 8;
     for (;;) {
       const step = job.next();
       if (step.done) {
         pending.delete(key);
-        remember(key, step.value);
+        if (done) done(step.value);
+        else remember(key, step.value);
         for (const listener of listeners) listener();
         break;
       }