{"record":{"id":"6e2b75a8a74c1d57","repo":"heygen-com/hyperframes","slug":"ffmpeg-and-ffprobe-are-required-getffmpeginstal","errorCode":null,"errorMessage":"FFmpeg and ffprobe are required. ${getFFmpegInstallHint()}","messagePattern":"FFmpeg and ffprobe are required\\. (.+?)","errorType":"exception","errorClass":"Error","httpStatus":null,"severity":"error","filePath":"packages/cli/src/commands/media-treatment-analysis.ts","lineNumber":15,"sourceCode":"import {\n  analyzeMediaGrade,\n  type MediaTreatmentAnalysis,\n} from \"@hyperframes/core/media-grade-analyzer\";\nimport { findFFmpeg, findFFprobe, getFFmpegInstallHint } from \"../browser/ffmpeg.js\";\n\ninterface CliMediaTreatmentAnalysis extends Omit<MediaTreatmentAnalysis, \"adjust\"> {\n  suggestedPatch: { adjust: MediaTreatmentAnalysis[\"adjust\"] };\n}\n\nexport function analyzeMediaTreatment(mediaPath: string): CliMediaTreatmentAnalysis {\n  const ffmpegPath = findFFmpeg();\n  const ffprobePath = findFFprobe();\n  if (!ffmpegPath || !ffprobePath) {\n    throw new Error(`FFmpeg and ffprobe are required. ${getFFmpegInstallHint()}`);\n  }\n  const analysis = analyzeMediaGrade(mediaPath, { ffmpegPath, ffprobePath });\n  const { adjust, ...evidence } = analysis;\n  return { ...evidence, suggestedPatch: { adjust } };\n}\n","sourceCodeStart":1,"sourceCodeEnd":21,"githubUrl":"https://github.com/heygen-com/hyperframes/blob/c2996c8626135db5253519359d8a063d3bafad8d/packages/cli/src/commands/media-treatment-analysis.ts#L1-L21","documentation":"Thrown by analyzeMediaTreatment() in packages/cli/src/commands/media-treatment-analysis.ts:11. The media analysis path (`hyperframes media-treatment --analyze`) shells out to ffmpeg and ffprobe to grade the source. findFFmpeg/findFFprobe are called with configuredMustExist, so they return undefined both when the binary isn't on PATH and when FFMPEG_PATH/FFPROBE_PATH point at a nonexistent file; the combined guard then throws with a platform-specific install hint.","triggerScenarios":"Running `hyperframes media-treatment --selector <sel> --analyze` (or calling analyzeMediaTreatment directly) where neither ffmpeg nor ffprobe resolves, or where an env override resolves to a missing path.","commonSituations":"Fresh machine or CI image without ffmpeg; FFMPEG_PATH / FFPROBE_PATH env vars left over from an old install pointing at a deleted binary; minimal Docker image (alpine) without ffmpeg package; Windows machine without the bin dir on PATH.","solutions":["Install ffmpeg (which provides ffprobe): `brew install ffmpeg` (macOS), `apt-get install -y ffmpeg` (Debian/Ubuntu), or follow the URL in the hint.","If you set FFMPEG_PATH/FFPROBE_PATH, verify the files exist at those paths or unset them so PATH lookup is used.","Confirm both binaries work: `ffmpeg -version` and `ffprobe -version`.","In Docker/CI, install ffmpeg in the image build stage before the analyze step."],"exampleFix":"# before\nhyperframes media-treatment --selector '#hero' --analyze\n# after\nbrew install ffmpeg            # or: apt-get install -y ffmpeg\nunset FFMPEG_PATH FFPROBE_PATH # if pointing at stale paths\nhyperframes media-treatment --selector '#hero' --analyze","handlingStrategy":"validation","validationCode":"import { findFFmpeg, findFFprobe } from '../browser/ffmpeg.js';\n\nfunction ensureFfmpeg(): { ffmpegPath: string; ffprobePath: string } {\n  const ffmpegPath = findFFmpeg();\n  const ffprobePath = findFFprobe();\n  if (!ffmpegPath || !ffprobePath) {\n    throw new Error('ffmpeg/ffprobe missing — install before running media analysis.');\n  }\n  return { ffmpegPath, ffprobePath };\n}","typeGuard":"function hasFfmpeg(): boolean {\n  return Boolean(findFFmpeg() && findFFprobe());\n}","tryCatchPattern":"try {\n  analyzeMediaTreatment(mediaPath);\n} catch (error) {\n  if (/FFmpeg and ffprobe are required/.test(String(error))) {\n    console.error('Install ffmpeg, then rerun. This is not retryable until PATH/env is fixed.');\n    process.exit(1);\n  }\n  throw error;\n}","preventionTips":["Install ffmpeg in your base image / machine setup so findFFmpeg always resolves.","If setting FFMPEG_PATH/FFPROBE_PATH, validate those files exist before invoking analysis.","Add an ffmpeg/ffprobe preflight to CI before any media-treatment --analyze step."],"tags":["ffmpeg","environment","media","dependencies"],"backgroundTag":null,"analyzedSha":"c2996c8626135db5253519359d8a063d3bafad8d","analyzedAt":"2026-08-12T22:18:56.877Z","schemaVersion":2},"datasetVersion":"2026-08-12T23:17:12.415Z"}