{"record":{"id":"54547f2bc2caf5fc","repo":"heygen-com/hyperframes","slug":"ffmpeg-and-ffprobe-are-required-install-getffm","errorCode":null,"errorMessage":"ffmpeg and ffprobe are required. Install: ${getFFmpegInstallHint()}","messagePattern":"ffmpeg and ffprobe are required\\. Install: (.+?)","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"critical","filePath":"packages/cli/src/background-removal/pipeline.ts","lineNumber":272,"sourceCode":"      throw new Error(\n        \"--background-output is not supported for image inputs. Use a video input (mp4/mov/webm) to produce both a cutout and a background plate.\",\n      );\n    }\n    bgFormat = inferOutputFormat(backgroundOutputPath);\n    if (bgFormat === \"png\") {\n      throw new Error(\n        \"--background-output must be .webm or .mov; .png is only valid for single-image inputs.\",\n      );\n    }\n  }\n\n  return { format, inputKind, bgFormat };\n}\n\nexport async function render(options: RenderOptions): Promise<RenderResult> {\n  const ffmpegPath = findFFmpeg();\n  if (!ffmpegPath || !findFFprobe()) {\n    throw new Error(`ffmpeg and ffprobe are required. Install: ${getFFmpegInstallHint()}`);\n  }\n\n  const { format, bgFormat } = resolveRenderTargets(\n    options.inputPath,\n    options.outputPath,\n    options.backgroundOutputPath,\n  );\n\n  const media = await probeMedia(options.inputPath);\n\n  options.onProgress?.({\n    kind: \"metadata\",\n    width: media.width,\n    height: media.height,\n    fps: media.fps,\n    frameCount: media.frameCount,\n  });\n","sourceCodeStart":254,"sourceCodeEnd":290,"githubUrl":"https://github.com/heygen-com/hyperframes/blob/c2996c8626135db5253519359d8a063d3bafad8d/packages/cli/src/background-removal/pipeline.ts#L254-L290","documentation":"Thrown at the top of render() when findFFmpeg() or findFFprobe() returns undefined. The background-removal pipeline shells out to ffmpeg (decode source to raw RGB24, re-encode RGBA to VP9/ProRes/PNG) and uses ffprobe indirectly via extractMediaMetadata, so both binaries are hard dependencies. The error includes a platform-specific install hint from getFFmpegInstallHint().","triggerScenarios":"Calling render() on a machine where ffmpeg/ffprobe are not on PATH, not at the FFMPEG_PATH_ENV/FFPROBE_PATH_ENV override, or the override points to a nonexistent file (configuredMustExist:true).","commonSituations":"Fresh CI runner without ffmpeg installed; user unset PATH; an env override (FFMPEG_PATH) points to a moved/removed binary; macOS without `brew install ffmpeg`; minimal Docker image missing ffmpeg.","solutions":["Install ffmpeg per the hint in the error: macOS `brew install ffmpeg`, Debian/Ubuntu `sudo apt-get install ffmpeg`, Windows download from ffmpeg.org and add bin/ to PATH.","Verify both binaries resolve: `ffmpeg -version` and `ffprobe -version`.","If ffmpeg is installed but not found, set FFMPEG_PATH and FFPROBE_PATH env vars to absolute binary paths (must exist)."],"exampleFix":"# before — ffmpeg missing\n$ hyperframes bg-remove ...# install\n$ brew install ffmpeg   # macOS\n$ sudo apt-get install -y ffmpeg  # Debian/Ubuntu\n# after\n$ hyperframes bg-remove ...","handlingStrategy":"validation","validationCode":"import { findFFmpeg, findFFprobe } from '@hyperframes/cli/browser/ffmpeg';\nif (!findFFmpeg() || !findFFprobe()) {\n  throw new Error('ffmpeg/ffprobe not found. Install ffmpeg before running background-removal.');\n}\nawait render(options);","typeGuard":"function ffBinariesAvailable(): boolean {\n  return Boolean(findFFmpeg() && findFFprobe());\n}","tryCatchPattern":"try {\n  await render(options);\n} catch (err) {\n  if (/ffmpeg and ffprobe are required/i.test((err as Error).message)) {\n    console.error('Install ffmpeg, then retry:', (err as Error).message);\n    process.exit(2);\n  }\n  throw err;\n}","preventionTips":["Run `ffmpeg -version` and `ffprobe -version` in CI before invoking render.","Bake ffmpeg into your Docker image so it is always present.","If using FFMPEG_PATH/FFPROBE_PATH env overrides, verify the files exist on startup."],"tags":["environment","ffmpeg","missing-dependency","background-removal"],"backgroundTag":null,"analyzedSha":"c2996c8626135db5253519359d8a063d3bafad8d","analyzedAt":"2026-08-12T22:18:56.877Z","schemaVersion":2},"datasetVersion":"2026-08-12T23:17:12.415Z"}