{"record":{"id":"e2e7f4c62981f31b","repo":"heygen-com/hyperframes","slug":"this-ffmpeg-build-has-neither-libx264-nor-videotoo","errorCode":null,"errorMessage":"This FFmpeg build has neither libx264 nor VideoToolbox H.264 encoding.","messagePattern":"This FFmpeg build has neither libx264 nor VideoToolbox H\\.264 encoding\\.","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"critical","filePath":"packages/cli/src/browser/ffmpeg.ts","lineNumber":23,"sourceCode":"export { FFMPEG_PATH_ENV, FFPROBE_PATH_ENV } from \"@hyperframes/parsers/ff-binaries\";\n\nexport type H264EncoderMode = \"software\" | \"gpu\";\n\n/**\n * Select the H.264 encoder class supported by an FFmpeg build.\n *\n * Some macOS FFmpeg distributions expose VideoToolbox but omit libx264. The\n * default CPU render path must not pass libx264-only options such as `-preset`\n * to those builds.\n */\nexport function resolveH264EncoderMode(\n  ffmpegEncodersOutput: string,\n  gpuRequested: boolean,\n): H264EncoderMode {\n  if (gpuRequested) return \"gpu\";\n  if (/\\blibx264\\b/.test(ffmpegEncodersOutput)) return \"software\";\n  if (/\\bh264_videotoolbox\\b/.test(ffmpegEncodersOutput)) return \"gpu\";\n  throw new Error(\"This FFmpeg build has neither libx264 nor VideoToolbox H.264 encoding.\");\n}\n\nexport function detectH264EncoderMode(ffmpegPath: string, gpuRequested: boolean): H264EncoderMode {\n  const encoders = execFileSync(ffmpegPath, [\"-hide_banner\", \"-encoders\"], {\n    encoding: \"utf-8\",\n    stdio: [\"ignore\", \"pipe\", \"pipe\"],\n    timeout: 5000,\n  });\n  return resolveH264EncoderMode(encoders, gpuRequested);\n}\n\n// `configuredMustExist`: the CLI surfaces an install hint when a binary is\n// missing, so an env override pointing at a nonexistent file reports as\n// not-found instead of being handed to spawn.\nexport function findFFmpeg(): string | undefined {\n  return findFfBinary(\"ffmpeg\", { configuredMustExist: true });\n}\n","sourceCodeStart":5,"sourceCodeEnd":41,"githubUrl":"https://github.com/heygen-com/hyperframes/blob/c2996c8626135db5253519359d8a063d3bafad8d/packages/cli/src/browser/ffmpeg.ts#L5-L41","documentation":"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').","triggerScenarios":"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.","commonSituations":"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).","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."],"exampleFix":"# before — minimal ffmpeg lacks H.264\n$ ffmpeg -hide_banner -encoders | grep libx264   # (no output)\n# install full build\n$ brew install ffmpeg   # macOS\n$ sudo apt-get install -y ffmpeg  # Debian/Ubuntu\n$ ffmpeg -hide_banner -encoders | grep libx264\n V....D libx264","handlingStrategy":"validation","validationCode":"import { execFileSync } from 'node:child_process';\nfunction hasH264Encoder(ffmpeg = 'ffmpeg'): boolean {\n  const out = execFileSync(ffmpeg, ['-hide_banner', '-encoders'], { encoding: 'utf-8' });\n  return /\\blibx264\\b/.test(out) || /\\bh264_videotoolbox\\b/.test(out);\n}\nif (!hasH264Encoder()) throw new Error('Install a full ffmpeg with libx264.');","typeGuard":"function h264Available(encodersOutput: string): boolean {\n  return /\\blibx264\\b/.test(encodersOutput) || /\\bh264_videotoolbox\\b/.test(encodersOutput);\n}","tryCatchPattern":"try {\n  detectH264EncoderMode(ffmpegPath, false);\n} catch (err) {\n  if (/neither libx264 nor VideoToolbox/i.test((err as Error).message)) {\n    console.error('Install a full ffmpeg build (libx264) and retry.');\n  }\n  throw err;\n}","preventionTips":["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."],"tags":["ffmpeg","h264","encoder","missing-dependency","environment"],"backgroundTag":null,"analyzedSha":"c2996c8626135db5253519359d8a063d3bafad8d","analyzedAt":"2026-08-12T22:18:56.877Z","schemaVersion":2},"datasetVersion":"2026-08-12T23:17:12.415Z"}