mirror of
https://github.com/heygen-com/hyperframes.git
synced 2026-11-18 07:50:13 +00:00
* 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
348 lines
11 KiB
TypeScript
348 lines
11 KiB
TypeScript
// 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);
|
||
}
|