{"record":{"id":"69413d9018341a77","repo":"heygen-com/hyperframes","slug":"python-3-is-required-for-text-to-speech-install-p","errorCode":null,"errorMessage":"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)","messagePattern":"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\\)","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"critical","filePath":"packages/cli/src/tts/synthesize.ts","lineNumber":134,"sourceCode":"\n/**\n * Synthesize text to speech using Kokoro-82M via kokoro-onnx.\n */\n// fallow-ignore-next-line complexity\nexport async function synthesize(\n  text: string,\n  outputPath: string,\n  options?: SynthesizeOptions,\n): Promise<SynthesizeResult> {\n  const voice = options?.voice ?? DEFAULT_VOICE;\n  const speed = options?.speed ?? 1.0;\n  const lang: SupportedLang = options?.lang ?? inferLangFromVoiceId(voice);\n\n  // 1. Ensure Python 3 is available with kokoro-onnx\n  options?.onProgress?.(\"Checking Python runtime...\");\n  const python = findPython();\n  if (!python) {\n    throw new Error(\n      \"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)\",\n    );\n  }\n\n  if (!hasPythonPackage(python, \"kokoro_onnx\")) {\n    throw new Error(\n      \"The kokoro-onnx package is not installed. Run: pip install kokoro-onnx soundfile (or point HYPERFRAMES_PYTHON at a venv python that has them)\",\n    );\n  }\n\n  if (!hasPythonPackage(python, \"soundfile\")) {\n    throw new Error(\"The soundfile package is not installed. Run: pip install soundfile\");\n  }\n\n  // 2. Ensure model and voices are downloaded (parallel on first run)\n  const [modelPath, voicesPath] = await Promise.all([\n    ensureModel(options?.model, { onProgress: options?.onProgress }),\n    ensureVoices({ onProgress: options?.onProgress }),","sourceCodeStart":116,"sourceCodeEnd":152,"githubUrl":"https://github.com/heygen-com/hyperframes/blob/c2996c8626135db5253519359d8a063d3bafad8d/packages/cli/src/tts/synthesize.ts#L116-L152","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Install Python 3.10+ (system package, pyenv, or conda) and ensure python3 --version prints 'Python 3.x'.","pip install kokoro-onnx soundfile into that interpreter (the next two checks will otherwise fail).","If Python already lives in a venv, export HYPERFRAMES_PYTHON=/abs/path/to/venv/bin/python so the probe skips PATH entirely.","Verify the interpreter is discoverable: run the same probe the library uses — `python3 --version` — and confirm it prints 'Python 3'.","On Windows, ensure python3 or python is resolvable by `where python3` (the library uses `where`, not PATH alone)."],"exampleFix":"# before\nexport HYPERFRAMES_PYTHON=  # empty, falls back to PATH which has no python3\nhyperframes render --voice ...\n# after\npython3 -m venv ~/.venvs/hf-tts\n~/.venvs/hf-tts/bin/pip install kokoro-onnx soundfile\nexport HYPERFRAMES_PYTHON=~/.venvs/hf-tts/bin/python\nhyperframes render --voice ...","handlingStrategy":"validation","validationCode":"import { execFileSync } from 'node:child_process';\n\nfunction resolvePython(): string | undefined {\n  const override = process.env.HYPERFRAMES_PYTHON;\n  const candidates = override ? [override] : ['python3', 'python'];\n  for (const c of candidates) {\n    try {\n      const v = execFileSync(c, ['--version'], { encoding: 'utf-8', stdio: 'pipe', timeout: 5000 });\n      if (/Python 3\\./.test(v)) return c;\n    } catch { /* not found */ }\n  }\n  return undefined;\n}\n\n// run BEFORE calling synthesize()\nconst python = resolvePython();\nif (!python) {\n  throw new Error('Install Python 3.10+ or set HYPERFRAMES_PYTHON before using TTS.');\n}","typeGuard":null,"tryCatchPattern":"import { synthesize } from '@hyperframes/cli/tts/synthesize';\n\ntry {\n  const result = await synthesize(text, outPath, { voice });\n} catch (err) {\n  if (err instanceof Error && /Python 3 is required/.test(err.message)) {\n    // environment-setup path: prompt the user to install Python / set HYPERFRAMES_PYTHON\n    console.error(err.message);\n    process.exitCode = 2;\n  } else {\n    throw err;\n  }\n}","preventionTips":["Set HYPERFRAMES_PYTHON in your environment to an absolute venv python that already has kokoro-onnx + soundfile.","Run a preflight readiness check (the CLI exposes a doctor/auth-status probe) before invoking TTS in CI.","Pin the Python version and packages in a requirements.txt or pyproject.toml alongside the project."],"tags":["tts","python-runtime","environment","kokoro","dependency"],"backgroundTag":null,"analyzedSha":"c2996c8626135db5253519359d8a063d3bafad8d","analyzedAt":"2026-08-12T22:18:56.877Z","schemaVersion":2},"datasetVersion":"2026-08-12T23:17:12.415Z"}