@ignix-social/editor 0.1.0

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

@@ -0,0 +1,122 @@
+#!/usr/bin/env node
+// Self-contained HeyGen TTS — single text in → one wav (+ optional words JSON)
+// out. A thin CLI over lib/tts.mjs (the same code the audio engine uses), so the
+// HeyGen REST call, starfish voice pick, mp3→wav transcode, and word-timestamp
+// filtering live in exactly one place. Bypasses the `hyperframes` CLI, which in
+// the published build is Kokoro-only.
+//
+// Usage:
+//   node heygen-tts.mjs "Text to speak"  -o narration.wav [--words narration.words.json]
+//   node heygen-tts.mjs ./script.txt     -o narration.wav --words narration.words.json
+//   node heygen-tts.mjs "Bonjour"        -o fr.wav --lang fr --voice <id>
+//   node heygen-tts.mjs --list           # list starfish voices and exit
+//
+// Flags: -o/--output (.wav → ffmpeg transcode; .mp3 → raw bytes), --words,
+//   --voice (starfish id), --speed, --lang, --list.
+// Requires: $HEYGEN_API_KEY / OAuth ~/.heygen credentials and ffmpeg for .wav output.
+
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { dirname, resolve } from "node:path";
+import { heygenAuthHeaders, heygenJSON, loadEnvFromDir } from "./lib/heygen.mjs";
+import { ffprobeDuration, resolveVoiceId, synthesizeOne, withWordIds } from "./lib/tts.mjs";
+
+const argv = process.argv.slice(2);
+function flag(name, def) {
+  const i = argv.indexOf(`--${name}`);
+  if (i < 0) return def;
+  if (i + 1 >= argv.length) return true;
+  const v = argv[i + 1];
+  return v.startsWith("--") ? true : v;
+}
+const die = (m) => {
+  console.error(`✗ heygen-tts: ${m}`);
+  process.exit(1);
+};
+
+// First arg that isn't a flag or the -o value is the text / .txt path.
+const positional = (() => {
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    if (a.startsWith("--")) {
+      const next = argv[i + 1];
+      if (next && !next.startsWith("--")) i++;
+      continue;
+    }
+    if (a === "-o") {
+      i++;
+      continue;
+    }
+    return a;
+  }
+  return null;
+})();
+
+const output = resolve(
+  (typeof flag("output") === "string" && flag("output")) ||
+    (argv.includes("-o") && argv[argv.indexOf("-o") + 1]) ||
+    "narration.wav",
+);
+const wordsPath = typeof flag("words") === "string" ? resolve(flag("words")) : null;
+const userVoice = typeof flag("voice") === "string" ? flag("voice") : null;
+const speedRaw = typeof flag("speed") === "string" ? Number(flag("speed")) : 1.0;
+const speed = isFinite(speedRaw) && speedRaw > 0 ? speedRaw : 1.0;
+const lang = typeof flag("lang") === "string" ? flag("lang") : "en";
+const listOnly = flag("list") === true;
+
+loadEnvFromDir(process.cwd());
+let authHeaders;
+try {
+  authHeaders = heygenAuthHeaders();
+} catch (e) {
+  die(e.message);
+}
+
+// ---------- --list ----------
+if (listOnly) {
+  const payload = await heygenJSON(`/voices?engine=starfish&type=public&limit=50`, {
+    headers: authHeaders,
+  });
+  for (const v of payload.data ?? payload.voices ?? []) {
+    console.log(`${v.voice_id}\t${v.name}\t${v.language ?? ""}`);
+  }
+  process.exit(0);
+}
+
+// ---------- resolve text + voice ----------
+if (!positional) die("no text given. Pass a string or a .txt path, or use --list.");
+const text =
+  positional.endsWith(".txt") && existsSync(resolve(positional))
+    ? readFileSync(resolve(positional), "utf8").trim()
+    : positional;
+if (!text) die("input text is empty");
+
+const voiceId = await resolveVoiceId({ provider: "heygen", userVoice, lang });
+if (!userVoice) console.error(`· using voice ${voiceId}`);
+
+// ---------- synthesize (shared engine code) ----------
+const { ok, words, error } = await synthesizeOne({
+  provider: "heygen",
+  text,
+  voiceId,
+  lang,
+  speed,
+  wavAbs: output,
+  hyperframesDir: process.cwd(),
+});
+// HeyGen's own refusal, verbatim: a caller shows it or acts on it (a deleted voice, a limit).
+if (!ok) die(error ?? "synthesis failed (HeyGen request/transcode error)");
+
+let wordCount = 0;
+if (wordsPath) {
+  if (words && words.length) {
+    mkdirSync(dirname(wordsPath), { recursive: true });
+    writeFileSync(wordsPath, JSON.stringify(withWordIds(words), null, 2));
+    wordCount = words.length;
+  } else {
+    console.error("⚠ no word_timestamps in response — run `hyperframes transcribe` instead");
+  }
+}
+
+const dur = ffprobeDuration(output);
+const durStr = isFinite(dur) ? ` (${dur.toFixed(2)}s)` : "";
+console.log(`✓ ${output}${durStr}${wordCount ? ` · ${wordsPath} (${wordCount} words)` : ""}`);

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

@@ -0,0 +1,38 @@
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import { spawnSync } from "node:child_process";
+import { mkdtempSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const script = fileURLToPath(new URL("./heygen-tts.mjs", import.meta.url));
+// Every fetch answers as HeyGen does for a voice that no longer exists.
+const refusing = `data:text/javascript,globalThis.fetch = async () => new Response(${JSON.stringify(
+  JSON.stringify({ error: { code: "voice_not_found", message: "Voice not found: vc_gone" } }),
+)}, { status: 404, headers: { "content-type": "application/json" } });`;
+
+test("a refused speech prints HeyGen's own message, so a caller can act on it", () => {
+  const dir = mkdtempSync(join(tmpdir(), "heygen-tts-"));
+  const run = spawnSync(
+    process.execPath,
+    ["--import", refusing, script, "Hello", "--voice", "vc_gone", "-o", join(dir, "out.mp3")],
+    {
+      cwd: dir,
+      encoding: "utf8",
+      env: {
+        ...process.env,
+        HEYGEN_API_KEY: "",
+        HYPERFRAMES_API_KEY: "",
+        HEYGEN_ACCESS_TOKEN: "t",
+      },
+    },
+  );
+  assert.equal(run.status, 1);
+  assert.match(run.stderr, /✗ heygen-tts: Voice not found: vc_gone\n/);
+  assert.doesNotMatch(
+    run.stderr,
+    /HTTP 404|"error"/,
+    "HeyGen's message alone, not the raw response",
+  );
+});

package/vendor/hyperframes/dist/skills/media-use/audio/scripts/heygen-voice.mjs

@@ -0,0 +1,98 @@
+#!/usr/bin/env node
+// HeyGen voice clones: `clone <audio> --name <n>`, `delete <voice_id>`, `list --prefix <p>` (references/tts.md).
+// The clone id works as `heygen-tts.mjs --voice <id>`. A refusal prints HeyGen's own message and exits 1.
+// Auth: same resolver as heygen-tts.mjs (lib/heygen.mjs).
+
+import { readFileSync } from "node:fs";
+import { extname } from "node:path";
+import { fileURLToPath } from "node:url";
+import { parseArgs } from "node:util";
+import { heygenAuthHeaders, heygenJSON, heygenMessage, loadEnvFromDir } from "./lib/heygen.mjs";
+
+const MEDIA_TYPES = { ".mp3": "audio/mpeg", ".wav": "audio/wav" };
+const POLL_MS = 2_000;
+const DEADLINE_MS = 120_000;
+
+async function clone(file, name, headers, { sleep, now }) {
+  const mediaType = MEDIA_TYPES[extname(file).toLowerCase()];
+  if (!mediaType) throw new Error(`unsupported audio file ${file}: use .mp3 or .wav`);
+  const data = readFileSync(file).toString("base64");
+  const created = await heygenJSON("/voices/clone", {
+    method: "POST",
+    headers,
+    body: { voice_name: name, audio: { type: "base64", media_type: mediaType, data } },
+  });
+  const id = created.data.voice_clone_id;
+  const deadline = now() + DEADLINE_MS;
+  for (;;) {
+    const { data: voice } = await heygenJSON(`/voices/${id}`, { headers });
+    if (voice.status === "complete") return { voice_id: voice.voice_id ?? id };
+    if (voice.status === "failed") throw new Error(voice.failure_message || "voice clone failed");
+    if (now() >= deadline) throw new Error(`voice clone ${id} not ready after 120 s`);
+    await sleep(POLL_MS);
+  }
+}
+
+async function list(prefix, headers) {
+  const mine = [];
+  const seen = new Set();
+  let token;
+  do {
+    if (token && seen.has(token)) throw new Error(`HeyGen returned page token ${token} twice`);
+    if (token) seen.add(token);
+    const query = new URLSearchParams({ type: "private", limit: "100" });
+    if (token) query.set("token", token);
+    const page = await heygenJSON(`/voices?${query}`, { headers });
+    mine.push(...page.data.filter((v) => (v.name ?? "").startsWith(prefix)));
+    token = page.has_more ? page.next_token : null;
+  } while (token);
+  // ponytail: the list response has no created_at, so one GET per match; bounded by the clone limit.
+  return Promise.all(
+    mine.map(async ({ voice_id, name }) => {
+      const { data } = await heygenJSON(`/voices/${voice_id}`, { headers });
+      return { voice_id, name, created_at: data.created_at ?? null };
+    }),
+  );
+}
+
+export async function main(
+  argv,
+  {
+    sleep = (ms) => new Promise((r) => setTimeout(r, ms)),
+    now = Date.now,
+    out = (s) => process.stdout.write(`${s}\n`),
+    err = (s) => process.stderr.write(`${s}\n`),
+  } = {},
+) {
+  try {
+    const { positionals, values } = parseArgs({
+      args: argv,
+      allowPositionals: true,
+      options: { name: { type: "string" }, prefix: { type: "string", default: "" } },
+    });
+    const [command, arg] = positionals;
+    if (command === "clone") {
+      if (!arg || !values.name) throw new Error("usage: clone <audio-file> --name <name>");
+      out(JSON.stringify(await clone(arg, values.name, heygenAuthHeaders(), { sleep, now })));
+    } else if (command === "delete") {
+      if (!arg) throw new Error("usage: delete <voice_id>");
+      await heygenJSON(`/voices/${encodeURIComponent(arg)}`, {
+        method: "DELETE",
+        headers: heygenAuthHeaders(),
+      });
+    } else if (command === "list") {
+      out(JSON.stringify(await list(values.prefix, heygenAuthHeaders())));
+    } else {
+      throw new Error("usage: heygen-voice.mjs clone|delete|list (see the header of this file)");
+    }
+    return 0;
+  } catch (e) {
+    err(heygenMessage(e));
+    return 1;
+  }
+}
+
+if (process.argv[1] === fileURLToPath(import.meta.url)) {
+  loadEnvFromDir(process.cwd());
+  process.exitCode = await main(process.argv.slice(2));
+}

package/vendor/hyperframes/dist/skills/media-use/audio/scripts/heygen-voice.test.mjs

@@ -0,0 +1,233 @@
+import { afterEach, beforeEach, test } from "node:test";
+import assert from "node:assert/strict";
+import { mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { main } from "./heygen-voice.mjs";
+
+const realFetch = globalThis.fetch;
+const savedEnv = {
+  HEYGEN_ACCESS_TOKEN: process.env.HEYGEN_ACCESS_TOKEN,
+  HEYGEN_API_KEY: process.env.HEYGEN_API_KEY,
+};
+let dir;
+let calls;
+
+beforeEach(() => {
+  dir = mkdtempSync(join(tmpdir(), "heygen-voice-"));
+  delete process.env.HEYGEN_ACCESS_TOKEN;
+  process.env.HEYGEN_API_KEY = "hg_test";
+  calls = [];
+});
+
+afterEach(() => {
+  globalThis.fetch = realFetch;
+  for (const [k, v] of Object.entries(savedEnv)) {
+    if (v === undefined) delete process.env[k];
+    else process.env[k] = v;
+  }
+  rmSync(dir, { recursive: true, force: true });
+});
+
+// routes: "METHOD /path" → array of [status, body] answered in order (last one repeats).
+function mockFetch(routes) {
+  globalThis.fetch = async (url, opts) => {
+    const key = `${opts.method} ${String(url).replace("https://api.heygen.com/v3", "")}`;
+    calls.push({ key, opts });
+    const queue = routes[key];
+    if (!queue) throw new Error(`unexpected request ${key}`);
+    const [status, body] = queue.length > 1 ? queue.shift() : queue[0];
+    return new Response(body === undefined ? null : JSON.stringify(body), { status });
+  };
+}
+
+async function run(argv, { sleep = async () => {}, now = () => 0 } = {}) {
+  const out = [];
+  const err = [];
+  const code = await main(argv, {
+    sleep,
+    now,
+    out: (s) => out.push(s),
+    err: (s) => err.push(s),
+  });
+  return { code, out: out.join("\n"), err: err.join("\n") };
+}
+
+function audioFile(name = "sample.mp3") {
+  const path = join(dir, name);
+  writeFileSync(path, Buffer.from("fake-audio"));
+  return path;
+}
+
+test("clone uploads base64 audio, polls until complete, prints the voice id", async () => {
+  mockFetch({
+    "POST /voices/clone": [[200, { data: { voice_clone_id: "vc1" } }]],
+    "GET /voices/vc1": [
+      [200, { data: { status: "processing", voice_id: "vc1" } }],
+      [200, { data: { status: "complete", voice_id: "vc1", name: "Me" } }],
+    ],
+  });
+  const sleeps = [];
+  const r = await run(["clone", audioFile(), "--name", "Me"], {
+    sleep: async (ms) => sleeps.push(ms),
+  });
+  assert.deepEqual(r, { code: 0, out: '{"voice_id":"vc1"}', err: "" });
+  assert.deepEqual(sleeps, [2000]);
+  const post = calls[0];
+  assert.equal(post.opts.headers["X-Api-Key"], "hg_test");
+  assert.deepEqual(JSON.parse(post.opts.body), {
+    voice_name: "Me",
+    audio: {
+      type: "base64",
+      media_type: "audio/mpeg",
+      data: Buffer.from("fake-audio").toString("base64"),
+    },
+  });
+});
+
+test("clone sends audio/wav for a .wav file", async () => {
+  mockFetch({
+    "POST /voices/clone": [[200, { data: { voice_clone_id: "vc1" } }]],
+    "GET /voices/vc1": [[200, { data: { status: "complete", voice_id: "vc1" } }]],
+  });
+  const r = await run(["clone", audioFile("take.WAV"), "--name", "Me"]);
+  assert.equal(r.code, 0);
+  assert.equal(JSON.parse(calls[0].opts.body).audio.media_type, "audio/wav");
+});
+
+test("clone prints HeyGen's refusal verbatim and exits 1", async () => {
+  const message =
+    "Voice clone limit reached (10). Delete unused clones or contact support to increase your limit.";
+  mockFetch({
+    "POST /voices/clone": [[400, { error: { code: "resource_limit_reached", message } }]],
+  });
+  const r = await run(["clone", audioFile(), "--name", "Me"]);
+  assert.deepEqual(r, { code: 1, out: "", err: message });
+});
+
+test("clone surfaces a failed clone's failure_message", async () => {
+  mockFetch({
+    "POST /voices/clone": [[200, { data: { voice_clone_id: "vc1" } }]],
+    "GET /voices/vc1": [[200, { data: { status: "failed", failure_message: "Audio too noisy" } }]],
+  });
+  const r = await run(["clone", audioFile(), "--name", "Me"]);
+  assert.deepEqual(r, { code: 1, out: "", err: "Audio too noisy" });
+});
+
+test("clone gives up after the 120 s deadline", async () => {
+  mockFetch({
+    "POST /voices/clone": [[200, { data: { voice_clone_id: "vc1" } }]],
+    "GET /voices/vc1": [[200, { data: { status: "processing" } }]],
+  });
+  let clock = 0;
+  const r = await run(["clone", audioFile(), "--name", "Me"], {
+    now: () => clock,
+    sleep: async (ms) => {
+      clock += ms;
+    },
+  });
+  assert.deepEqual(r, { code: 1, out: "", err: "voice clone vc1 not ready after 120 s" });
+  assert.equal(calls.filter((c) => c.key === "GET /voices/vc1").length, 61);
+});
+
+test("clone rejects an audio type other than mp3 or wav without calling HeyGen", async () => {
+  mockFetch({});
+  const r = await run(["clone", audioFile("take.ogg"), "--name", "Me"]);
+  assert.equal(r.code, 1);
+  assert.match(r.err, /use \.mp3 or \.wav/);
+  assert.equal(calls.length, 0);
+});
+
+test("delete calls DELETE /voices/<id> and exits 0", async () => {
+  mockFetch({ "DELETE /voices/vc1": [[200, { data: {} }]] });
+  const r = await run(["delete", "vc1"]);
+  assert.deepEqual(r, { code: 0, out: "", err: "" });
+});
+
+test("delete exits 0 on a 204 with no body, and escapes the id in the path", async () => {
+  mockFetch({ "DELETE /voices/a%2Fb": [[204]] });
+  const r = await run(["delete", "a/b"]);
+  assert.deepEqual(r, { code: 0, out: "", err: "" });
+});
+
+test("clone falls back to the clone id when the finished voice has no voice_id", async () => {
+  mockFetch({
+    "POST /voices/clone": [[200, { data: { voice_clone_id: "vc9" } }]],
+    "GET /voices/vc9": [[200, { data: { status: "complete" } }]],
+  });
+  const r = await run(["clone", audioFile(), "--name", "Me"]);
+  assert.deepEqual(r, { code: 0, out: '{"voice_id":"vc9"}', err: "" });
+});
+
+test("list skips a nameless voice and stops on a page token HeyGen repeats", async () => {
+  mockFetch({
+    "GET /voices?type=private&limit=100": [
+      [200, { data: [{ voice_id: "n", name: null }], has_more: true, next_token: "t2" }],
+    ],
+    "GET /voices?type=private&limit=100&token=t2": [
+      [200, { data: [], has_more: true, next_token: "t2" }],
+    ],
+  });
+  // A fake answers at once, so a list that never stops would starve any timeout: cap the calls instead.
+  const answer = globalThis.fetch;
+  globalThis.fetch = (...args) =>
+    calls.length >= 10 ? Promise.reject(new Error("paged forever")) : answer(...args);
+  const r = await run(["list", "--prefix", "desk-"]);
+  assert.deepEqual(r, { code: 1, out: "", err: "HeyGen returned page token t2 twice" });
+});
+
+test("delete prints HeyGen's 404 message verbatim and exits 1", async () => {
+  mockFetch({
+    "DELETE /voices/gone": [
+      [404, { error: { code: "voice_not_found", message: "Voice not found: gone" } }],
+    ],
+  });
+  const r = await run(["delete", "gone"]);
+  assert.deepEqual(r, { code: 1, out: "", err: "Voice not found: gone" });
+});
+
+test("list pages through private voices and returns prefix matches with created_at", async () => {
+  mockFetch({
+    "GET /voices?type=private&limit=100": [
+      [
+        200,
+        {
+          data: [
+            { voice_id: "a", name: "desk-1" },
+            { voice_id: "b", name: "other" },
+          ],
+          has_more: true,
+          next_token: "t2",
+        },
+      ],
+    ],
+    "GET /voices?type=private&limit=100&token=t2": [
+      [200, { data: [{ voice_id: "c", name: "desk-2" }], has_more: false }],
+    ],
+    "GET /voices/a": [[200, { data: { voice_id: "a", created_at: 1700000000 } }]],
+    "GET /voices/c": [[200, { data: { voice_id: "c", created_at: 1700000100 } }]],
+  });
+  const r = await run(["list", "--prefix", "desk-"]);
+  assert.equal(r.code, 0);
+  assert.deepEqual(JSON.parse(r.out), [
+    { voice_id: "a", name: "desk-1", created_at: 1700000000 },
+    { voice_id: "c", name: "desk-2", created_at: 1700000100 },
+  ]);
+});
+
+test("list prints HeyGen's refusal verbatim and exits 1", async () => {
+  const message = "Invalid or expired API key. Verify your x-api-key header.";
+  mockFetch({
+    "GET /voices?type=private&limit=100": [[401, { error: { code: "unauthorized", message } }]],
+  });
+  const r = await run(["list", "--prefix", "desk-"]);
+  assert.deepEqual(r, { code: 1, out: "", err: message });
+});
+
+test("a host-injected HEYGEN_ACCESS_TOKEN is sent as Bearer", async () => {
+  process.env.HEYGEN_ACCESS_TOKEN = "at_host";
+  mockFetch({ "DELETE /voices/vc1": [[200, { data: {} }]] });
+  await run(["delete", "vc1"]);
+  assert.equal(calls[0].opts.headers.Authorization, "Bearer at_host");
+  assert.equal(calls[0].opts.headers["X-Api-Key"], undefined);
+});

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

@@ -0,0 +1,39 @@
+import { closeSync, ftruncateSync, openSync, readFileSync, writeSync } from "node:fs";
+
+// Keep the merge base and output on the same file even if its pathname changes
+// while audio generation runs. The CLI owns this handle until write or exit.
+export function openAudioMeta(path) {
+  let fd;
+  try {
+    fd = openSync(path, "r+");
+  } catch (error) {
+    if (error.code !== "ENOENT") throw error;
+  }
+  let value = {};
+  if (fd !== undefined) {
+    try {
+      value = JSON.parse(readFileSync(fd, "utf8"));
+    } catch (error) {
+      closeSync(fd);
+      throw error;
+    }
+  }
+  return {
+    value,
+    write(meta) {
+      const bytes = Buffer.from(JSON.stringify(meta, null, 2));
+      // Defer new-file creation until generation succeeds. Never overwrite a
+      // file (or follow a link) that appeared since the missing merge base.
+      if (fd === undefined) fd = openSync(path, "wx");
+      try {
+        let offset = 0;
+        while (offset < bytes.length) {
+          offset += writeSync(fd, bytes, offset, bytes.length - offset, offset);
+        }
+        ftruncateSync(fd, bytes.length);
+      } finally {
+        closeSync(fd);
+      }
+    },
+  };
+}

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

@@ -0,0 +1,136 @@
+import assert from "node:assert/strict";
+import { test } from "node:test";
+import {
+  mkdtempSync,
+  readFileSync,
+  renameSync,
+  rmSync,
+  statSync,
+  symlinkSync,
+  writeFileSync,
+} from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { spawnSync } from "node:child_process";
+import { fileURLToPath } from "node:url";
+import { openAudioMeta } from "./audio-meta.mjs";
+
+function fixture(t) {
+  const dir = mkdtempSync(join(tmpdir(), "audio-meta-"));
+  t.after(() => rmSync(dir, { recursive: true, force: true }));
+  return dir;
+}
+
+test("updates the read file from byte zero, truncates, and retains its mode", (t) => {
+  const path = join(fixture(t), "meta.json");
+  writeFileSync(path, JSON.stringify({ voices: ["long existing voice metadata"] }), {
+    mode: 0o600,
+  });
+  const originalMode = statSync(path).mode;
+  const handle = openAudioMeta(path);
+  assert.deepEqual(handle.value, { voices: ["long existing voice metadata"] });
+  handle.write({ voices: ["声"] });
+  assert.equal(readFileSync(path, "utf8"), JSON.stringify({ voices: ["声"] }, null, 2));
+  assert.equal(statSync(path).mode, originalMode);
+});
+
+test("pathname replacement cannot redirect the existing-file write", (t) => {
+  const dir = fixture(t);
+  const path = join(dir, "meta.json");
+  const moved = join(dir, "original.json");
+  writeFileSync(path, "{}");
+  const handle = openAudioMeta(path);
+  renameSync(path, moved);
+  writeFileSync(path, "replacement must survive");
+  handle.write({ voices: [] });
+  assert.equal(readFileSync(path, "utf8"), "replacement must survive");
+  assert.deepEqual(JSON.parse(readFileSync(moved, "utf8")), { voices: [] });
+});
+
+test("existing symlink outputs retain their original target even after retargeting", (t) => {
+  const dir = fixture(t);
+  const path = join(dir, "meta.json");
+  const target = join(dir, "target.json");
+  const victim = join(dir, "victim.json");
+  writeFileSync(target, "{}");
+  writeFileSync(victim, "untouched");
+  symlinkSync(target, path);
+  const handle = openAudioMeta(path);
+  rmSync(path);
+  symlinkSync(victim, path);
+  handle.write({ bgm: null });
+  assert.equal(readFileSync(victim, "utf8"), "untouched");
+  assert.deepEqual(JSON.parse(readFileSync(target, "utf8")), { bgm: null });
+});
+
+test("missing output is created only when saved", (t) => {
+  const path = join(fixture(t), "meta.json");
+  const handle = openAudioMeta(path);
+  assert.deepEqual(handle.value, {});
+  assert.throws(() => statSync(path), { code: "ENOENT" });
+  handle.write({ sfx: [] });
+  assert.deepEqual(JSON.parse(readFileSync(path, "utf8")), { sfx: [] });
+});
+
+for (const replacement of ["file", "symlink"]) {
+  test(`new output does not overwrite a racing ${replacement}`, (t) => {
+    const dir = fixture(t);
+    const path = join(dir, "meta.json");
+    const victim = join(dir, "victim.json");
+    const handle = openAudioMeta(path);
+    writeFileSync(victim, "untouched");
+    if (replacement === "symlink") symlinkSync(victim, path);
+    else writeFileSync(path, "untouched");
+    assert.throws(() => handle.write({}), { code: "EEXIST" });
+    assert.equal(readFileSync(path, "utf8"), "untouched");
+    assert.equal(readFileSync(victim, "utf8"), "untouched");
+  });
+}
+
+test("malformed merge base remains an error without changing bytes", (t) => {
+  const path = join(fixture(t), "meta.json");
+  writeFileSync(path, "bad json");
+  assert.throws(() => openAudioMeta(path), SyntaxError);
+  assert.equal(readFileSync(path, "utf8"), "bad json");
+});
+
+test("CLI partial run retains unselected voices, BGM and SFX", (t) => {
+  const dir = fixture(t);
+  const path = join(dir, "meta.json");
+  const request = join(dir, "request.json");
+  const previous = {
+    voices: [{ id: "a", duration_s: 2 }],
+    bgm: { path: "bgm.wav" },
+    sfx: [{ name: "click" }],
+    tts_provider: "kokoro",
+    voice_id: "voice-a",
+  };
+  writeFileSync(path, JSON.stringify(previous));
+  writeFileSync(request, "{}");
+  const result = spawnSync(
+    process.execPath,
+    [
+      fileURLToPath(new URL("../audio.mjs", import.meta.url)),
+      "--request",
+      request,
+      "--hyperframes",
+      dir,
+      "--out",
+      path,
+      "--only",
+      "none",
+    ],
+    {
+      encoding: "utf8",
+      env: {
+        ...process.env,
+        HEYGEN_CONFIG_DIR: dir,
+        HEYGEN_API_KEY: "",
+        HYPERFRAMES_API_KEY: "",
+      },
+    },
+  );
+  assert.equal(result.status, 0, result.stderr);
+  const actual = JSON.parse(readFileSync(path, "utf8"));
+  for (const key of Object.keys(previous)) assert.deepEqual(actual[key], previous[key]);
+});

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

@@ -0,0 +1,4 @@
+// Music sits under narration; a silent film brings music forward.
+export const BGM_BED_VOLUME = 0.12;
+export const BGM_SILENT_VOLUME = 0.9;
+export const bgmDefaultVolume = (hasVoice) => (hasVoice ? BGM_BED_VOLUME : BGM_SILENT_VOLUME);