@mevdragon/vidfarm-devcli 0.13.0 → 0.15.0

package/.agents/skills/vidfarm-media/scripts/audio.mjs

@@ -0,0 +1,628 @@
+#!/usr/bin/env node
+// audio.mjs — vidfarm-media shared audio ENGINE: TTS + word timings + BGM + SFX.
+// The workflow skills (faceless-explainer, product-launch-video) call this via
+// thin adapters; general-video calls it directly. Everything resolves on the
+// user's own machine or the user's own provider keys — no third-party media
+// account, ever. The keyless local path (Kokoro TTS + whisper.cpp timings)
+// must always work with zero keys.
+//
+// USAGE
+//   node audio.mjs --request ./audio_request.json --hyperframes . --out ./audio_meta.json \
+//                  [--only tts,bgm,sfx] [--no-transcribe]
+//
+//   --request       neutral request JSON (schema below). Required.
+//   --hyperframes   project dir; all output paths in the meta are RELATIVE to it. Default ".".
+//   --only          comma list of sections to (re)compute: tts, bgm, sfx. Default: all.
+//                   Sections NOT listed are PRESERVED from an existing --out meta —
+//                   `--only sfx` after `--only tts,bgm` merges, never overwrites.
+//   --no-transcribe skip whisper word timings; estimate words instead (also $VF_MEDIA_NO_TRANSCRIBE=1).
+//   --out           meta JSON path. Default <hyperframes>/audio_meta.json.
+//
+// audio_request.json
+//   {
+//     "provider": "auto" | "local" | "openai" | "gemini" | "openrouter",  // default auto (= local Kokoro)
+//     "voice":    "af_heart" | "alloy" | "Kore" | ...,  // Kokoro voice id, or a cloud preset
+//     "style":    "calm, warm narrator",                 // cloud only — promptable voice direction
+//     "speed":    1.0,                                    // Kokoro only
+//     "lines":  [ { "id": "01", "text": "Spoken line.", "sfx": ["whoosh"] } ],
+//     "bgm": {
+//       "mode":   "retrieve" | "none",       // omitted = retrieve; there is NO generate mode
+//       "query":  "calm cinematic underscore",
+//       "file":   "./music/track.mp3",       // explicit local file wins
+//       "url":    "https://.../track.mp3",   // ...or an explicit URL
+//       "dir":    "./music",                 // ...or a local music dir (also $MUSIC_DIR)
+//       "volume": 0.8                         // optional; omitted = assembler default
+//     },
+//     "sfx_dir": "./sfx"                      // optional local SFX dir (also $SFX_DIR)
+//   }
+//   `id` is opaque and joins the meta back to the caller's model. Lines may carry
+//   only `sfx` (no text) — that is how adapters fetch SFX after narration exists.
+//
+// Output meta (--out), id-keyed:
+//   {
+//     "voices": [ { "id": "01", "path": "assets/voice/01.wav", "duration_s": 4.21,
+//                   "words": [ { "id": "w0", "text": "Spoken", "start": 0.02, "end": 0.31 } ] } ],
+//     "bgm":    { "path": "assets/bgm/track.mp3", "query": "...", "duration_s": 22.4 } | null,
+//     "sfx":    [ { "id": "01", "file": "assets/sfx/whoosh.mp3", "offset_s": 0,
+//                   "duration_s": 0.9, "volume": 0.35 } ],
+//     "notes":  [ "bgm: skipped — ..." ]
+//   }
+//   BGM is NOT loop-extended here: assemble-index loop-extends short beds at
+//   mount time. `bgm_pending` is never set — there is no detached generate step.
+//
+// ENGINES
+//   TTS      keyless local Kokoro-82M via `hyperframes tts` (DEFAULT — zero keys).
+//            Cloud `vidfarm tts` (promptable voice, BYOK) only when the request
+//            names a cloud voice/provider AND a provider key is in the env AND
+//            the vidfarm CLI is on PATH; falls back to Kokoro with a note.
+//   Timings  `hyperframes transcribe` (local whisper.cpp, word timestamps);
+//            on any failure, words are estimated by proportional character
+//            weighting across the line's duration. Never fatal.
+//   BGM      request file/url → My Files (`vidfarm files --search`, needs
+//            $VIDFARM_API_KEY) → local music dir keyword match → skip w/ note.
+//   SFX      local sfx dir ($SFX_DIR / request sfx_dir / skill assets/sfx) →
+//            My Files search → skip that cue w/ note.
+
+import { spawnSync } from "node:child_process";
+import {
+  copyFileSync, existsSync, mkdirSync, mkdtempSync, readFileSync, readdirSync,
+  statSync, writeFileSync
+} from "node:fs";
+import { createRequire } from "node:module";
+import { tmpdir } from "node:os";
+import { basename, dirname, extname, isAbsolute, join, relative, resolve } from "node:path";
+import { fileURLToPath, pathToFileURL } from "node:url";
+
+const HERE = dirname(fileURLToPath(import.meta.url));
+const SKILL_DIR = dirname(HERE);
+const AUDIO_EXT = new Set([".mp3", ".wav", ".m4a", ".aac", ".ogg", ".flac"]);
+const r3 = (n) => Math.round(n * 1000) / 1000;
+
+// Known cloud voice presets (mirrors vidfarm's speech service). A voice from
+// one of these families signals intent to use the BYOK cloud path.
+const OPENAI_VOICES = new Set([
+  "alloy", "ash", "ballad", "cedar", "coral", "echo", "fable", "marin",
+  "nova", "onyx", "sage", "shimmer", "verse"
+]);
+const GEMINI_VOICES = new Set([
+  "achernar", "achird", "algenib", "algieba", "alnilam", "aoede", "autonoe",
+  "callirrhoe", "charon", "despina", "enceladus", "erinome", "fenrir", "gacrux",
+  "iapetus", "kore", "laomedeia", "leda", "orus", "puck", "pulcherrima",
+  "rasalgethi", "sadachbia", "sadaltager", "schedar", "sulafat", "umbriel",
+  "vindemiatrix", "zephyr", "zubenelgenubi"
+]);
+const KOKORO_VOICE_RE = /^[a-z]{2}_[a-z0-9]+$/;
+
+// ── tiny CLI plumbing ─────────────────────────────────────────────────────────
+
+const HELP = `vidfarm-media audio engine — TTS + word timings + BGM + SFX, no media accounts.
+
+Usage:
+  node audio.mjs --request <audio_request.json> [--hyperframes <dir>] [--out <meta.json>]
+                 [--only tts,bgm,sfx] [--no-transcribe]
+
+Flags:
+  --request <path>   Neutral request JSON (required). Schema: header comment of this file.
+  --hyperframes <d>  Project dir; meta paths are relative to it (default ".").
+  --out <path>       Output meta JSON (default <hyperframes>/audio_meta.json).
+  --only <list>      Recompute only these sections (tts, bgm, sfx); others are
+                     preserved from an existing --out meta. Default: all three.
+  --no-transcribe    Skip whisper word timings; estimate by character weighting.
+  -h, --help         This text.
+
+Engines: local Kokoro TTS (\`hyperframes tts\`, zero keys, default) · cloud
+\`vidfarm tts\` when a cloud voice/provider is requested and a key exists ·
+whisper.cpp word timings (\`hyperframes transcribe\`) with estimation fallback ·
+BGM/SFX from user files, $MUSIC_DIR/$SFX_DIR, or My Files search ($VIDFARM_API_KEY).`;
+
+const argv = process.argv.slice(2);
+if (argv.includes("--help") || argv.includes("-h")) {
+  console.log(HELP);
+  process.exit(0);
+}
+const flag = (name, def) => {
+  const i = argv.indexOf(`--${name}`);
+  return i >= 0 && i + 1 < argv.length ? argv[i + 1] : def;
+};
+const die = (m) => {
+  console.error(`✗ media audio: ${m}`);
+  process.exit(1);
+};
+
+const requestPath = flag("request", null);
+if (!requestPath) die("--request <audio_request.json> is required (see --help)");
+const hyperframesDir = resolve(flag("hyperframes", "."));
+const outPath = resolve(flag("out", join(hyperframesDir, "audio_meta.json")));
+const only = new Set(
+  (flag("only", "tts,bgm,sfx") || "tts,bgm,sfx").split(",").map((s) => s.trim()).filter(Boolean)
+);
+const noTranscribe = argv.includes("--no-transcribe") || process.env.VF_MEDIA_NO_TRANSCRIBE === "1";
+
+if (!existsSync(requestPath)) die(`request not found at ${requestPath}`);
+let request;
+try {
+  request = JSON.parse(readFileSync(requestPath, "utf8"));
+} catch (e) {
+  die(`request parse: ${e.message}`);
+}
+const lines = Array.isArray(request.lines) ? request.lines : [];
+
+// ── spawn helpers ─────────────────────────────────────────────────────────────
+
+// Env for every hyperframes CLI spawn: telemetry off, skill self-update off,
+// and HEYGEN_CONFIG_DIR pointed at a fresh empty dir so the CLI can never pick
+// up a stray credential and silently prefer a non-local voice path.
+let scrubbedEnvCache = null;
+function scrubbedEnv() {
+  if (!scrubbedEnvCache) {
+    scrubbedEnvCache = {
+      ...process.env,
+      HYPERFRAMES_NO_TELEMETRY: "1",
+      HYPERFRAMES_SKIP_SKILLS: "1",
+      HEYGEN_CONFIG_DIR: mkdtempSync(join(tmpdir(), "vf-media-empty-"))
+    };
+  }
+  return scrubbedEnvCache;
+}
+
+// Prefer a locally installed hyperframes (resolved from this script's dir, then
+// the project dir, then cwd) over `npx -y hyperframes` — faster, offline-safe.
+let hfCliCache = null;
+function hyperframesCli() {
+  if (hfCliCache) return hfCliCache;
+  const bases = [
+    import.meta.url,
+    pathToFileURL(join(hyperframesDir, "__resolve__.js")).href,
+    pathToFileURL(join(process.cwd(), "__resolve__.js")).href
+  ];
+  for (const base of bases) {
+    try {
+      const cliJs = createRequire(base).resolve("hyperframes/dist/cli.js");
+      hfCliCache = { cmd: process.execPath, prefix: [cliJs] };
+      return hfCliCache;
+    } catch { /* keep walking */ }
+  }
+  hfCliCache = { cmd: "npx", prefix: ["-y", "hyperframes"] };
+  return hfCliCache;
+}
+
+function hasCommand(name) {
+  const probe = process.platform === "win32" ? "where" : "which";
+  try {
+    return spawnSync(probe, [name], { stdio: "ignore" }).status === 0;
+  } catch {
+    return false;
+  }
+}
+
+// Extract JSON from captured stdout, tolerating BOTH shapes we spawn:
+// the vidfarm devcli pretty-prints MULTI-LINE JSON (JSON.stringify(v, null, 2))
+// while the hyperframes CLI prints a single JSON line after log lines. Try:
+// (1) the whole trimmed stdout, (2) the first '{'/'[' through the last
+// '}'/']' (pretty JSON wrapped in log noise), (3) line-by-line, last first.
+function extractJson(out) {
+  if (!out) return null;
+  try {
+    return JSON.parse(out);
+  } catch { /* not bare JSON */ }
+  const starts = [out.indexOf("{"), out.indexOf("[")].filter((i) => i >= 0);
+  const first = starts.length ? Math.min(...starts) : -1;
+  const last = Math.max(out.lastIndexOf("}"), out.lastIndexOf("]"));
+  if (first >= 0 && last > first) {
+    try {
+      return JSON.parse(out.slice(first, last + 1));
+    } catch { /* not a clean block */ }
+  }
+  for (const line of out.split(/\r?\n/).reverse()) {
+    const t = line.trim();
+    if (!t.startsWith("{") && !t.startsWith("[")) continue;
+    try {
+      return JSON.parse(t);
+    } catch { /* not this line */ }
+  }
+  return null;
+}
+
+// Run a command, capture stdout, extract whatever JSON it printed (see extractJson).
+function runJson(cmd, args, env) {
+  const r = spawnSync(cmd, args, { encoding: "utf8", env, maxBuffer: 64 * 1024 * 1024 });
+  const out = (r.stdout ?? "").trim();
+  return { status: r.status, json: extractJson(out), stdout: out, stderr: (r.stderr ?? "").trim(), error: r.error };
+}
+
+// ── duration probing (never required, never fatal) ────────────────────────────
+
+function wavDurationSeconds(absPath) {
+  try {
+    const buf = readFileSync(absPath);
+    if (buf.length < 44 || buf.toString("ascii", 0, 4) !== "RIFF" || buf.toString("ascii", 8, 12) !== "WAVE") return null;
+    let pos = 12;
+    let byteRate = 0;
+    let dataSize = 0;
+    while (pos + 8 <= buf.length) {
+      const id = buf.toString("ascii", pos, pos + 4);
+      const size = buf.readUInt32LE(pos + 4);
+      if (id === "fmt ") byteRate = buf.readUInt32LE(pos + 16);
+      if (id === "data") dataSize = size;
+      pos += 8 + size + (size % 2);
+    }
+    return byteRate > 0 && dataSize > 0 ? dataSize / byteRate : null;
+  } catch {
+    return null;
+  }
+}
+
+function probeDurationSeconds(absPath) {
+  const ffprobe = process.env.HYPERFRAMES_FFPROBE_PATH || process.env.FFPROBE_PATH || "ffprobe";
+  try {
+    const r = spawnSync(ffprobe, ["-v", "error", "-show_entries", "format=duration", "-of", "csv=p=0", absPath], { encoding: "utf8" });
+    if (r.status === 0) {
+      const dur = parseFloat((r.stdout ?? "").trim());
+      if (Number.isFinite(dur) && dur > 0) return dur;
+    }
+  } catch { /* no ffprobe */ }
+  if (extname(absPath).toLowerCase() === ".wav") return wavDurationSeconds(absPath);
+  return null;
+}
+
+// ── word timings ──────────────────────────────────────────────────────────────
+
+// Estimation fallback: spread words across the audio duration by proportional
+// character weighting (the same approach vidfarm's caption system uses when a
+// provider returns no word timestamps).
+function estimateWords(text, durationS) {
+  const tokens = text.split(/\s+/).filter(Boolean);
+  if (!tokens.length) return [];
+  const weights = tokens.map((t) => Math.max(1, t.replace(/[^\p{L}\p{N}]/gu, "").length));
+  const total = weights.reduce((a, b) => a + b, 0);
+  const words = [];
+  let cursor = 0;
+  tokens.forEach((t, i) => {
+    const span = (durationS * weights[i]) / total;
+    words.push({ id: `w${i}`, text: t, start: r3(cursor), end: r3(cursor + span) });
+    cursor += span;
+  });
+  return words;
+}
+
+// Real timings via `hyperframes transcribe` (local whisper.cpp). Runs against
+// an ISOLATED temp dir — transcribe patches caption HTML under --dir, so it
+// must never see the project. Any failure → estimation, never a crash.
+function transcribeWords(absAudioPath, text, durationS, notes, lineId) {
+  if (noTranscribe) return estimateWords(text, durationS);
+  const { cmd, prefix } = hyperframesCli();
+  const dir = mkdtempSync(join(tmpdir(), "vf-media-stt-"));
+  const r = runJson(cmd, [...prefix, "transcribe", absAudioPath, "--dir", dir, "--json", "--optional"], scrubbedEnv());
+  if (r.json?.ok && r.json.transcriptPath && existsSync(r.json.transcriptPath)) {
+    try {
+      const words = JSON.parse(readFileSync(r.json.transcriptPath, "utf8"));
+      if (Array.isArray(words) && words.length) {
+        return words.map((w, i) => ({
+          id: w.id || `w${i}`,
+          text: String(w.text ?? "").trim(),
+          start: r3(Number(w.start) || 0),
+          end: r3(Number(w.end) || 0)
+        })).filter((w) => w.text);
+      }
+    } catch { /* fall through to estimate */ }
+  }
+  notes.push(`tts: line ${lineId} — whisper timings unavailable (${r.json?.reason || r.stderr.slice(0, 120) || "no output"}); estimated by character weighting`);
+  return estimateWords(text, durationS);
+}
+
+// ── TTS ───────────────────────────────────────────────────────────────────────
+
+const sanitize = (s) => String(s).replace(/[^A-Za-z0-9._-]+/g, "-").replace(/^-+|-+$/g, "") || "line";
+
+// Env keys per cloud provider (mirrors the devcli's resolveLocalSpeechAuth).
+// synthesizeCloud passes --provider explicitly, so ONLY a key for THAT provider
+// counts — a stray GEMINI key must not green-light an openai voice (that made
+// every line fail slowly in the cloud path and fall back one by one).
+const TTS_KEY_ENV = {
+  openai: ["OPENAI_API_KEY"],
+  gemini: ["GEMINI_API_KEY", "GOOGLE_GENERATIVE_AI_API_KEY"],
+  openrouter: ["OPENROUTER_API_KEY"]
+};
+
+function pickTtsEngine(notes) {
+  const provider = String(request.provider ?? "auto").toLowerCase();
+  const voice = typeof request.voice === "string" ? request.voice.trim() : "";
+  const voiceKey = voice.toLowerCase();
+  if (provider === "local" || provider === "kokoro") return { kind: "local" };
+  const cloudProvider = ["openai", "gemini", "openrouter"].includes(provider)
+    ? provider
+    : OPENAI_VOICES.has(voiceKey) ? "openai" : GEMINI_VOICES.has(voiceKey) ? "gemini" : null;
+  if (!cloudProvider) return { kind: "local" }; // auto + no cloud voice → keyless local
+  const hasKey = (TTS_KEY_ENV[cloudProvider] ?? []).some((name) => Boolean(process.env[name]?.trim()));
+  if (hasKey && hasCommand("vidfarm")) return { kind: "cloud", provider: cloudProvider };
+  notes.push(`tts: cloud voice/provider requested (${voice || cloudProvider}) but ${hasKey ? "no vidfarm CLI on PATH" : `no ${cloudProvider} key in env`} — using local Kokoro`);
+  return { kind: "local" };
+}
+
+function synthesizeLocal(text, outAbs, voice, speed) {
+  const { cmd, prefix } = hyperframesCli();
+  // Pass text via a temp .txt file (the CLI reads .txt inputs) — immune to
+  // leading-dash text and shell-length limits.
+  const txt = join(mkdtempSync(join(tmpdir(), "vf-media-tts-")), "line.txt");
+  writeFileSync(txt, text);
+  const args = [...prefix, "tts", txt, "-o", outAbs, "--json"];
+  if (voice && KOKORO_VOICE_RE.test(voice)) args.push("-v", voice);
+  if (Number.isFinite(speed) && speed > 0 && speed !== 1) args.push("-s", String(speed));
+  const r = runJson(cmd, args, scrubbedEnv());
+  if (!r.json?.ok) {
+    throw new Error(`local TTS failed: ${r.json?.error || r.stderr.slice(0, 200) || r.error?.message || `exit ${r.status}`}`);
+  }
+  return { path: r.json.outputPath || outAbs, duration: r.json.durationSeconds ?? null, engine: `kokoro/${r.json.voice ?? "af_heart"}` };
+}
+
+function synthesizeCloud(text, outAbs, provider) {
+  const args = ["tts", "--text", text, "--out", outAbs, "--json"];
+  if (request.voice) args.push("--voice", String(request.voice));
+  const style = request.style ?? request.instructions;
+  if (style) args.push("--style", String(style));
+  if (provider) args.push("--provider", provider);
+  const r = runJson("vidfarm", args, process.env);
+  if (!r.json?.ok) {
+    throw new Error(`vidfarm tts failed: ${r.json?.error || r.stderr.slice(0, 200) || `exit ${r.status}`}`);
+  }
+  const written = r.json.out || outAbs;
+  return { path: written, duration: null, engine: `vidfarm:${r.json.provider ?? provider}` };
+}
+
+function runTts(meta, notes) {
+  const spoken = lines.filter((l) => typeof l.text === "string" && l.text.trim());
+  meta.voices = [];
+  if (!spoken.length) return;
+  const engine = pickTtsEngine(notes);
+  const voiceDir = join(hyperframesDir, "assets", "voice");
+  mkdirSync(voiceDir, { recursive: true });
+  const speed = Number(request.speed) || 1;
+
+  for (const line of spoken) {
+    const id = String(line.id ?? meta.voices.length);
+    const text = line.text.trim();
+    const ext = engine.kind === "cloud" ? "mp3" : "wav";
+    const outAbs = join(voiceDir, `${sanitize(id)}.${ext}`);
+    let result;
+    if (engine.kind === "cloud") {
+      try {
+        result = synthesizeCloud(text, outAbs, engine.provider);
+      } catch (e) {
+        notes.push(`tts: line ${id} — ${e.message}; falling back to local Kokoro`);
+        result = synthesizeLocal(text, join(voiceDir, `${sanitize(id)}.wav`), request.voice, speed);
+      }
+    } else {
+      result = synthesizeLocal(text, outAbs, request.voice, speed);
+    }
+    const abs = isAbsolute(result.path) ? result.path : resolve(result.path);
+    const duration = result.duration ?? probeDurationSeconds(abs) ?? Math.max(0.4, text.length / 15);
+    const words = transcribeWords(abs, text, duration, notes, id);
+    meta.voices.push({
+      id,
+      path: relative(hyperframesDir, abs),
+      duration_s: r3(duration),
+      words,
+      engine: result.engine
+    });
+    console.error(`· tts ${id}: ${r3(duration)}s (${result.engine}, ${words.length} words)`);
+  }
+}
+
+// ── shared retrieval helpers (BGM + SFX) ──────────────────────────────────────
+
+const STOPWORDS = new Set(["a", "an", "and", "the", "of", "for", "with", "music", "track", "sound", "effect", "sfx", "audio"]);
+const tokensOf = (s) => String(s ?? "").toLowerCase().split(/[^a-z0-9]+/).filter((t) => t.length > 1 && !STOPWORDS.has(t));
+
+function listAudioFiles(dirAbs) {
+  try {
+    return readdirSync(dirAbs, { withFileTypes: true, recursive: true })
+      .filter((e) => e.isFile() && AUDIO_EXT.has(extname(e.name).toLowerCase()))
+      .map((e) => join(e.parentPath ?? e.path ?? dirAbs, e.name));
+  } catch {
+    return [];
+  }
+}
+
+function keywordPick(files, query) {
+  const qTokens = tokensOf(query);
+  if (!qTokens.length || !files.length) return null;
+  let best = null;
+  let bestScore = 0;
+  for (const f of files) {
+    const fTokens = new Set(tokensOf(basename(f)));
+    const score = qTokens.reduce((n, t) => n + (fTokens.has(t) ? 1 : 0), 0);
+    if (score > bestScore) {
+      best = f;
+      bestScore = score;
+    }
+  }
+  return best; // null when nothing shares a keyword — a random pick is worse than a skip
+}
+
+const myFilesAvailable = () => Boolean(process.env.VIDFARM_API_KEY) && hasCommand("vidfarm");
+
+// Search My Files and download the best audio hit into destDir. Returns the
+// absolute path or null. Optional — requires $VIDFARM_API_KEY.
+function myFilesFetchAudio(query, destDir) {
+  if (!myFilesAvailable()) return null;
+  const search = runJson("vidfarm", ["files", "--search", query, "--json"], process.env);
+  const results = Array.isArray(search.json?.results) ? search.json.results : [];
+  const hit = results.find((r) => AUDIO_EXT.has(extname(String(r.fileName ?? "")).toLowerCase()));
+  if (!hit) return null;
+  mkdirSync(destDir, { recursive: true });
+  const dest = join(destDir, sanitize(hit.fileName));
+  const dl = runJson("vidfarm", ["get-file", String(hit.id), dest, "--json"], process.env);
+  return dl.status === 0 && existsSync(dest) ? dest : null;
+}
+
+async function downloadUrl(url, destDir) {
+  const res = await fetch(url);
+  if (!res.ok) throw new Error(`download failed (${res.status}) for ${url}`);
+  const urlName = basename(new URL(url).pathname) || "bgm.mp3";
+  const name = AUDIO_EXT.has(extname(urlName).toLowerCase()) ? urlName : `${urlName}.mp3`;
+  mkdirSync(destDir, { recursive: true });
+  const dest = join(destDir, sanitize(name));
+  writeFileSync(dest, Buffer.from(await res.arrayBuffer()));
+  return dest;
+}
+
+function copyIn(srcAbs, destDir) {
+  mkdirSync(destDir, { recursive: true });
+  const dest = join(destDir, sanitize(basename(srcAbs)));
+  if (resolve(srcAbs) !== resolve(dest)) copyFileSync(srcAbs, dest);
+  return dest;
+}
+
+// ── BGM ───────────────────────────────────────────────────────────────────────
+// Resolution order: explicit file → explicit URL → My Files search → local
+// music dir keyword match → skip with a note. Never an account, never generated
+// off the user's machine. Looping to the video length is the assembler's job.
+
+async function runBgm(meta, notes) {
+  const bgm = request.bgm ?? {};
+  const mode = String(bgm.mode ?? "retrieve").toLowerCase();
+  meta.bgm = null;
+  if (mode === "none") return;
+  if (mode === "generate") notes.push("bgm: generate mode is not supported (no media accounts) — retrieving instead");
+  const query = String(bgm.query ?? "").trim();
+  const destDir = join(hyperframesDir, "assets", "bgm");
+  let abs = null;
+  let source = null;
+
+  const explicit = bgm.file ?? bgm.path;
+  if (explicit) {
+    const srcAbs = isAbsolute(explicit) ? explicit : resolve(hyperframesDir, explicit);
+    if (existsSync(srcAbs) && statSync(srcAbs).isFile()) {
+      abs = copyIn(srcAbs, destDir);
+      source = "file";
+    } else if (/^https?:\/\//i.test(String(explicit))) {
+      abs = await downloadUrl(String(explicit), destDir).catch((e) => (notes.push(`bgm: ${e.message}`), null));
+      source = abs ? "url" : null;
+    } else {
+      notes.push(`bgm: requested file not found at ${srcAbs}`);
+    }
+  }
+  if (!abs && bgm.url) {
+    abs = await downloadUrl(String(bgm.url), destDir).catch((e) => (notes.push(`bgm: ${e.message}`), null));
+    source = abs ? "url" : null;
+  }
+  if (!abs && query && myFilesAvailable()) {
+    abs = myFilesFetchAudio(`${query} music`, destDir);
+    source = abs ? "my-files" : null;
+  }
+  if (!abs) {
+    const musicDir = bgm.dir ? (isAbsolute(bgm.dir) ? bgm.dir : resolve(hyperframesDir, bgm.dir)) : process.env.MUSIC_DIR;
+    if (musicDir && existsSync(musicDir)) {
+      const pick = keywordPick(listAudioFiles(musicDir), query || "underscore");
+      if (pick) {
+        abs = copyIn(pick, destDir);
+        source = "music-dir";
+      } else {
+        notes.push(`bgm: no filename in ${musicDir} matches "${query}"`);
+      }
+    }
+  }
+  if (!abs) {
+    notes.push(`bgm: skipped — no user file/URL, no My Files match${process.env.VIDFARM_API_KEY ? "" : " (no $VIDFARM_API_KEY)"}, no local music dir. The video stays voice-only; pass bgm.file/bgm.url or set $MUSIC_DIR.`);
+    console.error("· bgm: skipped (see notes)");
+    return;
+  }
+  meta.bgm = {
+    path: relative(hyperframesDir, abs),
+    query: query || null,
+    duration_s: (() => {
+      const d = probeDurationSeconds(abs);
+      return d ? r3(d) : null;
+    })(),
+    source
+  };
+  if (bgm.volume != null) meta.bgm.volume = Number(bgm.volume);
+  console.error(`· bgm: ${meta.bgm.path} (${source})`);
+}
+
+// ── SFX ───────────────────────────────────────────────────────────────────────
+// Named cues per line. Order: local sfx dir(s) → My Files search → skip the cue
+// with a note. Unresolved cues never fail the run.
+
+function runSfx(meta, notes) {
+  meta.sfx = [];
+  const cueLines = lines.filter((l) => Array.isArray(l.sfx) && l.sfx.length);
+  if (!cueLines.length) return;
+  const destDir = join(hyperframesDir, "assets", "sfx");
+  const localDirs = [
+    request.sfx_dir ? (isAbsolute(request.sfx_dir) ? request.sfx_dir : resolve(hyperframesDir, request.sfx_dir)) : null,
+    process.env.SFX_DIR,
+    join(SKILL_DIR, "assets", "sfx")
+  ].filter((d) => d && existsSync(d));
+  const localFiles = localDirs.flatMap((d) => listAudioFiles(d));
+  const cache = new Map(); // cue name → abs path | null
+
+  const resolveCue = (cue) => {
+    const key = cue.toLowerCase();
+    if (cache.has(key)) return cache.get(key);
+    let abs = null;
+    const local = keywordPick(localFiles, cue);
+    if (local) abs = copyIn(local, destDir);
+    if (!abs && myFilesAvailable()) abs = myFilesFetchAudio(`${cue} sound effect`, destDir);
+    cache.set(key, abs);
+    return abs;
+  };
+
+  for (const line of cueLines) {
+    const id = String(line.id ?? "");
+    for (const rawCue of line.sfx) {
+      const cue = String(rawCue).trim();
+      if (!cue) continue;
+      const abs = resolveCue(cue);
+      if (!abs) {
+        notes.push(`sfx: "${cue}" (line ${id}) — no match in ${localDirs.length ? localDirs.join(", ") : "$SFX_DIR (unset)"}${myFilesAvailable() ? " or My Files" : ""}; cue skipped`);
+        continue;
+      }
+      meta.sfx.push({
+        id,
+        file: relative(hyperframesDir, abs),
+        offset_s: 0,
+        duration_s: r3(probeDurationSeconds(abs) ?? 1),
+        volume: 0.35,
+        cue
+      });
+    }
+  }
+  console.error(`· sfx: ${meta.sfx.length} cue(s) resolved`);
+}
+
+// ── main: merge-aware section runner ─────────────────────────────────────────
+
+async function main() {
+  // Sections not in --only are preserved from an existing meta (this is what
+  // makes the adapters' generate → fetch-sfx sequence accumulate).
+  let meta = { voices: [], bgm: null, sfx: [], notes: [] };
+  if (existsSync(outPath)) {
+    try {
+      const prev = JSON.parse(readFileSync(outPath, "utf8"));
+      meta = {
+        voices: Array.isArray(prev.voices) ? prev.voices : [],
+        bgm: prev.bgm ?? null,
+        sfx: Array.isArray(prev.sfx) ? prev.sfx : [],
+        notes: Array.isArray(prev.notes) ? prev.notes : []
+      };
+    } catch { /* corrupt sidecar — start fresh */ }
+  }
+  // Drop stale notes for the sections being recomputed.
+  meta.notes = meta.notes.filter((n) => ![...only].some((s) => String(n).startsWith(`${s}:`)));
+  const notes = meta.notes;
+
+  if (only.has("tts")) runTts(meta, notes);
+  if (only.has("bgm")) await runBgm(meta, notes);
+  if (only.has("sfx")) runSfx(meta, notes);
+
+  mkdirSync(dirname(outPath), { recursive: true });
+  writeFileSync(outPath, JSON.stringify(meta, null, 2));
+  console.log(
+    `✓ media audio: ${meta.voices.length} voice line(s), ` +
+    `${meta.bgm ? "1 bgm" : "no bgm"}, ${meta.sfx.length} sfx → ${outPath}` +
+    (notes.length ? ` (${notes.length} note(s) in meta)` : "")
+  );
+}
+
+main().catch((e) => die(e?.message ?? String(e)));

package/.agents/skills/vidfarm-media/scripts/wait-bgm.mjs

@@ -0,0 +1,31 @@
+#!/usr/bin/env node
+// wait-bgm.mjs — compatibility shim. The vidfarm-media engine resolves BGM
+// synchronously (user file / URL / My Files / local dir) and never sets
+// `bgm_pending`, so there is nothing to wait for. Kept so workflows that call
+// wait-bgm unconditionally keep working: report the BGM state and exit 0.
+//
+//   node wait-bgm.mjs [--meta ./audio_meta.json]
+
+import { existsSync, readFileSync } from "node:fs";
+import { resolve } from "node:path";
+
+const argv = process.argv.slice(2);
+if (argv.includes("--help") || argv.includes("-h")) {
+  console.log("Usage: node wait-bgm.mjs [--meta ./audio_meta.json]\nNo-op: the vidfarm-media engine never defers BGM (bgm_pending is never set).");
+  process.exit(0);
+}
+const i = argv.indexOf("--meta");
+const metaPath = resolve(i >= 0 && argv[i + 1] ? argv[i + 1] : "./audio_meta.json");
+
+if (!existsSync(metaPath)) {
+  console.log(`· wait-bgm: no meta at ${metaPath} — nothing pending.`);
+  process.exit(0);
+}
+try {
+  const meta = JSON.parse(readFileSync(metaPath, "utf8"));
+  if (meta.bgm?.path) console.log(`✓ wait-bgm: bgm ready at ${meta.bgm.path}.`);
+  else console.log("· wait-bgm: no bgm in meta (skipped at generate time — see meta notes). Nothing pending.");
+} catch {
+  console.log("· wait-bgm: meta unreadable — nothing pending.");
+}
+process.exit(0);