Write HTML. Render video. Built for agents.
JavaScript aiai-agentsanimationclaude-codeffmpegframeworkgsaphtmlhtml-to-videomcpmotion-graphicspuppeteerrenderingtypescriptvideo-editor
fix(cli): a render no FFmpeg encoder can finish stops before capture, not after it (#5831)
Miguel Ángel9fd5e4ae2df6
diff --git a/packages/cli/src/browser/ffmpeg.test.ts b/packages/cli/src/browser/ffmpeg.test.tsindex b409b8527e..4116504f2a 100644--- a/packages/cli/src/browser/ffmpeg.test.ts+++ b/packages/cli/src/browser/ffmpeg.test.ts@@ -1,11 +1,11 @@-import { execFileSync } from "node:child_process";import { tmpdir } from "node:os";import { join } from "node:path";import { afterEach, describe, expect, it, vi } from "vitest";import { findFFmpeg, findFFprobe, H264EncoderUnavailableError } from "./ffmpeg.js";+import { runCancellableProcess } from "../utils/cancellableProcess.js";-// Only child_process is mocked: the H264 encoder probe shells out, while the-// wrapper tests below resolve via env overrides and need the real `existsSync`.+// Only child_process is mocked, so no lookup shells out, while the wrapper+// tests below resolve via env overrides and need the real `existsSync`.vi.mock("node:child_process", () => ({ execFileSync: vi.fn(), execSync: vi.fn() }));// Only the distro probe is faked; `ffmpegInstallCommand` stays real so the@@ -16,7 +16,8 @@ vi.mock("./linuxDeps.js", async (importOriginal) => ({detectLinuxDistro: () => ({ family: linuxFamily, isWsl: false, prettyName: null }),}));-const mockExecFile = vi.mocked(execFileSync);+vi.mock("../utils/cancellableProcess.js", () => ({ runCancellableProcess: vi.fn() }));+const mockRun = vi.mocked(runCancellableProcess);afterEach(() => {vi.clearAllMocks();@@ -45,56 +46,76 @@ describe("findFFmpeg / findFFprobe", () => {});describe("resolveH264EncoderMode", () => {- it("falls back to VideoToolbox when libx264 is absent", async () => {- const { resolveH264EncoderMode } = await import("./ffmpeg.js");- const encoders = `- V....D h264_videotoolbox VideoToolbox H.264 Encoder-`;+ // The shape of an LGPL FFmpeg build: OpenH264 and VideoToolbox, no libx264.+ const noX264 = " V....D libopenh264 OpenH264\n V....D h264_videotoolbox VideoToolbox H.264\n";- expect(resolveH264EncoderMode(encoders, false)).toBe("gpu");+ it("falls back to a GPU encoder that works when libx264 is absent", async () => {+ const { resolveH264EncoderMode } = await import("./ffmpeg.js");+ expect(resolveH264EncoderMode(noX264, false, true)).toBe("gpu");});- it("does not treat a compiled Linux hardware encoder as usable", async () => {+ it("refuses a compiled GPU encoder whose probe failed, with or without --gpu", async () => {const { resolveH264EncoderMode } = await import("./ffmpeg.js");- const encoders = `- V....D h264_vaapi H.264/AVC (VAAPI)-`;+ expect(() => resolveH264EncoderMode(noX264, false, false)).toThrow(H264EncoderUnavailableError);+ expect(() => resolveH264EncoderMode(noX264, true, false)).toThrow(H264EncoderUnavailableError);+ });- expect(() => resolveH264EncoderMode(encoders, false)).toThrow(H264EncoderUnavailableError);+ it("encodes --gpu renders with libx264 when no GPU encoder works", async () => {+ const { resolveH264EncoderMode } = await import("./ffmpeg.js");+ expect(resolveH264EncoderMode(" V....D libx264 H.264\n", true, false)).toBe("software");+ expect(resolveH264EncoderMode(" V....D libx264 H.264\n", true, true)).toBe("gpu");});it("prefers libx264 when both encoders are available", async () => {const { resolveH264EncoderMode } = await import("./ffmpeg.js");expect(- resolveH264EncoderMode(" V....D libx264 H.264\n V....D h264_videotoolbox H.264\n", false),+ resolveH264EncoderMode(+ " V....D libx264 H.264\n V....D h264_videotoolbox H.264\n",+ false,+ true,+ ),).toBe("software");});- it("distinguishes a successful unsupported probe from an unavailable probe", async () => {- const { detectH264EncoderMode } = await import("./ffmpeg.js");- mockExecFile.mockReturnValue(" V....D libvpx-vp9 VP9\n");- expect(() => detectH264EncoderMode("/custom/ffmpeg", false)).toThrow(- H264EncoderUnavailableError,- );- const timeout = new Error("ETIMEDOUT");- mockExecFile.mockImplementationOnce(() => {- throw timeout;- });- expect(() => detectH264EncoderMode("/custom/ffmpeg", false)).toThrow(timeout);+ it("says whether HEVC could still encode when H.264 cannot", async () => {+ const { resolveH264EncoderMode } = await import("./ffmpeg.js");+ const refusal = (encoders: string) => {+ try {+ resolveH264EncoderMode(encoders, false, false);+ } catch (error) {+ return error as InstanceType<typeof H264EncoderUnavailableError>;+ }+ };+ expect(refusal(" V....D libx265 HEVC\n")?.hevcEncoderAvailable).toBe(true);+ expect(refusal(noX264)?.hevcEncoderAvailable).toBe(false);});- it("inspects the configured FFmpeg binary", async () => {- mockExecFile.mockReturnValue(- " V....D h264_videotoolbox VideoToolbox H.264 Encoder\n" as never,+ it("asks the configured FFmpeg, and probes the GPU only when libx264 is missing or --gpu is set", async () => {+ const { detectH264EncoderModeForRender } = await import("./ffmpeg.js");+ const signal = new AbortController().signal;+ const probeGpu = vi.fn(async () => null);+ mockRun.mockResolvedValue({ stdout: " V....D libx264 H.264\n" } as never);+ expect(await detectH264EncoderModeForRender("/custom/ffmpeg", false, signal, probeGpu)).toBe(+ "software",);- const { detectH264EncoderMode } = await import("./ffmpeg.js");-- expect(detectH264EncoderMode("/custom/ffmpeg", false)).toBe("gpu");- expect(mockExecFile).toHaveBeenCalledWith(+ expect(probeGpu).not.toHaveBeenCalled();+ expect(mockRun).toHaveBeenCalledWith("/custom/ffmpeg",["-hide_banner", "-encoders"],- expect.objectContaining({ encoding: "utf-8", windowsHide: true }),+ expect.objectContaining({ signal }),);++ mockRun.mockResolvedValue({ stdout: " V....D h264_videotoolbox H.264\n" } as never);+ await expect(+ detectH264EncoderModeForRender("/custom/ffmpeg", true, signal, probeGpu),+ ).rejects.toThrow(H264EncoderUnavailableError);+ expect(probeGpu).toHaveBeenCalledOnce();++ const timeout = new Error("ETIMEDOUT");+ mockRun.mockRejectedValueOnce(timeout);+ await expect(+ detectH264EncoderModeForRender("/custom/ffmpeg", false, signal, probeGpu),+ ).rejects.toThrow(timeout);});});diff --git a/packages/cli/src/browser/ffmpeg.ts b/packages/cli/src/browser/ffmpeg.tsindex ab5cd194f6..bfa96f4201 100644--- a/packages/cli/src/browser/ffmpeg.ts+++ b/packages/cli/src/browser/ffmpeg.ts@@ -1,4 +1,4 @@-import { execFileSync } from "node:child_process";+import { detectGpuEncoder } from "@hyperframes/engine";import { findFfBinary } from "@hyperframes/parsers/ff-binaries";import { detectLinuxDistro, ffmpegInstallCommand } from "./linuxDeps.js";import { runCancellableProcess } from "../utils/cancellableProcess.js";@@ -8,8 +8,8 @@ export { FFMPEG_PATH_ENV, FFPROBE_PATH_ENV } from "@hyperframes/parsers/ff-binarexport type H264EncoderMode = "software" | "gpu";export class H264EncoderUnavailableError extends Error {- constructor() {- super("This FFmpeg build has neither libx264 nor VideoToolbox H.264 encoding.");+ constructor(readonly hevcEncoderAvailable = false) {+ super("This FFmpeg build has no libx264 and no GPU H.264 encoder that works on this machine.");this.name = "H264EncoderUnavailableError";}}@@ -17,40 +17,38 @@ export class H264EncoderUnavailableError extends Error {/*** 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.+ * Some FFmpeg distributions omit libx264. Without a GPU encoder that passes+ * the engine's probe, the encoder falls back to libx264-only options such as+ * `-preset`, so those builds must be refused before capture.*/export function resolveH264EncoderMode(ffmpegEncodersOutput: string,gpuRequested: boolean,+ usableGpu: boolean,): H264EncoderMode {- if (gpuRequested) return "gpu";- if (/\blibx264\b/.test(ffmpegEncodersOutput)) return "software";- if (/\bh264_videotoolbox\b/.test(ffmpegEncodersOutput)) return "gpu";- throw new H264EncoderUnavailableError();+ if (gpuRequested && usableGpu) return "gpu";+ if (hasLibx264(ffmpegEncodersOutput)) return "software";+ if (usableGpu) return "gpu";+ throw new H264EncoderUnavailableError(/\blibx265\b/.test(ffmpegEncodersOutput));}-export function detectH264EncoderMode(ffmpegPath: string, gpuRequested: boolean): H264EncoderMode {- const encoders = execFileSync(ffmpegPath, ["-hide_banner", "-encoders"], {- encoding: "utf-8",- stdio: ["ignore", "pipe", "pipe"],- timeout: FIRST_LAUNCH_TIMEOUT_MS,- windowsHide: true,- });- return resolveH264EncoderMode(encoders, gpuRequested);+function hasLibx264(ffmpegEncodersOutput: string): boolean {+ return /\blibx264\b/.test(ffmpegEncodersOutput);}export async function detectH264EncoderModeForRender(ffmpegPath: string,gpuRequested: boolean,signal: AbortSignal,+ probeGpu: () => Promise<unknown> = detectGpuEncoder,): Promise<H264EncoderMode> {const result = await runCancellableProcess(ffmpegPath, ["-hide_banner", "-encoders"], {signal,timeoutMs: FIRST_LAUNCH_TIMEOUT_MS,});- return resolveH264EncoderMode(result.stdout, gpuRequested);+ const needsGpu = gpuRequested || !hasLibx264(result.stdout);+ const usableGpu = needsGpu && (await probeGpu()) !== null;+ return resolveH264EncoderMode(result.stdout, gpuRequested, usableGpu);}// `configuredMustExist`: the CLI surfaces an install hint when a binary isdiff --git a/packages/cli/src/commands/render.test.ts b/packages/cli/src/commands/render.test.tsindex 752189d78a..292098a6b0 100644--- a/packages/cli/src/commands/render.test.ts+++ b/packages/cli/src/commands/render.test.ts@@ -86,6 +86,7 @@ const ffmpegEncoderState = vi.hoisted(() => ({mode: "software" as "software" | "gpu",error: null as Error | null,encoders: null as string | null,+ usableGpu: false,}));const orphanCleanupState = vi.hoisted(() => ({calls: 0,@@ -210,10 +211,14 @@ vi.mock("../browser/ffmpeg.js", async (importOriginal) => {const actual = await importOriginal<typeof import("../browser/ffmpeg.js")>();return {...actual,- detectH264EncoderModeForRender: vi.fn(async () => {+ detectH264EncoderModeForRender: vi.fn(async (_path: string, gpuRequested: boolean) => {if (ffmpegEncoderState.error) throw ffmpegEncoderState.error;if (ffmpegEncoderState.encoders !== null)- return actual.resolveH264EncoderMode(ffmpegEncoderState.encoders, false);+ return actual.resolveH264EncoderMode(+ ffmpegEncoderState.encoders,+ gpuRequested,+ ffmpegEncoderState.usableGpu,+ );return ffmpegEncoderState.mode;}),findFFmpeg: vi.fn(() => "/usr/bin/ffmpeg"),@@ -474,6 +479,7 @@ describe("renderLocal browser GPU config", () => {ffmpegEncoderState.mode = "software";ffmpegEncoderState.error = null;ffmpegEncoderState.encoders = null;+ ffmpegEncoderState.usableGpu = false;orphanCleanupState.calls = 0;orphanCleanupState.killed = 0;orphanCleanupState.parentPid = () => null;@@ -950,6 +956,26 @@ describe("renderLocal browser GPU config", () => {expect(stderr.mock.calls.flat().join(" ")).toContain("libx264");});+ it("refuses a --gpu MP4 before capture when no GPU encoder works and FFmpeg lacks libx264", async () => {+ ffmpegEncoderState.encoders = " V....D libopenh264 OpenH264\n V....D h264_videotoolbox H.264\n";+ const stderr = vi.spyOn(console, "error").mockImplementation(() => undefined);++ await expect(+ renderLocal(PROJECT_DIR, "/tmp/out.mp4", {+ fps: { num: 30, den: 1 },+ quality: "high",+ format: "mp4",+ gpu: true,+ browserGpuMode: "software",+ hdrMode: "auto",+ quiet: true,+ }),+ ).rejects.toMatchObject({ name: "CliRuntimeError" });++ expect(producerState.createdJobs).toHaveLength(0);+ expect(stderr.mock.calls.flat().join(" ")).toContain("libx264");+ });+it.each(["webm", "mov", "png-sequence"] as const)("does not require H.264 for %s",async (format) => {@@ -1084,6 +1110,7 @@ describe("renderLocal browser GPU config", () => {// the software encoder's forced-keyframe lock.it("fails an HLS render instead of falling back to GPU H.264", async () => {ffmpegEncoderState.encoders = " V....D h264_videotoolbox H.264 (VideoToolbox)\n";+ ffmpegEncoderState.usableGpu = true;const stderr = vi.spyOn(console, "error").mockImplementation(() => undefined);await expect(diff --git a/packages/cli/src/commands/render.ts b/packages/cli/src/commands/render.tsindex 913109d64f..85c8859b66 100644--- a/packages/cli/src/commands/render.ts+++ b/packages/cli/src/commands/render.ts@@ -1008,21 +1008,22 @@ async function executeLocalRender(// HLS shares the H.264 encode path but cannot take the GPU fallback below:// its fixed-length segments need the software encoder's forced-keyframe lock.const isHls = options.format === "hls";- if (!options.gpu && (options.format === "mp4" || isHls) && preflight.ffmpegPath) {- let encoderMode: H264EncoderMode = "software";+ if ((options.format === "mp4" || isHls) && preflight.ffmpegPath) {+ const gpuRequested = options.gpu && !isHls;+ let encoderMode: H264EncoderMode = gpuRequested ? "gpu" : "software";try {encoderMode = await detectH264EncoderModeForRender(preflight.ffmpegPath,- false,+ gpuRequested,cancellation.signal,);} catch (error) {if (cancellation.signal.aborted) cancellation.signal.throwIfAborted();- // HDR MP4 uses HEVC; auto mode cannot resolve the codec until sources- // have been inspected. Forced SDR and HLS are definitely H.264 here.+ // HDR MP4 uses HEVC; auto mode cannot resolve the codec until sources are+ // inspected. Forced SDR, HLS, or no libx265 either: nothing here can encode.if (error instanceof H264EncoderUnavailableError &&- (options.hdrMode === "force-sdr" || isHls)+ (options.hdrMode === "force-sdr" || isHls || !error.hevcEncoderAvailable)) {errorBox(`${isHls ? "HLS" : "MP4"} H.264 encoder unavailable`,@@ -1049,12 +1050,15 @@ async function executeLocalRender();failCommand();}- if (encoderMode === "gpu") {+ if (encoderMode === "gpu" && !gpuRequested) {console.warn(- c.warn(" FFmpeg does not include libx264; falling back to VideoToolbox H.264 encoding."),+ c.warn(" FFmpeg does not include libx264; falling back to GPU H.264 encoding."),);options = { ...options, gpu: true };}+ if (encoderMode === "software" && gpuRequested && !options.quiet) {+ console.warn(c.warn(" No GPU encoder works on this machine; encoding with libx264."));+ }}cancellation.checkAncestors();