@hraness/dawg 0.0.0-stage → 0.3.0

package/src/media/process.ts

@@ -0,0 +1,226 @@
+/**
+ * Helpers shared by the media tools: bounded helper processes with progress
+ * taps, bounded HTTP downloads, temp directories, and cancellation.
+ */
+import { mkdtemp, rm } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import type { RunResult } from "../auth/runner.ts";
+import { MEDIA_LIMITS, type MediaRunContext } from "./types.ts";
+import { terminalSafeText } from "./vendor/util.ts";
+
+export class MediaToolError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = "MediaToolError";
+  }
+}
+
+export class MediaAbortError extends Error {
+  constructor() {
+    super("cancelled");
+    this.name = "MediaAbortError";
+  }
+}
+
+export function throwIfAborted(signal: AbortSignal): void {
+  if (signal.aborted) throw new MediaAbortError();
+}
+
+/** Deadline-bounded signal for one tool run. */
+export function budgetSignal(
+  context: MediaRunContext,
+  timeoutMs: number,
+): AbortSignal {
+  return AbortSignal.any([context.signal, AbortSignal.timeout(timeoutMs)]);
+}
+
+export type HelperOptions = Readonly<{
+  timeoutMs: number;
+  /** Parse one stderr/stdout chunk into a progress line, or undefined. */
+  progress?: (chunk: string) => string | undefined;
+  /** Progress lines closer than this are dropped (default 400 ms). */
+  minIntervalMs?: number;
+  cwd?: string;
+  env?: Readonly<Record<string, string | undefined>>;
+}>;
+
+/**
+ * Run one helper binary with the tool budget, SIGTERM→SIGKILL on abort, bounded
+ * output and throttled progress lines. Throws `MediaToolError` on non-zero exit.
+ */
+export async function runHelper(
+  context: MediaRunContext,
+  argv: readonly string[],
+  options: HelperOptions,
+): Promise<RunResult> {
+  throwIfAborted(context.signal);
+  const [command, ...args] = argv;
+  if (!command) throw new MediaToolError("empty command");
+  let last = 0;
+  let lastLine = "";
+  const result = await context.runner.run(command, args, {
+    timeoutMs: options.timeoutMs,
+    signal: context.signal,
+    maxOutputBytes: MEDIA_LIMITS.maxToolOutputBytes,
+    ...(options.env ? { env: options.env } : {}),
+    ...(options.progress
+      ? {
+          onOutput: (_stream, chunk) => {
+            const line = options.progress!(chunk);
+            if (line === undefined || line === lastLine) return;
+            const now = Date.now();
+            if (now - last < (options.minIntervalMs ?? 400)) return;
+            last = now;
+            lastLine = line;
+            context.progress(line);
+          },
+        }
+      : {}),
+  });
+  if (context.signal.aborted) throw new MediaAbortError();
+  if (result.killed)
+    throw new MediaToolError(
+      `${command} exceeded its ${Math.round(options.timeoutMs / 60_000)} min budget and was stopped`,
+    );
+  if (result.code !== 0) {
+    const detail =
+      lastMeaningfulLine(result.stderr) ?? lastMeaningfulLine(result.stdout);
+    throw new MediaToolError(
+      `${command} failed (exit ${result.code})${detail ? `: ${detail}` : ""}`,
+    );
+  }
+  return result;
+}
+
+export function lastMeaningfulLine(text: string): string | undefined {
+  const lines = text
+    .split(/\r?\n|\r/)
+    .map((line) => line.trim())
+    .filter((line) => line.length > 0);
+  const line = lines.at(-1);
+  return line === undefined ? undefined : terminalSafeText(line, 300, "");
+}
+
+/** `42%` from tqdm-style output (`demucs`, `yt-dlp --newline`). */
+export function percentProgress(label: string) {
+  return (chunk: string): string | undefined => {
+    const matches = chunk.match(/(\d{1,3}(?:\.\d)?)%/g);
+    const lastMatch = matches?.at(-1);
+    if (!lastMatch) return undefined;
+    const value = Math.min(100, Math.round(parseFloat(lastMatch)));
+    return `${label} ${value}%`;
+  };
+}
+
+export async function withTempDir<T>(
+  prefix: string,
+  work: (dir: string) => Promise<T>,
+): Promise<T> {
+  const dir = await mkdtemp(join(tmpdir(), `dawg-${prefix}-`));
+  try {
+    return await work(dir);
+  } finally {
+    await rm(dir, { recursive: true, force: true }).catch(() => undefined);
+  }
+}
+
+export type FetchLike = typeof fetch;
+
+/** Read a JSON body no larger than `maxBytes`. */
+export async function fetchJson(
+  fetcher: FetchLike,
+  url: string,
+  init: RequestInit & { maxBytes?: number },
+): Promise<unknown> {
+  const response = await fetcher(url, init);
+  const text = await readBoundedText(response, init.maxBytes ?? 1024 * 1024);
+  if (!response.ok)
+    throw new MediaToolError(
+      `${new URL(url).pathname} answered ${response.status}${text ? `: ${terminalSafeText(text, 200, "")}` : ""}`,
+    );
+  try {
+    return JSON.parse(text) as unknown;
+  } catch {
+    throw new MediaToolError(`${new URL(url).pathname} did not return JSON`);
+  }
+}
+
+async function readBoundedText(response: Response, maxBytes: number) {
+  if (!response.body) return "";
+  const reader = response.body.getReader();
+  const chunks: Uint8Array[] = [];
+  let total = 0;
+  for (;;) {
+    const { done, value } = await reader.read();
+    if (done) break;
+    total += value.byteLength;
+    if (total > maxBytes) {
+      await reader.cancel().catch(() => undefined);
+      throw new MediaToolError(`response exceeded ${maxBytes} bytes`);
+    }
+    chunks.push(value);
+  }
+  return new TextDecoder().decode(Buffer.concat(chunks));
+}
+
+/** Stream a response body to `path` (via `.part`), capped at `maxBytes`. */
+export async function downloadToFile(
+  fetcher: FetchLike,
+  url: string,
+  path: string,
+  options: Readonly<{
+    maxBytes: number;
+    signal: AbortSignal;
+    progress?: (receivedBytes: number, totalBytes: number | undefined) => void;
+  }>,
+): Promise<number> {
+  const response = await fetcher(url, { signal: options.signal });
+  if (!response.ok || !response.body)
+    throw new MediaToolError(
+      `download of ${new URL(url).pathname} answered ${response.status}`,
+    );
+  const declared = Number(response.headers.get("content-length") ?? "");
+  const total =
+    Number.isFinite(declared) && declared > 0 ? declared : undefined;
+  if (total !== undefined && total > options.maxBytes)
+    throw new MediaToolError(
+      `${new URL(url).pathname} is ${total} bytes, over the ${options.maxBytes}-byte cap`,
+    );
+  const part = `${path}.part`;
+  const writer = Bun.file(part).writer();
+  const reader = response.body.getReader();
+  let received = 0;
+  let lastReport = 0;
+  try {
+    for (;;) {
+      const { done, value } = await reader.read();
+      if (done) break;
+      received += value.byteLength;
+      if (received > options.maxBytes) {
+        await reader.cancel().catch(() => undefined);
+        throw new MediaToolError(
+          `download exceeded the ${options.maxBytes}-byte cap`,
+        );
+      }
+      writer.write(value);
+      const now = Date.now();
+      if (options.progress && now - lastReport > 500) {
+        lastReport = now;
+        options.progress(received, total);
+      }
+    }
+    await writer.end();
+    const { rename } = await import("node:fs/promises");
+    await rename(part, path);
+    return received;
+  } catch (error) {
+    try {
+      await writer.end();
+    } catch {
+      // already closed
+    }
+    await rm(part, { force: true }).catch(() => undefined);
+    throw error;
+  }
+}

package/src/media/registry.ts

@@ -0,0 +1,9 @@
+/** Lookup over `MEDIA_TOOLS` shared by the CLI and tests. */
+import type { AgentTool } from "../agent/tools.ts";
+import { MEDIA_TOOLS } from "./tools.ts";
+
+export function findMediaTool(name: string): AgentTool | undefined {
+  return MEDIA_TOOLS.find((tool) => tool.name === name);
+}
+
+export { MEDIA_TOOLS };

package/src/media/sidecar.ts

@@ -0,0 +1,72 @@
+/**
+ * `<name>.json` next to a downloaded wav: title, duration, source URL, hash,
+ * which backend fetched it and, for StemDeck downloads, the job id that later
+ * tools reuse for stems and beat grids.
+ */
+import { readJson, writeJsonAtomic } from "./paths.ts";
+import { finiteNumber, isRecord, optionalString } from "./vendor/util.ts";
+
+export type MediaSidecar = Readonly<{
+  title: string;
+  durationSeconds?: number;
+  source: string;
+  sha256?: string;
+  bytes?: number;
+  backend: "yt-dlp" | "stemdeck";
+  downloadedAt: string;
+  stemdeck?: Readonly<{ url: string; jobId: string }>;
+  bpm?: number;
+  key?: string;
+}>;
+
+export function sidecarPath(wavPath: string): string {
+  return wavPath.replace(/\.wav$/i, "") + ".json";
+}
+
+export async function readSidecar(
+  wavPath: string,
+): Promise<MediaSidecar | undefined> {
+  const value = await readJson(sidecarPath(wavPath));
+  if (!isRecord(value)) return undefined;
+  const title = optionalString(value.title, 200);
+  const source = optionalString(value.source, 2048);
+  const backend = value.backend;
+  if (!title || !source || (backend !== "yt-dlp" && backend !== "stemdeck"))
+    return undefined;
+  const stemdeck = isRecord(value.stemdeck)
+    ? {
+        url: optionalString(value.stemdeck.url, 2048),
+        jobId: optionalString(value.stemdeck.jobId, 80),
+      }
+    : undefined;
+  const duration = finiteNumber(value.durationSeconds);
+  const bpm = finiteNumber(value.bpm);
+  const key = optionalString(value.key, 20);
+  const sha256 = optionalString(value.sha256, 64);
+  const bytes = finiteNumber(value.bytes);
+  return {
+    title,
+    source,
+    backend,
+    downloadedAt: optionalString(value.downloadedAt, 40) ?? "",
+    ...(duration !== undefined ? { durationSeconds: duration } : {}),
+    ...(sha256 ? { sha256 } : {}),
+    ...(bytes !== undefined ? { bytes } : {}),
+    ...(stemdeck?.url && stemdeck.jobId
+      ? { stemdeck: { url: stemdeck.url, jobId: stemdeck.jobId } }
+      : {}),
+    ...(bpm !== undefined ? { bpm } : {}),
+    ...(key ? { key } : {}),
+  };
+}
+
+/** Merge one field into an existing sidecar (no-op when there is none). */
+export async function writeSidecarField(
+  wavPath: string,
+  field: string,
+  value: unknown,
+): Promise<void> {
+  const current = await readJson(sidecarPath(wavPath));
+  if (!isRecord(current)) return;
+  await writeJsonAtomic(sidecarPath(wavPath), { ...current, [field]: value });
+}

package/src/media/stemdeck.ts

@@ -0,0 +1,254 @@
+/**
+ * Minimal StemDeck client (the local separation service soundfish also talks
+ * to): submit a YouTube URL, poll the job, fetch its beat grid and stems. All
+ * bodies are validated from `unknown`, stem URLs must be same-origin
+ * `/api/jobs/<id>/stems/<name>.wav`, and every read is size-capped.
+ */
+import { join } from "node:path";
+import type { BeatGrid, MediaRunContext } from "./types.ts";
+import type { StemDeckHealth } from "./backend.ts";
+import {
+  MediaAbortError,
+  MediaToolError,
+  downloadToFile,
+  fetchJson,
+  throwIfAborted,
+} from "./process.ts";
+import { parseBeatGrid } from "./vendor/grid.ts";
+import { finiteNumber, isRecord, optionalString } from "./vendor/util.ts";
+
+export const STEM_NAMES = [
+  "vocals",
+  "drums",
+  "bass",
+  "guitar",
+  "piano",
+  "other",
+] as const;
+export type StemName = (typeof STEM_NAMES)[number];
+
+const JOB_ID_PATTERN = /^[A-Za-z0-9_-]{1,80}$/;
+const TERMINAL = new Set(["done", "error", "cancelled", "unavailable"]);
+const STAGES = new Set([
+  "queued",
+  "downloading",
+  "analyzing",
+  "separating",
+  "processing",
+]);
+
+export type StemDeckJob = Readonly<{
+  jobId: string;
+  title?: string;
+  durationSeconds?: number;
+  bpm?: number;
+  key?: string;
+  stems: readonly Readonly<{ name: StemName; url: string }>[];
+}>;
+
+export type StemDeckOptions = Readonly<{
+  /** Poll spacing; tests pass 0. */
+  pollIntervalMs?: number;
+  sleep?: (ms: number, signal: AbortSignal) => Promise<void>;
+}>;
+
+function defaultSleep(ms: number, signal: AbortSignal): Promise<void> {
+  return new Promise((resolve, reject) => {
+    if (signal.aborted) return reject(new MediaAbortError());
+    const timer = setTimeout(() => {
+      signal.removeEventListener("abort", onAbort);
+      resolve();
+    }, ms);
+    const onAbort = () => {
+      clearTimeout(timer);
+      reject(new MediaAbortError());
+    };
+    signal.addEventListener("abort", onAbort, { once: true });
+  });
+}
+
+export function createStemDeck(
+  health: StemDeckHealth,
+  context: MediaRunContext,
+  options: StemDeckOptions = {},
+) {
+  const base = new URL(health.url);
+  // `URL` keeps "/" for an empty path; drop it so paths join without "//".
+  const basePath = base.pathname.replace(/\/+$/u, "");
+  const fetcher = context.fetch ?? fetch;
+  const pollIntervalMs = options.pollIntervalMs ?? 2_000;
+  const sleep = options.sleep ?? defaultSleep;
+  const api = (path: string) => `${base.origin}${basePath}${path}`;
+
+  async function submit(sourceUrl: string): Promise<string> {
+    const body = await fetchJson(fetcher, api("/api/jobs"), {
+      method: "POST",
+      headers: {
+        "content-type": "application/json",
+        accept: "application/json",
+      },
+      body: JSON.stringify({ url: sourceUrl, stems: [...STEM_NAMES] }),
+      signal: context.signal,
+      maxBytes: 64 * 1024,
+    });
+    const jobId = isRecord(body) ? optionalString(body.job_id, 80) : undefined;
+    if (!jobId || !JOB_ID_PATTERN.test(jobId))
+      throw new MediaToolError("StemDeck did not return a job id");
+    return jobId;
+  }
+
+  async function cancel(jobId: string): Promise<void> {
+    try {
+      await fetcher(api(`/api/jobs/${jobId}/cancel`), {
+        method: "POST",
+        signal: AbortSignal.timeout(2_000),
+      });
+    } catch {
+      // Best effort; the job times out on its own.
+    }
+  }
+
+  function parseJob(jobId: string, body: unknown): StemDeckJob {
+    if (!isRecord(body))
+      throw new MediaToolError("StemDeck job body was not an object");
+    const stems = Array.isArray(body.stems)
+      ? body.stems.slice(0, 16).flatMap((entry) => {
+          if (!isRecord(entry)) return [];
+          const name = optionalString(entry.name, 20);
+          const url = optionalString(entry.url, 512);
+          if (
+            !name ||
+            !url ||
+            !(STEM_NAMES as readonly string[]).includes(name)
+          )
+            return [];
+          const expected = `${basePath}/api/jobs/${jobId}/stems/${name}.wav`;
+          let resolved: URL;
+          try {
+            resolved = new URL(url, base.origin);
+          } catch {
+            return [];
+          }
+          if (resolved.origin !== base.origin || resolved.pathname !== expected)
+            return [];
+          return [{ name: name as StemName, url: resolved.toString() }];
+        })
+      : [];
+    const title = optionalString(body.title, 200);
+    const duration = finiteNumber(body.duration);
+    const bpm = finiteNumber(body.bpm);
+    const key = optionalString(body.key, 20);
+    return {
+      jobId,
+      ...(title ? { title } : {}),
+      ...(duration !== undefined && duration > 0
+        ? { durationSeconds: duration }
+        : {}),
+      ...(bpm !== undefined && bpm > 0 ? { bpm } : {}),
+      ...(key ? { key } : {}),
+      stems,
+    };
+  }
+
+  /** Poll until the job ends; progress lines read `stemdeck separating 42%`. */
+  async function wait(jobId: string, timeoutMs: number): Promise<StemDeckJob> {
+    const deadline = Date.now() + timeoutMs;
+    let lastLine = "";
+    for (;;) {
+      throwIfAborted(context.signal);
+      if (Date.now() > deadline) {
+        await cancel(jobId);
+        throw new MediaToolError(
+          `StemDeck job ${jobId} exceeded its ${Math.round(timeoutMs / 60_000)} min budget`,
+        );
+      }
+      let body: unknown;
+      try {
+        body = await fetchJson(fetcher, api(`/api/jobs/${jobId}`), {
+          signal: context.signal,
+          maxBytes: 256 * 1024,
+        });
+      } catch (error) {
+        if (context.signal.aborted) {
+          await cancel(jobId);
+          throw new MediaAbortError();
+        }
+        throw error;
+      }
+      const status = isRecord(body)
+        ? optionalString(body.status, 20)
+        : undefined;
+      if (status === "done") return parseJob(jobId, body);
+      if (status !== undefined && TERMINAL.has(status)) {
+        const detail = isRecord(body)
+          ? optionalString(body.error, 200)
+          : undefined;
+        throw new MediaToolError(
+          `StemDeck job ${status}${detail ? `: ${detail}` : ""}`,
+        );
+      }
+      const stage =
+        status !== undefined && STAGES.has(status)
+          ? status
+          : ((isRecord(body) ? optionalString(body.stage, 20) : undefined) ??
+            "working");
+      const progress = isRecord(body) ? finiteNumber(body.progress) : undefined;
+      const line =
+        progress === undefined
+          ? `stemdeck ${stage}`
+          : `stemdeck ${stage} ${Math.round(Math.min(1, Math.max(0, progress)) * 100)}%`;
+      if (line !== lastLine) {
+        lastLine = line;
+        context.progress(line);
+      }
+      try {
+        await sleep(pollIntervalMs, context.signal);
+      } catch (error) {
+        await cancel(jobId);
+        throw error;
+      }
+    }
+  }
+
+  async function beats(jobId: string): Promise<BeatGrid | undefined> {
+    try {
+      const response = await fetcher(api(`/api/jobs/${jobId}/beats`), {
+        signal: context.signal,
+        headers: { accept: "application/json" },
+      });
+      if (!response.ok) return undefined;
+      const bytes = new Uint8Array(await response.arrayBuffer());
+      if (bytes.byteLength > 4 * 1024 * 1024) return undefined;
+      return parseBeatGrid(bytes);
+    } catch (error) {
+      if (context.signal.aborted) throw new MediaAbortError();
+      return undefined;
+    }
+  }
+
+  /** Download every stem into `dir` as `<name>.wav`. */
+  async function fetchStems(
+    job: StemDeckJob,
+    dir: string,
+    maxBytesPerStem: number,
+  ): Promise<readonly string[]> {
+    const written: string[] = [];
+    for (const [index, stem] of job.stems.entries()) {
+      throwIfAborted(context.signal);
+      context.progress(
+        `stemdeck fetching ${stem.name} (${index + 1}/${job.stems.length})`,
+      );
+      const path = join(dir, `${stem.name}.wav`);
+      await downloadToFile(fetcher, stem.url, path, {
+        maxBytes: maxBytesPerStem,
+        signal: context.signal,
+      });
+      written.push(path);
+    }
+    return written;
+  }
+
+  return { health, submit, wait, beats, fetchStems, cancel };
+}
+
+export type StemDeckClient = ReturnType<typeof createStemDeck>;