Skip to content

Commit 5fc70db

Browse files
committed
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.
1 parent af5f3e5 commit 5fc70db

5 files changed

Lines changed: 102 additions & 12 deletions

File tree

‎skills-manifest.json‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -42,7 +42,7 @@
4242
"files": 3
4343
},
4444
"hyperframes-media": {
45-
"hash": "eb72d0765185b36d",
45+
"hash": "9cf2c41b10147eba",
4646
"files": 44
4747
},
4848
"hyperframes-registry": {

‎skills/hyperframes-media/scripts/audio.mjs‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -145,7 +145,7 @@ if (only.has("tts") && lines.length) {
145145
}
146146
const rel = `assets/voice/${id}.wav`;
147147
const abs = join(hyperframesDir, rel);
148-
const { ok, words } = await synthesizeOne({
148+
const { ok, words, error } = await synthesizeOne({
149149
provider: ttsProvider,
150150
text,
151151
voiceId,
@@ -155,7 +155,7 @@ if (only.has("tts") && lines.length) {
155155
hyperframesDir,
156156
});
157157
if (!ok) {
158-
anomalies.push(`line ${id}: TTS failed — omitted`);
158+
anomalies.push(`line ${id}: TTS failed${error ? ` (${error})` : ""} — omitted`);
159159
return null;
160160
}
161161
let wordArr = words; // heygen: native; else transcribe

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

Lines changed: 4 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -94,7 +94,7 @@ const voiceId = await resolveVoiceId({ provider: "heygen", userVoice, lang });
9494
if (!userVoice) console.error(`· using voice ${voiceId}`);
9595

9696
// ---------- synthesize (shared engine code) ----------
97-
const { ok, words } = await synthesizeOne({
97+
const { ok, words, error } = await synthesizeOne({
9898
provider: "heygen",
9999
text,
100100
voiceId,
@@ -103,7 +103,9 @@ const { ok, words } = await synthesizeOne({
103103
wavAbs: output,
104104
hyperframesDir: process.cwd(),
105105
});
106-
if (!ok) die("synthesis failed (HeyGen request/transcode error)");
106+
if (!ok) {
107+
die(error ? `synthesis failed: ${error}` : "synthesis failed (HeyGen request/transcode error)");
108+
}
107109

108110
let wordCount = 0;
109111
if (wordsPath) {

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

Lines changed: 25 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -200,9 +200,13 @@ save(audio, sys.argv[3])
200200
`;
201201

202202
// ── synthesize one line ───────────────────────────────────────────────────────
203-
// Writes wav at wavAbs. Returns { ok, words } — words is the raw
203+
// Writes wav at wavAbs. Returns { ok, words, error? } — words is the raw
204204
// [{text,start,end}] array for HeyGen (native), or null for ElevenLabs/Kokoro
205205
// (caller must transcribeWav). Never throws; failures return { ok:false }.
206+
// `error` is only populated for the heygen provider, where the underlying
207+
// HTTP failure (e.g. a 402 plan-upgrade response) carries a real diagnostic
208+
// message worth surfacing — a spawned CLI's bare exit code for the other two
209+
// providers doesn't.
206210
export async function synthesizeOne({
207211
provider,
208212
text,
@@ -239,14 +243,24 @@ async function synthesizeHeygen({ text, voiceId, lang, speed, wavAbs }) {
239243
body,
240244
});
241245
const inner = payload.data ?? payload;
242-
if (!inner.audio_url) return { ok: false, words: null };
246+
if (!inner.audio_url) {
247+
return { ok: false, words: null, error: "HeyGen response had no audio_url" };
248+
}
243249
const res = await fetch(inner.audio_url);
244-
if (!res.ok) return { ok: false, words: null };
250+
if (!res.ok) {
251+
return {
252+
ok: false,
253+
words: null,
254+
error: `failed to download synthesized audio: HTTP ${res.status}`,
255+
};
256+
}
245257
const bytes = Buffer.from(await res.arrayBuffer());
246258
// .wav output → transcode to 44.1k mono; .mp3 → raw bytes (no ffmpeg). The
247259
// engine always asks for .wav; the standalone heygen-tts CLI may ask for .mp3.
248260
if (wavAbs.endsWith(".wav")) {
249-
if (!transcodeToWav(bytes, wavAbs)) return { ok: false, words: null };
261+
if (!transcodeToWav(bytes, wavAbs)) {
262+
return { ok: false, words: null, error: "ffmpeg transcode to wav failed" };
263+
}
250264
} else {
251265
mkdirSync(dirname(wavAbs), { recursive: true });
252266
writeFileSync(wavAbs, bytes);
@@ -258,8 +272,13 @@ async function synthesizeHeygen({ text, voiceId, lang, speed, wavAbs }) {
258272
.map((w) => ({ text: w.word, start: w.start, end: w.end }))
259273
: [];
260274
return { ok: true, words };
261-
} catch {
262-
return { ok: false, words: null };
275+
} catch (e) {
276+
// heygenJSON's own thrown Error already carries the HTTP status and
277+
// response body (e.g. "HeyGen POST /voices/speech → HTTP 402
278+
// plan_upgrade_required..."). Surfacing it here, not swallowing it, is
279+
// the whole fix — callers used to see nothing but a generic "synthesis
280+
// failed" with no way to tell a plan-upgrade 402 from a transient 500.
281+
return { ok: false, words: null, error: e.message };
263282
}
264283
}
265284

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

Lines changed: 70 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -3,7 +3,7 @@ import assert from "node:assert/strict";
33
import { mkdtempSync, writeFileSync, chmodSync, rmSync } from "node:fs";
44
import { join } from "node:path";
55
import { tmpdir } from "node:os";
6-
import { parseFfmpegDurationBanner, ffprobeDuration } from "./tts.mjs";
6+
import { parseFfmpegDurationBanner, ffprobeDuration, synthesizeOne } from "./tts.mjs";
77

88
test("parseFfmpegDurationBanner reads ffmpeg's stderr Duration line", () => {
99
const stderr = [
@@ -64,3 +64,72 @@ test("ffprobeDuration returns NaN when neither ffprobe nor ffmpeg resolve", () =
6464
rmSync(dir, { recursive: true, force: true });
6565
}
6666
});
67+
68+
// Regression: synthesizeHeygen used to collapse every failure (a real HTTP
69+
// error from HeyGen, a missing audio_url, a failed transcode) into a bare
70+
// { ok: false }, so callers could never tell a 402 plan-upgrade response
71+
// from a transient 500 or a local ffmpeg problem. heygenJSON already throws
72+
// a message carrying the HTTP status and response body — the fix is just to
73+
// stop swallowing it. Exercised via the real synthesizeOne() -> heygenJSON()
74+
// -> global fetch() path (heygenJSON has no seam to mock other than fetch
75+
// itself, which is a real global here, not a per-module import).
76+
test("synthesizeOne surfaces the real HeyGen HTTP error instead of a bare ok:false", async () => {
77+
const dir = mkdtempSync(join(tmpdir(), "heygen-tts-error-"));
78+
const originalFetch = globalThis.fetch;
79+
const originalApiKey = process.env.HEYGEN_API_KEY;
80+
try {
81+
process.env.HEYGEN_API_KEY = "fake-key-for-test";
82+
globalThis.fetch = async () => ({
83+
ok: false,
84+
status: 402,
85+
text: async () => JSON.stringify({ error: "plan_upgrade_required" }),
86+
});
87+
88+
const result = await synthesizeOne({
89+
provider: "heygen",
90+
text: "hello",
91+
voiceId: "some-voice",
92+
wavAbs: join(dir, "out.wav"),
93+
hyperframesDir: dir,
94+
});
95+
96+
assert.equal(result.ok, false);
97+
assert.match(result.error, /HTTP 402/);
98+
assert.match(result.error, /plan_upgrade_required/);
99+
} finally {
100+
globalThis.fetch = originalFetch;
101+
if (originalApiKey === undefined) delete process.env.HEYGEN_API_KEY;
102+
else process.env.HEYGEN_API_KEY = originalApiKey;
103+
rmSync(dir, { recursive: true, force: true });
104+
}
105+
});
106+
107+
test("synthesizeOne reports a missing audio_url distinctly from an HTTP error", async () => {
108+
const dir = mkdtempSync(join(tmpdir(), "heygen-tts-no-url-"));
109+
const originalFetch = globalThis.fetch;
110+
const originalApiKey = process.env.HEYGEN_API_KEY;
111+
try {
112+
process.env.HEYGEN_API_KEY = "fake-key-for-test";
113+
globalThis.fetch = async () => ({
114+
ok: true,
115+
status: 200,
116+
json: async () => ({ data: {} }),
117+
});
118+
119+
const result = await synthesizeOne({
120+
provider: "heygen",
121+
text: "hello",
122+
voiceId: "some-voice",
123+
wavAbs: join(dir, "out.wav"),
124+
hyperframesDir: dir,
125+
});
126+
127+
assert.equal(result.ok, false);
128+
assert.match(result.error, /no audio_url/);
129+
} finally {
130+
globalThis.fetch = originalFetch;
131+
if (originalApiKey === undefined) delete process.env.HEYGEN_API_KEY;
132+
else process.env.HEYGEN_API_KEY = originalApiKey;
133+
rmSync(dir, { recursive: true, force: true });
134+
}
135+
});

0 commit comments

Comments
 (0)