{"record":{"id":"26a84c99f41efce0","repo":"heygen-com/hyperframes","slug":"ffmpeg-is-required-to-extract-audio-from-video-in","errorCode":null,"errorMessage":"ffmpeg is required to extract audio from video. Install: ${getFFmpegInstallHint()}","messagePattern":"ffmpeg is required to extract audio from video\\. Install: (.+?)","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"packages/cli/src/whisper/transcribe.ts","lineNumber":308,"sourceCode":" *\n * MUST be unique per call AND per process: callers run many `transcribe`\n * invocations in parallel (e.g. the product-launch-video audio pipeline spawns\n * one `hyperframes transcribe` per scene at once). A `Date.now()`-based name\n * collides when two conversions land in the same millisecond — they clobber\n * each other's WAV in the shared tmpdir, so whisper transcribes the wrong\n * scene's audio and every colliding scene gets identical word timings.\n */\nfunction tempWavPath(): string {\n  return join(tmpdir(), `hyperframes-audio-${process.pid}-${randomUUID()}.wav`);\n}\n\n/**\n * Extract audio from a video file as 16kHz mono WAV (whisper requirement).\n */\nfunction extractAudio(videoPath: string): string {\n  const ffmpegPath = findFFmpeg();\n  if (!ffmpegPath) {\n    throw new Error(\n      `ffmpeg is required to extract audio from video. Install: ${getFFmpegInstallHint()}`,\n    );\n  }\n  const wavPath = tempWavPath();\n  execFileSync(\n    ffmpegPath,\n    [\"-i\", videoPath, \"-vn\", \"-ar\", \"16000\", \"-ac\", \"1\", \"-f\", \"wav\", \"-y\", wavPath],\n    {\n      stdio: \"ignore\",\n      timeout: resolveAudioPreparationTimeoutMs(getMediaDurationSeconds(videoPath)),\n    },\n  );\n  return wavPath;\n}\n\n/**\n * Check if a WAV file is already 16kHz mono via ffprobe.\n */","sourceCodeStart":290,"sourceCodeEnd":326,"githubUrl":"https://github.com/heygen-com/hyperframes/blob/c2996c8626135db5253519359d8a063d3bafad8d/packages/cli/src/whisper/transcribe.ts#L290-L326","documentation":"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.","triggerScenarios":"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.","commonSituations":"First-time use on a machine without ffmpeg; CI container without ffmpeg installed; ffmpeg installed but not on PATH; using a minimal Docker image.","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."],"exampleFix":null,"handlingStrategy":"fallback","validationCode":"import { hasFFmpeg } from \"./manager.js\";\n\nif (!hasFFmpeg()) {\n  throw new Error(`ffmpeg is required for video transcription. Install it first.`);\n}","typeGuard":null,"tryCatchPattern":"try {\n  const wavPath = extractAudio(videoPath);\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 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."],"tags":["whisper","ffmpeg","dependencies","audio","video"],"backgroundTag":null,"analyzedSha":"c2996c8626135db5253519359d8a063d3bafad8d","analyzedAt":"2026-08-12T22:18:56.877Z","schemaVersion":2},"datasetVersion":"2026-08-12T23:17:12.415Z"}