heygen-com/hyperframes · critical

Python 3 is required for text-to-speech. Install Python 3.10

Error message

Python 3 is required for text-to-speech. Install Python 3.10+ and run: pip install kokoro-onnx soundfile (or point HYPERFRAMES_PYTHON at a venv python that has them)

What it means

Thrown by synthesize() when findPython() returns undefined — the TTS pipeline (Kokoro-82M via kokoro-onnx) requires a Python 3 interpreter and this library shells out to it via execFileSync. findPython() first checks the HYPERFRAMES_PYTHON env override, then probes python3 and python on PATH, verifying each emits a 'Python 3' version string. If none of the three routes yields a usable interpreter, synthesis cannot proceed.

Source

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

/**
 * Synthesize text to speech using Kokoro-82M via kokoro-onnx.
 */
// fallow-ignore-next-line complexity
export async function synthesize(
  text: string,
  outputPath: string,
  options?: SynthesizeOptions,
): Promise<SynthesizeResult> {
  const voice = options?.voice ?? DEFAULT_VOICE;
  const speed = options?.speed ?? 1.0;
  const lang: SupportedLang = options?.lang ?? inferLangFromVoiceId(voice);

  // 1. Ensure Python 3 is available with kokoro-onnx
  options?.onProgress?.("Checking Python runtime...");
  const python = findPython();
  if (!python) {
    throw new Error(
      "Python 3 is required for text-to-speech. Install Python 3.10+ and run: pip install kokoro-onnx soundfile (or point HYPERFRAMES_PYTHON at a venv python that has them)",
    );
  }

  if (!hasPythonPackage(python, "kokoro_onnx")) {
    throw new Error(
      "The kokoro-onnx package is not installed. Run: pip install kokoro-onnx soundfile (or point HYPERFRAMES_PYTHON at a venv python that has them)",
    );
  }

  if (!hasPythonPackage(python, "soundfile")) {
    throw new Error("The soundfile package is not installed. Run: pip install soundfile");
  }

  // 2. Ensure model and voices are downloaded (parallel on first run)
  const [modelPath, voicesPath] = await Promise.all([
    ensureModel(options?.model, { onProgress: options?.onProgress }),
    ensureVoices({ onProgress: options?.onProgress }),

View on GitHub (pinned to c2996c8626)

Solutions

1. Install Python 3.10+ (system package, pyenv, or conda) and ensure python3 --version prints 'Python 3.x'.
2. pip install kokoro-onnx soundfile into that interpreter (the next two checks will otherwise fail).
3. If Python already lives in a venv, export HYPERFRAMES_PYTHON=/abs/path/to/venv/bin/python so the probe skips PATH entirely.
4. Verify the interpreter is discoverable: run the same probe the library uses — `python3 --version` — and confirm it prints 'Python 3'.
5. On Windows, ensure python3 or python is resolvable by `where python3` (the library uses `where`, not PATH alone).

Example fix

# before
export HYPERFRAMES_PYTHON=  # empty, falls back to PATH which has no python3
hyperframes render --voice ...
# after
python3 -m venv ~/.venvs/hf-tts
~/.venvs/hf-tts/bin/pip install kokoro-onnx soundfile
export HYPERFRAMES_PYTHON=~/.venvs/hf-tts/bin/python
hyperframes render --voice ...

import { execFileSync } from 'node:child_process';

function resolvePython(): string | undefined {
  const override = process.env.HYPERFRAMES_PYTHON;
  const candidates = override ? [override] : ['python3', 'python'];
  for (const c of candidates) {
    try {
      const v = execFileSync(c, ['--version'], { encoding: 'utf-8', stdio: 'pipe', timeout: 5000 });
      if (/Python 3\./.test(v)) return c;
    } catch { /* not found */ }
  }
  return undefined;
}

// run BEFORE calling synthesize()
const python = resolvePython();
if (!python) {
  throw new Error('Install Python 3.10+ or set HYPERFRAMES_PYTHON before using TTS.');
}

import { synthesize } from '@hyperframes/cli/tts/synthesize';

try {
  const result = await synthesize(text, outPath, { voice });
} catch (err) {
  if (err instanceof Error && /Python 3 is required/.test(err.message)) {
    // environment-setup path: prompt the user to install Python / set HYPERFRAMES_PYTHON
    console.error(err.message);
    process.exitCode = 2;
  } else {
    throw err;
  }
}

When it happens

Trigger: Calling synthesize() (directly or via a CLI command that does TTS) on a machine where: HYPERFRAMES_PYTHON is unset/empty, neither python3 nor python is on PATH, or every discovered interpreter is Python 2. Also when HYPERFRAMES_PYTHON points at a binary that fails to start or times out within the 5s --version probe.

Common situations: Fresh CI runner or Docker image without Python preinstalled; macOS where only python3 exists but is not linked; a venv whose python was moved/deleted after HYPERFRAMES_PYTHON was set; system-default python being Python 2 on older distros; PATH shadowing where a python shim (pyenv, asdf) errors during version detection.

Related errors

• The kokoro-onnx package is not installed. Run: pip install k
• The soundfile package is not installed. Run: pip install sou
• Failed to load @puppeteer/browsers: ${cause} Fix: run `npm i
• Synthesis completed but no output file was created
• Speech was generated but metadata could not be read. Check t

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