Skip to content

Write HTML. Render video. Built for agents.

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.ts
index 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.ts
index 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-binar
export 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 is
diff --git a/packages/cli/src/commands/render.test.ts b/packages/cli/src/commands/render.test.ts
index 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.ts
index 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();