@hraness/dawg 0.2.0 → 0.3.0

package/src/audio/engine.ts

@@ -1,7 +1,10 @@
 import type { TrackScore } from "../../core/score.ts";
 import { PlaybackLock } from "./lock.ts";
 import { LoopPlayer } from "./player.ts";
-import { DEFAULT_SAMPLE_RATE, RENDER_CHANNELS, renderScorePcm } from "./wav.ts";
+import { LoopRenderer, type LoopRender } from "./renderer.ts";
+import { clickSounds, clicksIn, type ClickLevel } from "./click.ts";
+import type { LiveNotePcm } from "./live.ts";
+import { DEFAULT_SAMPLE_RATE, RENDER_CHANNELS } from "./wav.ts";
 
 /**
  * How dawgd (or a file-mode window) makes sound.
@@ -195,36 +198,96 @@ export type AudioEngineOptions = Readonly<{
   /** Set false to drive `pump()` manually (tests). */
   timer?: boolean;
   spawn?: (command: readonly string[]) => PlayerProcess;
+  /** Set false to render on the calling thread instead of a worker. */
+  worker?: boolean;
+  /** Project root for sampler voices; without it samplers render silent. */
+  projectRoot?: string;
+  /** Base delay before a dead player is respawned; doubles per attempt. */
+  respawnMs?: number;
+  /** Player lifecycle notices worth a status line. */
+  onStatus?: (status: AudioStatus) => void;
 }>;
 
+export type AudioStatus = Readonly<{
+  /** `restarting`: the player died and is being respawned; `stopped`: gave up. */
+  state: "restarting" | "stopped";
+  message: string;
+}>;
+
+/** Respawns of a dying player before playback is declared stopped. */
+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. */
+const LEAD_RENDER_FACTOR = 1.5;
+
 type Loop = Readonly<{
   pcm: Int16Array;
   frames: number;
   framesPerBeat: number;
 }>;
 
+/**
+ * The click bus: the engine asks `beatAt` for the transport beat at a stream
+ * frame's wall time (undefined while the transport is stopped; negative
+ * during a count-in) and mixes a click on every step it crosses. It is a
+ * monitoring bus only, never part of a loop render or an export.
+ */
+export type ClickBus = Readonly<{
+  volume: number;
+  beatsPerBar: number;
+  subdivision: number;
+  beatAt: (monotonicMs: number) => number | undefined;
+}>;
+
+type LiveVoice = {
+  pcm: Int16Array;
+  frames: number;
+  /** Frames of this voice already mixed. */
+  position: number;
+  /** Fade-out frames left once released early; undefined while sounding. */
+  fadeLeft: number | undefined;
+  fadeFrames: number;
+};
+
+type PlayRequest = {
+  score: TrackScore;
+  beat: number | undefined;
+  /** Monotonic ms when `beat` was observed. */
+  atMs: number;
+  generation: number;
+  waiters: { resolve: () => void; reject: (error: Error) => void }[];
+};
+
 /**
  * The gapless audio engine. It renders the score into one seamless loop
  * (tails folded onto the start) and streams it to a long-lived stdin player.
  *
  * 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 exactly `leadMs` of audio queued ahead of now. The device
+ * 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
  * 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. An edit re-renders and swaps the buffer for every frame not
- * yet written, mapping the current beat into the new loop, so tempo and
- * length changes keep the musical position.
+ * re-renders. Renders run in a worker; an edit re-renders off-thread and
+ * swaps the buffer for every frame not yet written, mapping the current beat
+ * into the new loop, so tempo and length changes keep the musical position.
+ * Edits that arrive while a render is in flight coalesce into one render of
+ * the newest score.
  */
 export class AudioEngine {
   public readonly info: AudioBackendInfo;
   private readonly lock: PlaybackLock;
-  private readonly sampleRate: number;
-  private readonly leadFrames: number;
+  public readonly sampleRate: number;
+  private leadFrames: number;
+  private readonly defaultLeadFrames: number;
   private readonly tickMs: number;
   private readonly now: () => number;
   private readonly useTimer: boolean;
   private readonly spawnPlayer: (command: readonly string[]) => PlayerProcess;
+  private readonly renderer: LoopRenderer;
+  private readonly respawnMs: number;
+  private readonly onStatus: ((status: AudioStatus) => void) | undefined;
   private fallback: LoopPlayer | undefined;
   private child: PlayerProcess | undefined;
   private timer: ReturnType<typeof setInterval> | undefined;
@@ -238,6 +301,17 @@ export class AudioEngine {
   private starting: Promise<void> | undefined;
   private generation = 0;
   private spawns = 0;
+  private queued: PlayRequest | undefined;
+  private draining = false;
+  private lastRenderMs = 0;
+  private respawns = 0;
+  private respawnTimer: ReturnType<typeof setTimeout> | undefined;
+  /** Play mode: keep a player running without a loop for live voices. */
+  private monitoring = false;
+  private readonly voices = new Map<number, LiveVoice>();
+  private click: ClickBus | undefined;
+  private clickVoices: { sound: Float32Array; position: number }[] = [];
+  private sounds: Readonly<Record<ClickLevel, Float32Array>> | undefined;
 
   public constructor(options: AudioEngineOptions = {}) {
     this.sampleRate = options.sampleRate ?? DEFAULT_SAMPLE_RATE;
@@ -247,12 +321,22 @@ export class AudioEngine {
     this.leadFrames = Math.round(
       ((options.leadMs ?? 200) * this.sampleRate) / 1000,
     );
+    this.defaultLeadFrames = this.leadFrames;
     this.tickMs = options.tickMs ?? 20;
     this.now = options.now ?? (() => performance.now());
     this.useTimer = options.timer ?? true;
     this.spawnPlayer = options.spawn ?? spawnStdinPlayer;
+    this.respawnMs = options.respawnMs ?? 250;
+    this.onStatus = options.onStatus;
+    this.renderer = new LoopRenderer({
+      sampleRate: this.sampleRate,
+      ...(options.worker === undefined ? {} : { worker: options.worker }),
+      ...(options.projectRoot === undefined
+        ? {}
+        : { projectRoot: options.projectRoot }),
+    });
     if (this.info.backend === "afplay")
-      this.fallback = new LoopPlayer(options.lockPath);
+      this.fallback = new LoopPlayer(options.lockPath, options.projectRoot);
   }
 
   /** Whether a streaming player process is currently running. */
@@ -265,14 +349,180 @@ export class AudioEngine {
     return this.spawns;
   }
 
+  /** Milliseconds the most recent loop render took. */
+  public get renderMs(): number {
+    return this.lastRenderMs;
+  }
+
+  /**
+   * Set the queue lead (play mode drops it to ~60 ms so a key sounds soon
+   * after it is pressed); `undefined` restores the constructed lead.
+   */
+  public setLeadMs(ms: number | undefined): void {
+    this.leadFrames =
+      ms === undefined
+        ? this.defaultLeadFrames
+        : Math.max(1, Math.round((ms * this.sampleRate) / 1000));
+  }
+
+  /** Lead in milliseconds: how far ahead of now a new live voice sounds. */
+  public get leadMs(): number {
+    return (this.lead * 1000) / this.sampleRate;
+  }
+
+  /** Whether live voices and the click can sound (a streaming backend). */
+  public get canMonitor(): boolean {
+    return this.info.backend !== "none" && !this.fallback;
+  }
+
+  /**
+   * Play mode: keep the player running while the transport is stopped so
+   * live notes and the click sound over silence. Off stops a loopless player.
+   */
+  public async monitor(on: boolean): Promise<void> {
+    if (!this.canMonitor) return;
+    this.monitoring = on;
+    if (on) {
+      if (this.child || this.starting) return;
+      this.starting = this.start(undefined, 0).finally(() => {
+        this.starting = undefined;
+      });
+      await this.starting;
+      return;
+    }
+    this.voices.clear();
+    this.clickVoices = [];
+    if (!this.loop) await this.stopAsync();
+  }
+
+  public get monitoringLive(): boolean {
+    return this.monitoring;
+  }
+
+  /**
+   * Start a live voice at the write head: it sounds `leadMs` from now, and
+   * the return value is the monotonic ms its first frame is scheduled at
+   * (before the device's own output latency). A
+   * voice with the same id is replaced in place (a re-rendered, longer or
+   * released note keeps its position, so the swap is seamless).
+   */
+  public noteOn(id: number, note: LiveNotePcm): number {
+    const existing = this.voices.get(id);
+    if (existing) {
+      existing.pcm = note.pcm;
+      existing.frames = note.frames;
+      existing.fadeLeft = undefined;
+    } else
+      this.voices.set(id, {
+        pcm: note.pcm,
+        frames: note.frames,
+        position: 0,
+        fadeLeft: undefined,
+        fadeFrames: Math.max(1, Math.round(this.sampleRate * 0.01)),
+      });
+    // Write what is due now so the voice joins the very next chunk.
+    const first = this.written;
+    this.pump();
+    return this.frameMs(first);
+  }
+
+  /** Fade a live voice out over ~10 ms (sustain lifted, mode left). */
+  public noteOff(id: number): void {
+    const voice = this.voices.get(id);
+    if (voice && voice.fadeLeft === undefined)
+      voice.fadeLeft = voice.fadeFrames;
+  }
+
+  /** Frames of live voice `id` already mixed, or undefined once finished. */
+  public voicePosition(id: number): number | undefined {
+    return this.voices.get(id)?.position;
+  }
+
+  public get liveVoices(): number {
+    return this.voices.size;
+  }
+
+  /** Mix the click bus into the stream (undefined turns it off). */
+  public setClick(click: ClickBus | undefined): void {
+    this.click = click;
+    if (!click) this.clickVoices = [];
+    else this.sounds ??= clickSounds(this.sampleRate);
+  }
+
+  /** Frames kept queued ahead of the clock right now. */
+  public get lead(): number {
+    // Play mode keeps its short lead: renders run off-thread, so a slow
+    // render delays the swap, not the stream.
+    const adaptive =
+      this.monitoring && 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),
+      Math.floor(this.sampleRate * 0.9),
+    );
+  }
+
   /**
    * Start playback at `beat`, or, when already playing, swap in the new
-   * score at the current position without restarting the player.
+   * score at the current position without restarting the player. Resolves
+   * once the render has been applied (or superseded by a newer one).
    */
-  public async play(score: TrackScore, beat?: number): Promise<void> {
-    if (this.info.backend === "none") return;
+  public play(score: TrackScore, beat?: number): Promise<void> {
+    if (this.info.backend === "none") return Promise.resolve();
     if (this.fallback) return this.fallback.play(score, beat);
-    const loop = this.render(score);
+    return new Promise<void>((resolve, reject) => {
+      const waiters = this.queued?.waiters ?? [];
+      waiters.push({ resolve, reject });
+      this.queued = {
+        score,
+        beat,
+        atMs: this.now(),
+        generation: this.generation,
+        waiters,
+      };
+      void this.drain();
+    });
+  }
+
+  private async drain(): Promise<void> {
+    if (this.draining) return;
+    this.draining = true;
+    try {
+      while (this.queued) {
+        const request = this.queued;
+        this.queued = undefined;
+        try {
+          const render = await this.renderer.render(request.score);
+          this.lastRenderMs = render.renderMs;
+          // Stopped while rendering: the result is stale, not an error.
+          if (request.generation === this.generation)
+            await this.apply(this.toLoop(render, request.score), request);
+          for (const waiter of request.waiters) waiter.resolve();
+        } catch (error) {
+          for (const waiter of request.waiters)
+            waiter.reject(
+              error instanceof Error ? error : new Error(String(error)),
+            );
+        }
+      }
+    } finally {
+      this.draining = false;
+    }
+  }
+
+  private async apply(loop: Loop, request: PlayRequest): Promise<void> {
+    // The transport kept moving while the render ran.
+    const beat =
+      request.beat === undefined
+        ? undefined
+        : request.beat +
+          ((this.now() - request.atMs) * this.sampleRate) /
+            1000 /
+            loop.framesPerBeat;
     if (this.child) {
       this.swap(loop, beat);
       return;
@@ -303,10 +553,14 @@ export class AudioEngine {
    * by adding it.
    */
   private queuedBeats(loop: Loop): number {
+    return this.queuedFrames() / loop.framesPerBeat;
+  }
+
+  private queuedFrames(): number {
     const elapsed = Math.floor(
       ((this.now() - this.startMs) * this.sampleRate) / 1000,
     );
-    return Math.max(0, this.written - elapsed) / loop.framesPerBeat;
+    return Math.max(0, this.written - elapsed);
   }
 
   public stop(): void {
@@ -315,11 +569,19 @@ export class AudioEngine {
 
   public async stopAsync(): Promise<void> {
     this.generation += 1;
+    this.respawns = 0;
+    if (this.respawnTimer) clearTimeout(this.respawnTimer);
+    this.respawnTimer = undefined;
     if (this.fallback) {
       this.fallback.stop();
       return;
     }
     await this.starting?.catch(() => undefined);
+    if (this.monitoring && this.child) {
+      // Play mode: the transport stopped, the live player keeps running.
+      this.loop = undefined;
+      return;
+    }
     if (this.timer) clearInterval(this.timer);
     this.timer = undefined;
     const child = this.child;
@@ -337,6 +599,13 @@ export class AudioEngine {
     await this.lock.release();
   }
 
+  /** Stops playback and releases the render worker. */
+  public async dispose(): Promise<void> {
+    this.monitoring = false;
+    await this.stopAsync();
+    this.renderer.dispose();
+  }
+
   /**
    * Write every frame due by now plus the lead. Called by the timer; tests
    * call it directly with an injected clock.
@@ -344,22 +613,22 @@ export class AudioEngine {
   public pump(): void {
     const child = this.child;
     const loop = this.loop;
-    if (!child || !loop) return;
+    if (!child || (!loop && !this.monitoring)) return;
     const due =
       Math.floor(((this.now() - this.startMs) * this.sampleRate) / 1000) +
-      this.leadFrames;
+      this.lead;
     let 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) {
       const skipped = remaining - this.sampleRate;
-      this.cursor = (this.cursor + skipped) % loop.frames;
+      if (loop) this.cursor = (this.cursor + skipped) % loop.frames;
       this.written += skipped;
       remaining = this.sampleRate;
     }
     const out = new Int16Array(remaining * RENDER_CHANNELS);
     let offset = 0;
-    while (offset < remaining) {
+    while (loop && offset < remaining) {
       const take = Math.min(remaining - offset, loop.frames - this.cursor);
       out.set(
         loop.pcm.subarray(
@@ -371,6 +640,7 @@ export class AudioEngine {
       offset += take;
       this.cursor = (this.cursor + take) % loop.frames;
     }
+    this.mixLive(out, this.written, remaining);
     this.written += remaining;
     try {
       child.stdin.write(new Uint8Array(out.buffer));
@@ -380,14 +650,72 @@ export class AudioEngine {
     }
   }
 
-  private render(score: TrackScore): Loop {
-    const audio = renderScorePcm(score, {
-      sampleRate: this.sampleRate,
-      loop: true,
-    });
+  /** Wall time (monotonic ms) stream frame `frame` sounds at. */
+  private frameMs(frame: number): number {
+    return this.startMs + (frame * 1000) / this.sampleRate;
+  }
+
+  /** Add live voices and the click bus to a block about to be written. */
+  private mixLive(out: Int16Array, firstFrame: number, frames: number): void {
+    if (this.voices.size === 0 && !this.click && this.clickVoices.length === 0)
+      return;
+    for (const [id, voice] of this.voices) {
+      let index = 0;
+      for (; index < frames && voice.position < voice.frames; index += 1) {
+        let gain = 1;
+        if (voice.fadeLeft !== undefined) {
+          if (voice.fadeLeft <= 0) break;
+          gain = voice.fadeLeft / voice.fadeFrames;
+          voice.fadeLeft -= 1;
+        }
+        const at = index * RENDER_CHANNELS;
+        const from = voice.position * RENDER_CHANNELS;
+        out[at] = clamp16(out[at]! + voice.pcm[from]! * gain);
+        out[at + 1] = clamp16(out[at + 1]! + voice.pcm[from + 1]! * gain);
+        voice.position += 1;
+      }
+      if (
+        voice.position >= voice.frames ||
+        (voice.fadeLeft !== undefined && voice.fadeLeft <= 0)
+      )
+        this.voices.delete(id);
+    }
+    const click = this.click;
+    if (click && this.sounds) {
+      const from = click.beatAt(this.frameMs(firstFrame));
+      const to = click.beatAt(this.frameMs(firstFrame + frames));
+      // A stopped transport, a seek or a loop wrap fires no click.
+      if (from !== undefined && to !== undefined && to > from && to - from < 2)
+        for (const event of clicksIn(from, to, frames, click)) {
+          this.clickVoices.push({
+            sound: this.sounds[event.level],
+            position: -event.offset,
+          });
+        }
+    }
+    if (this.clickVoices.length === 0) return;
+    const level = 32767 * Math.max(0, Math.min(1, click?.volume ?? 0)) * 0.5;
+    for (const voice of this.clickVoices) {
+      for (let index = 0; index < frames; index += 1) {
+        const position = voice.position + index;
+        if (position < 0) continue;
+        if (position >= voice.sound.length) break;
+        const value = voice.sound[position]! * level;
+        const at = index * RENDER_CHANNELS;
+        out[at] = clamp16(out[at]! + value);
+        out[at + 1] = clamp16(out[at + 1]! + value);
+      }
+      voice.position += frames;
+    }
+    this.clickVoices = this.clickVoices.filter(
+      (voice) => voice.position < voice.sound.length,
+    );
+  }
+
+  private toLoop(render: LoopRender, score: TrackScore): Loop {
     return {
-      pcm: audio.pcm,
-      frames: audio.frames,
+      pcm: render.pcm,
+      frames: render.frames,
       framesPerBeat: (60 * this.sampleRate) / score.tempoBpm,
     };
   }
@@ -416,7 +744,7 @@ export class AudioEngine {
     this.loop = next;
   }
 
-  private async start(loop: Loop, beat: number): Promise<void> {
+  private async start(loop: Loop | undefined, beat: number): Promise<void> {
     const generation = this.generation;
     if (!(await this.lock.acquire())) return;
     if (generation !== this.generation) {
@@ -435,20 +763,62 @@ export class AudioEngine {
     this.loop = loop;
     this.startMs = this.now();
     this.written = 0;
-    this.cursor = this.frameForBeat(loop, beat);
+    this.cursor = loop ? this.frameForBeat(loop, beat) : 0;
     void child.exited.then(() => {
       if (this.child !== child) return;
-      // The player died while we still want sound: stop cleanly rather than
-      // spin; the next play() starts a fresh player.
-      this.child = undefined;
-      this.loop = undefined;
-      if (this.timer) clearInterval(this.timer);
-      this.timer = undefined;
-      void this.lock.release();
+      this.onPlayerExit(generation);
     });
     this.pump();
     if (this.useTimer) this.timer = setInterval(() => this.pump(), this.tickMs);
   }
+
+  /**
+   * The player died while we still want sound. Respawn it a bounded number
+   * of times, resuming from the frame the listener last heard, and report
+   * each attempt; after that, stop cleanly rather than show a silent
+   * "playing" transport.
+   */
+  private onPlayerExit(generation: number): void {
+    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 diedAt = this.now();
+    this.child = undefined;
+    this.loop = undefined;
+    if (this.timer) clearInterval(this.timer);
+    this.timer = undefined;
+    void this.lock.release().then(() => {
+      if ((!loop && !this.monitoring) || generation !== this.generation) return;
+      if (ranMs >= RESPAWN_RESET_MS) this.respawns = 0;
+      if (this.respawns >= MAX_RESPAWNS) {
+        this.onStatus?.({
+          state: "stopped",
+          message: `audio player exited ${MAX_RESPAWNS} times; playback stopped`,
+        });
+        return;
+      }
+      this.respawns += 1;
+      const delay = this.respawnMs * 2 ** (this.respawns - 1);
+      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)
+          return;
+        const frame = heard + ((this.now() - diedAt) * this.sampleRate) / 1000;
+        const beat = loop ? frame / loop.framesPerBeat : 0;
+        this.starting = this.start(loop, beat).finally(() => {
+          this.starting = undefined;
+        });
+      }, delay);
+    });
+  }
 }
 
 function spawnStdinPlayer(command: readonly string[]): PlayerProcess {
@@ -465,3 +835,7 @@ function spawnStdinPlayer(command: readonly string[]): PlayerProcess {
     kill: () => child.kill(),
   };
 }
+
+function clamp16(value: number): number {
+  return Math.max(-32768, Math.min(32767, Math.round(value)));
+}