@hraness/dawg 0.6.0 → 0.7.0

package/src/audio/engine.ts

@@ -9,12 +9,21 @@ import {
   type ClickLevel,
 } from "./click.ts";
 import type { LiveNotePcm } from "./live.ts";
+import { RING_OUT_FADE_SECONDS } from "./instruments.ts";
 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 { 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.
@@ -29,7 +38,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;
@@ -39,6 +49,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;
@@ -48,8 +62,17 @@ 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;
+/** 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",
@@ -98,8 +121,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 = {},
@@ -127,13 +151,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",
@@ -143,26 +194,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. */
@@ -204,8 +255,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;
@@ -227,6 +291,12 @@ 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;
+  /** Native sink output device name (default: system default). */
+  device?: string;
+  /** Native sink device buffer frames (default 128; 0 = device default). */
+  bufferFrames?: number;
 }>;
 
 export type AudioStatus = Readonly<{
@@ -239,7 +309,13 @@ export type AudioStatus = Readonly<{
 const MAX_RESPAWNS = 3;
 /** 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<{
@@ -308,8 +384,16 @@ type LiveVoice = {
   /** Fade-out frames left once released early; undefined while sounding. */
   fadeLeft: number | undefined;
   fadeFrames: number;
+  /** Rings to its end on note-off (0.6.1 modal ring-out). */
+  ringOut?: boolean;
 };
 
+/**
+ * At most this many ring-out voices sound at once; the oldest beyond it fades
+ * over `RING_OUT_FADE_SECONDS` (spec 7.3: 32 resonator voices).
+ */
+export const MAX_RING_OUT_VOICES = 32;
+
 type PlayRequest = {
   score: TrackScore;
   beat: number | undefined;
@@ -325,8 +409,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
@@ -342,6 +426,8 @@ 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;
@@ -392,17 +478,37 @@ 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;
+    const device = options.device ?? process.env.DAWG_AUDIO_DEVICE?.trim();
+    const 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.respawnMs = options.respawnMs ?? 250;
     this.onStatus = options.onStatus;
     this.renderer = new LoopRenderer({
@@ -443,6 +549,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;
@@ -531,14 +648,18 @@ export class AudioEngine {
       existing.frames = note.frames;
       existing.fadeLeft = undefined;
       existing.fadeFrames = this.releaseFrames(note);
-    } else
+      existing.ringOut = note.ringOut === true;
+    } else {
       this.voices.set(id, {
         pcm: note.pcm,
         frames: note.frames,
         position: 0,
         fadeLeft: undefined,
         fadeFrames: this.releaseFrames(note),
+        ...(note.ringOut ? { ringOut: true } : {}),
       });
+      if (note.ringOut) this.capRingOut();
+    }
     // Write what is due now so the voice joins the very next chunk.
     const first = this.written;
     this.pump();
@@ -553,11 +674,39 @@ export class AudioEngine {
     );
   }
 
-  /** Fade a live voice out over ~10 ms (sustain lifted, mode left). */
-  public noteOff(id: number): void {
+  /**
+   * Past `MAX_RING_OUT_VOICES` ringing voices, fade the oldest still at full
+   * level over `RING_OUT_FADE_SECONDS` (Map order is start order).
+   */
+  private capRingOut(): void {
+    let ringing = 0;
+    for (const voice of this.voices.values())
+      if (voice.ringOut && voice.fadeLeft === undefined) ringing += 1;
+    for (const voice of this.voices.values()) {
+      if (ringing <= MAX_RING_OUT_VOICES) break;
+      if (!voice.ringOut || voice.fadeLeft !== undefined) continue;
+      this.fadeRingOut(voice);
+      ringing -= 1;
+    }
+  }
+
+  private fadeRingOut(voice: LiveVoice): void {
+    voice.fadeFrames = Math.max(
+      1,
+      Math.round(this.sampleRate * RING_OUT_FADE_SECONDS),
+    );
+    voice.fadeLeft = voice.fadeFrames;
+  }
+
+  /**
+   * Fade a live voice out over ~10 ms (sustain lifted, mode left). A
+   * ring-out voice keeps ringing; `noteOff(id, true)` silences it too.
+   */
+  public noteOff(id: number, force = false): void {
     const voice = this.voices.get(id);
-    if (voice && voice.fadeLeft === undefined)
-      voice.fadeLeft = voice.fadeFrames;
+    if (!voice || voice.fadeLeft !== undefined) return;
+    if (!voice.ringOut) voice.fadeLeft = voice.fadeFrames;
+    else if (force) this.fadeRingOut(voice);
   }
 
   /** Frames of live voice `id` already mixed, or undefined once finished. */
@@ -578,14 +727,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),
@@ -678,7 +827,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,
     );
@@ -740,10 +900,21 @@ 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;
+    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) {
@@ -823,6 +994,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;
   }
 

package/src/audio/fit.ts

@@ -31,6 +31,7 @@ import {
   sampleAt,
 } from "./dsp/stft.ts";
 import { hermite4 } from "./dsp/interp.ts";
+import { pitchShiftJob } from "./dsp/shift.ts";
 import type { FitMap } from "./warp.ts";
 
 export type FitAlgorithm = "repitch" | "beats" | "tones";
@@ -52,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. */
@@ -146,6 +152,76 @@ export function fittedBuffer(
   return out;
 }
 
+/**
+ * Live renders pitch-shift buffers up to this long synchronously; longer
+ * ones run between blocks while the voice plays a repitch. A phase-vocoder
+ * shift with formant keeping costs about 30 ms per second of 22.05 kHz
+ * audio, so only very short sounds fit the 10 ms note-on budget.
+ */
+export const LIVE_SYNC_SHIFT_SECONDS = 0.1;
+
+/**
+ * `buffer` pitch-shifted by `semitones` (formant semitones, 0 keeps),
+ * cached under `key` with the fits (0.6.1 `shift`, `formant`). Returns
+ * undefined only in a live render while a long shift is still running.
+ */
+export function shiftedBuffer(
+  key: string,
+  buffer: Float32Array,
+  sampleRate: number,
+  semitones: number,
+  formant: number | undefined,
+): Float32Array | undefined {
+  const hit = cache.get(key);
+  if (hit) {
+    cache.delete(key);
+    cache.set(key, hit);
+    return hit;
+  }
+  const work = () =>
+    pitchShiftJob(buffer, sampleRate, semitones, {
+      ...(formant === undefined ? {} : { formant }),
+    });
+  if (live && buffer.length > LIVE_SYNC_SHIFT_SECONDS * sampleRate) {
+    missed = true;
+    if (!pending.has(key)) {
+      pending.set(key, { job: work(), window: key });
+      schedule();
+    }
+    return undefined;
+  }
+  pending.delete(key);
+  const out = drain(work());
+  remember(key, out);
+  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();
@@ -159,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;
       }