@hraness/dawg 0.0.0-stage → 0.3.0

package/src/media/cli.ts

@@ -0,0 +1,173 @@
+/**
+ * `dawg media <verb>`: the same six tools from the shell, plus `doctor`.
+ *
+ *   dawg media doctor
+ *   dawg media download <youtube-url> [--name <slug>] [--track <name>]
+ *   dawg media stems <file>
+ *   dawg media analyze <file>
+ *   dawg media notes <file> [--kind drums|bass|vocals|guitar|piano|other] [--from s] [--to s]
+ *   dawg media sample <file> <name> [--begin 0..1] [--end 0..1] [--root C4]
+ *   dawg media lyrics <file> [--lang en]
+ *
+ * Progress goes to stderr, the JSON result to stdout. Ctrl-C sends SIGTERM to
+ * the helper (SIGKILL after 15 s) and exits 130.
+ */
+import { systemRunner, type CommandRunner } from "../auth/runner.ts";
+import { doctor, formatDoctor } from "./backend.ts";
+import { trackSlug } from "./paths.ts";
+import { MediaAbortError } from "./process.ts";
+import { findMediaTool } from "./registry.ts";
+import type { MediaHost, MediaResult } from "./types.ts";
+import { errorMessage } from "./vendor/util.ts";
+
+export type Output = { write(text: string): unknown };
+
+export const MEDIA_HELP = `dawg media — local media tools (see DAWG.md "Media tools")
+
+  dawg media doctor                      backend + binaries + install commands
+  dawg media download <url> [--name n]   YouTube audio → tracks/<slug>/downloads/<n>.wav
+  dawg media stems <file>                six stems → <file>.stems/
+  dawg media analyze <file>              tempo, key, beat grid, peaks → <file>.analysis.json
+  dawg media notes <file> [--kind k] [--from s] [--to s]
+                                         notes/hits + quantized snippet → <file>.<kind>.notes.json
+  dawg media sample <file> <name> [--begin f] [--end f] [--root C4]
+                                         48 kHz wav → tracks/<slug>/samples/<name>.wav + sampler snippet
+  dawg media lyrics <file> [--lang en]   whisper transcript → <file>.lyrics.json/.txt
+
+Options: --track <name> picks the track folder (default main); --json prints only the result.
+Env: DAWG_STEMDECK_URL (default http://127.0.0.1:8000).`;
+
+const VERBS: Record<string, { tool: string; positional: string[] }> = {
+  download: { tool: "download_audio", positional: ["url"] },
+  stems: { tool: "split_stems", positional: ["file"] },
+  analyze: { tool: "analyze_audio", positional: ["file"] },
+  notes: { tool: "transcribe_notes", positional: ["file"] },
+  sample: { tool: "import_sample", positional: ["file", "name"] },
+  lyrics: { tool: "transcribe_lyrics", positional: ["file"] },
+};
+
+const NUMERIC = new Set(["from", "to", "begin", "end"]);
+
+export function parseMediaArgv(argv: readonly string[]): {
+  verb: string | undefined;
+  args: Record<string, unknown>;
+  track: string;
+  json: boolean;
+  help: boolean;
+} {
+  const [verb, ...rest] = argv;
+  const args: Record<string, unknown> = {};
+  const positional: string[] = [];
+  let track = "main";
+  let json = false;
+  let help = false;
+  for (let index = 0; index < rest.length; index += 1) {
+    const item = rest[index]!;
+    if (item === "--help" || item === "-h") help = true;
+    else if (item === "--json") json = true;
+    else if (item.startsWith("--")) {
+      const key = item.slice(2);
+      const value = rest[index + 1];
+      if (value === undefined) throw new Error(`--${key} needs a value`);
+      index += 1;
+      if (key === "track") track = value;
+      else if (NUMERIC.has(key)) {
+        const parsed = Number(value);
+        if (!Number.isFinite(parsed))
+          throw new Error(`--${key} must be a number`);
+        args[key] = parsed;
+      } else args[key] = value;
+    } else positional.push(item);
+  }
+  const spec = verb ? VERBS[verb] : undefined;
+  if (spec) {
+    spec.positional.forEach((name, index) => {
+      if (positional[index] !== undefined) args[name] = positional[index];
+    });
+    if (positional.length > spec.positional.length)
+      throw new Error(
+        `unexpected argument ${positional[spec.positional.length]}`,
+      );
+  }
+  return { verb, args, track, json, help };
+}
+
+export async function runMediaCommand(
+  argv: readonly string[],
+  cwd: string,
+  stdout: Output,
+  stderr: Output,
+  options: {
+    runner?: CommandRunner;
+    fetch?: typeof fetch;
+    signal?: AbortSignal;
+  } = {},
+): Promise<number> {
+  let parsed: ReturnType<typeof parseMediaArgv>;
+  try {
+    parsed = parseMediaArgv(argv.slice(1));
+  } catch (error) {
+    stderr.write(`${errorMessage(error)}\n${MEDIA_HELP}\n`);
+    return 2;
+  }
+  if (parsed.help || parsed.verb === undefined) {
+    stdout.write(`${MEDIA_HELP}\n`);
+    return parsed.verb === undefined && !parsed.help ? 2 : 0;
+  }
+  const host: MediaHost = {
+    projectRoot: cwd,
+    trackSlug: trackSlug(parsed.track),
+    runner: options.runner ?? systemRunner,
+    ...(options.fetch ? { fetch: options.fetch } : {}),
+    env: process.env,
+  };
+  if (parsed.verb === "doctor") {
+    const report = await doctor({
+      ...host,
+      ...(options.signal ? { signal: options.signal } : {}),
+    });
+    if (parsed.json) stdout.write(`${JSON.stringify(report, null, 2)}\n`);
+    else stdout.write(`${formatDoctor(report).join("\n")}\n`);
+    return 0;
+  }
+  const spec = VERBS[parsed.verb];
+  const tool = spec ? findMediaTool(spec.tool) : undefined;
+  if (!spec || !tool) {
+    stderr.write(`unknown media command ${parsed.verb}\n${MEDIA_HELP}\n`);
+    return 2;
+  }
+  const controller = new AbortController();
+  const onInterrupt = () => controller.abort(new MediaAbortError());
+  process.once("SIGINT", onInterrupt);
+  process.once("SIGTERM", onInterrupt);
+  const signal = options.signal
+    ? AbortSignal.any([options.signal, controller.signal])
+    : controller.signal;
+  try {
+    const plan = tool.plan(parsed.args, undefined as never);
+    if (plan.kind !== "media") throw new Error("not a media tool");
+    let lastLine = "";
+    const result: MediaResult = await plan.run({
+      ...host,
+      signal,
+      progress: (line) => {
+        if (line === lastLine || parsed.json) return;
+        lastLine = line;
+        stderr.write(`· ${line}\n`);
+      },
+    });
+    if (!parsed.json) stderr.write(`✓ ${result.summary}\n`);
+    stdout.write(`${JSON.stringify(result.content, null, 2)}\n`);
+    return 0;
+  } catch (error) {
+    if (signal.aborted || error instanceof MediaAbortError) {
+      stderr.write("cancelled\n");
+      return 130;
+    }
+    stderr.write(`✗ ${errorMessage(error)}\n`);
+    return 1;
+  } finally {
+    process.off("SIGINT", onInterrupt);
+    process.off("SIGTERM", onInterrupt);
+  }
+}

package/src/media/download.ts

@@ -0,0 +1,281 @@
+/**
+ * `download_audio(url, name?)`: YouTube only. With yt-dlp installed the audio
+ * is extracted straight to `tracks/<slug>/downloads/<name>.wav`; without it a
+ * running StemDeck does the download and separation, the stems land in
+ * `<name>.stems/` and ffmpeg (when present) sums them back into `<name>.wav`.
+ * A `<name>.json` sidecar records title, duration, source URL and sha256 so
+ * later tools (and the brief) never fetch the same thing twice.
+ */
+import { readdir, rename, rm } from "node:fs/promises";
+import { join } from "node:path";
+import { detectStemDeck, missingTool } from "./backend.ts";
+import {
+  downloadsDir,
+  ensureDir,
+  exists,
+  formatBytes,
+  formatSeconds,
+  freshPath,
+  projectPath,
+  readJson,
+  sha256File,
+  trackSlug,
+  writeJsonAtomic,
+} from "./paths.ts";
+import {
+  MediaToolError,
+  runHelper,
+  throwIfAborted,
+  withTempDir,
+} from "./process.ts";
+import { readSidecar, sidecarPath, type MediaSidecar } from "./sidecar.ts";
+import {
+  STEM_NAMES,
+  createStemDeck,
+  type StemDeckOptions,
+} from "./stemdeck.ts";
+import {
+  MEDIA_LIMITS,
+  type MediaResult,
+  type MediaRunContext,
+} from "./types.ts";
+import {
+  finiteNumber,
+  isRecord,
+  optionalString,
+  validateYoutubeUrl,
+} from "./vendor/util.ts";
+
+export type { MediaSidecar } from "./sidecar.ts";
+
+export type DownloadArgs = Readonly<{ url: string; name?: string }>;
+
+export type DownloadOptions = Readonly<{
+  stemdeck?: StemDeckOptions;
+  now?: () => Date;
+}>;
+
+function ytdlpProgress(chunk: string): string | undefined {
+  if (/\[ExtractAudio\]/.test(chunk)) return "yt-dlp converting to wav";
+  const match = chunk.match(/\[download\]\s+(\d{1,3}(?:\.\d)?)%/g)?.at(-1);
+  if (!match) return undefined;
+  const percent = Math.min(
+    100,
+    Math.round(parseFloat(match.replace(/.*\]\s+/, ""))),
+  );
+  return `yt-dlp ${percent}%`;
+}
+
+export async function downloadAudio(
+  args: DownloadArgs,
+  context: MediaRunContext,
+  options: DownloadOptions = {},
+): Promise<MediaResult> {
+  const url = validateYoutubeUrl(args.url);
+  const dir = await ensureDir(downloadsDir(context));
+  const now = options.now ?? (() => new Date());
+  // Reuse an earlier download of the same source.
+  for (const name of await readdir(dir)) {
+    if (!name.endsWith(".json")) continue;
+    const wav = join(dir, name.replace(/\.json$/, ".wav"));
+    const sidecar = await readSidecar(wav);
+    if (sidecar?.source === url && (await exists(wav))) {
+      const relativePath = projectPath(context.projectRoot, wav);
+      return {
+        summary: `already downloaded: ${relativePath}`,
+        outputs: [
+          relativePath,
+          projectPath(context.projectRoot, sidecarPath(wav)),
+        ],
+        content: { reused: true, wav: relativePath, ...sidecar },
+      };
+    }
+  }
+  if (context.runner.which("yt-dlp")) {
+    if (!context.runner.which("ffmpeg"))
+      throw new MediaToolError(missingTool("ffmpeg"));
+    return downloadWithYtDlp(url, args.name, dir, context, now);
+  }
+  const health = await detectStemDeck(context);
+  if (!health)
+    throw new MediaToolError(
+      `${missingTool("yt-dlp")}; no StemDeck answered at the configured URL either`,
+    );
+  return downloadWithStemDeck(
+    url,
+    args.name,
+    dir,
+    context,
+    health,
+    options,
+    now,
+  );
+}
+
+async function downloadWithYtDlp(
+  url: string,
+  requestedName: string | undefined,
+  dir: string,
+  context: MediaRunContext,
+  now: () => Date,
+): Promise<MediaResult> {
+  return withTempDir("download", async (temp) => {
+    context.progress("yt-dlp starting");
+    await runHelper(
+      context,
+      [
+        "yt-dlp",
+        "--no-playlist",
+        "--newline",
+        "--no-colors",
+        "--no-progress",
+        "--progress",
+        "--max-filesize",
+        `${Math.floor(MEDIA_LIMITS.downloadMaxBytes / (1024 * 1024))}m`,
+        "--write-info-json",
+        "--no-write-playlist-metafiles",
+        "-x",
+        "--audio-format",
+        "wav",
+        "-o",
+        join(temp, "audio.%(ext)s"),
+        "--",
+        url,
+      ],
+      { timeoutMs: MEDIA_LIMITS.downloadTimeoutMs, progress: ytdlpProgress },
+    );
+    throwIfAborted(context.signal);
+    const wavTemp = join(temp, "audio.wav");
+    if (!(await exists(wavTemp)))
+      throw new MediaToolError(
+        "yt-dlp finished without producing audio.wav (over the 500 MiB cap, or no audio stream)",
+      );
+    const size = Bun.file(wavTemp).size;
+    if (size > MEDIA_LIMITS.downloadMaxBytes)
+      throw new MediaToolError(
+        `downloaded audio is ${formatBytes(size)}, over the 500 MiB cap`,
+      );
+    const info = await readJson(join(temp, "audio.info.json"));
+    const title =
+      (isRecord(info) ? optionalString(info.title, 200) : undefined) ??
+      "download";
+    const duration = isRecord(info) ? finiteNumber(info.duration) : undefined;
+    const base = trackSlug(requestedName ?? title);
+    const { path: wav, base: finalBase } = await freshPath(dir, base, ".wav");
+    await rename(wavTemp, wav).catch(async () => {
+      // Temp dir may sit on another volume.
+      await Bun.write(wav, Bun.file(wavTemp));
+      await rm(wavTemp, { force: true });
+    });
+    const sha256 = await sha256File(wav);
+    const sidecar: MediaSidecar = {
+      title,
+      ...(duration !== undefined ? { durationSeconds: duration } : {}),
+      source: url,
+      sha256,
+      bytes: size,
+      backend: "yt-dlp",
+      downloadedAt: now().toISOString(),
+    };
+    await writeJsonAtomic(sidecarPath(wav), sidecar);
+    const relativePath = projectPath(context.projectRoot, wav);
+    return {
+      summary: `downloaded ${finalBase}.wav (${duration !== undefined ? formatSeconds(duration) : formatBytes(size)})`,
+      outputs: [
+        relativePath,
+        projectPath(context.projectRoot, sidecarPath(wav)),
+      ],
+      content: { wav: relativePath, ...sidecar },
+    };
+  });
+}
+
+async function downloadWithStemDeck(
+  url: string,
+  requestedName: string | undefined,
+  dir: string,
+  context: MediaRunContext,
+  health: NonNullable<Awaited<ReturnType<typeof detectStemDeck>>>,
+  options: DownloadOptions,
+  now: () => Date,
+): Promise<MediaResult> {
+  const client = createStemDeck(health, context, options.stemdeck);
+  context.progress("stemdeck submitting");
+  const jobId = await client.submit(url);
+  const job = await client.wait(jobId, MEDIA_LIMITS.downloadTimeoutMs);
+  if (job.stems.length === 0)
+    throw new MediaToolError("StemDeck finished the job but offered no stems");
+  const base = trackSlug(requestedName ?? job.title ?? "download");
+  const { path: wav, base: finalBase } = await freshPath(dir, base, ".wav");
+  const stemsDir = await ensureDir(join(dir, `${finalBase}.stems`));
+  const stemPaths = await client.fetchStems(
+    job,
+    stemsDir,
+    MEDIA_LIMITS.downloadMaxBytes,
+  );
+  const outputs = stemPaths.map((path) =>
+    projectPath(context.projectRoot, path),
+  );
+  let mixed = false;
+  if (context.runner.which("ffmpeg")) {
+    context.progress("ffmpeg mixing stems");
+    const inputs = stemPaths.flatMap((path) => ["-i", path]);
+    await runHelper(
+      context,
+      [
+        "ffmpeg",
+        "-hide_banner",
+        "-nostdin",
+        "-loglevel",
+        "error",
+        "-y",
+        ...inputs,
+        "-filter_complex",
+        `amix=inputs=${stemPaths.length}:normalize=0`,
+        "-c:a",
+        "pcm_s16le",
+        wav,
+      ],
+      { timeoutMs: MEDIA_LIMITS.sampleTimeoutMs },
+    );
+    mixed = true;
+  }
+  const sidecar: MediaSidecar = {
+    title: job.title ?? finalBase,
+    ...(job.durationSeconds !== undefined
+      ? { durationSeconds: job.durationSeconds }
+      : {}),
+    source: url,
+    ...(mixed
+      ? { sha256: await sha256File(wav), bytes: Bun.file(wav).size }
+      : {}),
+    backend: "stemdeck",
+    downloadedAt: now().toISOString(),
+    stemdeck: { url: health.url, jobId },
+    ...(job.bpm !== undefined ? { bpm: job.bpm } : {}),
+    ...(job.key ? { key: job.key } : {}),
+  };
+  await writeJsonAtomic(sidecarPath(wav), sidecar);
+  const relativeWav = projectPath(context.projectRoot, wav);
+  return {
+    summary: `stemdeck downloaded ${finalBase} (${job.stems.length} stems${mixed ? " + mix" : ""})`,
+    outputs: [
+      ...(mixed ? [relativeWav] : []),
+      projectPath(context.projectRoot, sidecarPath(wav)),
+      ...outputs,
+    ],
+    content: {
+      ...(mixed
+        ? { wav: relativeWav }
+        : {
+            wav: null,
+            note: "ffmpeg is not installed, so no mixed wav was written; the stems are complete",
+          }),
+      stems: Object.fromEntries(
+        job.stems.map((stem, index) => [stem.name, outputs[index]]),
+      ),
+      expectedStems: STEM_NAMES,
+      ...sidecar,
+    },
+  };
+}