ffmpeg is required to extract audio from video. Install: ${g

Error message

ffmpeg is required to extract audio from video. Install: ${getFFmpegInstallHint()}

What it means

Thrown by extractAudio when ffmpeg cannot be found on the system and the input to transcription is a video file. ffmpeg is required to demux and extract the audio track as 16kHz mono WAV (the format whisper requires). Without ffmpeg, there is no way to get audio from a video file for transcription. The error includes a platform-specific install hint.

Source

Thrown at packages/cli/src/whisper/transcribe.ts:308

 *
 * MUST be unique per call AND per process: callers run many `transcribe`
 * invocations in parallel (e.g. the product-launch-video audio pipeline spawns
 * one `hyperframes transcribe` per scene at once). A `Date.now()`-based name
 * collides when two conversions land in the same millisecond — they clobber
 * each other's WAV in the shared tmpdir, so whisper transcribes the wrong
 * scene's audio and every colliding scene gets identical word timings.
 */
function tempWavPath(): string {
  return join(tmpdir(), `hyperframes-audio-${process.pid}-${randomUUID()}.wav`);
}

/**
 * Extract audio from a video file as 16kHz mono WAV (whisper requirement).
 */
function extractAudio(videoPath: string): string {
  const ffmpegPath = findFFmpeg();
  if (!ffmpegPath) {
    throw new Error(
      `ffmpeg is required to extract audio from video. Install: ${getFFmpegInstallHint()}`,
    );
  }
  const wavPath = tempWavPath();
  execFileSync(
    ffmpegPath,
    ["-i", videoPath, "-vn", "-ar", "16000", "-ac", "1", "-f", "wav", "-y", wavPath],
    {
      stdio: "ignore",
      timeout: resolveAudioPreparationTimeoutMs(getMediaDurationSeconds(videoPath)),
    },
  );
  return wavPath;
}

/**
 * Check if a WAV file is already 16kHz mono via ffprobe.
 */

View on GitHub (pinned to c2996c8626)

Solutions

Install ffmpeg: macOS (brew install ffmpeg), Debian/Ubuntu (apt install ffmpeg), Fedora (dnf install ffmpeg), Windows (download from ffmpeg.org or use winget install ffmpeg).
If ffmpeg is installed but not found, add its directory to PATH or set HYPERFRAMES_FFMPEG to the binary path.
If you already have a 16kHz mono WAV, pass the audio file directly instead of the video to avoid extraction.

Defensive patterns

Strategy: fallback

Validate before calling

import { hasFFmpeg } from "./manager.js";

if (!hasFFmpeg()) {
  throw new Error(`ffmpeg is required for video transcription. Install it first.`);
}

Try / catch

try {
  const wavPath = extractAudio(videoPath);
} catch (err) {
  if (err instanceof Error && err.message.includes("ffmpeg is required")) {
    console.error(`${err.message}`);
    process.exit(1);
  }
  throw err;
}

Prevention

Install ffmpeg before using video transcription (brew install ffmpeg / apt install ffmpeg).
If you already have a 16kHz mono WAV, pass it directly instead of the video to skip extraction.
Set HYPERFRAMES_FFMPEG to the binary path if ffmpeg isn't on PATH.

When it happens

Trigger: Running hyperframes transcribe (or any command that triggers transcription) on a video file (MP4, MOV, etc.) when ffmpeg is not installed or not on PATH. findFFmpeg returns undefined, so extraction cannot proceed.

Common situations: First-time use on a machine without ffmpeg; CI container without ffmpeg installed; ffmpeg installed but not on PATH; using a minimal Docker image.

Related errors

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