From 976781345a02cfeabe5bce2feb4dca13f3ab3c2e Mon Sep 17 00:00:00 2001
From: miga-heygen <miguel.sierra_miga@heygen.com>
Date: Wed, 16 Sep 2026 13:31:19 +0000
Subject: [PATCH 1/3] fix(media-use): reconcile disk-only narration WAVs into
 the audio ledger
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

A narration WAV can land in assets/voice/<id>.wav without ever going
through this engine's own TTS synthesis loop: hand-placed, copied over
from another project, or left behind by a run that wrote the file but
didn't finish registering it. audio_meta.json's voices[] only grows
inside that loop, so a file like this was invisible to every consumer
that trusts voices[] (each skill's assemble-index.mjs <audio> emission,
captions.mjs) with zero warning — the render succeeds and simply plays
without that narration line.

Reconcile assets/voice/ against voices[] on every engine invocation,
independent of --only, before the BGM sizing decision that depends on
voices[]. Only backfills ids the current request still asks for with
non-empty text, so a stale file from a since-edited or since-cleared
script line is left untouched, not resurrected. Extracted the line's
"has real text" check into a shared lineText() helper so the synthesis
loop and the new reconciliation pass can't drift on that decision.

Co-Authored-By: Miguel Ángel <miguel.sierra@heygen.com>
---
 skills-manifest.json                          |   4 +-
 skills/media-use/audio/scripts/audio.mjs      |  43 +++++-
 .../audio/scripts/audio.reconcile.test.mjs    | 145 ++++++++++++++++++
 3 files changed, 188 insertions(+), 4 deletions(-)
 create mode 100644 skills/media-use/audio/scripts/audio.reconcile.test.mjs

diff --git a/skills-manifest.json b/skills-manifest.json
index e411541e93..e6bc5578c9 100644
--- a/skills-manifest.json
+++ b/skills-manifest.json
@@ -50,8 +50,8 @@
       "files": 12
     },
     "media-use": {
-      "hash": "08a544dfaca9e846",
-      "files": 158
+      "hash": "2d9427289f60e8c6",
+      "files": 159
     },
     "motion-graphics": {
       "hash": "32641ae2b94c4a8f",
diff --git a/skills/media-use/audio/scripts/audio.mjs b/skills/media-use/audio/scripts/audio.mjs
index 167eb679ca..3df6b8956d 100644
--- a/skills/media-use/audio/scripts/audio.mjs
+++ b/skills/media-use/audio/scripts/audio.mjs
@@ -39,7 +39,7 @@
 // the generate path it is spawned detached (bgm_pending:true) — run wait-bgm.mjs
 // before assembling.
 
-import { existsSync, mkdirSync, readFileSync } from "node:fs";
+import { existsSync, mkdirSync, readdirSync, readFileSync } from "node:fs";
 import { dirname, join, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
 import { heygenAuthHeaders, heygenCredential, loadEnvFromDir } from "./lib/heygen.mjs";
@@ -68,6 +68,7 @@ const die = (m) => {
   process.exit(1);
 };
 const r3 = (x) => Number(x.toFixed(3));
+const lineText = (line) => String(line.text ?? "").trim();
 
 // Two independent reports of an unbounded Promise.all over TTS lines
 // overwhelming a machine: one OOM'd 12/13 concurrent Kokoro TTS +
@@ -140,7 +141,7 @@ if (only.has("tts") && lines.length) {
   console.error(`· tts: ${ttsProvider} · voice ${voiceId} · ${lines.length} line(s)`);
   const synthLine = async (line) => {
     const id = String(line.id);
-    const text = String(line.text ?? "").trim();
+    const text = lineText(line);
     if (!text) {
       anomalies.push(`line ${id}: empty text — skipped`);
       return null;
@@ -174,6 +175,44 @@ if (only.has("tts") && lines.length) {
   for (const v of voices)
     console.error(`  voice ${v.id}: ${v.path} (${v.duration_s}s, ${v.words.length} words)`);
 }
+
+// ── reconcile externally-supplied narration ──────────────────────────────────
+// A narration WAV can land in assets/voice/<id>.wav without ever going
+// through the synthLine loop above — hand-placed, copied over from another
+// run, or left behind by one that generated the file but didn't finish
+// registering it. voices[] only ever grows inside that loop, so such a file
+// is invisible to every consumer that trusts voices[] (assemble-index.mjs's
+// <audio> emission, captions.mjs) with zero warning. Runs every invocation,
+// independent of --only, so a workflow that reassembles after only bgm/sfx
+// still picks up a line that TTS registered in an earlier run and a manual
+// drop-in registers on the very next run. Only reconciles ids the current
+// request still asks for AND still has real text for (`lines`, same
+// empty-text exclusion synthLine uses above) — a stale file from a
+// since-edited or since-cleared script line is left alone, not resurrected.
+const voiceDir = join(hyperframesDir, "assets", "voice");
+if (lines.length && existsSync(voiceDir)) {
+  const expectedIds = new Set(lines.filter(lineText).map((l) => String(l.id)));
+  const knownIds = new Set(voices.map((v) => String(v.id)));
+  for (const file of readdirSync(voiceDir)) {
+    if (!file.endsWith(".wav")) continue;
+    const id = file.slice(0, -".wav".length);
+    if (knownIds.has(id) || !expectedIds.has(id)) continue;
+    const rel = `assets/voice/${file}`;
+    const dur = ffprobeDuration(join(hyperframesDir, rel));
+    if (!isFinite(dur) || dur <= 0) {
+      anomalies.push(
+        `voice ${id}: found ${rel} on disk but couldn't read its duration — not reconciled`,
+      );
+      continue;
+    }
+    // No word timing is available for a file that never went through TTS —
+    // captions.mjs simply has nothing to render for this line, same as any
+    // other voice with an empty words[] today.
+    voices.push({ id, path: rel, duration_s: r3(dur), words: [] });
+    knownIds.add(id);
+    anomalies.push(`voice ${id}: found ${rel} on disk, missing from the ledger — reconciled`);
+  }
+}
 const hasVoice = voices.length > 0;
 const totalDuration = r3(voices.reduce((a, v) => a + (v.duration_s || 0), 0));
 
diff --git a/skills/media-use/audio/scripts/audio.reconcile.test.mjs b/skills/media-use/audio/scripts/audio.reconcile.test.mjs
new file mode 100644
index 0000000000..add7f2d911
--- /dev/null
+++ b/skills/media-use/audio/scripts/audio.reconcile.test.mjs
@@ -0,0 +1,145 @@
+import assert from "node:assert/strict";
+import { existsSync, mkdirSync, mkdtempSync, readFileSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { spawnSync } from "node:child_process";
+import test from "node:test";
+
+// Regression: a narration WAV that lands in assets/voice/<id>.wav without ever
+// going through this engine's own TTS loop (hand-placed, copied from another
+// run, or left over from an interrupted one) used to be invisible to every
+// consumer that trusts audio_meta.json's voices[] — assemble-index.mjs never
+// emits an <audio> element for it, with no warning at all. The fix
+// reconciles assets/voice/ against voices[] on every engine invocation.
+
+const engineScript = new URL("./audio.mjs", import.meta.url).pathname;
+const HAS_FFMPEG =
+  spawnSync("ffmpeg", ["-version"], { stdio: "ignore" }).status === 0 &&
+  spawnSync("ffprobe", ["-version"], { stdio: "ignore" }).status === 0;
+
+function setupProject({ lines, existingVoices, voiceFiles }) {
+  const dir = mkdtempSync(join(tmpdir(), "mu-audio-reconcile-"));
+  writeFileSync(join(dir, "audio_request.json"), JSON.stringify({ lines }));
+  if (existingVoices) {
+    writeFileSync(
+      join(dir, "audio_meta.json"),
+      JSON.stringify({ bgm: null, voices: existingVoices, sfx: [] }),
+    );
+  }
+  if (voiceFiles?.length) {
+    const voiceDir = join(dir, "assets", "voice");
+    mkdirSync(voiceDir, { recursive: true });
+    for (const file of voiceFiles) {
+      // 1s silent tone — small, deterministic, real enough for ffprobe to read a duration.
+      const gen = spawnSync(
+        "ffmpeg",
+        ["-y", "-f", "lavfi", "-i", "anullsrc=r=8000:cl=mono", "-t", "1", join(voiceDir, file)],
+        { encoding: "utf8" },
+      );
+      assert.equal(gen.status, 0, gen.stderr);
+    }
+  }
+  return dir;
+}
+
+function runEngine(dir, extraArgs = []) {
+  const outPath = join(dir, "audio_meta.json");
+  const r = spawnSync(
+    process.execPath,
+    [
+      engineScript,
+      "--request",
+      join(dir, "audio_request.json"),
+      "--hyperframes",
+      dir,
+      "--out",
+      outPath,
+      "--only",
+      "",
+      ...extraArgs,
+    ],
+    { encoding: "utf8" },
+  );
+  assert.equal(r.status, 0, r.stderr);
+  return JSON.parse(readFileSync(outPath, "utf8"));
+}
+
+test(
+  "a narration WAV present on disk but missing from the ledger is backfilled",
+  { skip: !HAS_FFMPEG },
+  () => {
+    const dir = setupProject({
+      lines: [{ id: "01", text: "Hello" }],
+      existingVoices: [],
+      voiceFiles: ["01.wav"],
+    });
+
+    const meta = runEngine(dir);
+
+    assert.equal(meta.voices.length, 1, JSON.stringify(meta));
+    assert.equal(meta.voices[0].id, "01");
+    assert.equal(meta.voices[0].path, "assets/voice/01.wav");
+    assert.ok(meta.voices[0].duration_s > 0, "expected a real, positive duration");
+    assert.deepEqual(meta.voices[0].words, []);
+  },
+);
+
+test("a voice already present in the ledger is not duplicated", { skip: !HAS_FFMPEG }, () => {
+  const dir = setupProject({
+    lines: [{ id: "01", text: "Hello" }],
+    existingVoices: [{ id: "01", path: "assets/voice/01.wav", duration_s: 2.5, words: [] }],
+    voiceFiles: ["01.wav"],
+  });
+
+  const meta = runEngine(dir);
+
+  assert.equal(meta.voices.length, 1);
+  // The pre-existing ledger entry wins verbatim — reconciliation only fills gaps.
+  assert.equal(meta.voices[0].duration_s, 2.5);
+});
+
+test(
+  "a stale WAV for a line the current script no longer asks for is left alone",
+  { skip: !HAS_FFMPEG },
+  () => {
+    const dir = setupProject({
+      lines: [{ id: "01", text: "Hello" }],
+      existingVoices: [],
+      voiceFiles: ["01.wav", "99.wav"],
+    });
+
+    const meta = runEngine(dir);
+
+    assert.equal(meta.voices.length, 1);
+    assert.equal(meta.voices[0].id, "01");
+    assert.ok(
+      !meta.voices.some((v) => v.id === "99"),
+      "a file with no matching request line must not be resurrected",
+    );
+  },
+);
+
+test(
+  "a WAV for a line whose text was since cleared is left alone, not resurrected",
+  { skip: !HAS_FFMPEG },
+  () => {
+    const dir = setupProject({
+      lines: [{ id: "01", text: "   " }],
+      existingVoices: [],
+      voiceFiles: ["01.wav"],
+    });
+
+    const meta = runEngine(dir);
+
+    assert.deepEqual(meta.voices, [], "empty-text line must not resurrect a leftover WAV");
+  },
+);
+
+test("no assets/voice directory at all is a no-op, not a crash", { skip: !HAS_FFMPEG }, () => {
+  const dir = setupProject({ lines: [{ id: "01", text: "Hello" }], existingVoices: [] });
+  assert.equal(existsSync(join(dir, "assets", "voice")), false);
+
+  const meta = runEngine(dir);
+
+  assert.deepEqual(meta.voices, []);
+});

From f255dec219df566db8e63a2ce4124dc32ec3c9ed Mon Sep 17 00:00:00 2001
From: miga-heygen <miguel.sierra_miga@heygen.com>
Date: Wed, 16 Sep 2026 13:34:43 +0000
Subject: [PATCH 2/3] test(media-use): clean up reconcile test fixtures and
 drop dead tracking
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

knownIds.add(id) inside the reconciliation loop could never affect
anything: id is derived uniquely from each disk filename, and readdirSync
never returns the same filename twice in one pass, so no iteration could
ever re-observe an id it just added. Removed it along with the unused
extraArgs parameter on the test's runEngine helper, and switched the test
fixtures to the house mkdtempSync/t.after(cleanup) pattern already used
elsewhere in this skill (skills/media-use/scripts/dither.test.mjs) instead
of leaking a temp directory per test run.

Co-Authored-By: Miguel Ángel <miguel.sierra@heygen.com>
---
 skills-manifest.json                          |  2 +-
 skills/media-use/audio/scripts/audio.mjs      |  3 +-
 .../audio/scripts/audio.reconcile.test.mjs    | 59 +++++++++++--------
 3 files changed, 37 insertions(+), 27 deletions(-)

diff --git a/skills-manifest.json b/skills-manifest.json
index e6bc5578c9..6f20ee091b 100644
--- a/skills-manifest.json
+++ b/skills-manifest.json
@@ -50,7 +50,7 @@
       "files": 12
     },
     "media-use": {
-      "hash": "2d9427289f60e8c6",
+      "hash": "996aae05cefb6062",
       "files": 159
     },
     "motion-graphics": {
diff --git a/skills/media-use/audio/scripts/audio.mjs b/skills/media-use/audio/scripts/audio.mjs
index 3df6b8956d..c15ec61ad9 100644
--- a/skills/media-use/audio/scripts/audio.mjs
+++ b/skills/media-use/audio/scripts/audio.mjs
@@ -191,7 +191,7 @@ if (only.has("tts") && lines.length) {
 // since-edited or since-cleared script line is left alone, not resurrected.
 const voiceDir = join(hyperframesDir, "assets", "voice");
 if (lines.length && existsSync(voiceDir)) {
-  const expectedIds = new Set(lines.filter(lineText).map((l) => String(l.id)));
+  const expectedIds = new Set(lines.filter((l) => lineText(l)).map((l) => String(l.id)));
   const knownIds = new Set(voices.map((v) => String(v.id)));
   for (const file of readdirSync(voiceDir)) {
     if (!file.endsWith(".wav")) continue;
@@ -209,7 +209,6 @@ if (lines.length && existsSync(voiceDir)) {
     // captions.mjs simply has nothing to render for this line, same as any
     // other voice with an empty words[] today.
     voices.push({ id, path: rel, duration_s: r3(dur), words: [] });
-    knownIds.add(id);
     anomalies.push(`voice ${id}: found ${rel} on disk, missing from the ledger — reconciled`);
   }
 }
diff --git a/skills/media-use/audio/scripts/audio.reconcile.test.mjs b/skills/media-use/audio/scripts/audio.reconcile.test.mjs
index add7f2d911..4d2f26a772 100644
--- a/skills/media-use/audio/scripts/audio.reconcile.test.mjs
+++ b/skills/media-use/audio/scripts/audio.reconcile.test.mjs
@@ -1,5 +1,5 @@
 import assert from "node:assert/strict";
-import { existsSync, mkdirSync, mkdtempSync, readFileSync, writeFileSync } from "node:fs";
+import { existsSync, mkdirSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
 import { spawnSync } from "node:child_process";
@@ -17,7 +17,7 @@ const HAS_FFMPEG =
   spawnSync("ffmpeg", ["-version"], { stdio: "ignore" }).status === 0 &&
   spawnSync("ffprobe", ["-version"], { stdio: "ignore" }).status === 0;
 
-function setupProject({ lines, existingVoices, voiceFiles }) {
+function fixture({ lines, existingVoices, voiceFiles }) {
   const dir = mkdtempSync(join(tmpdir(), "mu-audio-reconcile-"));
   writeFileSync(join(dir, "audio_request.json"), JSON.stringify({ lines }));
   if (existingVoices) {
@@ -39,11 +39,14 @@ function setupProject({ lines, existingVoices, voiceFiles }) {
       assert.equal(gen.status, 0, gen.stderr);
     }
   }
-  return dir;
+  return { dir, cleanup: () => rmSync(dir, { recursive: true, force: true }) };
 }
 
-function runEngine(dir, extraArgs = []) {
+function runEngine(dir) {
   const outPath = join(dir, "audio_meta.json");
+  // --only "" disables the tts/bgm/sfx stages entirely (none of their names
+  // appear in the empty split), so only the unconditional reconciliation
+  // pass runs — no TTS provider or network access needed for this test.
   const r = spawnSync(
     process.execPath,
     [
@@ -56,7 +59,6 @@ function runEngine(dir, extraArgs = []) {
       outPath,
       "--only",
       "",
-      ...extraArgs,
     ],
     { encoding: "utf8" },
   );
@@ -67,12 +69,13 @@ function runEngine(dir, extraArgs = []) {
 test(
   "a narration WAV present on disk but missing from the ledger is backfilled",
   { skip: !HAS_FFMPEG },
-  () => {
-    const dir = setupProject({
+  (t) => {
+    const { dir, cleanup } = fixture({
       lines: [{ id: "01", text: "Hello" }],
       existingVoices: [],
       voiceFiles: ["01.wav"],
     });
+    t.after(cleanup);
 
     const meta = runEngine(dir);
 
@@ -84,29 +87,35 @@ test(
   },
 );
 
-test("a voice already present in the ledger is not duplicated", { skip: !HAS_FFMPEG }, () => {
-  const dir = setupProject({
-    lines: [{ id: "01", text: "Hello" }],
-    existingVoices: [{ id: "01", path: "assets/voice/01.wav", duration_s: 2.5, words: [] }],
-    voiceFiles: ["01.wav"],
-  });
+test(
+  "a voice already present in the ledger is not duplicated",
+  { skip: !HAS_FFMPEG },
+  (t) => {
+    const { dir, cleanup } = fixture({
+      lines: [{ id: "01", text: "Hello" }],
+      existingVoices: [{ id: "01", path: "assets/voice/01.wav", duration_s: 2.5, words: [] }],
+      voiceFiles: ["01.wav"],
+    });
+    t.after(cleanup);
 
-  const meta = runEngine(dir);
+    const meta = runEngine(dir);
 
-  assert.equal(meta.voices.length, 1);
-  // The pre-existing ledger entry wins verbatim — reconciliation only fills gaps.
-  assert.equal(meta.voices[0].duration_s, 2.5);
-});
+    assert.equal(meta.voices.length, 1);
+    // The pre-existing ledger entry wins verbatim — reconciliation only fills gaps.
+    assert.equal(meta.voices[0].duration_s, 2.5);
+  },
+);
 
 test(
   "a stale WAV for a line the current script no longer asks for is left alone",
   { skip: !HAS_FFMPEG },
-  () => {
-    const dir = setupProject({
+  (t) => {
+    const { dir, cleanup } = fixture({
       lines: [{ id: "01", text: "Hello" }],
       existingVoices: [],
       voiceFiles: ["01.wav", "99.wav"],
     });
+    t.after(cleanup);
 
     const meta = runEngine(dir);
 
@@ -122,12 +131,13 @@ test(
 test(
   "a WAV for a line whose text was since cleared is left alone, not resurrected",
   { skip: !HAS_FFMPEG },
-  () => {
-    const dir = setupProject({
+  (t) => {
+    const { dir, cleanup } = fixture({
       lines: [{ id: "01", text: "   " }],
       existingVoices: [],
       voiceFiles: ["01.wav"],
     });
+    t.after(cleanup);
 
     const meta = runEngine(dir);
 
@@ -135,8 +145,9 @@ test(
   },
 );
 
-test("no assets/voice directory at all is a no-op, not a crash", { skip: !HAS_FFMPEG }, () => {
-  const dir = setupProject({ lines: [{ id: "01", text: "Hello" }], existingVoices: [] });
+test("no assets/voice directory at all is a no-op, not a crash", { skip: !HAS_FFMPEG }, (t) => {
+  const { dir, cleanup } = fixture({ lines: [{ id: "01", text: "Hello" }], existingVoices: [] });
+  t.after(cleanup);
   assert.equal(existsSync(join(dir, "assets", "voice")), false);
 
   const meta = runEngine(dir);

From 1772ce7ef61c09d2e304b9a40d5d9fbc36160292 Mon Sep 17 00:00:00 2001
From: miga-heygen <miguel.sierra_miga@heygen.com>
Date: Wed, 16 Sep 2026 13:42:00 +0000
Subject: [PATCH 3/3] style(media-use): satisfy oxfmt on the new reconciliation
 test file
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Co-Authored-By: Miguel Ángel <miguel.sierra@heygen.com>
---
 skills-manifest.json                          |  2 +-
 .../audio/scripts/audio.reconcile.test.mjs    | 28 ++++++++-----------
 2 files changed, 13 insertions(+), 17 deletions(-)

diff --git a/skills-manifest.json b/skills-manifest.json
index 6f20ee091b..7706e7f56f 100644
--- a/skills-manifest.json
+++ b/skills-manifest.json
@@ -50,7 +50,7 @@
       "files": 12
     },
     "media-use": {
-      "hash": "996aae05cefb6062",
+      "hash": "a7208c47707dfab0",
       "files": 159
     },
     "motion-graphics": {
diff --git a/skills/media-use/audio/scripts/audio.reconcile.test.mjs b/skills/media-use/audio/scripts/audio.reconcile.test.mjs
index 4d2f26a772..f9a73e7021 100644
--- a/skills/media-use/audio/scripts/audio.reconcile.test.mjs
+++ b/skills/media-use/audio/scripts/audio.reconcile.test.mjs
@@ -87,24 +87,20 @@ test(
   },
 );
 
-test(
-  "a voice already present in the ledger is not duplicated",
-  { skip: !HAS_FFMPEG },
-  (t) => {
-    const { dir, cleanup } = fixture({
-      lines: [{ id: "01", text: "Hello" }],
-      existingVoices: [{ id: "01", path: "assets/voice/01.wav", duration_s: 2.5, words: [] }],
-      voiceFiles: ["01.wav"],
-    });
-    t.after(cleanup);
+test("a voice already present in the ledger is not duplicated", { skip: !HAS_FFMPEG }, (t) => {
+  const { dir, cleanup } = fixture({
+    lines: [{ id: "01", text: "Hello" }],
+    existingVoices: [{ id: "01", path: "assets/voice/01.wav", duration_s: 2.5, words: [] }],
+    voiceFiles: ["01.wav"],
+  });
+  t.after(cleanup);
 
-    const meta = runEngine(dir);
+  const meta = runEngine(dir);
 
-    assert.equal(meta.voices.length, 1);
-    // The pre-existing ledger entry wins verbatim — reconciliation only fills gaps.
-    assert.equal(meta.voices[0].duration_s, 2.5);
-  },
-);
+  assert.equal(meta.voices.length, 1);
+  // The pre-existing ledger entry wins verbatim — reconciliation only fills gaps.
+  assert.equal(meta.voices[0].duration_s, 2.5);
+});
 
 test(
   "a stale WAV for a line the current script no longer asks for is left alone",