Skip to content

armgit / Cap

Public Imported from GitHub
0

Open source Loom alternative. Beautiful, shareable screen recordings.

feat(media-server): opt-in nvenc encode path and decode thread env knobs

Richie McIlroycc3b4d219706
diff --git a/apps/media-server/Dockerfile b/apps/media-server/Dockerfile
index 05fc8842d..4891e6452 100644
--- a/apps/media-server/Dockerfile
+++ b/apps/media-server/Dockerfile
@@ -19,7 +19,7 @@ RUN bun test src/__tests__/lib/audio-quality-policy.test.ts src/__tests__/lib/au
&& bun test src/__tests__/lib/media-size.test.ts src/__tests__/lib/media-probe.integration.test.ts \
&& bun test src/__tests__/lib/media-audio.integration.test.ts \
&& bun test src/__tests__/lib/recording-verification.integration.test.ts src/__tests__/lib/job-manager.test.ts \
- && bun test src/__tests__/lib/media-transfer.test.ts src/__tests__/lib/capcodec-encoder.test.ts \
+ && bun test src/__tests__/lib/media-transfer.test.ts src/__tests__/lib/capcodec-encoder.test.ts src/__tests__/lib/nvenc-encoder.test.ts \
&& bun test src/__tests__/routes/recording-verification.test.ts \
&& bun test src/__tests__/routes/video.test.ts \
&& bun test src/__tests__/lib/media-routes-real-world.integration.test.ts \
diff --git a/apps/media-server/src/__tests__/lib/nvenc-encoder.test.ts b/apps/media-server/src/__tests__/lib/nvenc-encoder.test.ts
new file mode 100644
index 000000000..f598e3d80
--- /dev/null
+++ b/apps/media-server/src/__tests__/lib/nvenc-encoder.test.ts
@@ -0,0 +1,642 @@
+import { describe, expect, test } from "bun:test";
+import { join } from "node:path";
+import type { VideoMetadata } from "../../lib/job-manager";
+import { decodeThreadsFromEnv } from "../../lib/media-common";
+import {
+ buildTranscodeEditArgs,
+ renderEditedVideo,
+} from "../../lib/media-edit";
+import { probeVideo } from "../../lib/media-probe";
+import {
+ buildProcessVideoArgs,
+ type ProcessVideoArgsInput,
+ pickMobileSafeH264Level,
+ processVideo,
+} from "../../lib/media-video";
+import {
+ buildNvencEncodeArgs,
+ buildNvencScaleFilter,
+ canDecodeOnGpu,
+ getVideoEncoderStatus,
+ type NvencOptions,
+ nvencCq,
+ nvencFallbackReason,
+ nvencOptionsFromEnv,
+ recordNvencAttempt,
+ selectedVideoEncoder,
+} from "../../lib/nvenc-encoder";
+
+const enabled = { CAP_MEDIA_VIDEO_ENCODER: "nvenc" };
+const defaults: NvencOptions = {
+ preset: "p5",
+ cqOffset: 2,
+ lookahead: 20,
+ spatialAq: true,
+ temporalAq: false,
+};
+const opts: ProcessVideoArgsInput["opts"] = {
+ maxWidth: 1920,
+ maxHeight: 1080,
+ preset: "medium",
+ crf: 23,
+ audioBitrate: "128k",
+};
+const nvencVideoArgs = [
+ "-c:v",
+ "h264_nvenc",
+ "-preset",
+ "p5",
+ "-tune",
+ "hq",
+ "-rc",
+ "vbr",
+ "-cq",
+ "25",
+ "-b:v",
+ "0",
+ "-spatial-aq",
+ "1",
+ "-rc-lookahead",
+ "20",
+ "-profile:v",
+ "high",
+ "-g",
+ "250",
+];
+const gpuScale =
+ "scale_cuda='min(1920,iw)':'min(1080,ih)':force_original_aspect_ratio=decrease:format=nv12,scale_cuda=trunc(iw/2)*2:trunc(ih/2)*2";
+const cpuScale =
+ "scale='min(1920,iw)':'min(1080,ih)':force_original_aspect_ratio=decrease,scale=trunc(iw/2)*2:trunc(ih/2)*2";
+
+function metadata(
+ width: number,
+ height: number,
+ videoCodec: string,
+): VideoMetadata {
+ return {
+ duration: 10,
+ width,
+ height,
+ fps: 30,
+ videoCodec,
+ audioCodec: "aac",
+ audioChannels: 2,
+ sampleRate: 48_000,
+ bitrate: 0,
+ fileSize: 0,
+ };
+}
+
+function processArgs(
+ source: VideoMetadata,
+ overrides: Partial<ProcessVideoArgsInput> = {},
+): ProcessVideoArgsInput {
+ return {
+ inputPath: "in.mp4",
+ outputPath: "out.mp4",
+ videoCodec: source.videoCodec,
+ hasAudio: true,
+ opts,
+ targetH264Level: pickMobileSafeH264Level(source, opts).ffmpegValue,
+ normalizeH264Level: false,
+ videoTranscode: true,
+ audioTranscode: false,
+ extraInputArgs: [],
+ extraOutputArgs: [],
+ decodeThreads: "2",
+ ...overrides,
+ };
+}
+
+const outputTail = [
+ "-c:a",
+ "copy",
+ "-movflags",
+ "+faststart",
+ "-progress",
+ "pipe:2",
+ "-y",
+ "out.mp4",
+];
+
+describe("nvenc encoder selection", () => {
+ test("is off unless CAP_MEDIA_VIDEO_ENCODER is nvenc", () => {
+ expect(selectedVideoEncoder({})).toBe("libx264");
+ expect(selectedVideoEncoder({ CAP_MEDIA_VIDEO_ENCODER: "x264" })).toBe(
+ "libx264",
+ );
+ expect(selectedVideoEncoder({ CAP_MEDIA_VIDEO_ENCODER: "capcodec" })).toBe(
+ "capcodec",
+ );
+ expect(selectedVideoEncoder(enabled)).toBe("nvenc");
+ expect(nvencOptionsFromEnv({})).toBeNull();
+ expect(
+ nvencOptionsFromEnv({ CAP_MEDIA_VIDEO_ENCODER: "capcodec" }),
+ ).toBeNull();
+ expect(getVideoEncoderStatus({})).toEqual({
+ active: "libx264",
+ nvenc: null,
+ });
+ });
+
+ test("uses p5, cq = crf + 2, lookahead 20 and spatial AQ by default", () => {
+ expect(nvencOptionsFromEnv(enabled)).toEqual(defaults);
+ });
+
+ test("reads tuning overrides from the environment", () => {
+ expect(
+ nvencOptionsFromEnv({
+ ...enabled,
+ CAP_NVENC_PRESET: " P7 ",
+ CAP_NVENC_CQ_OFFSET: "-3",
+ CAP_NVENC_LOOKAHEAD: "0",
+ CAP_NVENC_SPATIAL_AQ: "off",
+ CAP_NVENC_TEMPORAL_AQ: "1",
+ }),
+ ).toEqual({
+ preset: "p7",
+ cqOffset: -3,
+ lookahead: 0,
+ spatialAq: false,
+ temporalAq: true,
+ });
+ });
+
+ test("ignores invalid tuning overrides", () => {
+ expect(
+ nvencOptionsFromEnv({
+ ...enabled,
+ CAP_NVENC_PRESET: "slow",
+ CAP_NVENC_CQ_OFFSET: "2.5",
+ CAP_NVENC_LOOKAHEAD: "64",
+ CAP_NVENC_SPATIAL_AQ: "maybe",
+ CAP_NVENC_TEMPORAL_AQ: "",
+ }),
+ ).toEqual(defaults);
+ });
+
+ test("maps crf to a bounded cq", () => {
+ expect(nvencCq(23, 2)).toBe("25");
+ expect(nvencCq(18, 2)).toBe("20");
+ expect(nvencCq(20.5, 0)).toBe("20.5");
+ expect(nvencCq(50, 5)).toBe("51");
+ expect(nvencCq(0, -4)).toBe("1");
+ expect(nvencCq(Number.NaN, 2)).toBe("25");
+ });
+
+ test("builds constant-quality VBR encoder args", () => {
+ expect(buildNvencEncodeArgs(defaults, 23)).toEqual(nvencVideoArgs);
+ expect(
+ buildNvencEncodeArgs(
+ { ...defaults, lookahead: 0, spatialAq: false, temporalAq: true },
+ 18,
+ ),
+ ).toEqual([
+ "-c:v",
+ "h264_nvenc",
+ "-preset",
+ "p5",
+ "-tune",
+ "hq",
+ "-rc",
+ "vbr",
+ "-cq",
+ "20",
+ "-b:v",
+ "0",
+ "-temporal-aq",
+ "1",
+ "-profile:v",
+ "high",
+ "-g",
+ "250",
+ ]);
+ });
+
+ test("scales on the GPU with the CPU path's box and even dimensions", () => {
+ expect(buildNvencScaleFilter(1920, 1080)).toBe(gpuScale);
+ });
+
+ test("decodes on the GPU only for unrotated NVDEC codecs", () => {
+ for (const codec of ["h264", "hevc", "vp9", "av1"]) {
+ expect(canDecodeOnGpu(codec, 0)).toBe(true);
+ }
+ expect(canDecodeOnGpu("vp8", 0)).toBe(false);
+ expect(canDecodeOnGpu("prores", 0)).toBe(false);
+ expect(canDecodeOnGpu("hevc", 90)).toBe(false);
+ expect(canDecodeOnGpu("h264", null)).toBe(false);
+ });
+});
+
+describe("nvenc fallback", () => {
+ test("falls back to libx264 on any failure that was not a cancellation", () => {
+ expect(
+ nvencFallbackReason(
+ new Error("FFmpeg exited with code 1. Last stderr: No device"),
+ false,
+ ),
+ ).toBe("FFmpeg exited with code 1. Last stderr: No device");
+ expect(nvencFallbackReason("boom", false)).toBe("boom");
+ expect(nvencFallbackReason(new Error(""), false)).toBe("unknown error");
+ expect(
+ nvencFallbackReason(new Error("x".repeat(2000)), false),
+ ).toHaveLength(500);
+ expect(nvencFallbackReason(new Error("killed"), true)).toBeNull();
+ });
+
+ test("reports the last attempt through the encoder status", () => {
+ const before = getVideoEncoderStatus(enabled).nvenc;
+ recordNvencAttempt("process", "No NVENC capable devices found");
+ const fellBack = getVideoEncoderStatus(enabled).nvenc;
+ expect(fellBack?.attempts).toBe((before?.attempts ?? 0) + 1);
+ expect(fellBack?.fallbacks).toBe((before?.fallbacks ?? 0) + 1);
+ expect(fellBack?.lastAttempt).toMatchObject({
+ job: "process",
+ fellBack: true,
+ reason: "No NVENC capable devices found",
+ });
+ recordNvencAttempt("edit");
+ const succeeded = getVideoEncoderStatus(enabled).nvenc;
+ expect(succeeded?.fallbacks).toBe(fellBack?.fallbacks);
+ expect(succeeded?.lastAttempt).toMatchObject({
+ job: "edit",
+ fellBack: false,
+ reason: null,
+ });
+ });
+});
+
+describe("process video args", () => {
+ test("keeps the default libx264 args unchanged", () => {
+ const source = metadata(3024, 1964, "h264");
+ expect(buildProcessVideoArgs(processArgs(source))).toEqual([
+ "ffmpeg",
+ "-threads",
+ "2",
+ "-i",
+ "in.mp4",
+ "-c:v",
+ "libx264",
+ "-preset",
+ "medium",
+ "-crf",
+ "23",
+ "-vf",
+ cpuScale,
+ "-pix_fmt",
+ "yuv420p",
+ "-level:v",
+ "4.2",
+ ...outputTail,
+ ]);
+ });
+
+ test("runs a 3024x1964 H.264 source fully on the GPU", () => {
+ const source = metadata(3024, 1964, "h264");
+ expect(
+ buildProcessVideoArgs(
+ processArgs(source, {
+ nvenc: { options: defaults, gpuDecode: true },
+ }),
+ ),
+ ).toEqual([
+ "ffmpeg",
+ "-threads",
+ "2",
+ "-hwaccel",
+ "cuda",
+ "-hwaccel_output_format",
+ "cuda",
+ "-i",
+ "in.mp4",
+ ...nvencVideoArgs,
+ "-vf",
+ gpuScale,
+ "-level:v",
+ "4.2",
+ ...outputTail,
+ ]);
+ });
+
+ test("runs a 4K HEVC source fully on the GPU", () => {
+ const source = metadata(3840, 2160, "hevc");
+ expect(
+ buildProcessVideoArgs(
+ processArgs(source, {
+ inputPath: "in.mov",
+ audioTranscode: true,
+ nvenc: { options: defaults, gpuDecode: true },
+ }),
+ ),
+ ).toEqual([
+ "ffmpeg",
+ "-threads",
+ "2",
+ "-hwaccel",
+ "cuda",
+ "-hwaccel_output_format",
+ "cuda",
+ "-i",
+ "in.mov",
+ ...nvencVideoArgs,
+ "-vf",
+ gpuScale,
+ "-level:v",
+ "4.2",
+ "-c:a",
+ "aac",
+ "-b:a",
+ "128k",
+ "-movflags",
+ "+faststart",
+ "-progress",
+ "pipe:2",
+ "-y",
+ "out.mp4",
+ ]);
+ });
+
+ test("keeps -bf 0 for a 1080p VP9 webm", () => {
+ const source = metadata(1920, 1080, "vp9");
+ expect(
+ buildProcessVideoArgs(
+ processArgs(source, {
+ inputPath: "in.webm",
+ audioTranscode: true,
+ nvenc: { options: defaults, gpuDecode: true },
+ }),
+ ),
+ ).toEqual([
+ "ffmpeg",
+ "-threads",
+ "2",
+ "-hwaccel",
+ "cuda",
+ "-hwaccel_output_format",
+ "cuda",
+ "-i",
+ "in.webm",
+ ...nvencVideoArgs,
+ "-vf",
+ gpuScale,
+ "-level:v",
+ "4.2",
+ "-bf",
+ "0",
+ "-c:a",
+ "aac",
+ "-b:a",
+ "128k",
+ "-movflags",
+ "+faststart",
+ "-progress",
+ "pipe:2",
+ "-y",
+ "out.mp4",
+ ]);
+ });
+
+ test("scales on the CPU before NVENC when the GPU cannot decode", () => {
+ const source = metadata(1280, 720, "vp8");
+ expect(
+ buildProcessVideoArgs(
+ processArgs(source, {
+ inputPath: "in.webm",
+ decodeThreads: "4",
+ extraInputArgs: ["-fflags", "+genpts"],
+ extraOutputArgs: ["-max_muxing_queue_size", "4096"],
+ nvenc: { options: defaults, gpuDecode: false },
+ }),
+ ),
+ ).toEqual([
+ "ffmpeg",
+ "-threads",
+ "4",
+ "-fflags",
+ "+genpts",
+ "-i",
+ "in.webm",
+ ...nvencVideoArgs,
+ "-vf",
+ cpuScale,
+ "-pix_fmt",
+ "yuv420p",
+ "-level:v",
+ "4.2",
+ "-bf",
+ "0",
+ "-c:a",
+ "copy",
+ "-movflags",
+ "+faststart",
+ "-max_muxing_queue_size",
+ "4096",
+ "-progress",
+ "pipe:2",
+ "-y",
+ "out.mp4",
+ ]);
+ });
+
+ test("never touches level normalization or stream copies", () => {
+ const source = metadata(1920, 1080, "h264");
+ const nvenc = { options: defaults, gpuDecode: false };
+ expect(
+ buildProcessVideoArgs(
+ processArgs(source, { normalizeH264Level: true, nvenc }),
+ ),
+ ).toEqual([
+ "ffmpeg",
+ "-threads",
+ "2",
+ "-i",
+ "in.mp4",
+ "-c:v",
+ "copy",
+ "-bsf:v",
+ "h264_metadata=level=4.2",
+ ...outputTail,
+ ]);
+ expect(
+ buildProcessVideoArgs(
+ processArgs(source, { videoTranscode: false, hasAudio: false }),
+ ),
+ ).toEqual([
+ "ffmpeg",
+ "-threads",
+ "2",
+ "-i",
+ "in.mp4",
+ "-c:v",
+ "copy",
+ "-an",
+ ...outputTail.slice(2),
+ ]);
+ });
+});
+
+describe("edit re-encode args", () => {
+ const range = [{ start: 1, end: 3 }];
+
+ test("swaps libx264 for NVENC and keeps the rest of the edit graph", () => {
+ const libx264 = buildTranscodeEditArgs("in.mp4", range, "out.mp4", true);
+ const nvenc = buildTranscodeEditArgs(
+ "in.mp4",
+ range,
+ "out.mp4",
+ true,
+ 30,
+ defaults,
+ );
+ expect(libx264.slice(libx264.indexOf("[v]") + 1)).toEqual([
+ "-c:v",
+ "libx264",
+ "-preset",
+ "fast",
+ "-crf",
+ "18",
+ "-pix_fmt",
+ "yuv420p",
+ "-enc_time_base:v",
+ "1/30",
+ "-map",
+ "[a]",
+ "-c:a",
+ "aac",
+ "-b:a",
+ "160k",
+ "-movflags",
+ "+faststart",
+ "out.mp4",
+ ]);
+ expect(nvenc).toEqual([
+ "ffmpeg",
+ "-hide_banner",
+ "-y",
+ "-ss",
+ "1.000",
+ "-t",
+ "2.000",
+ "-i",
+ "in.mp4",
+ "-filter_complex",
+ "[0:v:0]fps=30,setpts=PTS-STARTPTS[v0];[0:a:0]asetpts=PTS-STARTPTS[a0];[v0][a0]concat=n=1:v=1:a=1[v][a]",
+ "-map",
+ "[v]",
+ "-c:v",
+ "h264_nvenc",
+ "-preset",
+ "p5",
+ "-tune",
+ "hq",
+ "-rc",
+ "vbr",
+ "-cq",
+ "20",
+ "-b:v",
+ "0",
+ "-spatial-aq",
+ "1",
+ "-rc-lookahead",
+ "20",
+ "-profile:v",
+ "high",
+ "-g",
+ "250",
+ "-pix_fmt",
+ "yuv420p",
+ "-enc_time_base:v",
+ "1/30",
+ "-map",
+ "[a]",
+ "-c:a",
+ "aac",
+ "-b:a",
+ "160k",
+ "-movflags",
+ "+faststart",
+ "out.mp4",
+ ]);
+ });
+});
+
+describe("decode thread overrides", () => {
+ test("keep today's defaults unless set to a valid count", () => {
+ const name = "MEDIA_SERVER_VERIFY_DECODE_THREADS";
+ expect(decodeThreadsFromEnv(name, 1, {})).toBe("1");
+ expect(decodeThreadsFromEnv(name, 1, { [name]: " " })).toBe("1");
+ expect(decodeThreadsFromEnv(name, 1, { [name]: "4" })).toBe("4");
+ expect(decodeThreadsFromEnv(name, 2, { [name]: "0" })).toBe("0");
+ expect(decodeThreadsFromEnv(name, 2, { [name]: "-1" })).toBe("2");
+ expect(decodeThreadsFromEnv(name, 2, { [name]: "1.5" })).toBe("2");
+ expect(decodeThreadsFromEnv(name, 2, { [name]: "65" })).toBe("2");
+ expect(decodeThreadsFromEnv(name, 2, { [name]: "auto" })).toBe("2");
+ });
+});
+
+describe("nvenc jobs on hosts without an NVENC device", () => {
+ const fixture = join(
+ import.meta.dir,
+ "..",
+ "fixtures",
+ "test-with-audio.mp4",
+ );
+
+ async function withNvencEnv<T>(run: () => Promise<T>): Promise<T> {
+ const previous = process.env.CAP_MEDIA_VIDEO_ENCODER;
+ process.env.CAP_MEDIA_VIDEO_ENCODER = "nvenc";
+ try {
+ return await run();
+ } finally {
+ if (previous === undefined) delete process.env.CAP_MEDIA_VIDEO_ENCODER;
+ else process.env.CAP_MEDIA_VIDEO_ENCODER = previous;
+ }
+ }
+
+ function expectRecordedAttempt(job: "process" | "edit", attempts: number) {
+ const status = getVideoEncoderStatus(enabled).nvenc;
+ expect(status?.attempts).toBe(attempts + 1);
+ expect(status?.lastAttempt?.job).toBe(job);
+ if (status?.lastAttempt?.fellBack) {
+ expect(status.lastAttempt.reason).toBeString();
+ }
+ }
+
+ test("still produces the transcode", async () => {
+ const metadata = await probeVideo(`file://${fixture}`);
+ const attempts = getVideoEncoderStatus(enabled).nvenc?.attempts ?? 0;
+ const output = await withNvencEnv(() =>
+ processVideo(fixture, metadata, { maxWidth: 160, maxHeight: 120 }),
+ );
+ try {
+ const result = await probeVideo(`file://${output.path}`);
+ expect(result.videoCodec).toBe("h264");
+ expect(result.width).toBe(160);
+ expect(result.height).toBe(120);
+ expect(result.audioCodec).toBe("aac");
+ expectRecordedAttempt("process", attempts);
+ } finally {
+ await output.cleanup();
+ }
+ });
+
+ test("still renders the edit", async () => {
+ const metadata = await probeVideo(`file://${fixture}`);
+ const attempts = getVideoEncoderStatus(enabled).nvenc?.attempts ?? 0;
+ const output = await withNvencEnv(() =>
+ renderEditedVideo({
+ inputPath: fixture,
+ keepRanges: [{ start: 0, end: 0.5 }],
+ metadata,
+ }),
+ );
+ try {
+ const result = await probeVideo(`file://${output.path}`);
+ expect(result.videoCodec).toBe("h264");
+ expect(result.audioCodec).toBe("aac");
+ expectRecordedAttempt("edit", attempts);
+ } finally {
+ await output.cleanup();
+ }
+ });
+});
diff --git a/apps/media-server/src/lib/media-common.ts b/apps/media-server/src/lib/media-common.ts
index ad3c69224..875a8faba 100644
--- a/apps/media-server/src/lib/media-common.ts
+++ b/apps/media-server/src/lib/media-common.ts
@@ -32,6 +32,20 @@ export const DOWNLOAD_TIMEOUT_MS = 10 * 60 * 1000;
export const UPLOAD_TIMEOUT_MS = 10 * 60 * 1000;
const mediaFetch: typeof fetch = globalThis.fetch.bind(globalThis);
+export function decodeThreadsFromEnv(
+ name: string,
+ fallback: number,
+ env: Record<string, string | undefined> = process.env,
+): string {
+ const raw = env[name]?.trim();
+ if (!raw) return String(fallback);
+ const value = Number(raw);
+ if (!Number.isInteger(value) || value < 0 || value > 64) {
+ return String(fallback);
+ }
+ return String(value);
+}
+
export async function withTimeout<T>(
promise: Promise<T>,
timeoutMs: number,
diff --git a/apps/media-server/src/lib/media-edit.ts b/apps/media-server/src/lib/media-edit.ts
index aa8b69c53..406dd7034 100644
--- a/apps/media-server/src/lib/media-edit.ts
+++ b/apps/media-server/src/lib/media-edit.ts
@@ -1,6 +1,14 @@
import { writeFile } from "node:fs/promises";
import { file, spawn } from "bun";
import type { VideoMetadata } from "./job-manager";
+import {
+ buildNvencEncodeArgs,
+ logNvencFallback,
+ type NvencOptions,
+ nvencFallbackReason,
+ nvencOptionsFromEnv,
+ recordNvencAttempt,
+} from "./nvenc-encoder";
import { registerSubprocess, terminateProcess } from "./subprocess";
import { createTempFile, type TempFileHandle } from "./temp-files";
@@ -24,6 +32,7 @@ const DEFAULT_TIMEOUT_MS = 10 * 60 * 1000;
const MAX_TIMEOUT_MS = 60 * 60 * 1000;
const DEFAULT_OUTPUT_FPS = 30;
const MAX_TRANSCODE_RANGES_PER_BATCH = 4;
+const EDIT_CRF = 18;
function roundTime(value: number) {
return Math.round(value * 1000) / 1000;
@@ -154,6 +163,7 @@ export function buildTranscodeEditArgs(
outputPath: string,
hasAudio: boolean,
fps = DEFAULT_OUTPUT_FPS,
+ nvenc: NvencOptions | null = null,
) {
if (ranges.length === 0 || ranges.length > MAX_TRANSCODE_RANGES_PER_BATCH) {
throw new Error(
@@ -187,12 +197,9 @@ export function buildTranscodeEditArgs(
[...filters, concat].join(";"),
"-map",
"[v]",
- "-c:v",
- "libx264",
- "-preset",
- "fast",
- "-crf",
- "18",
+ ...(nvenc
+ ? buildNvencEncodeArgs(nvenc, EDIT_CRF)
+ : ["-c:v", "libx264", "-preset", "fast", "-crf", String(EDIT_CRF)]),
"-pix_fmt",
"yuv420p",
"-enc_time_base:v",
@@ -398,6 +405,7 @@ async function renderTranscodedEdit(
hasAudio: boolean,
fps: number | undefined,
timeoutMs: number,
+ nvenc: NvencOptions | null,
onProgress?: ProgressCallback,
abortSignal?: AbortSignal,
) {
@@ -411,7 +419,14 @@ async function renderTranscodedEdit(
const batchFile = await createTempFile(".mp4");
batchFiles.push(batchFile);
await runFfmpegCommand(
- buildTranscodeEditArgs(inputPath, batch, batchFile.path, hasAudio, fps),
+ buildTranscodeEditArgs(
+ inputPath,
+ batch,
+ batchFile.path,
+ hasAudio,
+ fps,
+ nvenc,
+ ),
getRemainingTimeoutMs(startedAt, timeoutMs),
abortSignal,
);
@@ -456,14 +471,36 @@ export async function renderEditedVideo({
}
const timeoutMs = getTimeoutMs(normalizedRanges);
+ const render = (nvenc: NvencOptions | null) =>
+ renderTranscodedEdit(
+ inputPath,
+ normalizedRanges,
+ Boolean(metadata.audioCodec),
+ metadata.fps,
+ timeoutMs,
+ nvenc,
+ onProgress,
+ abortSignal,
+ );
- return await renderTranscodedEdit(
- inputPath,
- normalizedRanges,
- Boolean(metadata.audioCodec),
- metadata.fps,
- timeoutMs,
- onProgress,
- abortSignal,
- );
+ const nvenc = nvencOptionsFromEnv();
+ if (nvenc) {
+ try {
+ const outputFile = await render(nvenc);
+ recordNvencAttempt("edit");
+ return outputFile;
+ } catch (error) {
+ const reason = nvencFallbackReason(error, abortSignal?.aborted ?? false);
+ if (reason === null) throw error;
+ recordNvencAttempt("edit", reason);
+ logNvencFallback({
+ job: "edit",
+ sourceCodec: metadata.videoCodec,
+ gpuDecode: false,
+ reason,
+ });
+ }
+ }
+
+ return await render(null);
}
diff --git a/apps/media-server/src/lib/media-video.ts b/apps/media-server/src/lib/media-video.ts
index d2645568e..3b74caa1c 100644
--- a/apps/media-server/src/lib/media-video.ts
+++ b/apps/media-server/src/lib/media-video.ts
@@ -13,6 +13,7 @@ import { uploadDriveResumable } from "./drive-resumable-upload";
import type { VideoMetadata } from "./job-manager";
import {
DOWNLOAD_TIMEOUT_MS,
+ decodeThreadsFromEnv,
normalizeLocalPath,
PROCESS_TIMEOUT_MS,
type ProgressCallback,
@@ -21,6 +22,17 @@ import {
} from "./media-common";
import { probeVideoFile } from "./media-probe";
import { fetchMedia, materializeMedia } from "./media-transfer";
+import {
+ buildNvencEncodeArgs,
+ buildNvencScaleFilter,
+ canDecodeOnGpu,
+ logNvencFallback,
+ NVENC_HWACCEL_INPUT_ARGS,
+ type NvencOptions,
+ nvencFallbackReason,
+ nvencOptionsFromEnv,
+ recordNvencAttempt,
+} from "./nvenc-encoder";
import {
downloadUrlToPathParallel,
parallelDownloadOptionsFromEnv,
@@ -1441,10 +1453,11 @@ export function pickMobileSafeH264Level(
return { value: 52, ffmpegValue: "5.2" };
}
-async function probeH264Level(
+async function probeVideoStreamEntries(
inputPath: string,
+ showEntries: string,
abortSignal?: AbortSignal,
-): Promise<number | null> {
+): Promise<string | null> {
const proc = registerSubprocess(
spawn({
cmd: [
@@ -1454,7 +1467,7 @@ async function probeH264Level(
"-select_streams",
"v:0",
"-show_entries",
- "stream=level",
+ showEntries,
"-of",
"default=noprint_wrappers=1:nokey=1",
inputPath,
@@ -1488,10 +1501,7 @@ async function probeH264Level(
);
const exitCode = await proc.exited;
if (exitCode !== 0) return null;
-
- const rawLevel = stdout.trim().split(/\s+/)[0] ?? "";
- const level = Number.parseInt(rawLevel, 10);
- return Number.isFinite(level) && level > 0 ? level : null;
+ return stdout.trim();
} catch {
return null;
} finally {
@@ -1502,6 +1512,37 @@ async function probeH264Level(
}
}
+async function probeH264Level(
+ inputPath: string,
+ abortSignal?: AbortSignal,
+): Promise<number | null> {
+ const stdout = await probeVideoStreamEntries(
+ inputPath,
+ "stream=level",
+ abortSignal,
+ );
+ if (stdout === null) return null;
+ const rawLevel = stdout.split(/\s+/)[0] ?? "";
+ const level = Number.parseInt(rawLevel, 10);
+ return Number.isFinite(level) && level > 0 ? level : null;
+}
+
+async function probeVideoRotation(
+ inputPath: string,
+ abortSignal?: AbortSignal,
+): Promise<number | null> {
+ const stdout = await probeVideoStreamEntries(
+ inputPath,
+ "stream_side_data=rotation",
+ abortSignal,
+ );
+ if (stdout === null) return null;
+ const rawRotation = stdout.split(/\s+/)[0] ?? "";
+ if (rawRotation === "") return 0;
+ const rotation = Number.parseFloat(rawRotation);
+ return Number.isFinite(rotation) ? rotation : null;
+}
+
export async function processVideo(
inputPath: string,
metadata: VideoMetadata,
@@ -1566,38 +1607,142 @@ export async function processVideo(
throw err;
}
}
+ const argsInput: ProcessVideoArgsInput = {
+ inputPath,
+ outputPath: outputTempFile.path,
+ videoCodec: metadata.videoCodec,
+ hasAudio: Boolean(metadata.audioCodec),
+ opts,
+ targetH264Level: targetH264Level.ffmpegValue,
+ normalizeH264Level,
+ videoTranscode,
+ audioTranscode,
+ extraInputArgs,
+ extraOutputArgs,
+ decodeThreads: decodeThreadsFromEnv(
+ "MEDIA_SERVER_PROCESS_DECODE_THREADS",
+ 2,
+ ),
+ };
+ const totalDurationUs = metadata.duration * 1_000_000;
+ const nvenc =
+ videoTranscode && !normalizeH264Level ? nvencOptionsFromEnv() : null;
+
+ try {
+ if (nvenc) {
+ const gpuDecode = canDecodeOnGpu(
+ metadata.videoCodec,
+ await probeVideoRotation(inputPath, abortSignal),
+ );
+ try {
+ await runTranscodeCommand(
+ buildProcessVideoArgs({
+ ...argsInput,
+ nvenc: { options: nvenc, gpuDecode },
+ }),
+ outputTempFile.path,
+ totalDurationUs,
+ processTimeoutMs,
+ onProgress,
+ abortSignal,
+ );
+ recordNvencAttempt("process");
+ return outputTempFile;
+ } catch (error) {
+ const reason = nvencFallbackReason(
+ error,
+ abortSignal?.aborted ?? false,
+ );
+ if (reason === null) throw error;
+ recordNvencAttempt("process", reason);
+ logNvencFallback({
+ job: "process",
+ sourceCodec: metadata.videoCodec,
+ gpuDecode,
+ reason,
+ });
+ }
+ }
+
+ await runTranscodeCommand(
+ buildProcessVideoArgs(argsInput),
+ outputTempFile.path,
+ totalDurationUs,
+ processTimeoutMs,
+ onProgress,
+ abortSignal,
+ );
+ return outputTempFile;
+ } catch (err) {
+ await outputTempFile.cleanup();
+ throw err;
+ }
+}
+
+export interface ProcessVideoArgsInput {
+ inputPath: string;
+ outputPath: string;
+ videoCodec: string;
+ hasAudio: boolean;
+ opts: Pick<
+ Required<VideoProcessingOptions>,
+ "maxWidth" | "maxHeight" | "preset" | "crf" | "audioBitrate"
+ >;
+ targetH264Level: string;
+ normalizeH264Level: boolean;
+ videoTranscode: boolean;
+ audioTranscode: boolean;
+ extraInputArgs: string[];
+ extraOutputArgs: string[];
+ decodeThreads: string;
+ nvenc?: { options: NvencOptions; gpuDecode: boolean } | null;
+}
+
+export function buildProcessVideoArgs(input: ProcessVideoArgsInput): string[] {
+ const { opts, nvenc } = input;
+ const gpuDecode = Boolean(nvenc?.gpuDecode);
+ const cpuScaleFilter = `scale='min(${opts.maxWidth},iw)':'min(${opts.maxHeight},ih)':force_original_aspect_ratio=decrease,scale=trunc(iw/2)*2:trunc(ih/2)*2`;
const ffmpegArgs: string[] = [
"ffmpeg",
"-threads",
- "2",
- ...extraInputArgs,
+ input.decodeThreads,
+ ...(gpuDecode ? NVENC_HWACCEL_INPUT_ARGS : []),
+ ...input.extraInputArgs,
"-i",
- inputPath,
+ input.inputPath,
];
- if (normalizeH264Level) {
+ if (input.normalizeH264Level) {
ffmpegArgs.push(
"-c:v",
"copy",
"-bsf:v",
- `h264_metadata=level=${targetH264Level.ffmpegValue}`,
+ `h264_metadata=level=${input.targetH264Level}`,
);
- } else if (videoTranscode) {
- ffmpegArgs.push(
- "-c:v",
- "libx264",
- "-preset",
- opts.preset,
- "-crf",
- opts.crf.toString(),
- "-vf",
- `scale='min(${opts.maxWidth},iw)':'min(${opts.maxHeight},ih)':force_original_aspect_ratio=decrease,scale=trunc(iw/2)*2:trunc(ih/2)*2`,
- "-pix_fmt",
- "yuv420p",
- "-level:v",
- targetH264Level.ffmpegValue,
- );
- if (metadata.videoCodec === "vp8" || metadata.videoCodec === "vp9") {
+ } else if (input.videoTranscode) {
+ if (nvenc) {
+ ffmpegArgs.push(
+ ...buildNvencEncodeArgs(nvenc.options, opts.crf),
+ ...(gpuDecode
+ ? ["-vf", buildNvencScaleFilter(opts.maxWidth, opts.maxHeight)]
+ : ["-vf", cpuScaleFilter, "-pix_fmt", "yuv420p"]),
+ );
+ } else {
+ ffmpegArgs.push(
+ "-c:v",
+ "libx264",
+ "-preset",
+ opts.preset,
+ "-crf",
+ opts.crf.toString(),
+ "-vf",
+ cpuScaleFilter,
+ "-pix_fmt",
+ "yuv420p",
+ );
+ }
+ ffmpegArgs.push("-level:v", input.targetH264Level);
+ if (input.videoCodec === "vp8" || input.videoCodec === "vp9") {
// Reordered B-frames can make MP4 duration exclude the tail of sparse browser captures.
ffmpegArgs.push("-bf", "0");
}
@@ -1605,8 +1750,8 @@ export async function processVideo(
ffmpegArgs.push("-c:v", "copy");
}
- if (metadata.audioCodec) {
- if (audioTranscode) {
+ if (input.hasAudio) {
+ if (input.audioTranscode) {
ffmpegArgs.push("-c:a", "aac", "-b:a", opts.audioBitrate);
} else {
ffmpegArgs.push("-c:a", "copy");
@@ -1618,13 +1763,23 @@ export async function processVideo(
ffmpegArgs.push(
"-movflags",
"+faststart",
- ...extraOutputArgs,
+ ...input.extraOutputArgs,
"-progress",
"pipe:2",
"-y",
- outputTempFile.path,
+ input.outputPath,
);
+ return ffmpegArgs;
+}
+async function runTranscodeCommand(
+ ffmpegArgs: string[],
+ outputPath: string,
+ totalDurationUs: number,
+ processTimeoutMs: number,
+ onProgress?: ProgressCallback,
+ abortSignal?: AbortSignal,
+): Promise<void> {
const proc = registerSubprocess(
spawn({
cmd: ffmpegArgs,
@@ -1632,7 +1787,6 @@ export async function processVideo(
stderr: "pipe",
}),
);
- const totalDurationUs = metadata.duration * 1_000_000;
let abortCleanup: (() => void) | undefined;
if (abortSignal) {
abortCleanup = () => {
@@ -1686,7 +1840,7 @@ export async function processVideo(
);
}
- const outputSize = await file(outputTempFile.path).size;
+ const outputSize = await file(outputPath).size;
if (outputSize === 0) {
throw new Error("FFmpeg produced empty output file");
}
@@ -1694,11 +1848,6 @@ export async function processVideo(
processTimeoutMs,
() => terminateProcess(proc),
);
-
- return outputTempFile;
- } catch (err) {
- await outputTempFile.cleanup();
- throw err;
} finally {
if (abortCleanup) {
abortSignal?.removeEventListener("abort", abortCleanup);
diff --git a/apps/media-server/src/lib/nvenc-encoder.ts b/apps/media-server/src/lib/nvenc-encoder.ts
new file mode 100644
index 000000000..6a784780f
--- /dev/null
+++ b/apps/media-server/src/lib/nvenc-encoder.ts
@@ -0,0 +1,190 @@
+const DEFAULT_PRESET = "p5";
+const DEFAULT_CQ_OFFSET = 2;
+const DEFAULT_LOOKAHEAD = 20;
+const MAX_LOOKAHEAD = 32;
+const GOP_LENGTH = "250";
+const NVENC_PRESETS = new Set(["p1", "p2", "p3", "p4", "p5", "p6", "p7"]);
+const NVDEC_CODECS = new Set(["h264", "hevc", "vp9", "av1"]);
+const MAX_FALLBACK_REASON_LENGTH = 500;
+
+export const NVENC_HWACCEL_INPUT_ARGS = [
+ "-hwaccel",
+ "cuda",
+ "-hwaccel_output_format",
+ "cuda",
+];
+
+export type VideoEncoderName = "libx264" | "capcodec" | "nvenc";
+export type NvencJobKind = "process" | "edit";
+
+export interface NvencOptions {
+ preset: string;
+ cqOffset: number;
+ lookahead: number;
+ spatialAq: boolean;
+ temporalAq: boolean;
+}
+
+interface NvencAttempt {
+ job: NvencJobKind;
+ at: string;
+ fellBack: boolean;
+ reason: string | null;
+}
+
+const nvencStatus: {
+ attempts: number;
+ fallbacks: number;
+ lastAttempt: NvencAttempt | null;
+} = { attempts: 0, fallbacks: 0, lastAttempt: null };
+
+type Env = Record<string, string | undefined>;
+
+export function selectedVideoEncoder(env: Env = process.env): VideoEncoderName {
+ const value = env.CAP_MEDIA_VIDEO_ENCODER;
+ if (value === "capcodec" || value === "nvenc") return value;
+ return "libx264";
+}
+
+function parseBoundedInt(
+ raw: string | undefined,
+ min: number,
+ max: number,
+): number | undefined {
+ if (raw === undefined || raw.trim() === "") return undefined;
+ const value = Number(raw);
+ if (!Number.isInteger(value) || value < min || value > max) return undefined;
+ return value;
+}
+
+function parseToggle(raw: string | undefined): boolean | undefined {
+ const normalized = raw?.trim().toLowerCase();
+ if (normalized === "1" || normalized === "true" || normalized === "on") {
+ return true;
+ }
+ if (normalized === "0" || normalized === "false" || normalized === "off") {
+ return false;
+ }
+ return undefined;
+}
+
+export function nvencOptionsFromEnv(
+ env: Env = process.env,
+): NvencOptions | null {
+ if (selectedVideoEncoder(env) !== "nvenc") return null;
+ const preset = env.CAP_NVENC_PRESET?.trim().toLowerCase() ?? "";
+ return {
+ preset: NVENC_PRESETS.has(preset) ? preset : DEFAULT_PRESET,
+ cqOffset:
+ parseBoundedInt(env.CAP_NVENC_CQ_OFFSET, -51, 51) ?? DEFAULT_CQ_OFFSET,
+ lookahead:
+ parseBoundedInt(env.CAP_NVENC_LOOKAHEAD, 0, MAX_LOOKAHEAD) ??
+ DEFAULT_LOOKAHEAD,
+ spatialAq: parseToggle(env.CAP_NVENC_SPATIAL_AQ) ?? true,
+ temporalAq: parseToggle(env.CAP_NVENC_TEMPORAL_AQ) ?? false,
+ };
+}
+
+export function nvencCq(crf: number, cqOffset: number): string {
+ const base = Number.isFinite(crf) ? crf : 23;
+ const cq = Math.min(51, Math.max(1, base + cqOffset));
+ return String(Math.round(cq * 1000) / 1000);
+}
+
+export function buildNvencEncodeArgs(
+ options: NvencOptions,
+ crf: number,
+): string[] {
+ return [
+ "-c:v",
+ "h264_nvenc",
+ "-preset",
+ options.preset,
+ "-tune",
+ "hq",
+ "-rc",
+ "vbr",
+ "-cq",
+ nvencCq(crf, options.cqOffset),
+ "-b:v",
+ "0",
+ ...(options.spatialAq ? ["-spatial-aq", "1"] : []),
+ ...(options.temporalAq ? ["-temporal-aq", "1"] : []),
+ ...(options.lookahead > 0
+ ? ["-rc-lookahead", String(options.lookahead)]
+ : []),
+ "-profile:v",
+ "high",
+ // h264_nvenc otherwise inherits the preset's GOP; pin libx264's default keyint.
+ "-g",
+ GOP_LENGTH,
+ ];
+}
+
+export function buildNvencScaleFilter(
+ maxWidth: number,
+ maxHeight: number,
+): string {
+ return `scale_cuda='min(${maxWidth},iw)':'min(${maxHeight},ih)':force_original_aspect_ratio=decrease:format=nv12,scale_cuda=trunc(iw/2)*2:trunc(ih/2)*2`;
+}
+
+// FFmpeg skips autorotation for hardware frames, so rotated sources decode on the CPU to keep the libx264 geometry.
+export function canDecodeOnGpu(
+ videoCodec: string,
+ rotation: number | null,
+): boolean {
+ return NVDEC_CODECS.has(videoCodec) && rotation === 0;
+}
+
+export function nvencFallbackReason(
+ error: unknown,
+ aborted: boolean,
+): string | null {
+ if (aborted) return null;
+ const message = error instanceof Error ? error.message : String(error);
+ return message.slice(-MAX_FALLBACK_REASON_LENGTH) || "unknown error";
+}
+
+export function recordNvencAttempt(
+ job: NvencJobKind,
+ fallbackReason: string | null = null,
+): void {
+ nvencStatus.attempts += 1;
+ if (fallbackReason !== null) nvencStatus.fallbacks += 1;
+ nvencStatus.lastAttempt = {
+ job,
+ at: new Date().toISOString(),
+ fellBack: fallbackReason !== null,
+ reason: fallbackReason,
+ };
+}
+
+export function logNvencFallback(details: {
+ job: NvencJobKind;
+ sourceCodec: string;
+ gpuDecode: boolean;
+ reason: string;
+}): void {
+ console.warn(
+ JSON.stringify({
+ event: "nvenc_fallback_to_libx264",
+ timestamp: new Date().toISOString(),
+ ...details,
+ }),
+ );
+}
+
+export function getVideoEncoderStatus(env: Env = process.env) {
+ const active = selectedVideoEncoder(env);
+ return {
+ active,
+ nvenc:
+ active === "nvenc"
+ ? {
+ attempts: nvencStatus.attempts,
+ fallbacks: nvencStatus.fallbacks,
+ lastAttempt: nvencStatus.lastAttempt,
+ }
+ : null,
+ };
+}
diff --git a/apps/media-server/src/lib/recording-verification.ts b/apps/media-server/src/lib/recording-verification.ts
index 9a599fbf0..948115302 100644
--- a/apps/media-server/src/lib/recording-verification.ts
+++ b/apps/media-server/src/lib/recording-verification.ts
@@ -5,7 +5,7 @@ import { lstat } from "node:fs/promises";
import { isAbsolute } from "node:path";
import { Readable } from "node:stream";
import { setTimeout as sleep } from "node:timers/promises";
-import { PROCESS_TIMEOUT_MS } from "./media-common";
+import { decodeThreadsFromEnv, PROCESS_TIMEOUT_MS } from "./media-common";
import {
fetchMedia,
MediaTransferBudgetError,
@@ -890,8 +890,9 @@ async function decodeRecording(
"1",
"-filter_complex_threads",
"1",
+ // FFmpeg's H.264/HEVC decoders are bit-exact across thread counts, so decoded hashes do not depend on this.
"-threads",
- "1",
+ decodeThreadsFromEnv("MEDIA_SERVER_VERIFY_DECODE_THREADS", 1),
"-protocol_whitelist",
remote ? "http,https,tcp,tls" : "file",
"-f",
diff --git a/apps/media-server/src/lib/video-input-validation.ts b/apps/media-server/src/lib/video-input-validation.ts
index 41e265323..2adb2dbbe 100644
--- a/apps/media-server/src/lib/video-input-validation.ts
+++ b/apps/media-server/src/lib/video-input-validation.ts
@@ -1,5 +1,9 @@
import { spawn } from "bun";
-import { PROCESS_TIMEOUT_MS, withTimeout } from "./media-common";
+import {
+ decodeThreadsFromEnv,
+ PROCESS_TIMEOUT_MS,
+ withTimeout,
+} from "./media-common";
import { registerSubprocess, terminateProcess } from "./subprocess";
const MAX_DIAGNOSTIC_LENGTH = 8_192;
@@ -22,7 +26,7 @@ export async function validateVideoInput(
"-err_detect",
"explode+crccheck",
"-threads",
- "2",
+ decodeThreadsFromEnv("MEDIA_SERVER_VALIDATE_DECODE_THREADS", 2),
"-i",
inputPath,
"-map",
diff --git a/apps/media-server/src/routes/health.ts b/apps/media-server/src/routes/health.ts
index 07b2731ab..6a69c7ef2 100644
--- a/apps/media-server/src/routes/health.ts
+++ b/apps/media-server/src/routes/health.ts
@@ -2,6 +2,7 @@ import os from "node:os";
import { Hono } from "hono";
import { getSystemResources } from "../lib/job-manager";
import { getMediaEngineStatus } from "../lib/media-engine";
+import { getVideoEncoderStatus } from "../lib/nvenc-encoder";
const health = new Hono();
@@ -25,6 +26,7 @@ health.get("/", (c) => {
available: mediaEngine.available,
version: mediaEngine.version,
},
+ videoEncoder: getVideoEncoderStatus(),
system: {
...resources,
loadAvg5m,