{"record":{"id":"fde69e1ec38c8bfc","repo":"heygen-com/hyperframes","slug":"ffmpeg-is-required-to-prepare-audio-install-ge","errorCode":null,"errorMessage":"ffmpeg is required to prepare audio. Install: ${getFFmpegInstallHint()}","messagePattern":"ffmpeg is required to prepare audio\\. Install: (.+?)","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"packages/cli/src/whisper/transcribe.ts","lineNumber":361,"sourceCode":"    const audio = parsed.streams?.find((s) => s.codec_type === \"audio\");\n    return audio?.sample_rate === \"16000\" && audio?.channels === 1;\n  } catch {\n    return false;\n  }\n}\n\n/**\n * Convert audio file to 16kHz mono WAV if not already in that format.\n */\nfunction prepareAudio(audioPath: string): string {\n  if (extname(audioPath).toLowerCase() === \".wav\" && isWav16kMono(audioPath)) {\n    return audioPath;\n  }\n\n  // Convert to whisper-compatible WAV\n  const ffmpegPath = findFFmpeg();\n  if (!ffmpegPath) {\n    throw new Error(`ffmpeg is required to prepare audio. Install: ${getFFmpegInstallHint()}`);\n  }\n  const wavPath = tempWavPath();\n  execFileSync(\n    ffmpegPath,\n    [\"-i\", audioPath, \"-ar\", \"16000\", \"-ac\", \"1\", \"-f\", \"wav\", \"-y\", wavPath],\n    {\n      stdio: \"ignore\",\n      timeout: resolveAudioPreparationTimeoutMs(getMediaDurationSeconds(audioPath)),\n    },\n  );\n  return wavPath;\n}\n\n/**\n * Map a ggml model file-stem to whisper.cpp's `--dtw` alignment-heads preset.\n *\n * The two mostly coincide, so the stem was long passed straight to `--dtw` — but\n * they diverge for the large family: the model files are hyphenated","sourceCodeStart":343,"sourceCodeEnd":379,"githubUrl":"https://github.com/heygen-com/hyperframes/blob/c2996c8626135db5253519359d8a063d3bafad8d/packages/cli/src/whisper/transcribe.ts#L343-L379","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","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."],"exampleFix":"// before: hyperframes transcribe audio.mp3   (ffmpeg missing)\n// after (option A): install ffmpeg, then retry\n// after (option B): pre-convert manually:\n//   ffmpeg -i audio.mp3 -ar 16000 -ac 1 -f wav audio_16k.wav\n//   hyperframes transcribe audio_16k.wav","handlingStrategy":"fallback","validationCode":"import { hasFFmpeg } from \"./manager.js\";\n\nfunction needsFfmpeg(audioPath: string): boolean {\n  if (!hasFFmpeg()) return false; // can't convert anyway\n  return true; // caller should check hasFFmpeg first\n}\n\n// Validate before calling prepareAudio\nif (!hasFFmpeg()) {\n  console.error(\"ffmpeg is required to prepare audio. Install it first.\");\n}","typeGuard":null,"tryCatchPattern":"try {\n  const wavPath = prepareAudio(audioPath);\n} catch (err) {\n  if (err instanceof Error && err.message.includes(\"ffmpeg is required\")) {\n    console.error(`${err.message}`);\n    process.exit(1);\n  }\n  throw err;\n}","preventionTips":["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."],"tags":["whisper","ffmpeg","dependencies","audio"],"backgroundTag":null,"analyzedSha":"c2996c8626135db5253519359d8a063d3bafad8d","analyzedAt":"2026-08-12T22:18:56.877Z","schemaVersion":2},"datasetVersion":"2026-08-12T23:17:12.415Z"}