Files
hyperframes/packages/engine/src/utils/gpuEncoder.ts
T
Miguel Ángel 90f7fe624f fix(engine): GPU renders use the NVENC preset names the host's ffmpeg lists (#6930)
* fix(engine): GPU renders use the NVENC preset names the host's ffmpeg lists

* fix(engine): one ffmpeg stdout reader for encoder detection and preset listing

* ci(engine): raise the engine unpacked size budget for the NVENC preset reader
2026-11-01 15:46:57 +00:00

348 lines
11 KiB
TypeScript
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
// fallow-ignore-file complexity
/**
* GPU Encoder Detection
*
* Shared GPU encoder detection and naming utilities used by both
* chunkEncoder and streamingEncoder services.
*/
import { spawn } from "child_process";
import { getFfmpegBinary } from "./ffmpegBinaries.js";
import { ManagedChildProcess } from "./managedChildProcess.js";
import { trackChildProcess } from "./processTracker.js";
export type ConcreteGpuEncoder = "nvenc" | "videotoolbox" | "vaapi" | "qsv" | "amf";
export type GpuEncoder = ConcreteGpuEncoder | null;
const GPU_ENCODER_CANDIDATES: ConcreteGpuEncoder[] = [
"nvenc",
"videotoolbox",
"vaapi",
"qsv",
"amf",
];
const H264_ENCODER_BY_GPU: Record<ConcreteGpuEncoder, string> = {
nvenc: "h264_nvenc",
videotoolbox: "h264_videotoolbox",
vaapi: "h264_vaapi",
qsv: "h264_qsv",
amf: "h264_amf",
};
const GPU_PROBE_TIMEOUT_MS = 2000;
const GPU_PROBE_KILL_GRACE_MS = 1000;
export function getCompiledGpuEncoders(ffmpegEncodersStdout: string): ConcreteGpuEncoder[] {
return GPU_ENCODER_CANDIDATES.filter((encoder) =>
ffmpegEncodersStdout.includes(H264_ENCODER_BY_GPU[encoder]),
);
}
export async function selectUsableGpuEncoder(
candidates: readonly ConcreteGpuEncoder[],
isUsable: (encoder: ConcreteGpuEncoder) => Promise<boolean>,
): Promise<GpuEncoder> {
const results = await Promise.all(
candidates.map(async (encoder) => {
try {
return { encoder, usable: await isUsable(encoder) };
} catch {
return { encoder, usable: false };
}
}),
);
for (const result of results) {
if (result.usable) {
return result.encoder;
}
}
return null;
}
/** ffmpeg's stdout, or null when it did not exit cleanly within the deadline. */
async function ffmpegStdout(
args: string[],
deadlineMs: number,
terminationGraceMs?: number,
): Promise<string | null> {
const ffmpeg = spawn(getFfmpegBinary(), args, {
stdio: ["ignore", "pipe", "pipe"],
// See runFfmpeg.ts: keeps a console window off the user's desktop on Windows.
windowsHide: true,
});
trackChildProcess(ffmpeg);
let stdout = "";
ffmpeg.stdout.on("data", (data) => {
stdout += data.toString();
});
const outcome = await new ManagedChildProcess(ffmpeg, {
deadlineAtMs: Date.now() + deadlineMs,
terminationGraceMs,
}).wait();
return outcome.reason === "exit" && outcome.exitCode === 0 ? stdout : null;
}
export async function detectGpuEncoder(): Promise<GpuEncoder> {
const stdout = await ffmpegStdout(["-encoders"], 30_000);
if (stdout === null) return null;
const candidates = getCompiledGpuEncoders(stdout);
return selectUsableGpuEncoder(candidates, canUseGpuEncoder).catch(() => null);
}
let cachedGpuEncoder: Promise<GpuEncoder> | undefined = undefined;
export function getCachedGpuEncoder(): Promise<GpuEncoder> {
cachedGpuEncoder ??= detectGpuEncoder();
return cachedGpuEncoder;
}
export function resetCachedGpuEncoder() {
cachedGpuEncoder = undefined;
}
export function getGpuEncoderName(encoder: GpuEncoder, codec: "h264" | "h265"): string {
if (!encoder) return codec === "h264" ? "libx264" : "libx265";
switch (encoder) {
case "nvenc":
return codec === "h264" ? "h264_nvenc" : "hevc_nvenc";
case "videotoolbox":
return codec === "h264" ? "h264_videotoolbox" : "hevc_videotoolbox";
case "vaapi":
return codec === "h264" ? "h264_vaapi" : "hevc_vaapi";
case "qsv":
return codec === "h264" ? "h264_qsv" : "hevc_qsv";
case "amf":
return codec === "h264" ? "h264_amf" : "hevc_amf";
default:
return codec === "h264" ? "libx264" : "libx265";
}
}
export function buildVideoToolboxRateControlArgs(input: {
bitrate?: string;
width: number;
height: number;
fps: number;
quality: number;
}): string[] {
if (input.bitrate) return ["-b:v", input.bitrate, "-allow_sw", "1"];
// VideoToolbox rejects FFmpeg's generic qscale path on supported macOS
// builds. Derive a bitrate from pixel rate instead: the three CRF-shaped
// quality tiers map to roughly 5M / 10M / 12M at 1080p24.
const bitsPerPixel = input.quality <= 15 ? 0.24 : input.quality <= 18 ? 0.16 : 0.08;
const megabitsPerSecond = Math.max(
1,
Math.round((input.width * input.height * input.fps * bitsPerPixel) / 1_000_000),
);
return ["-b:v", `${megabitsPerSecond}M`, "-allow_sw", "1"];
}
// Minimum probe dimensions must clear every GPU encoder's hardware minimum.
// NVIDIA data-center SKUs (L4/T4/A10/A100) reject frames below ~257px on
// either dimension with "Frame Dimension less than the minimum supported
// value" (observed on driver 595.58.03, CUDA 13.2). The documented SDK
// minimums (145×49 H.264, 129×33 HEVC) are lower, but the driver enforces
// a stricter per-SKU alignment. 320×240 clears all known GPU encoder
// minimums (NVENC, VideoToolbox, VAAPI, QSV, AMF) while staying cheap.
const GPU_PROBE_WIDTH = 320;
const GPU_PROBE_HEIGHT = 240;
export function getProbeArgs(encoder: ConcreteGpuEncoder): string[] {
const args = [
"-hide_banner",
"-loglevel",
"error",
"-f",
"lavfi",
"-i",
`color=size=${GPU_PROBE_WIDTH}x${GPU_PROBE_HEIGHT}:rate=1:duration=1`,
"-frames:v",
"1",
"-an",
];
if (encoder === "vaapi") {
args.push("-vaapi_device", "/dev/dri/renderD128", "-vf", "format=nv12,hwupload");
}
args.push("-c:v", getGpuEncoderName(encoder, "h264"));
if (encoder === "videotoolbox") {
args.push(
...buildVideoToolboxRateControlArgs({
width: GPU_PROBE_WIDTH,
height: GPU_PROBE_HEIGHT,
fps: 1,
quality: 23,
}),
);
}
if (encoder === "amf") {
args.push("-rc", "cqp", "-qp_i", "28", "-qp_p", "28");
}
args.push("-f", "null", "-");
return args;
}
async function canUseGpuEncoder(encoder: ConcreteGpuEncoder): Promise<boolean> {
const ffmpeg = spawn(getFfmpegBinary(), getProbeArgs(encoder), {
stdio: ["ignore", "ignore", "pipe"],
windowsHide: true,
});
trackChildProcess(ffmpeg);
const outcome = await new ManagedChildProcess(ffmpeg, {
deadlineAtMs: Date.now() + GPU_PROBE_TIMEOUT_MS,
terminationGraceMs: GPU_PROBE_KILL_GRACE_MS,
}).wait();
const usable = outcome.reason === "exit" && outcome.exitCode === 0;
logGpuProbeFailure(encoder, {
code: outcome.exitCode,
signal: outcome.signal,
stderr: outcome.stderr,
error: outcome.error,
timedOut: outcome.reason === "deadline",
});
return usable;
}
function logGpuProbeFailure(
encoder: ConcreteGpuEncoder,
result: {
code?: number | null;
error?: Error;
signal?: NodeJS.Signals | null;
stderr?: string;
timedOut?: boolean;
},
): void {
if (!isGpuProbeDebugEnabled()) return;
if (result.code === 0 && !result.error && !result.timedOut) return;
const reason = result.error
? result.error.message
: result.timedOut
? `timed out after ${GPU_PROBE_TIMEOUT_MS}ms`
: `exit=${String(result.code)} signal=${String(result.signal ?? "")}`;
const stderr = result.stderr?.trim();
console.warn(`[gpuEncoder] ${encoder} probe failed: ${reason}${stderr ? `\n${stderr}` : ""}`);
}
function isGpuProbeDebugEnabled(): boolean {
const value = process.env.HYPERFRAMES_DEBUG_GPU_PROBE;
return value === "1" || value === "true";
}
// libx264 preset names (ultrafast/superfast/.../placebo) mapped to the
// equivalent NVENC p1..p7 preset. NVENC rejects libx264 names with
// AVERROR(EINVAL) ("Error applying encoder options: Invalid argument"),
// which surfaces as a generic "FFmpeg exited with code -22" — so callers
// that share a single `preset` field across CPU and GPU paths (e.g. the
// `draft`/`standard`/`high` quality tiers) must translate before passing
// the value to h264_nvenc / hevc_nvenc.
const NVENC_PRESET_MAP: Record<string, string> = {
ultrafast: "p1",
superfast: "p1",
veryfast: "p2",
faster: "p3",
fast: "p4",
medium: "p4",
slow: "p5",
slower: "p6",
veryslow: "p7",
placebo: "p7",
};
// QSV accepts most libx264 preset names but rejects `ultrafast`,
// `superfast`, and `placebo`. Map those to the nearest supported values.
const QSV_PRESET_MAP: Record<string, string> = {
ultrafast: "veryfast",
superfast: "veryfast",
placebo: "veryslow",
};
/**
* Translate a libx264-style `-preset` value to one accepted by the given
* GPU encoder.
*
* - `nvenc`: libx264 names → `p1`..`p7`. Already-native `pN` values pass
* through unchanged. Unknown values fall back to `p4` (medium).
* - `qsv`: `ultrafast`/`superfast`/`placebo` → nearest supported name;
* everything else passes through.
* - `videotoolbox`, `vaapi`, `amf`, `null`: no remap (they either ignore
* `-preset` entirely or accept the libx264 vocabulary).
*/
export function mapPresetForGpuEncoder(
encoder: GpuEncoder,
preset: string,
nvencPresets?: ReadonlySet<string>,
): string {
switch (encoder) {
case "nvenc":
if (nvencPresets && nvencPresets.size > 0 && !nvencPresets.has("p4"))
return legacyNvencPreset(preset, nvencPresets);
if (/^p[1-7]$/.test(preset)) return preset;
return NVENC_PRESET_MAP[preset] ?? "p4";
case "qsv":
return QSV_PRESET_MAP[preset] ?? preset;
default:
return preset;
}
}
// Builds on an older NVENC SDK list `default slow medium fast hp hq ...` and reject p1..p7.
const LEGACY_NVENC_PRESET_MAP: Record<string, string> = {
ultrafast: "hp",
superfast: "hp",
veryfast: "hp",
faster: "fast",
fast: "fast",
medium: "medium",
slow: "slow",
slower: "slow",
veryslow: "slow",
placebo: "slow",
};
function legacyNvencPreset(preset: string, accepted: ReadonlySet<string>): string {
if (accepted.has(preset) && !/^p[1-7]$/.test(preset)) return preset;
const mapped = LEGACY_NVENC_PRESET_MAP[preset] ?? "medium";
return accepted.has(mapped) ? mapped : "default";
}
/** The names an encoder lists under its `-preset` option in `ffmpeg -h encoder=<name>`. */
export function parseEncoderPresetNames(helpText: string): ReadonlySet<string> {
const names = new Set<string>();
let inPreset = false;
for (const line of helpText.split(/\r?\n/)) {
if (/^\s{1,3}-\S/.test(line)) {
inPreset = /^\s{1,3}-preset\s/.test(line);
continue;
}
const entry = inPreset ? /^\s{4,}([a-z][a-z0-9_]*)\s+-?\d+\s+[E.]\S{3}/.exec(line) : null;
if (entry) names.add(entry[1]!);
}
return names;
}
let cachedNvencPresets: Promise<ReadonlySet<string>> | undefined = undefined;
/** The presets this ffmpeg's h264_nvenc takes; empty when it cannot be read, which keeps the pN names. */
export function getCachedNvencPresets(): Promise<ReadonlySet<string>> {
cachedNvencPresets ??= readNvencPresets();
return cachedNvencPresets;
}
async function readNvencPresets(): Promise<ReadonlySet<string>> {
const help = await ffmpegStdout(
["-hide_banner", "-h", "encoder=h264_nvenc"],
GPU_PROBE_TIMEOUT_MS,
GPU_PROBE_KILL_GRACE_MS,
).catch(() => null);
return help === null ? new Set() : parseEncoderPresetNames(help);
}