heygen-com/hyperframes · error · Error

FFmpeg is required to extract video frames for snapshots. ${

Error message

FFmpeg is required to extract video frames for snapshots. ${getFFmpegInstallHint()}

What it means

Thrown by requireSnapshotFfmpeg when ffmpegPath is undefined. Snapshot capture for video clips uses ffmpeg to extract a single frame (working around Chrome-headless's unreliable <video> seeking), so ffmpeg is mandatory for that path. findFFmpeg() is called upstream and returns undefined when no ffmpeg is found on PATH.

Source

Thrown at packages/cli/src/commands/snapshot.ts:108

  const atClipEnd = Math.abs(globalTime - clipEnd) <= clipEndTolerance;
  if (!atClipEnd) return relativeTime;

  const sourceEnd = sourceDuration > 0 ? sourceDuration : relativeTime;
  return Math.max(0, Math.min(relativeTime, sourceEnd - 1 / 30));
}

/** Prefer the runtime's canonical absolute media start. The authored value is
 * only a compatibility fallback for pages built with an older runtime. */
export function resolveSnapshotVideoClipStart(input: {
  authoredStart: number;
  runtimeResolvedStart: number | null;
}): number {
  return input.runtimeResolvedStart ?? input.authoredStart;
}

export function requireSnapshotFfmpeg(ffmpegPath: string | undefined): string {
  if (ffmpegPath) return ffmpegPath;
  throw new Error(
    `FFmpeg is required to extract video frames for snapshots. ${getFFmpegInstallHint()}`,
  );
}

/**
 * Extract a single frame from a video file at `timeSeconds` via FFmpeg.
 * Used to work around Chrome-headless's inability to reliably seek
 * <video> elements during snapshot capture.
 */
async function extractVideoFrameToBuffer(
  videoPath: string,
  timeSeconds: number,
  useVp9AlphaDecoder = false,
): Promise<Buffer | null> {
  const tmp = mkdtempSync(join(tmpdir(), "hf-snapshot-frame-"));
  const outPath = join(tmp, "frame.png");
  try {
    const ffmpegPath = requireSnapshotFfmpeg(findFFmpeg());

View on GitHub (pinned to c2996c8626)

Solutions

1. Install ffmpeg and ensure it is on PATH (`ffmpeg -version`)
2. Follow the install hint echoed in the error message (brew install ffmpeg / winget / apt)
3. In CI add an ffmpeg setup step (e.g. `apt-get install -y ffmpeg`)
4. If ffmpeg lives elsewhere, set the path your host configures for HYPERFRAMES_FFMPEG_PATH

import { execFileSync } from "node:child_process";
function ffmpegAvailable(): boolean {
  try { execFileSync("ffmpeg", ["-version"], { stdio: "ignore" }); return true; }
  catch { return false; }
}
if (!ffmpegAvailable()) throw new Error("Install ffmpeg before snapshotting video clips.");

When it happens

Trigger: Capturing a snapshot from a composition containing a <video> clip triggers requireSnapshotFfmpeg(findFFmpeg()) at snapshot.ts:126; if findFFmpeg() returned undefined the function throws with the platform install hint appended.

Common situations: ffmpeg not installed (common on fresh macOS/Windows); ffmpeg installed but not on PATH in the current shell/CI; running in a minimal container without media tools; snapshotting a video-backed composition for the first time.

Related errors

• FFmpeg and ffprobe are required. ${getFFmpegInstallHint()}
• Unable to bake required browser media proxies (${summary})
• [build-zip] ffmpeg-static binary missing at ${ffmpegBinary}.
• Unsupported output extension: ${ext}. Use .webm (VP9 alpha),
• ffmpeg and ffprobe are required. Install: ${getFFmpegInstall

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