heygen-com/hyperframes · critical

The soundfile package is not installed. Run: pip install sou

Error message

The soundfile package is not installed. Run: pip install soundfile

What it means

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.

Source

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

  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 }),
  ]);

  // 3. Ensure synthesis script is cached
  const scriptPath = ensureSynthScript();

  // 4. Ensure output directory exists
  mkdirSync(dirname(outputPath), { recursive: true });

  // 5. Run synthesis
  options?.onProgress?.(`Generating speech with voice ${voice} (${lang})...`);
  try {
    const espeakLang = ESPEAK_LANG_OVERRIDES[lang] ?? lang;

View on GitHub (pinned to c2996c8626)

Solutions

1. Install soundfile into the probed interpreter: `<resolved-python> -m pip install soundfile`.
2. On Alpine/musl, also `apk add libsndfile` (or switch to a glibc-based image).
3. Verify by hand: `<resolved-python> -c 'import soundfile; print(soundfile.__version__)'`.
4. If reinstalling, clear the wheel cache: `pip install --force-reinstall --no-cache-dir soundfile`.

Example fix

# before
$HYPERFRAMES_PYTHON -m pip install kokoro-onnx   # soundfile missing
# after
$HYPERFRAMES_PYTHON -m pip install kokoro-onnx soundfile

import { execFileSync } from 'node:child_process';

const python = process.env.HYPERFRAMES_PYTHON ?? 'python3';
try {
  execFileSync(python, ['-c', 'import soundfile'], { stdio: 'pipe', timeout: 10_000 });
} catch {
  throw new Error(`Run: ${python} -m pip install soundfile`);
}

try {
  await synthesize(text, out, { voice });
} catch (err) {
  if (err instanceof Error && /soundfile package is not installed/.test(err.message)) {
    console.error(err.message); // install hint
  } else throw err;
}

When it happens

Trigger: 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.

Common situations: 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.

Related errors

• Python 3 is required for text-to-speech. Install Python 3.10
• The kokoro-onnx package is not installed. Run: pip install k
• Failed to load @puppeteer/browsers: ${cause} Fix: run `npm i
• remove-background needs the optional native module '${name}'
• CUDA execution provider not available. Use --device cpu or i

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