This FFmpeg build has neither libx264 nor VideoToolbox H.264

Error message

This FFmpeg build has neither libx264 nor VideoToolbox H.264 encoding.

What it means

Thrown by resolveH264EncoderMode() when ffmpeg's `-encoders` output contains neither libx264 (software H.264) nor h264_videotoolbox (macOS hardware H.264). The function must pick one of these two encoder classes to drive the CPU/GPU render path; with neither present it cannot proceed. This is distinct from gpuRequested=true (which short-circuits to 'gpu').

Source

Thrown at packages/cli/src/browser/ffmpeg.ts:23

export { FFMPEG_PATH_ENV, FFPROBE_PATH_ENV } from "@hyperframes/parsers/ff-binaries";

export type H264EncoderMode = "software" | "gpu";

/**
 * Select the H.264 encoder class supported by an FFmpeg build.
 *
 * Some macOS FFmpeg distributions expose VideoToolbox but omit libx264. The
 * default CPU render path must not pass libx264-only options such as `-preset`
 * to those builds.
 */
export function resolveH264EncoderMode(
  ffmpegEncodersOutput: string,
  gpuRequested: boolean,
): H264EncoderMode {
  if (gpuRequested) return "gpu";
  if (/\blibx264\b/.test(ffmpegEncodersOutput)) return "software";
  if (/\bh264_videotoolbox\b/.test(ffmpegEncodersOutput)) return "gpu";
  throw new Error("This FFmpeg build has neither libx264 nor VideoToolbox H.264 encoding.");
}

export function detectH264EncoderMode(ffmpegPath: string, gpuRequested: boolean): H264EncoderMode {
  const encoders = execFileSync(ffmpegPath, ["-hide_banner", "-encoders"], {
    encoding: "utf-8",
    stdio: ["ignore", "pipe", "pipe"],
    timeout: 5000,
  });
  return resolveH264EncoderMode(encoders, gpuRequested);
}

// `configuredMustExist`: the CLI surfaces an install hint when a binary is
// missing, so an env override pointing at a nonexistent file reports as
// not-found instead of being handed to spawn.
export function findFFmpeg(): string | undefined {
  return findFfBinary("ffmpeg", { configuredMustExist: true });
}

View on GitHub (pinned to c2996c8626)

Solutions

Install a full ffmpeg build that includes libx264: macOS `brew install ffmpeg`; Debian/Ubuntu `sudo apt-get install ffmpeg`; confirm with `ffmpeg -hide_banner -encoders | grep -E 'libx264|h264_videotoolbox'`.
On Linux, ensure the x264 development package is present if you built ffmpeg from source (recompile with --enable-libx264 --enable-gpl).
If you intentionally run a VP9-only build, you cannot use the H.264 render path — install a standard ffmpeg.

Example fix

# before — minimal ffmpeg lacks H.264
$ ffmpeg -hide_banner -encoders | grep libx264   # (no output)
# install full build
$ brew install ffmpeg   # macOS
$ sudo apt-get install -y ffmpeg  # Debian/Ubuntu
$ ffmpeg -hide_banner -encoders | grep libx264
 V....D libx264

Defensive patterns

Strategy: validation

Validate before calling

import { execFileSync } from 'node:child_process';
function hasH264Encoder(ffmpeg = 'ffmpeg'): boolean {
  const out = execFileSync(ffmpeg, ['-hide_banner', '-encoders'], { encoding: 'utf-8' });
  return /\blibx264\b/.test(out) || /\bh264_videotoolbox\b/.test(out);
}
if (!hasH264Encoder()) throw new Error('Install a full ffmpeg with libx264.');

Type guard

function h264Available(encodersOutput: string): boolean {
  return /\blibx264\b/.test(encodersOutput) || /\bh264_videotoolbox\b/.test(encodersOutput);
}

Try / catch

try {
  detectH264EncoderMode(ffmpegPath, false);
} catch (err) {
  if (/neither libx264 nor VideoToolbox/i.test((err as Error).message)) {
    console.error('Install a full ffmpeg build (libx264) and retry.');
  }
  throw err;
}

Prevention

Use a standard ffmpeg distribution (Homebrew, apt, the official static builds) that includes libx264.
In CI/Docker, assert `ffmpeg -hide_banner -encoders | grep libx264` before rendering.
Avoid custom minimal ffmpeg builds unless you also drop the H.264 render path.

When it happens

Trigger: detectH264EncoderMode(ffmpegPath, false) is called; ffmpeg runs `-hide_banner -encoders`; the output matches neither /\blibx264\b/ nor /\bh264_videotoolbox\b/. Common with a custom minimal ffmpeg build (only libvpx/vp9, no H.264), or an ffmpeg that lists encoders under different naming.

Common situations: User installed a stripped-down ffmpeg (e.g. only VP8/VP9 for WebM work); an Alpine edge build that split encoders into separate packages; a Linux build without libx264 (GPL) and no VideoToolbox (macOS-only).

Related errors

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