@ignix-social/editor 0.1.0

package/vendor/hyperframes/dist/skills/media-use/audio/scripts/lib/tts.test.mjs

@@ -0,0 +1,230 @@
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import {
+  mkdirSync,
+  mkdtempSync,
+  readFileSync,
+  writeFileSync,
+  chmodSync,
+  rmSync,
+  existsSync,
+} from "node:fs";
+import { join, dirname } from "node:path";
+import { tmpdir } from "node:os";
+import {
+  parseFfmpegDurationBanner,
+  ffprobeDuration,
+  synthesizeOne,
+  synthesizeHeygen,
+  synthResult,
+  pickProvider,
+} from "./tts.mjs";
+
+test("parseFfmpegDurationBanner reads ffmpeg's stderr Duration line", () => {
+  const stderr = [
+    "ffmpeg version 6.0",
+    "Input #0, wav, from 'a.wav':",
+    "  Duration: 00:00:03.42, bitrate: 705 kb/s",
+    "At least one output file must be specified",
+  ].join("\n");
+  assert.equal(parseFfmpegDurationBanner(stderr), 3.42);
+});
+
+test("parseFfmpegDurationBanner handles an hours component", () => {
+  const stderr = "  Duration: 01:02:03.50, start: 0.000000, bitrate: 128 kb/s";
+  assert.equal(parseFfmpegDurationBanner(stderr), 3723.5);
+});
+
+test("parseFfmpegDurationBanner returns NaN when there is no Duration line", () => {
+  assert.ok(Number.isNaN(parseFfmpegDurationBanner("ffmpeg: command not found")));
+  assert.ok(Number.isNaN(parseFfmpegDurationBanner("")));
+  assert.ok(Number.isNaN(parseFfmpegDurationBanner(undefined)));
+});
+
+// Regression for the actual bug: ffprobeDuration used to collapse "ffprobe
+// binary is missing" (ENOENT — the "essentials"-style Windows ffmpeg build
+// with no ffprobe.exe) and "file is genuinely unreadable" into the same NaN,
+// giving audio.mjs no way to tell "measure differently" from "give up".
+//
+// Builds an isolated PATH containing only a fake `ffmpeg` stub (no `ffprobe`
+// at all) so ffprobeDuration's spawnSync("ffprobe", ...) call ENOENTs for
+// real, then verifies it recovers the duration via the ffmpeg fallback
+// instead of returning NaN.
+test("ffprobeDuration falls back to ffmpeg when the ffprobe binary itself is missing", () => {
+  const dir = mkdtempSync(join(tmpdir(), "tts-ffprobe-fallback-"));
+  const fakeFfmpeg = join(dir, "ffmpeg");
+  writeFileSync(
+    fakeFfmpeg,
+    "#!/bin/sh\necho 'Duration: 00:00:02.50, start: 0.000000, bitrate: 128 kb/s' 1>&2\nexit 1\n",
+  );
+  chmodSync(fakeFfmpeg, 0o755);
+  const originalPath = process.env.PATH;
+  try {
+    process.env.PATH = dir; // only the fake ffmpeg resolves; no real ffprobe on this PATH
+    assert.equal(ffprobeDuration("/does/not/matter.wav"), 2.5);
+  } finally {
+    process.env.PATH = originalPath;
+    rmSync(dir, { recursive: true, force: true });
+  }
+});
+
+test("ffprobeDuration returns NaN when neither ffprobe nor ffmpeg resolve", () => {
+  const dir = mkdtempSync(join(tmpdir(), "tts-no-binaries-"));
+  const originalPath = process.env.PATH;
+  try {
+    process.env.PATH = dir; // empty directory — nothing resolves
+    assert.ok(Number.isNaN(ffprobeDuration("/does/not/matter.wav")));
+  } finally {
+    process.env.PATH = originalPath;
+    rmSync(dir, { recursive: true, force: true });
+  }
+});
+
+test("synthesizeOne(elevenlabs) creates the output dir before writing", async () => {
+  const dir = mkdtempSync(join(tmpdir(), "tts-el-mkdir-"));
+  const wavAbs = join(dir, "assets", "voice", "line-0.wav"); // nested, not yet created
+  const savedKey = process.env.ELEVENLABS_API_KEY;
+  try {
+    // Unset the key so the Python side fails fast — the mkdir must run before
+    // the spawn regardless, which is what this guards.
+    delete process.env.ELEVENLABS_API_KEY;
+    await synthesizeOne({
+      provider: "elevenlabs",
+      text: "hi",
+      voiceId: "v",
+      wavAbs,
+      hyperframesDir: dir,
+    });
+    assert.ok(existsSync(dirname(wavAbs)), "output directory should be created");
+  } finally {
+    if (savedKey === undefined) delete process.env.ELEVENLABS_API_KEY;
+    else process.env.ELEVENLABS_API_KEY = savedKey;
+    rmSync(dir, { recursive: true, force: true });
+  }
+});
+
+test("synthesizeHeygen surfaces a thrown HTTP error (e.g. 402) instead of swallowing it", async () => {
+  const res = await synthesizeHeygen(
+    { text: "hi", voiceId: "v1", lang: "en", speed: 1, wavAbs: "/tmp/x.wav" },
+    {
+      heygenAuthHeaders: () => ({}),
+      heygenJSON: async () => {
+        throw new Error("HeyGen POST /voices/speech → HTTP 402\nplan_upgrade_required");
+      },
+    },
+  );
+  assert.equal(res.ok, false);
+  assert.match(res.error, /402/);
+  assert.match(res.error, /plan_upgrade_required/);
+});
+
+test("synthesizeHeygen surfaces a failed audio_url fetch with its status", async () => {
+  const res = await synthesizeHeygen(
+    { text: "hi", voiceId: "v1", lang: "en", speed: 1, wavAbs: "/tmp/x.wav" },
+    {
+      heygenAuthHeaders: () => ({}),
+      heygenJSON: async () => ({ data: { audio_url: "http://audio.example/x" } }),
+      fetch: async () => ({ ok: false, status: 403 }),
+    },
+  );
+  assert.equal(res.ok, false);
+  assert.match(res.error, /HTTP 403/);
+});
+
+test("synthesizeHeygen reports a missing audio_url", async () => {
+  const res = await synthesizeHeygen(
+    { text: "hi", voiceId: "v1", lang: "en", speed: 1, wavAbs: "/tmp/x.wav" },
+    { heygenAuthHeaders: () => ({}), heygenJSON: async () => ({}) },
+  );
+  assert.equal(res.ok, false);
+  assert.match(res.error, /no audio_url/);
+});
+
+test("synthesizeHeygen reports wav transcode failures", async () => {
+  const dir = mkdtempSync(join(tmpdir(), "hf-tts-test-"));
+  try {
+    const res = await synthesizeHeygen(
+      { text: "hi", voiceId: "v1", lang: "en", speed: 1, wavAbs: join(dir, "voice.wav") },
+      {
+        heygenAuthHeaders: () => ({}),
+        heygenJSON: async () => ({ data: { audio_url: "http://audio.example/x" } }),
+        fetch: async () => ({ ok: true, status: 200, arrayBuffer: async () => new ArrayBuffer(0) }),
+        transcodeToWav: () => false,
+      },
+    );
+    assert.equal(res.ok, false);
+    assert.equal(res.error, "wav transcode failed (ffmpeg)");
+  } finally {
+    rmSync(dir, { recursive: true, force: true });
+  }
+});
+
+test("synthResult names a non-zero subprocess exit", () => {
+  const res = synthResult({ status: 2 }, "/tmp/none.wav", "kokoro (npx hyperframes tts)");
+  assert.equal(res.ok, false);
+  assert.match(res.error, /kokoro .* exited with status 2/);
+});
+
+// Kokoro shells out to `npx hyperframes tts`; a fake npx on PATH records the argv
+// synthesizeOne really builds, so a dropped flag fails here. Windows runs npx via
+// node directly, so the stub never resolves there.
+async function kokoroArgv(options) {
+  const dir = mkdtempSync(join(tmpdir(), "tts-kokoro-argv-"));
+  const argvLog = join(dir, "argv.txt");
+  writeFileSync(join(dir, "npx"), `#!/bin/sh\nprintf '%s\\n' "$@" > "${argvLog}"\n`);
+  chmodSync(join(dir, "npx"), 0o755);
+  const originalPath = process.env.PATH;
+  try {
+    process.env.PATH = dir;
+    await synthesizeOne({
+      provider: "kokoro",
+      text: "hi",
+      voiceId: "am_michael",
+      wavAbs: join(dir, "line-0.wav"),
+      hyperframesDir: dir,
+      ...options,
+    });
+    return readFileSync(argvLog, "utf8").trim().split("\n");
+  } finally {
+    process.env.PATH = originalPath;
+    rmSync(dir, { recursive: true, force: true });
+  }
+}
+
+test(
+  "synthesizeOne(kokoro) forwards a non-default speed to the CLI",
+  { skip: process.platform === "win32" },
+  async () => {
+    const argv = await kokoroArgv({ speed: 0.8, lang: "es" });
+    assert.deepEqual(argv.slice(-4), ["--lang", "es", "--speed", "0.8"]);
+  },
+);
+
+test(
+  "synthesizeOne(kokoro) leaves --speed off at the default",
+  { skip: process.platform === "win32" },
+  async () => {
+    assert.ok(!(await kokoroArgv({})).includes("--speed"));
+  },
+);
+
+test("pickProvider heygen with an unreadable credentials path says to fix that path", () => {
+  const saved = ["HEYGEN_API_KEY", "HYPERFRAMES_API_KEY", "HEYGEN_CONFIG_DIR"].map((k) => [
+    k,
+    process.env[k],
+  ]);
+  const dir = mkdtempSync(join(tmpdir(), "tts-cred-"));
+  try {
+    delete process.env.HEYGEN_API_KEY;
+    delete process.env.HYPERFRAMES_API_KEY;
+    process.env.HEYGEN_CONFIG_DIR = dir;
+    mkdirSync(join(dir, "credentials"));
+    assert.throws(() => pickProvider("heygen"), /fix or remove that path/);
+  } finally {
+    for (const [k, v] of saved) {
+      if (v === undefined) delete process.env[k];
+      else process.env[k] = v;
+    }
+    rmSync(dir, { recursive: true, force: true });
+  }
+});

package/vendor/hyperframes/dist/skills/media-use/audio/scripts/lyria-recipe.py

@@ -0,0 +1,136 @@
+#!/usr/bin/env python3
+"""Generate BGM using Google Lyria RealTime API.
+
+Usage:
+    python lyria-recipe.py --output <path> --duration <seconds> [tuning flags]
+
+Requires:
+    $GOOGLE_API_KEY or $GEMINI_API_KEY environment variable (treated as aliases).
+    pip install google-genai python-dotenv. audio.mjs Step 4b installs these on
+    demand when a key is set but google.genai is not importable; if that install
+    fails it falls back to local MusicGen rather than leaving the video with no BGM.
+"""
+
+from __future__ import annotations
+
+import argparse
+import asyncio
+import os
+import sys
+import wave
+from pathlib import Path
+
+# Windows sizes stdio to the ANSI code page (cp1252). These scripts emit UTF-8 on
+# every platform; say so rather than depending on the console's code page. Carry
+# `errors` across: reconfigure() resets it to "strict", and CPython deliberately gives
+# stderr "backslashreplace" so the diagnostic path can never itself raise.
+for _stream in (sys.stdout, sys.stderr):
+    if hasattr(_stream, "reconfigure"):
+        _stream.reconfigure(encoding="utf-8", errors=_stream.errors)
+
+DEFAULT_PROMPT = "Uplifting corporate tech, bright and modern, gentle piano with synth pads"
+SAMPLE_RATE = 48000
+CHANNELS = 2
+SAMPLE_WIDTH = 2  # 16-bit
+
+
+def parse_args() -> argparse.Namespace:
+    p = argparse.ArgumentParser(description="Generate BGM via Google Lyria RealTime.")
+    p.add_argument("--output", required=True, help="Output WAV path.")
+    p.add_argument("--duration", type=float, required=True, help="Target duration in seconds.")
+    p.add_argument("--prompt", default=DEFAULT_PROMPT, help="Mood / instrumentation prompt.")
+    p.add_argument("--negative-prompt", default=None, help="Styles to exclude (optional).")
+    p.add_argument("--bpm", type=int, default=110)
+    p.add_argument("--brightness", type=float, default=0.8, help="0-1, higher = brighter mood.")
+    p.add_argument("--density", type=float, default=0.5, help="0-1, higher = fuller mix.")
+    p.add_argument(
+        "--scale",
+        default="MAJOR",
+        help="MAJOR / MINOR / PENTATONIC / etc. — see google.genai.types.Scale. Pass empty string for none.",
+    )
+    return p.parse_args()
+
+
+async def generate_bgm(args: argparse.Namespace) -> dict:
+    from google import genai
+    from google.genai import types
+
+    api_key = os.environ.get("GOOGLE_API_KEY") or os.environ.get("GEMINI_API_KEY") or ""
+    if not api_key:
+        raise RuntimeError("Neither GOOGLE_API_KEY nor GEMINI_API_KEY is set.")
+
+    client = genai.Client(
+        api_key=api_key,
+        http_options={"api_version": "v1alpha"},
+    )
+
+    out_path = Path(args.output)
+    out_path.parent.mkdir(parents=True, exist_ok=True)
+
+    target_bytes = int(args.duration * SAMPLE_RATE * CHANNELS * SAMPLE_WIDTH)
+
+    cfg: dict = {"bpm": args.bpm, "temperature": 1.0}
+    if args.density is not None:
+        cfg["density"] = args.density
+    if args.brightness is not None:
+        cfg["brightness"] = args.brightness
+    if args.scale:
+        scale_enum = getattr(types.Scale, args.scale, None)
+        if scale_enum:
+            cfg["scale"] = scale_enum
+
+    prompts = [types.WeightedPrompt(text=args.prompt, weight=1.0)]
+    if args.negative_prompt:
+        prompts.append(types.WeightedPrompt(text=args.negative_prompt, weight=-1.0))
+
+    buf = bytearray()
+    timeout = args.duration + 8
+
+    async with client.aio.live.music.connect(
+        model="models/lyria-realtime-exp",
+    ) as session:
+        await session.set_weighted_prompts(prompts=prompts)
+        await session.set_music_generation_config(
+            config=types.LiveMusicGenerationConfig(**cfg),
+        )
+        await session.play()
+
+        async def collect():
+            while len(buf) < target_bytes:
+                async for msg in session.receive():
+                    sc = msg.server_content
+                    if sc and sc.audio_chunks:
+                        for chunk in sc.audio_chunks:
+                            buf.extend(chunk.data)
+                            if len(buf) >= target_bytes:
+                                return
+                await asyncio.sleep(1e-6)
+
+        try:
+            await asyncio.wait_for(collect(), timeout=timeout)
+        except TimeoutError:
+            print(f"Timeout after {timeout:.0f}s, collected {len(buf)} bytes", file=sys.stderr)
+
+    audio = bytes(buf[:target_bytes])
+    with wave.open(str(out_path), "wb") as wf:
+        wf.setnchannels(CHANNELS)
+        wf.setsampwidth(SAMPLE_WIDTH)
+        wf.setframerate(SAMPLE_RATE)
+        wf.writeframes(audio)
+
+    actual_duration = len(audio) / (SAMPLE_RATE * CHANNELS * SAMPLE_WIDTH)
+    print(f"BGM: {out_path} ({actual_duration:.2f}s)")
+    return {"file": str(out_path), "duration_sec": round(actual_duration, 2)}
+
+
+def main() -> None:
+    args = parse_args()
+    try:
+        asyncio.run(generate_bgm(args))
+    except RuntimeError as exc:
+        print(f"BGM generation failed: {exc}", file=sys.stderr)
+        sys.exit(1)
+
+
+if __name__ == "__main__":
+    main()

package/vendor/hyperframes/dist/skills/media-use/audio/scripts/wait-bgm.mjs

@@ -0,0 +1,175 @@
+#!/usr/bin/env node
+// Phase 4c pre-assemble helper — wait for detached BGM, then write status.
+//
+// audio.mjs may launch Lyria / MusicGen in a detached process so voice work can
+// keep moving. Before assemble-index.mjs decides whether to emit the BGM audio
+// track, this script gives the background renderer a bounded chance to finish
+// and converts log/process state into a small bgm_status.json file.
+//
+// Always exits 0 for normal pipeline use: missing/failed BGM should not block a
+// voice/captions/SFX render. Structural invocation errors still exit 1.
+//
+// Usage:
+//   node wait-bgm.mjs --audio-meta ./audio_meta.json --hyperframes . \
+//     [--timeout-ms 120000] [--interval-ms 2000] [--out ./bgm_status.json]
+
+import { existsSync, readFileSync, statSync, writeFileSync } from "node:fs";
+import { join, resolve } from "node:path";
+import { recordInManifest } from "./lib/media-record.mjs";
+
+const argv = process.argv.slice(2);
+const flag = (name, def) => {
+  const i = argv.indexOf(`--${name}`);
+  return i >= 0 && i + 1 < argv.length ? argv[i + 1] : def;
+};
+
+function die(msg) {
+  console.error(`✗ wait-bgm.mjs: ${msg}`);
+  process.exit(1);
+}
+
+const audioMetaPath = resolve(flag("audio-meta", "./audio_meta.json"));
+const hyperframesDir = resolve(flag("hyperframes", "."));
+const outPath = resolve(flag("out", join(hyperframesDir, "bgm_status.json")));
+const timeoutMs = Math.max(0, Number(flag("timeout-ms", "120000")) || 0);
+const intervalMs = Math.max(250, Number(flag("interval-ms", "2000")) || 2000);
+
+function sleep(ms) {
+  return new Promise((resolveSleep) => setTimeout(resolveSleep, ms));
+}
+
+function isProcessAlive(pid) {
+  if (!pid || !Number.isFinite(Number(pid))) return false;
+  try {
+    process.kill(Number(pid), 0);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+function readTail(path, maxChars = 6000) {
+  if (!path) return "";
+  try {
+    const txt = readFileSync(path, "utf8");
+    return txt.slice(Math.max(0, txt.length - maxChars));
+  } catch (error) {
+    if (error.code === "ENOENT" || error.code === "ENOTDIR") return "";
+    throw error;
+  }
+}
+
+function detectFailure(logTail) {
+  if (!logTail) return "";
+  const lines = logTail.split("\n");
+  // Bare "out of range" over-matched benign BGM-renderer logs (e.g. a "sample rate
+  // out of range, resampling" notice), mislabelling a healthy track as failed and
+  // silently dropping the music. Anchor to the actual crash strings instead:
+  // Python "(list) index out of range" and torch "index … out of bounds".
+  const idx = lines.findIndex((line) =>
+    /(Traceback|IndexError|RuntimeError|Exception|Killed|No space left|Cannot allocate|index out of range|out of bounds)/i.test(
+      line,
+    ),
+  );
+  if (idx < 0) return "";
+  return lines.slice(idx).join("\n").trim();
+}
+
+function writeStatus(status) {
+  const payload = {
+    generated_at: new Date().toISOString(),
+    ...status,
+  };
+  writeFileSync(outPath, JSON.stringify(payload, null, 2) + "\n");
+  return payload;
+}
+
+if (!existsSync(audioMetaPath)) die(`audio_meta.json missing at ${audioMetaPath}`);
+
+const audioMeta = JSON.parse(readFileSync(audioMetaPath, "utf8"));
+const bgmPath = audioMeta.bgm?.path || "";
+const bgmAbsPath = bgmPath ? join(hyperframesDir, bgmPath) : "";
+const logPath = audioMeta.bgm_log || "";
+const pid = audioMeta.bgm_pid || null;
+
+const base = {
+  enabled: Boolean(audioMeta.bgm_pending && bgmPath),
+  provider: audioMeta.bgm_provider || null,
+  mode: audioMeta.bgm_mode || null,
+  path: bgmPath || null,
+  log: logPath || null,
+  pid,
+  target_duration_s: audioMeta.bgm_target_duration_s || null,
+  seed_duration_s: audioMeta.bgm_seed_duration_s || null,
+  loop_count: audioMeta.bgm_loop_count || null,
+  timeout_ms: timeoutMs,
+};
+
+if (!base.enabled) {
+  const status = writeStatus({
+    ...base,
+    status: "disabled",
+    ready: false,
+    waited_ms: 0,
+    message: "BGM not requested or disabled in audio_meta.json.",
+  });
+  console.log(`✓ bgm: ${status.status} (${status.message})`);
+  process.exit(0);
+}
+
+const started = Date.now();
+let lastFailure = "";
+let lastTail = "";
+
+while (Date.now() - started <= timeoutMs) {
+  if (existsSync(bgmAbsPath)) {
+    const size = statSync(bgmAbsPath).size;
+    writeStatus({
+      ...base,
+      status: "ready",
+      ready: true,
+      waited_ms: Date.now() - started,
+      size_bytes: size,
+      message: `BGM ready at ${bgmPath}.`,
+    });
+    console.log(`✓ bgm: ready (${bgmPath}, ${size}B)`);
+    const generated = { path: bgmPath, type: "bgm", source: "generated", provider: base.provider };
+    for (const anomaly of recordInManifest(hyperframesDir, [generated]))
+      console.error(`  ${anomaly}`);
+    process.exit(0);
+  }
+
+  lastTail = readTail(logPath);
+  lastFailure = detectFailure(lastTail);
+  const alive = isProcessAlive(pid);
+  if (lastFailure || (!alive && logPath && existsSync(logPath))) {
+    const message = lastFailure
+      ? `BGM renderer failed; see ${logPath}.`
+      : `BGM renderer exited without writing ${bgmPath}; see ${logPath}.`;
+    const status = writeStatus({
+      ...base,
+      status: "failed",
+      ready: false,
+      waited_ms: Date.now() - started,
+      process_alive: alive,
+      message,
+      error_tail: lastFailure || lastTail.slice(-2000),
+    });
+    console.log(`! bgm: failed (${status.message})`);
+    process.exit(0);
+  }
+
+  if (timeoutMs === 0) break;
+  await sleep(Math.min(intervalMs, Math.max(0, timeoutMs - (Date.now() - started))));
+}
+
+const status = writeStatus({
+  ...base,
+  status: "timeout",
+  ready: false,
+  waited_ms: Date.now() - started,
+  process_alive: isProcessAlive(pid),
+  message: `Timed out waiting for ${bgmPath}; assemble-index will skip BGM if still absent.`,
+  log_tail: lastTail.slice(-2000),
+});
+console.log(`! bgm: timeout after ${status.waited_ms}ms (${bgmPath})`);

package/vendor/hyperframes/dist/skills/media-use/audio/scripts/wait-bgm.test.mjs

@@ -0,0 +1,108 @@
+import assert from "node:assert/strict";
+import { mkdirSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { spawnSync } from "node:child_process";
+import { join } from "node:path";
+import { tmpdir } from "node:os";
+import { test } from "node:test";
+import { runInNewContext } from "node:vm";
+
+const source = readFileSync(new URL("./wait-bgm.mjs", import.meta.url), "utf8");
+const start = source.indexOf("function readTail(");
+const end = source.indexOf("\nfunction detectFailure(", start);
+function load(read) {
+  return runInNewContext(`${source.slice(start, end)}; readTail`, {
+    readFileSync: read,
+    existsSync: () => true,
+    statSync: () => {
+      throw new Error("pathname stat must not precede log read");
+    },
+  });
+}
+
+test("reads a log once without a separate pathname check", () => {
+  let calls = 0;
+  const read = load((path, encoding) => {
+    calls++;
+    assert.equal(path, "renderer.log");
+    assert.equal(encoding, "utf8");
+    return "prefix\nRuntimeError: failed";
+  });
+  assert.equal(read("renderer.log", 20), "RuntimeError: failed");
+  assert.equal(calls, 1);
+});
+
+test("preserves UTF-16 character tail boundaries and zero-length tails", () => {
+  const txt = "🎵日本語".repeat(2000);
+  const read = load(() => txt);
+  assert.equal(read("log"), txt.slice(-6000));
+  assert.equal(read("log", 0), "");
+});
+
+for (const code of ["ENOENT", "ENOTDIR"]) {
+  test(`a log removed during polling is absent (${code})`, () => {
+    const read = load(() => {
+      throw Object.assign(new Error(code), { code });
+    });
+    assert.equal(read("log"), "");
+  });
+}
+
+test("preserves unexpected read errors", () => {
+  const error = Object.assign(new Error("denied"), { code: "EACCES" });
+  assert.throws(
+    () =>
+      load(() => {
+        throw error;
+      })("log"),
+    (caught) => caught === error,
+  );
+});
+
+test("empty log path does not access the filesystem", () => {
+  assert.equal(
+    load(() => {
+      throw new Error("unexpected read");
+    })(""),
+    "",
+  );
+});
+
+test("records locally made music as generated once it is ready", () => {
+  const dir = mkdtempSync(join(tmpdir(), "mu-wait-bgm-"));
+  try {
+    mkdirSync(join(dir, "assets/bgm"), { recursive: true });
+    writeFileSync(join(dir, "assets/bgm/track.wav"), "generated music");
+    writeFileSync(
+      join(dir, "audio_meta.json"),
+      JSON.stringify({
+        bgm: { path: "assets/bgm/track.wav" },
+        bgm_pending: true,
+        bgm_provider: "musicgen",
+        bgm_mode: "detached-single",
+      }),
+    );
+    const script = new URL("./wait-bgm.mjs", import.meta.url).pathname;
+    const args = ["--audio-meta", join(dir, "audio_meta.json"), "--hyperframes", dir];
+
+    const run = spawnSync(process.execPath, [script, ...args, "--timeout-ms", "1000"], {
+      encoding: "utf8",
+    });
+
+    assert.equal(run.status, 0, run.stderr);
+    const records = readFileSync(join(dir, ".media/manifest.jsonl"), "utf8")
+      .trim()
+      .split("\n")
+      .map((line) => JSON.parse(line));
+    assert.deepEqual(
+      records.map(({ path, type, source, provenance }) => [
+        path,
+        type,
+        source,
+        provenance.provider,
+      ]),
+      [["assets/bgm/track.wav", "bgm", "generated", "musicgen"]],
+    );
+  } finally {
+    rmSync(dir, { recursive: true, force: true });
+  }
+});

package/vendor/hyperframes/dist/skills/media-use/luts/README.md

@@ -0,0 +1,28 @@
+# LUT library (authoring)
+
+`index.json` is the agent-consumed catalog of color-grade looks. Each entry resolves
+on demand — no `.cube` bodies are committed to the repo.
+
+Each look has:
+
+- `id`, `description`, `tags`, `intensity` — matching + application metadata.
+- `url` (optional) — a hosted `.cube` downloaded, validated, and frozen at resolve
+  time, exactly like bgm/image assets.
+- `params` (optional) — a deterministic `buildCube` spec used offline (`--local-only`)
+  or as a fallback if the `url` download/validation fails.
+
+An entry needs at least one of `url` or `params`; prefer both (CDN url with a params
+fallback) so resolution is never blocked on the network.
+
+## Hosting a new look (operators)
+
+1. Generate the `.cube` (e.g. `resolve -t lut --params '{...}'` or a graded export).
+2. Upload it to the public CDN origin bucket:
+
+   ```
+   aws s3 cp <id>.cube s3://heygen-public/luts/<id>.cube
+   ```
+
+   It is then served at `https://static.heygen.ai/luts/<id>.cube` (CloudFront).
+
+3. Add an entry to `index.json` with that `url` (and ideally a `params` fallback).