@hraness/dawg 0.0.0-stage → 0.3.0

package/src/audio/live.ts

@@ -0,0 +1,152 @@
+/**
+ * Live voices for play mode: one note of one track, rendered through the
+ * same offline renderer the loop uses (`renderScorePcm`), so a key sounds
+ * exactly like the note it records as: the track's instrument voice (synth,
+ * drum kit or sampler), filter, pan, delay and reverb. Nothing is forked;
+ * this module only builds a one-note score and caches the result.
+ *
+ * The offline renderer is untouched, so loop renders and exports stay
+ * byte-identical. Live audio never reaches a render or an export: the engine
+ * mixes it into the stream only.
+ */
+import {
+  SCORE_LIMITS,
+  TrackScore,
+  isSamplerInstrument,
+  type Track,
+} from "../../core/score.ts";
+import { sampleKey, type SampleBank } from "./samples.ts";
+import { RENDER_CHANNELS, renderScorePcm } from "./wav.ts";
+
+/** A rendered live note: interleaved stereo 16-bit PCM. */
+export type LiveNotePcm = Readonly<{ pcm: Int16Array; frames: number }>;
+
+export type LiveNoteRequest = Readonly<{
+  score: TrackScore;
+  trackId: string;
+  pitch: number;
+  /** 0..1, as score notes store it. */
+  velocity: number;
+  /** How long the key is held. */
+  seconds: number;
+  /** Decoded sampler voices; without it sampler tracks are silent. */
+  samples?: SampleBank;
+}>;
+
+/** Longest a single live note is rendered for (a held sustain pedal). */
+export const MAX_LIVE_NOTE_SECONDS = 8;
+const CACHE_ENTRIES = 96;
+
+/**
+ * Renders and caches live notes. Repeated keys hit the cache, so the key
+ * handler only pays for a render the first time a pitch/length is played.
+ */
+export class LiveSynth {
+  private readonly cache = new Map<string, LiveNotePcm>();
+
+  public constructor(private readonly sampleRate: number) {}
+
+  public get rate(): number {
+    return this.sampleRate;
+  }
+
+  public get cached(): number {
+    return this.cache.size;
+  }
+
+  public render(request: LiveNoteRequest): LiveNotePcm | undefined {
+    const track = request.score.tracks.find(
+      (candidate) => candidate.id === request.trackId,
+    );
+    if (!track) return undefined;
+    const { score } = request;
+    const ticksPerSecond = (score.ticksPerBeat * score.tempoBpm) / 60;
+    const seconds = Math.max(
+      0.01,
+      Math.min(MAX_LIVE_NOTE_SECONDS, request.seconds),
+    );
+    const durationTicks = Math.max(
+      1,
+      Math.min(SCORE_LIMITS.maxTick, Math.round(seconds * ticksPerSecond)),
+    );
+    const velocity = Math.max(0, Math.min(1, request.velocity));
+    const pitch = Math.max(0, Math.min(127, Math.round(request.pitch)));
+    const key = JSON.stringify([
+      liveTrack(track),
+      pitch,
+      velocity,
+      durationTicks,
+      score.tempoBpm,
+      score.ticksPerBeat,
+      this.sampleRate,
+      samplerDigest(track, request.samples),
+    ]);
+    const hit = this.cache.get(key);
+    if (hit) {
+      // Refresh LRU order.
+      this.cache.delete(key);
+      this.cache.set(key, hit);
+      return hit;
+    }
+    const beats = durationTicks / score.ticksPerBeat;
+    const bars = Math.max(
+      1,
+      Math.min(SCORE_LIMITS.maxBars, Math.ceil(beats / score.beatsPerBar)),
+    );
+    const single = new TrackScore({
+      tempoBpm: score.tempoBpm,
+      beatsPerBar: score.beatsPerBar,
+      bars,
+      ticksPerBeat: score.ticksPerBeat,
+      tracks: [liveTrack(track)],
+      notes: [
+        {
+          id: "live",
+          trackId: track.id,
+          startTick: 0,
+          durationTicks,
+          pitch,
+          velocity,
+        },
+      ],
+    });
+    const audio = renderScorePcm(single, {
+      sampleRate: this.sampleRate,
+      maxSeconds: MAX_LIVE_NOTE_SECONDS + 4,
+      ...(request.samples ? { samples: request.samples } : {}),
+    });
+    const frames = audibleFrames(audio.pcm);
+    const rendered: LiveNotePcm = {
+      pcm: audio.pcm.subarray(0, frames * RENDER_CHANNELS),
+      frames,
+    };
+    this.cache.set(key, rendered);
+    while (this.cache.size > CACHE_ENTRIES) {
+      const oldest = this.cache.keys().next().value;
+      if (oldest === undefined) break;
+      this.cache.delete(oldest);
+    }
+    return rendered;
+  }
+}
+
+/** The track as it sounds live: audible regardless of mute and solo. */
+function liveTrack(track: Track): Track {
+  const { solo: _solo, ...rest } = track;
+  return { ...rest, muted: false };
+}
+
+function samplerDigest(track: Track, bank: SampleBank | undefined): string[] {
+  if (!isSamplerInstrument(track.instrument) || !track.sampler || !bank)
+    return [];
+  return Object.keys(track.sampler.voices)
+    .sort()
+    .map((voice) => bank.voices.get(sampleKey(track.id, voice))?.sha256 ?? "-");
+}
+
+/** Frames up to the last non-silent sample, so mixing skips the dead tail. */
+function audibleFrames(pcm: Int16Array): number {
+  let last = pcm.length - 1;
+  while (last >= 0 && pcm[last] === 0) last -= 1;
+  return Math.ceil((last + 1) / RENDER_CHANNELS);
+}

package/src/audio/lock.ts

@@ -0,0 +1,57 @@
+import { mkdir, rm, stat, utimes } from "node:fs/promises";
+
+/** Locks older than this without a heartbeat belong to a crashed player. */
+const STALE_LOCK_MS = 15_000;
+const HEARTBEAT_MS = 5_000;
+
+/**
+ * The per-session audio lock: one directory that at most one process (a
+ * window in file mode, or dawgd) holds while it is making sound. Its mtime
+ * is a heartbeat so a crashed owner is reclaimed after STALE_LOCK_MS.
+ */
+export class PlaybackLock {
+  private owned = false;
+  private heartbeat: ReturnType<typeof setInterval> | undefined;
+
+  public constructor(private readonly path: string | undefined) {}
+
+  public get held(): boolean {
+    return this.path === undefined || this.owned;
+  }
+
+  public async acquire(): Promise<boolean> {
+    if (!this.path) return true;
+    if (this.owned) return true;
+    try {
+      await mkdir(this.path);
+      await Bun.write(`${this.path}/owner`, `${process.pid}\n`);
+      this.owned = true;
+      this.heartbeat = setInterval(() => {
+        if (!this.path || !this.owned) return;
+        void utimes(this.path, new Date(), new Date()).catch(() => undefined);
+      }, HEARTBEAT_MS);
+      return true;
+    } catch (error) {
+      if ((error as { code?: string }).code !== "EEXIST") throw error;
+      try {
+        if (Date.now() - (await stat(this.path)).mtimeMs > STALE_LOCK_MS) {
+          await rm(this.path, { recursive: true, force: true });
+          return this.acquire();
+        }
+      } catch {
+        /* another window released between stat and retry */
+      }
+      return false;
+    }
+  }
+
+  public async release(): Promise<void> {
+    if (!this.owned || !this.path) return;
+    this.owned = false;
+    if (this.heartbeat) {
+      clearInterval(this.heartbeat);
+      this.heartbeat = undefined;
+    }
+    await rm(this.path, { recursive: true, force: true });
+  }
+}

package/src/audio/player.ts

@@ -0,0 +1,134 @@
+import { unlink } from "node:fs/promises";
+import type { TrackScore } from "../../core/score.ts";
+import { PlaybackLock } from "./lock.ts";
+import { SampleLibrary, hasSamplerTracks, type SampleBank } from "./samples.ts";
+import { RENDER_CHANNELS, encodeWav, renderScorePcm } from "./wav.ts";
+
+/** Small best-effort local player. The score and transport remain testable without a sound device. */
+export class LoopPlayer {
+  private process: { kill: () => void; exited?: Promise<number> } | undefined;
+  private file: string | undefined;
+  private readonly lock: PlaybackLock;
+  private readonly lockPath: string | undefined;
+
+  private library: SampleLibrary | undefined;
+
+  public constructor(
+    lockPath?: string,
+    private readonly projectRoot?: string,
+  ) {
+    this.lockPath = lockPath;
+    this.lock = new PlaybackLock(lockPath);
+  }
+
+  private get ownsLock(): boolean {
+    return this.lockPath !== undefined && this.lock.held;
+  }
+
+  /** Whether this process currently owns the session's shared audio lock. */
+  public get ownsPlaybackLock(): boolean {
+    return this.ownsLock;
+  }
+
+  /**
+   * Render one seamless loop (tails folded onto the start), rotated so the
+   * file begins at `beat`, then (re)start the one-shot player on it. This is
+   * the last-resort backend; streaming players never restart on edits.
+   */
+  public async play(score: TrackScore, beat = 0): Promise<void> {
+    await this.stopAsync();
+    if (process.env.DAWG_AUDIO === "0") return;
+    if (this.lockPath && !(await this.acquireLock())) return;
+    let samples: SampleBank | undefined;
+    if (this.projectRoot !== undefined && hasSamplerTracks(score)) {
+      this.library ??= new SampleLibrary({ projectRoot: this.projectRoot });
+      samples = await this.library.load(score).catch(() => undefined);
+    }
+    const path = `/tmp/dawg-${process.pid}-${Date.now()}-${Math.random().toString(36).slice(2)}.wav`;
+    await Bun.write(path, renderLoopWav(score, beat, samples));
+    this.file = path;
+    this.spawn(path);
+  }
+
+  private spawn(path: string): void {
+    const command =
+      process.platform === "darwin"
+        ? ["afplay", path]
+        : [
+            "ffplay",
+            "-nodisp",
+            "-autoexit",
+            "-loglevel",
+            "quiet",
+            "-loop",
+            "0",
+            path,
+          ];
+    try {
+      const child = Bun.spawn(command, { stdout: "ignore", stderr: "ignore" });
+      this.process = child;
+      void child.exited.then(() => {
+        if (this.process !== child) return;
+        this.process = undefined;
+        // afplay is one-shot, so restart the same rendered loop while the
+        // session still owns the playback lock. Stop clears `this.file` first.
+        if (this.file === path && this.ownsLock) {
+          this.spawn(path);
+          return;
+        }
+        void this.cleanup().then(() => this.releaseLock());
+      });
+    } catch {
+      void this.cleanup().then(() => this.releaseLock());
+    }
+  }
+
+  public stop(): void {
+    void this.stopAsync();
+  }
+
+  private async stopAsync(): Promise<void> {
+    const child = this.process;
+    this.process = undefined;
+    child?.kill();
+    await child?.exited;
+    await this.cleanup();
+    await this.releaseLock();
+  }
+
+  private async acquireLock(): Promise<boolean> {
+    return this.lock.acquire();
+  }
+
+  private async releaseLock(): Promise<void> {
+    await this.lock.release();
+  }
+
+  private async cleanup(): Promise<void> {
+    if (!this.file) return;
+    const path = this.file;
+    this.file = undefined;
+    await unlink(path).catch(() => undefined);
+  }
+}
+
+/** A loop-folded WAV whose first frame is `beat` into the loop. */
+export function renderLoopWav(
+  score: TrackScore,
+  beat = 0,
+  samples?: SampleBank,
+): Uint8Array {
+  const audio = renderScorePcm(score, { loop: true, samples });
+  const framesPerBeat = (60 * audio.sampleRate) / score.tempoBpm;
+  const start =
+    ((Math.round(Math.max(0, beat) * framesPerBeat) % audio.frames) +
+      audio.frames) %
+    audio.frames;
+  const rotated = new Int16Array(audio.pcm.length);
+  rotated.set(audio.pcm.subarray(start * RENDER_CHANNELS));
+  rotated.set(
+    audio.pcm.subarray(0, start * RENDER_CHANNELS),
+    (audio.frames - start) * RENDER_CHANNELS,
+  );
+  return encodeWav(rotated, audio.sampleRate, RENDER_CHANNELS);
+}

package/src/audio/render-worker.ts

@@ -0,0 +1,68 @@
+/**
+ * Off-thread loop renderer for the audio engine. One worker per engine
+ * keeps a stem cache across renders, so an edit re-renders only the tracks
+ * it touched while the daemon loop keeps serving windows and pumping audio.
+ */
+import { scoreFromJSON } from "../../core/score.ts";
+import { SampleLibrary, hasSamplerTracks } from "./samples.ts";
+import { StemRenderer } from "./wav.ts";
+
+export type RenderRequest = Readonly<{
+  id: number;
+  score: unknown;
+  sampleRate: number;
+  /** Project root sampler voices resolve under; omitted = samplers silent. */
+  projectRoot?: string;
+}>;
+
+export type RenderReply =
+  | Readonly<{
+      id: number;
+      ok: true;
+      frames: number;
+      sampleRate: number;
+      pcm: Int16Array;
+      /** Milliseconds spent rendering, excluding transfer. */
+      renderMs: number;
+    }>
+  | Readonly<{ id: number; ok: false; error: string }>;
+
+declare const self: Worker;
+
+const renderer = new StemRenderer();
+let library: SampleLibrary | undefined;
+
+self.onmessage = async (event: MessageEvent<RenderRequest>) => {
+  const { id, score, sampleRate, projectRoot } = event.data;
+  try {
+    const started = performance.now();
+    const parsed = scoreFromJSON(score);
+    let samples;
+    if (projectRoot !== undefined && hasSamplerTracks(parsed)) {
+      if (library?.projectRoot !== projectRoot)
+        library = new SampleLibrary({ projectRoot });
+      samples = await library.load(parsed);
+    }
+    const audio = renderer.render(parsed, {
+      sampleRate,
+      loop: true,
+      samples,
+    });
+    const reply: RenderReply = {
+      id,
+      ok: true,
+      frames: audio.frames,
+      sampleRate: audio.sampleRate,
+      pcm: audio.pcm,
+      renderMs: performance.now() - started,
+    };
+    self.postMessage(reply, [audio.pcm.buffer]);
+  } catch (error) {
+    const reply: RenderReply = {
+      id,
+      ok: false,
+      error: error instanceof Error ? error.message : String(error),
+    };
+    self.postMessage(reply);
+  }
+};

package/src/audio/renderer.ts

@@ -0,0 +1,174 @@
+import type { TrackScore } from "../../core/score.ts";
+import type { RenderReply, RenderRequest } from "./render-worker.ts";
+import { SampleLibrary, hasSamplerTracks } from "./samples.ts";
+import { StemRenderer } from "./wav.ts";
+
+export type LoopRender = Readonly<{
+  pcm: Int16Array;
+  frames: number;
+  sampleRate: number;
+  /** Milliseconds the render itself took (worker or inline). */
+  renderMs: number;
+}>;
+
+export type LoopRendererOptions = Readonly<{
+  sampleRate: number;
+  /** Set false to render on the calling thread (tests, diagnostics). */
+  worker?: boolean;
+  /**
+   * Project root sampler voices resolve under (decoded in the worker, or
+   * inline on fallback). Without it sampler tracks render silent.
+   */
+  projectRoot?: string;
+}>;
+
+/**
+ * Renders loops for the engine off the main thread. A single long-lived
+ * worker owns a stem cache; the PCM buffer comes back transferred, not
+ * copied. If the worker cannot start or crashes, rendering falls back to the
+ * calling thread with its own cache, so sound never depends on the worker.
+ */
+export class LoopRenderer {
+  private readonly sampleRate: number;
+  private readonly useWorker: boolean;
+  private worker: Bun.Worker | undefined;
+  private workerBroken = false;
+  private inline: StemRenderer | undefined;
+  private library: SampleLibrary | undefined;
+  private readonly projectRoot: string | undefined;
+  private nextId = 1;
+  private readonly pending = new Map<
+    number,
+    { resolve: (render: LoopRender) => void; reject: (error: Error) => void }
+  >();
+  private disposed = false;
+
+  public constructor(options: LoopRendererOptions) {
+    this.sampleRate = options.sampleRate;
+    this.useWorker = options.worker ?? true;
+    this.projectRoot = options.projectRoot;
+  }
+
+  /** True while renders run in the worker. */
+  public get offThread(): boolean {
+    return this.useWorker && !this.workerBroken;
+  }
+
+  public async render(score: TrackScore): Promise<LoopRender> {
+    if (this.disposed) throw new Error("renderer disposed");
+    if (this.offThread) {
+      try {
+        return await this.renderInWorker(score);
+      } catch (error) {
+        if (!(error instanceof WorkerLostError)) throw error;
+      }
+    }
+    return this.renderInline(score);
+  }
+
+  /** Stops the worker; in-flight renders fall back inline on their callers. */
+  public dispose(): void {
+    this.disposed = true;
+    this.failWorker(new WorkerLostError("renderer disposed"));
+  }
+
+  private async renderInline(score: TrackScore): Promise<LoopRender> {
+    this.inline ??= new StemRenderer();
+    const started = performance.now();
+    let samples;
+    if (this.projectRoot !== undefined && hasSamplerTracks(score)) {
+      this.library ??= new SampleLibrary({ projectRoot: this.projectRoot });
+      samples = await this.library.load(score);
+    }
+    const audio = this.inline.render(score, {
+      sampleRate: this.sampleRate,
+      loop: true,
+      samples,
+    });
+    return {
+      pcm: audio.pcm,
+      frames: audio.frames,
+      sampleRate: audio.sampleRate,
+      renderMs: performance.now() - started,
+    };
+  }
+
+  private renderInWorker(score: TrackScore): Promise<LoopRender> {
+    const worker = this.ensureWorker();
+    const id = this.nextId;
+    this.nextId += 1;
+    return new Promise<LoopRender>((resolve, reject) => {
+      this.pending.set(id, { resolve, reject });
+      const request: RenderRequest = {
+        id,
+        score: score.toJSON(),
+        sampleRate: this.sampleRate,
+        ...(this.projectRoot === undefined
+          ? {}
+          : { projectRoot: this.projectRoot }),
+      };
+      try {
+        worker.postMessage(request);
+      } catch (error) {
+        this.failWorker(
+          new WorkerLostError(
+            error instanceof Error ? error.message : String(error),
+          ),
+        );
+      }
+    });
+  }
+
+  private ensureWorker(): Bun.Worker {
+    if (this.worker) return this.worker;
+    let worker: Bun.Worker;
+    try {
+      // The DOM lib's Worker type lacks Bun's `unref`; the runtime object is Bun's.
+      worker = new Worker(
+        new URL("./render-worker.ts", import.meta.url).href,
+      ) as unknown as Bun.Worker;
+    } catch (error) {
+      throw new WorkerLostError(
+        error instanceof Error ? error.message : String(error),
+      );
+    }
+    worker.addEventListener("message", (event: Event) => {
+      const reply = (event as MessageEvent<RenderReply>).data;
+      const waiter = this.pending.get(reply.id);
+      if (!waiter) return;
+      this.pending.delete(reply.id);
+      if (reply.ok)
+        waiter.resolve({
+          pcm: reply.pcm,
+          frames: reply.frames,
+          sampleRate: reply.sampleRate,
+          renderMs: reply.renderMs,
+        });
+      else waiter.reject(new Error(reply.error));
+    });
+    worker.addEventListener("error", (event: Event) => {
+      const message = (event as Partial<ErrorEvent>).message;
+      this.failWorker(
+        new WorkerLostError(
+          typeof message === "string" ? message : "worker error",
+        ),
+      );
+    });
+    // A render worker never keeps the process alive on its own.
+    worker.unref();
+    this.worker = worker;
+    return worker;
+  }
+
+  private failWorker(error: WorkerLostError): void {
+    this.workerBroken = true;
+    const worker = this.worker;
+    this.worker = undefined;
+    worker?.terminate();
+    const waiters = [...this.pending.values()];
+    this.pending.clear();
+    for (const waiter of waiters) waiter.reject(error);
+  }
+}
+
+class WorkerLostError extends Error {}