Open source Loom alternative. Beautiful, shareable screen recordings.
Rust appcapcossloommacnextjsnextjs15open-sourceossreactrecordrustscreen-capturescreen-recorderscreenshotsolidjstauritauri-apptypescriptvite
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/Dockerfileindex 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.tsnew file mode 100644index 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.tsindex 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.tsindex 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.tsindex 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.tsnew file mode 100644index 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.tsindex 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.tsindex 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.tsindex 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,