fix(hyperframes-media): surface the real HeyGen TTS error instead of a generic message

synthesizeHeygen's catch block collapsed every failure into a bare
{ ok: false }, discarding heygenJSON's own thrown error - which already
carries the HTTP status and response body (e.g. "HeyGen POST
/voices/speech -> HTTP 402\nplan_upgrade_required..."). Callers only ever
saw "synthesis failed (HeyGen request/transcode error)" or "TTS failed -
omitted", with no way to tell a free-plan 402 from a transient 500,
forcing a manual REST call just to diagnose. Now threads an `error` field
through synthesizeOne's return value from every heygen failure branch
(missing audio_url, failed audio download, failed transcode, and the
underlying HTTP error) and both callers (heygen-tts.mjs, audio.mjs)
surface it instead of the generic fallback.

Author: miguel-heygen

skills-manifest.json

@@ -38,8 +38,8 @@
       "files": 3
     },
     "hyperframes-media": {
-      "hash": "096b2ab0a43b05dd",
-      "files": 40
+      "hash": "edf35041e6a5ca11",
+      "files": 41
     },
     "hyperframes-registry": {
       "hash": "e3b389526834109d",

skills/hyperframes-media/scripts/audio.mjs

@@ -134,7 +134,7 @@ if (only.has("tts") && lines.length) {
     }
     const rel = `assets/voice/${id}.wav`;
     const abs = join(hyperframesDir, rel);
-    const { ok, words } = await synthesizeOne({
+    const { ok, words, error } = await synthesizeOne({
       provider: ttsProvider,
       text,
       voiceId,
@@ -144,7 +144,7 @@ if (only.has("tts") && lines.length) {
       hyperframesDir,
     });
     if (!ok) {
-      anomalies.push(`line ${id}: TTS failed — omitted`);
+      anomalies.push(`line ${id}: TTS failed${error ? ` (${error})` : ""} — omitted`);
       return null;
     }
     let wordArr = words; // heygen: native; else transcribe

skills/hyperframes-media/scripts/heygen-tts.mjs

@@ -94,7 +94,7 @@ const voiceId = await resolveVoiceId({ provider: "heygen", userVoice, lang });
 if (!userVoice) console.error(`· using voice ${voiceId}`);
 
 // ---------- synthesize (shared engine code) ----------
-const { ok, words } = await synthesizeOne({
+const { ok, words, error } = await synthesizeOne({
   provider: "heygen",
   text,
   voiceId,
@@ -103,7 +103,9 @@ const { ok, words } = await synthesizeOne({
   wavAbs: output,
   hyperframesDir: process.cwd(),
 });
-if (!ok) die("synthesis failed (HeyGen request/transcode error)");
+if (!ok) {
+  die(error ? `synthesis failed: ${error}` : "synthesis failed (HeyGen request/transcode error)");
+}
 
 let wordCount = 0;
 if (wordsPath) {

skills/hyperframes-media/scripts/lib/tts.mjs

@@ -122,9 +122,13 @@ save(audio, sys.argv[3])
 `;
 
 // ── synthesize one line ───────────────────────────────────────────────────────
-// Writes wav at wavAbs. Returns { ok, words } — words is the raw
+// Writes wav at wavAbs. Returns { ok, words, error? } — words is the raw
 // [{text,start,end}] array for HeyGen (native), or null for ElevenLabs/Kokoro
 // (caller must transcribeWav). Never throws; failures return { ok:false }.
+// `error` is only populated for the heygen provider, where the underlying
+// HTTP failure (e.g. a 402 plan-upgrade response) carries a real diagnostic
+// message worth surfacing — a spawned CLI's bare exit code for the other two
+// providers doesn't.
 export async function synthesizeOne({
   provider,
   text,
@@ -161,14 +165,24 @@ async function synthesizeHeygen({ text, voiceId, lang, speed, wavAbs }) {
       body,
     });
     const inner = payload.data ?? payload;
-    if (!inner.audio_url) return { ok: false, words: null };
+    if (!inner.audio_url) {
+      return { ok: false, words: null, error: "HeyGen response had no audio_url" };
+    }
     const res = await fetch(inner.audio_url);
-    if (!res.ok) return { ok: false, words: null };
+    if (!res.ok) {
+      return {
+        ok: false,
+        words: null,
+        error: `failed to download synthesized audio: HTTP ${res.status}`,
+      };
+    }
     const bytes = Buffer.from(await res.arrayBuffer());
     // .wav output → transcode to 44.1k mono; .mp3 → raw bytes (no ffmpeg). The
     // engine always asks for .wav; the standalone heygen-tts CLI may ask for .mp3.
     if (wavAbs.endsWith(".wav")) {
-      if (!transcodeToWav(bytes, wavAbs)) return { ok: false, words: null };
+      if (!transcodeToWav(bytes, wavAbs)) {
+        return { ok: false, words: null, error: "ffmpeg transcode to wav failed" };
+      }
     } else {
       mkdirSync(dirname(wavAbs), { recursive: true });
       writeFileSync(wavAbs, bytes);
@@ -180,8 +194,13 @@ async function synthesizeHeygen({ text, voiceId, lang, speed, wavAbs }) {
           .map((w) => ({ text: w.word, start: w.start, end: w.end }))
       : [];
     return { ok: true, words };
-  } catch {
-    return { ok: false, words: null };
+  } catch (e) {
+    // heygenJSON's own thrown Error already carries the HTTP status and
+    // response body (e.g. "HeyGen POST /voices/speech → HTTP 402
+    // plan_upgrade_required..."). Surfacing it here, not swallowing it, is
+    // the whole fix — callers used to see nothing but a generic "synthesis
+    // failed" with no way to tell a plan-upgrade 402 from a transient 500.
+    return { ok: false, words: null, error: e.message };
   }
 }
 

skills/hyperframes-media/scripts/lib/tts.test.mjs

@@ -0,0 +1,75 @@
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import { mkdtempSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { synthesizeOne } from "./tts.mjs";
+
+// Regression: synthesizeHeygen used to collapse every failure (a real HTTP
+// error from HeyGen, a missing audio_url, a failed transcode) into a bare
+// { ok: false }, so callers could never tell a 402 plan-upgrade response
+// from a transient 500 or a local ffmpeg problem. heygenJSON already throws
+// a message carrying the HTTP status and response body — the fix is just to
+// stop swallowing it. Exercised via the real synthesizeOne() -> heygenJSON()
+// -> global fetch() path (heygenJSON has no seam to mock other than fetch
+// itself, which is a real global here, not a per-module import).
+test("synthesizeOne surfaces the real HeyGen HTTP error instead of a bare ok:false", async () => {
+  const dir = mkdtempSync(join(tmpdir(), "heygen-tts-error-"));
+  const originalFetch = globalThis.fetch;
+  const originalApiKey = process.env.HEYGEN_API_KEY;
+  try {
+    process.env.HEYGEN_API_KEY = "fake-key-for-test";
+    globalThis.fetch = async () => ({
+      ok: false,
+      status: 402,
+      text: async () => JSON.stringify({ error: "plan_upgrade_required" }),
+    });
+
+    const result = await synthesizeOne({
+      provider: "heygen",
+      text: "hello",
+      voiceId: "some-voice",
+      wavAbs: join(dir, "out.wav"),
+      hyperframesDir: dir,
+    });
+
+    assert.equal(result.ok, false);
+    assert.match(result.error, /HTTP 402/);
+    assert.match(result.error, /plan_upgrade_required/);
+  } finally {
+    globalThis.fetch = originalFetch;
+    if (originalApiKey === undefined) delete process.env.HEYGEN_API_KEY;
+    else process.env.HEYGEN_API_KEY = originalApiKey;
+    rmSync(dir, { recursive: true, force: true });
+  }
+});
+
+test("synthesizeOne reports a missing audio_url distinctly from an HTTP error", async () => {
+  const dir = mkdtempSync(join(tmpdir(), "heygen-tts-no-url-"));
+  const originalFetch = globalThis.fetch;
+  const originalApiKey = process.env.HEYGEN_API_KEY;
+  try {
+    process.env.HEYGEN_API_KEY = "fake-key-for-test";
+    globalThis.fetch = async () => ({
+      ok: true,
+      status: 200,
+      json: async () => ({ data: {} }),
+    });
+
+    const result = await synthesizeOne({
+      provider: "heygen",
+      text: "hello",
+      voiceId: "some-voice",
+      wavAbs: join(dir, "out.wav"),
+      hyperframesDir: dir,
+    });
+
+    assert.equal(result.ok, false);
+    assert.match(result.error, /no audio_url/);
+  } finally {
+    globalThis.fetch = originalFetch;
+    if (originalApiKey === undefined) delete process.env.HEYGEN_API_KEY;
+    else process.env.HEYGEN_API_KEY = originalApiKey;
+    rmSync(dir, { recursive: true, force: true });
+  }
+});