heygen-com/hyperframes · error · Error

FFmpeg and ffprobe are required. ${getFFmpegInstallHint()}

Error message

FFmpeg and ffprobe are required. ${getFFmpegInstallHint()}

What it means

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.

Source

Thrown at packages/cli/src/commands/media-treatment-analysis.ts:15

import {
  analyzeMediaGrade,
  type MediaTreatmentAnalysis,
} from "@hyperframes/core/media-grade-analyzer";
import { findFFmpeg, findFFprobe, getFFmpegInstallHint } from "../browser/ffmpeg.js";

interface CliMediaTreatmentAnalysis extends Omit<MediaTreatmentAnalysis, "adjust"> {
  suggestedPatch: { adjust: MediaTreatmentAnalysis["adjust"] };
}

export function analyzeMediaTreatment(mediaPath: string): CliMediaTreatmentAnalysis {
  const ffmpegPath = findFFmpeg();
  const ffprobePath = findFFprobe();
  if (!ffmpegPath || !ffprobePath) {
    throw new Error(`FFmpeg and ffprobe are required. ${getFFmpegInstallHint()}`);
  }
  const analysis = analyzeMediaGrade(mediaPath, { ffmpegPath, ffprobePath });
  const { adjust, ...evidence } = analysis;
  return { ...evidence, suggestedPatch: { adjust } };
}

View on GitHub (pinned to c2996c8626)

Solutions

1. Install ffmpeg (which provides ffprobe): `brew install ffmpeg` (macOS), `apt-get install -y ffmpeg` (Debian/Ubuntu), or follow the URL in the hint.
2. If you set FFMPEG_PATH/FFPROBE_PATH, verify the files exist at those paths or unset them so PATH lookup is used.
3. Confirm both binaries work: `ffmpeg -version` and `ffprobe -version`.
4. In Docker/CI, install ffmpeg in the image build stage before the analyze step.

Example fix

# before
hyperframes media-treatment --selector '#hero' --analyze
# after
brew install ffmpeg            # or: apt-get install -y ffmpeg
unset FFMPEG_PATH FFPROBE_PATH # if pointing at stale paths
hyperframes media-treatment --selector '#hero' --analyze

import { findFFmpeg, findFFprobe } from '../browser/ffmpeg.js';

function ensureFfmpeg(): { ffmpegPath: string; ffprobePath: string } {
  const ffmpegPath = findFFmpeg();
  const ffprobePath = findFFprobe();
  if (!ffmpegPath || !ffprobePath) {
    throw new Error('ffmpeg/ffprobe missing — install before running media analysis.');
  }
  return { ffmpegPath, ffprobePath };
}

function hasFfmpeg(): boolean {
  return Boolean(findFFmpeg() && findFFprobe());
}

try {
  analyzeMediaTreatment(mediaPath);
} catch (error) {
  if (/FFmpeg and ffprobe are required/.test(String(error))) {
    console.error('Install ffmpeg, then rerun. This is not retryable until PATH/env is fixed.');
    process.exit(1);
  }
  throw error;
}

When it happens

Trigger: 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.

Common situations: 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.

Related errors

• [build-zip] ffmpeg-static binary missing at ${ffmpegBinary}.
• ffmpeg and ffprobe are required. Install: ${getFFmpegInstall
• This FFmpeg build has neither libx264 nor VideoToolbox H.264
• Could not extract a frame from video: ${framePath}
• FFmpeg is required to extract video frames for snapshots. ${

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