Skip to content

fix(hyperframes-media): surface the real reason a TTS line failed [P2]#1999

Draft
miguel-heygen wants to merge 1 commit into
mainfrom
fix/heygen-tts-surface-error
Draft

fix(hyperframes-media): surface the real reason a TTS line failed [P2]#1999
miguel-heygen wants to merge 1 commit into
mainfrom
fix/heygen-tts-surface-error

Conversation

@miguel-heygen

Copy link
Copy Markdown
Collaborator

Problem

synthesizeHeygen() swallowed every failure into a bare { ok: false }:

  • a thrown HTTP error (e.g. 402 plan_upgrade_required from heygenJSON) was caught and discarded by a bare catch {},
  • a missing audio_url, a failed audio fetch, and a failed transcode each returned { ok:false } with no reason.

audio.mjs then logged line N: TTS failed — omitted for every line with zero diagnostic detail, so the actual cause (a plan/billing error, an auth problem, etc.) took a hand-rolled repro script to find. Reported from real usage: "surface e.message in the anomaly text."

Fix

Every failure path now returns an { error } string stating why — the caught exception message, the HTTP status, the missing audio_url, or the failed transcode stage — and audio.mjs appends it to the anomaly (TTS failed — omitted (<error>)). The subprocess providers (elevenlabs / kokoro) get the same treatment via a shared synthResult() helper (naming the non-zero exit or the missing wav).

synthesizeHeygen takes an optional injectable deps arg (defaults to the real network/ffmpeg impls) purely so the failure paths are unit-testable.

Verification

tts.test.mjs (node:test) — 4 new tests, 9 total pass: a thrown 402 surfaces in error (contains 402 + plan_upgrade_required); a non-ok audio fetch surfaces its HTTP status; a missing audio_url is named; synthResult names a non-zero subprocess exit. No behavior change on the success path.

@miguel-heygen miguel-heygen changed the title fix(hyperframes-media): surface the real reason a TTS line failed [P2] fix(hyperframes-media): surface the real reason a TTS line failed Jul 7, 2026
@miguel-heygen miguel-heygen changed the title [P2] fix(hyperframes-media): surface the real reason a TTS line failed fix(hyperframes-media): surface the real reason a TTS line failed [P2] Jul 7, 2026
synthesizeHeygen() swallowed every failure into a bare { ok:false }: a thrown
HTTP error (e.g. 402 plan_upgrade_required from heygenJSON) was caught and
discarded, a missing audio_url / failed audio fetch / failed transcode all
returned nothing. audio.mjs then logged 'TTS failed — omitted' for every line
with zero detail, so the actual cause took a hand-rolled repro to find.

Each failure path now returns an { error } string (the caught message, the HTTP
status, or the specific stage that failed), and audio.mjs appends it to the
anomaly. The subprocess providers (elevenlabs/kokoro) get the same treatment via
a shared synthResult() helper. synthesizeHeygen takes an injectable deps arg so
the failure paths are unit-tested (thrown 402, non-ok fetch, missing audio_url).
@miguel-heygen miguel-heygen force-pushed the fix/heygen-tts-surface-error branch from 9fef490 to 7e4e2dd Compare July 8, 2026 02:43
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant