ffmpeg is required to prepare audio. Install: ${getFFmpegIns

Error message

ffmpeg is required to prepare audio. Install: ${getFFmpegInstallHint()}

What it means

Thrown by prepareAudio when ffmpeg cannot be found and the input audio file is not already in the required 16kHz mono WAV format. ffmpeg is needed to convert other audio formats (MP3, AAC, non-16kHz WAV, etc.) to the 16kHz mono WAV that whisper.cpp expects. If the input is already a 16kHz mono WAV (verified via ffprobe), this function returns early and never throws.

Source

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

    const audio = parsed.streams?.find((s) => s.codec_type === "audio");
    return audio?.sample_rate === "16000" && audio?.channels === 1;
  } catch {
    return false;
  }
}

/**
 * Convert audio file to 16kHz mono WAV if not already in that format.
 */
function prepareAudio(audioPath: string): string {
  if (extname(audioPath).toLowerCase() === ".wav" && isWav16kMono(audioPath)) {
    return audioPath;
  }

  // Convert to whisper-compatible WAV
  const ffmpegPath = findFFmpeg();
  if (!ffmpegPath) {
    throw new Error(`ffmpeg is required to prepare audio. Install: ${getFFmpegInstallHint()}`);
  }
  const wavPath = tempWavPath();
  execFileSync(
    ffmpegPath,
    ["-i", audioPath, "-ar", "16000", "-ac", "1", "-f", "wav", "-y", wavPath],
    {
      stdio: "ignore",
      timeout: resolveAudioPreparationTimeoutMs(getMediaDurationSeconds(audioPath)),
    },
  );
  return wavPath;
}

/**
 * Map a ggml model file-stem to whisper.cpp's `--dtw` alignment-heads preset.
 *
 * The two mostly coincide, so the stem was long passed straight to `--dtw` — but
 * they diverge for the large family: the model files are hyphenated

View on GitHub (pinned to c2996c8626)

Solutions

Install ffmpeg (macOS: brew install ffmpeg; Debian/Ubuntu: apt install ffmpeg; Fedora: dnf install ffmpeg).
Pre-convert the audio to 16kHz mono WAV manually: ffmpeg -i input.mp3 -ar 16000 -ac 1 -f wav output.wav, then pass the WAV file.
If ffmpeg is installed but not found, set HYPERFRAMES_FFMPEG to its path.
Ensure ffprobe is also installed (usually ships with ffmpeg) so isWav16kMono can detect already-compatible files.

Example fix

// before: hyperframes transcribe audio.mp3   (ffmpeg missing)
// after (option A): install ffmpeg, then retry
// after (option B): pre-convert manually:
//   ffmpeg -i audio.mp3 -ar 16000 -ac 1 -f wav audio_16k.wav
//   hyperframes transcribe audio_16k.wav

Defensive patterns

Strategy: fallback

Validate before calling

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

function needsFfmpeg(audioPath: string): boolean {
  if (!hasFFmpeg()) return false; // can't convert anyway
  return true; // caller should check hasFFmpeg first
}

// Validate before calling prepareAudio
if (!hasFFmpeg()) {
  console.error("ffmpeg is required to prepare audio. Install it first.");
}

Try / catch

try {
  const wavPath = prepareAudio(audioPath);
} 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 audio transcription.
Pre-convert audio to 16kHz mono WAV to bypass ffmpeg dependency: ffmpeg -i input.mp3 -ar 16000 -ac 1 output.wav.
Ensure ffprobe is installed alongside ffmpeg so isWav16kMono can detect already-compatible WAVs.

When it happens

Trigger: Running transcription on an audio file (MP3, M4A, WAV at non-16kHz, etc.) when ffmpeg is not installed. The isWav16kMono check fails (no ffprobe either), so conversion is attempted, but findFFmpeg returns undefined.

Common situations: Passing an MP3 or M4A audio file without ffmpeg installed; a WAV file at 44.1kHz stereo that needs conversion; CI without ffmpeg; system where ffmpeg was removed.

Related errors

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