heygen-com/hyperframes · critical

ffmpeg and ffprobe are required. Install: ${getFFmpegInstall

Error message

ffmpeg and ffprobe are required. Install: ${getFFmpegInstallHint()}

What it means

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().

Source

Thrown at packages/cli/src/background-removal/pipeline.ts:272

      throw new Error(
        "--background-output is not supported for image inputs. Use a video input (mp4/mov/webm) to produce both a cutout and a background plate.",
      );
    }
    bgFormat = inferOutputFormat(backgroundOutputPath);
    if (bgFormat === "png") {
      throw new Error(
        "--background-output must be .webm or .mov; .png is only valid for single-image inputs.",
      );
    }
  }

  return { format, inputKind, bgFormat };
}

export async function render(options: RenderOptions): Promise<RenderResult> {
  const ffmpegPath = findFFmpeg();
  if (!ffmpegPath || !findFFprobe()) {
    throw new Error(`ffmpeg and ffprobe are required. Install: ${getFFmpegInstallHint()}`);
  }

  const { format, bgFormat } = resolveRenderTargets(
    options.inputPath,
    options.outputPath,
    options.backgroundOutputPath,
  );

  const media = await probeMedia(options.inputPath);

  options.onProgress?.({
    kind: "metadata",
    width: media.width,
    height: media.height,
    fps: media.fps,
    frameCount: media.frameCount,
  });

View on GitHub (pinned to c2996c8626)

Solutions

1. 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.
2. Verify both binaries resolve: `ffmpeg -version` and `ffprobe -version`.
3. If ffmpeg is installed but not found, set FFMPEG_PATH and FFPROBE_PATH env vars to absolute binary paths (must exist).

Example fix

# before — ffmpeg missing
$ hyperframes bg-remove ...# install
$ brew install ffmpeg   # macOS
$ sudo apt-get install -y ffmpeg  # Debian/Ubuntu
# after
$ hyperframes bg-remove ...

import { findFFmpeg, findFFprobe } from '@hyperframes/cli/browser/ffmpeg';
if (!findFFmpeg() || !findFFprobe()) {
  throw new Error('ffmpeg/ffprobe not found. Install ffmpeg before running background-removal.');
}
await render(options);

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

try {
  await render(options);
} catch (err) {
  if (/ffmpeg and ffprobe are required/i.test((err as Error).message)) {
    console.error('Install ffmpeg, then retry:', (err as Error).message);
    process.exit(2);
  }
  throw err;
}

When it happens

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

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

Related errors

• This FFmpeg build has neither libx264 nor VideoToolbox H.264
• CUDA execution provider not available. Use --device cpu or i
• Unsupported output extension: ${ext}. Use .webm (VP9 alpha),
• No frames produced from ${inputPath}. Decoder stderr: ${deco
• Could not extract a frame from video: ${framePath}

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