Skip to content

Commit 63182f6

Browse files
fix(cli): reject confirmed unsupported SDR encoders (#3679)
1 parent ab07d67 commit 63182f6

4 files changed

Lines changed: 117 additions & 13 deletions

File tree

‎packages/cli/src/browser/ffmpeg.test.ts‎

Lines changed: 21 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -2,7 +2,7 @@ import { execFileSync } from "node:child_process";
22
import { tmpdir } from "node:os";
33
import { join } from "node:path";
44
import { afterEach, describe, expect, it, vi } from "vitest";
5-
import { findFFmpeg, findFFprobe } from "./ffmpeg.js";
5+
import { findFFmpeg, findFFprobe, H264EncoderUnavailableError } from "./ffmpeg.js";
66

77
// Only child_process is mocked: the H264 encoder probe shells out, while the
88
// wrapper tests below resolve via env overrides and need the real `existsSync`.
@@ -60,9 +60,27 @@ describe("resolveH264EncoderMode", () => {
6060
V....D h264_vaapi H.264/AVC (VAAPI)
6161
`;
6262

63-
expect(() => resolveH264EncoderMode(encoders, false)).toThrow(
64-
"neither libx264 nor VideoToolbox",
63+
expect(() => resolveH264EncoderMode(encoders, false)).toThrow(H264EncoderUnavailableError);
64+
});
65+
66+
it("prefers libx264 when both encoders are available", async () => {
67+
const { resolveH264EncoderMode } = await import("./ffmpeg.js");
68+
expect(
69+
resolveH264EncoderMode(" V....D libx264 H.264\n V....D h264_videotoolbox H.264\n", false),
70+
).toBe("software");
71+
});
72+
73+
it("distinguishes a successful unsupported probe from an unavailable probe", async () => {
74+
const { detectH264EncoderMode } = await import("./ffmpeg.js");
75+
mockExecFile.mockReturnValue(" V....D libvpx-vp9 VP9\n");
76+
expect(() => detectH264EncoderMode("/custom/ffmpeg", false)).toThrow(
77+
H264EncoderUnavailableError,
6578
);
79+
const timeout = new Error("ETIMEDOUT");
80+
mockExecFile.mockImplementationOnce(() => {
81+
throw timeout;
82+
});
83+
expect(() => detectH264EncoderMode("/custom/ffmpeg", false)).toThrow(timeout);
6684
});
6785

6886
it("inspects the configured FFmpeg binary", async () => {

‎packages/cli/src/browser/ffmpeg.ts‎

Lines changed: 8 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -6,6 +6,13 @@ export { FFMPEG_PATH_ENV, FFPROBE_PATH_ENV } from "@hyperframes/parsers/ff-binar
66

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

9+
export class H264EncoderUnavailableError extends Error {
10+
constructor() {
11+
super("This FFmpeg build has neither libx264 nor VideoToolbox H.264 encoding.");
12+
this.name = "H264EncoderUnavailableError";
13+
}
14+
}
15+
916
/**
1017
* Select the H.264 encoder class supported by an FFmpeg build.
1118
*
@@ -20,7 +27,7 @@ export function resolveH264EncoderMode(
2027
if (gpuRequested) return "gpu";
2128
if (/\blibx264\b/.test(ffmpegEncodersOutput)) return "software";
2229
if (/\bh264_videotoolbox\b/.test(ffmpegEncodersOutput)) return "gpu";
23-
throw new Error("This FFmpeg build has neither libx264 nor VideoToolbox H.264 encoding.");
30+
throw new H264EncoderUnavailableError();
2431
}
2532

2633
export function detectH264EncoderMode(ffmpegPath: string, gpuRequested: boolean): H264EncoderMode {

‎packages/cli/src/commands/render.test.ts‎

Lines changed: 73 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -78,6 +78,7 @@ const preflightState = vi.hoisted(() => ({
7878
const ffmpegEncoderState = vi.hoisted(() => ({
7979
mode: "software" as "software" | "gpu",
8080
error: null as Error | null,
81+
encoders: null as string | null,
8182
}));
8283
const orphanCleanupState = vi.hoisted(() => ({
8384
calls: 0,
@@ -180,14 +181,20 @@ vi.mock("../telemetry/events.js", () => ({
180181
}),
181182
}));
182183

183-
vi.mock("../browser/ffmpeg.js", () => ({
184-
detectH264EncoderMode: vi.fn(() => {
185-
if (ffmpegEncoderState.error) throw ffmpegEncoderState.error;
186-
return ffmpegEncoderState.mode;
187-
}),
188-
findFFmpeg: vi.fn(() => "/usr/bin/ffmpeg"),
189-
getFFmpegInstallHint: vi.fn(() => "brew install ffmpeg"),
190-
}));
184+
vi.mock("../browser/ffmpeg.js", async (importOriginal) => {
185+
const actual = await importOriginal<typeof import("../browser/ffmpeg.js")>();
186+
return {
187+
...actual,
188+
detectH264EncoderMode: vi.fn(() => {
189+
if (ffmpegEncoderState.error) throw ffmpegEncoderState.error;
190+
if (ffmpegEncoderState.encoders !== null)
191+
return actual.resolveH264EncoderMode(ffmpegEncoderState.encoders, false);
192+
return ffmpegEncoderState.mode;
193+
}),
194+
findFFmpeg: vi.fn(() => "/usr/bin/ffmpeg"),
195+
getFFmpegInstallHint: vi.fn(() => "brew install ffmpeg"),
196+
};
197+
});
191198

192199
vi.mock("../browser/preflight.js", () => ({
193200
runEnvironmentChecks: vi.fn(async () => preflightState.result),
@@ -294,6 +301,7 @@ describe("renderLocal browser GPU config", () => {
294301
trackingState.renderObservations = [];
295302
ffmpegEncoderState.mode = "software";
296303
ffmpegEncoderState.error = null;
304+
ffmpegEncoderState.encoders = null;
297305
orphanCleanupState.calls = 0;
298306
orphanCleanupState.killed = 0;
299307
resetTrialState();
@@ -478,6 +486,63 @@ describe("renderLocal browser GPU config", () => {
478486
expect(producerState.createdJobs[0]?.useGpu).toBe(true);
479487
});
480488

489+
it("rejects confirmed unsupported SDR MP4 before loading the producer", async () => {
490+
ffmpegEncoderState.encoders = " V....D h264_vaapi H.264/AVC (VAAPI)\n";
491+
const { loadProducer } = await import("../utils/producer.js");
492+
vi.mocked(loadProducer).mockClear();
493+
const stderr = vi.spyOn(console, "error").mockImplementation(() => undefined);
494+
495+
await expect(
496+
renderLocal("/tmp/project", "/tmp/out.mp4", {
497+
fps: { num: 30, den: 1 },
498+
quality: "high",
499+
format: "mp4",
500+
gpu: false,
501+
browserGpuMode: "software",
502+
hdrMode: "force-sdr",
503+
quiet: true,
504+
}),
505+
).rejects.toMatchObject({ name: "CliRuntimeError" });
506+
507+
expect(loadProducer).not.toHaveBeenCalled();
508+
expect(producerState.createdJobs).toHaveLength(0);
509+
expect(stderr.mock.calls.flat().join(" ")).toContain("libx264");
510+
});
511+
512+
it.each(["webm", "mov", "png-sequence"] as const)(
513+
"does not require H.264 for %s",
514+
async (format) => {
515+
ffmpegEncoderState.encoders = " V....D libvpx-vp9 VP9\n";
516+
await renderLocal("/tmp/project", `/tmp/out.${format}`, {
517+
fps: { num: 30, den: 1 },
518+
quality: "high",
519+
format,
520+
gpu: false,
521+
browserGpuMode: "software",
522+
hdrMode: "force-sdr",
523+
quiet: true,
524+
});
525+
expect(producerState.createdJobs).toHaveLength(1);
526+
},
527+
);
528+
529+
it.each(["auto", "force-hdr"] as const)(
530+
"does not reject potential HEVC output in %s mode",
531+
async (hdrMode) => {
532+
ffmpegEncoderState.encoders = " V....D libx265 HEVC\n";
533+
await renderLocal("/tmp/project", "/tmp/out.mp4", {
534+
fps: { num: 30, den: 1 },
535+
quality: "high",
536+
format: "mp4",
537+
gpu: false,
538+
browserGpuMode: "software",
539+
hdrMode,
540+
quiet: true,
541+
});
542+
expect(producerState.createdJobs).toHaveLength(1);
543+
},
544+
);
545+
481546
it("lets the encoder surface its own error when capability detection fails", async () => {
482547
ffmpegEncoderState.error = new Error("encoder probe timed out");
483548
const warn = vi.spyOn(console, "warn").mockImplementation(() => undefined);

‎packages/cli/src/commands/render.ts‎

Lines changed: 15 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -77,7 +77,11 @@ import { isDevMode } from "../utils/env.js";
7777
import { buildDockerRunArgs, resolveDockerPlatform } from "../utils/dockerRunArgs.js";
7878
import { normalizeErrorMessage } from "../utils/errorMessage.js";
7979
import { runEnvironmentChecks } from "../browser/preflight.js";
80-
import { detectH264EncoderMode } from "../browser/ffmpeg.js";
80+
import {
81+
detectH264EncoderMode,
82+
getFFmpegInstallHint,
83+
H264EncoderUnavailableError,
84+
} from "../browser/ffmpeg.js";
8185
import { chromeLaunchRemediation } from "../browser/linuxDeps.js";
8286
import { macosOldChromeCrashRemediation } from "../browser/macosOldChromeCrash.js";
8387
import { windowsChromeCrashRemediation } from "../browser/windowsCrash.js";
@@ -838,6 +842,16 @@ export async function renderLocal(
838842
try {
839843
encoderMode = detectH264EncoderMode(preflight.ffmpegPath, false);
840844
} catch (error) {
845+
// HDR MP4 uses HEVC; auto mode cannot resolve the codec until sources
846+
// have been inspected. Only forced SDR is definitely H.264 here.
847+
if (error instanceof H264EncoderUnavailableError && options.hdrMode === "force-sdr") {
848+
errorBox(
849+
"MP4 H.264 encoder unavailable",
850+
error.message,
851+
`Install an FFmpeg build with libx264 support (${getFFmpegInstallHint()}), or render WebM instead: hyperframes render --format webm --output output.webm`,
852+
);
853+
failCommand();
854+
}
841855
// Capability probing is advisory. Let the real encode surface the
842856
// authoritative FFmpeg error instead of failing here with a bare stack.
843857
if (!options.quiet) {

0 commit comments

Comments
 (0)