{"record":{"id":"643ca01c0316d405","repo":"heygen-com/hyperframes","slug":"the-soundfile-package-is-not-installed-run-pip-i","errorCode":null,"errorMessage":"The soundfile package is not installed. Run: pip install soundfile","messagePattern":"The soundfile package is not installed\\. Run: pip install soundfile","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"critical","filePath":"packages/cli/src/tts/synthesize.ts","lineNumber":146,"sourceCode":"  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 }),\n  ]);\n\n  // 3. Ensure synthesis script is cached\n  const scriptPath = ensureSynthScript();\n\n  // 4. Ensure output directory exists\n  mkdirSync(dirname(outputPath), { recursive: true });\n\n  // 5. Run synthesis\n  options?.onProgress?.(`Generating speech with voice ${voice} (${lang})...`);\n  try {\n    const espeakLang = ESPEAK_LANG_OVERRIDES[lang] ?? lang;","sourceCodeStart":128,"sourceCodeEnd":164,"githubUrl":"https://github.com/heygen-com/hyperframes/blob/c2996c8626135db5253519359d8a063d3bafad8d/packages/cli/src/tts/synthesize.ts#L128-L164","documentation":"Thrown when kokoro_onnx imports fine but hasPythonPackage(python, 'soundfile') returns false. soundfile (libsndfile bindings) is what the inline synth script uses to write the output WAV; without it the Python side could synthesize samples but could not persist them. The probe runs `python -c 'import soundfile'`, so it also fails on a broken libsndfile.","triggerScenarios":"kokoro-onnx is installed but soundfile was omitted from the same pip install command; soundfile wheel present but system libsndfile missing (rare on modern wheels, common on minimal Alpine/musl images); numpy ABI drift breaking the soundfile import.","commonSituations":"User ran `pip install kokoro-onnx` alone (the error message for [241] suggests installing both, but a partial install or network failure mid-install leaves only one); Alpine/musl-based Docker images where libsndfile must be installed via apk; a Python upgrade that left soundfile compiled against an older numpy.","solutions":["Install soundfile into the probed interpreter: `<resolved-python> -m pip install soundfile`.","On Alpine/musl, also `apk add libsndfile` (or switch to a glibc-based image).","Verify by hand: `<resolved-python> -c 'import soundfile; print(soundfile.__version__)'`.","If reinstalling, clear the wheel cache: `pip install --force-reinstall --no-cache-dir soundfile`."],"exampleFix":"# before\n$HYPERFRAMES_PYTHON -m pip install kokoro-onnx   # soundfile missing\n# after\n$HYPERFRAMES_PYTHON -m pip install kokoro-onnx soundfile","handlingStrategy":"validation","validationCode":"import { execFileSync } from 'node:child_process';\n\nconst python = process.env.HYPERFRAMES_PYTHON ?? 'python3';\ntry {\n  execFileSync(python, ['-c', 'import soundfile'], { stdio: 'pipe', timeout: 10_000 });\n} catch {\n  throw new Error(`Run: ${python} -m pip install soundfile`);\n}","typeGuard":null,"tryCatchPattern":"try {\n  await synthesize(text, out, { voice });\n} catch (err) {\n  if (err instanceof Error && /soundfile package is not installed/.test(err.message)) {\n    console.error(err.message); // install hint\n  } else throw err;\n}","preventionTips":["Always install kokoro-onnx and soundfile together (the install hint in [240] names both).","On Alpine/musl images, also `apk add libsndfile` — the soundfile wheel needs the system lib.","Verify imports after every Python or package upgrade."],"tags":["tts","python-runtime","dependency","soundfile","libsndfile","environment"],"backgroundTag":null,"analyzedSha":"c2996c8626135db5253519359d8a063d3bafad8d","analyzedAt":"2026-08-12T22:18:56.877Z","schemaVersion":2},"datasetVersion":"2026-08-12T23:17:12.415Z"}