What causes "Speech synthesis failed${detail}" in heygen-com/hyperframes?

Read the detail (last 500 chars of stderr) — it carries the Python traceback; address the specific exception it names.

Speech synthesis failed

Error message

Speech synthesis failed${detail}

What it means

The catch-all at the end of synthesize()'s try block. Fires when execFileSync threw a non-SyntaxError (i.e. the Python process exited non-zero, was killed by the 300s timeout, or could not be spawned), OR when JSON.parse threw but the output file does NOT exist (so it is not the [244] path). detail appends the last 500 chars of stderr when present on the thrown error object, so the message usually carries the Python traceback.

Solutions

Read the detail (last 500 chars of stderr) — it carries the Python traceback; address the specific exception it names.
Re-download the model: delete the cached Kokoro model and voices under the HF cache dir and rerun (ensureModel/ensureVoices will re-fetch).
Install espeak-ng system-wide if the error mentions phonemization for a non-English lang.
For timeout (300s) on long text, synthesize shorter segments and concatenate.
Run the cached synth-v2.py manually with the same argv to reproduce the Python-side error outside the library.

Defensive patterns

Strategy: try-catch

Try / catch

try {
  return await synthesize(text, out, { voice });
} catch (err) {
  if (err instanceof Error && err.message.startsWith('Speech synthesis failed')) {
    // err.message includes the last 500 chars of the Python stderr — inspect it
    console.error('TTS subprocess error:', err.message);
    // retry with shorter text, a different voice, or after re-downloading the model
  }
  throw err;
}

Prevention

Keep the Kokoro model/voices cache intact — re-run ensureModel/ensureVoices if downloads were interrupted.
Install espeak-ng system-wide before using non-English voices.
Chunk very long texts to stay well under the 300s subprocess timeout.
Capture and log the embedded stderr tail to diagnose the underlying Python exception quickly.

When it happens

Trigger: Python raised during model load (corrupt/missing Kokoro model file), during phonemization (unsupported voice id, espeak-ng missing for non-English lang), OOM during inference, the 300_000ms execFileSync timeout fired, or the model/voices paths passed in argv do not exist. Any unhandled Python exception produces a non-zero exit → this error.

Common situations: First-run model download was interrupted leaving a truncated .onnx; voice id not present in voices.bin; espeak-ng not installed on the system for Mandarin/other non-English langs; very long input text exceeding memory; a GPU/CPU mismatch in onnxruntime causing a crash at inference.

Related errors

AI-assisted analysis of heygen-com/hyperframes@c2996c8626 (2026-08-12). Data as JSON: /api/errors/1176768f993b5c78. Report an issue: GitHub.

Appendix: source

Thrown at packages/cli/src/tts/synthesize.ts:209

      sampleRate: result.sampleRate,
      durationSeconds: result.durationSeconds,
      langApplied: result.langApplied,
    };
  } catch (err: unknown) {
    // If the error is our own JSON parse failure but the file was created,
    // re-throw with a clearer message rather than returning fabricated data
    if (err instanceof SyntaxError && existsSync(outputPath)) {
      throw new Error(
        "Speech was generated but metadata could not be read. Check the output file manually.",
      );
    }

    let detail = "";
    if (err && typeof err === "object" && "stderr" in err) {
      const stderr = String(err.stderr).trim();
      if (stderr) detail = `\n${stderr.slice(-500)}`;
    }
    throw new Error(`Speech synthesis failed${detail}`);
  }
}

View on GitHub (pinned to c2996c8626)