// fallow-ignore-file code-duplication complexity /** * Chunk Encoder Service * * Encodes captured frames into video using FFmpeg. * Supports CPU (libx264) and GPU encoding. */ import { frameSequencePath } from "./extractedFrameIndex.js"; import { closeSync, copyFileSync, existsSync, ftruncateSync, mkdirSync, openSync, readFileSync, readdirSync, statSync, writeFileSync, writeSync, } from "fs"; import { join, dirname, extname, resolve } from "path"; import { DEFAULT_CONFIG, type EngineConfig } from "../config.js"; import { type GpuEncoder, getCachedGpuEncoder, getCachedNvencPresets, getGpuEncoderName, buildVideoToolboxRateControlArgs, mapPresetForGpuEncoder, } from "../utils/gpuEncoder.js"; import { type HdrTransfer, getHdrEncoderColorParams, hdrFrameTagsFilter } from "../utils/hdr.js"; import { withEvenDimensionPad } from "../utils/evenDimensions.js"; import { SDR_CAPTURE_TO_BT709_FILTER, SDR_RGB_TO_TAGGED_BT709_FILTER, } from "../utils/sdrCaptureColor.js"; import { describeFfmpegFailure, ffmpegStatsReader, formatFfmpegError, isExternalFfmpegInterruption, runFfmpeg, } from "../utils/runFfmpeg.js"; import { extractAudioMetadata } from "../utils/ffprobe.js"; import { type Fps, fpsToFfmpegArg, fpsToNumber } from "@hyperframes/core"; import type { EncoderOptions, EncodeResult, MuxResult } from "./chunkEncoder.types.js"; import { appendVp9CpuUsedArg } from "./vp9Options.js"; import { appendSoftwareEncoderThreadsArg } from "./softwareEncoderThreads.js"; import { appendRenderProvenanceArgs } from "../utils/renderProvenance.js"; import { createStagingDir } from "@hyperframes/core/atomic-file"; export type { EncoderOptions, EncodeResult, MuxResult } from "./chunkEncoder.types.js"; export const ENCODER_PRESETS = { draft: { preset: "ultrafast", quality: 28, codec: "h264" as const }, standard: { preset: "medium", quality: 18, codec: "h264" as const }, high: { preset: "fast", quality: 15, codec: "h264" as const }, }; export type ChromaSubsampling = "420" | "444"; export interface EncoderPreset { preset: string; quality: number; codec: "h264" | "h265" | "vp9" | "prores"; pixelFormat: string; hdr?: { transfer: HdrTransfer }; } function appendEncodeTimeoutMessage(error: string, timedOut: boolean, timeoutMs: number): string { if (!timedOut) return error; return ( `${error}\nFFmpeg killed after writing no new frame for ffmpegEncodeTimeout (${timeoutMs} ms). ` + "An encode that is still writing frames is never stopped; if this encoder legitimately " + "pauses longer between frames, raise FFMPEG_ENCODE_TIMEOUT_MS (ms)." ); } function isAacSidecar(audioPath: string): boolean { return extname(audioPath).toLowerCase() === ".aac"; } const KNOWN_NON_AAC_AUDIO_EXTENSIONS = new Set([ ".flac", ".mp3", ".oga", ".ogg", ".opus", ".wav", ".webm", ]); export interface MuxVideoWithAudioOptions extends Partial< Pick > { /** * Codec of the sidecar audio when the caller already knows it. HyperFrames * render paths pass the mixed AAC sidecar by contract, so muxing should not * depend on the file extension alone. */ audioCodec?: "aac"; /** Replaces `-i ` (which is then unused), e.g. with a concat-demuxer input. */ videoInputArgs?: readonly string[]; /** * @deprecated No longer used. `-avoid_negative_ts` is never passed for * mp4/mov muxing (ffmpeg's `auto` default already resolves to `disabled` * for those containers), so the AAC priming edit list is preserved * unconditionally and this flag has no effect. See issue #3487. Kept for * source compatibility; it will be removed in a future major. */ preserveAudioPrimingEditList?: boolean; } async function shouldCopyAacSidecar( audioPath: string, options: MuxVideoWithAudioOptions | undefined, ) { if (options?.audioCodec === "aac" || isAacSidecar(audioPath)) return true; const audioExtension = extname(audioPath).toLowerCase(); if (KNOWN_NON_AAC_AUDIO_EXTENSIONS.has(audioExtension)) return false; try { const metadata = await extractAudioMetadata(audioPath); return metadata.audioCodec === "aac"; } catch { // Preserve the pre-existing fallback for invalid or unprobeable sidecars: // let the final ffmpeg transcode path surface the actionable mux error. return false; } } /** ProRes profile names in the order users are told about them. */ export const PRORES_PROFILE_NAMES = ["4444", "hq", "422", "lt", "proxy"] as const; export type ProresProfile = (typeof PRORES_PROFILE_NAMES)[number]; /** The one table for `-profile:v` and pixel format; all but 4444 are 4:2:2 without alpha. */ export const PRORES_PROFILES: Record< ProresProfile, { profile: string; pixelFormat: string; alpha: boolean } > = { "4444": { profile: "4444", pixelFormat: "yuva444p10le", alpha: true }, hq: { profile: "3", pixelFormat: "yuv422p10le", alpha: false }, "422": { profile: "2", pixelFormat: "yuv422p10le", alpha: false }, lt: { profile: "1", pixelFormat: "yuv422p10le", alpha: false }, proxy: { profile: "0", pixelFormat: "yuv422p10le", alpha: false }, }; export function isProresProfile(value: unknown): value is ProresProfile { return typeof value === "string" && (PRORES_PROFILE_NAMES as readonly string[]).includes(value); } /** * Get encoder preset for a given quality and output format. * WebM uses VP9 with alpha-capable pixel format; MP4 uses h264 (or h265 for HDR); * MOV uses ProRes 4444 with alpha for editor-compatible transparency, or a 422 profile without alpha. */ export function getEncoderPreset( quality: "draft" | "standard" | "high", format: "mp4" | "webm" | "mov" = "mp4", hdr?: { transfer: HdrTransfer }, proresProfile: ProresProfile = "4444", chromaSubsampling: ChromaSubsampling = "420", ): EncoderPreset { const base = ENCODER_PRESETS[quality]; if (format === "webm") { return { preset: base.preset === "ultrafast" ? "realtime" : "good", quality: base.quality, codec: "vp9", pixelFormat: "yuva420p", }; } if (format === "mov") { const { profile, pixelFormat } = PRORES_PROFILES[proresProfile]; return { preset: profile, quality: base.quality, codec: "prores", pixelFormat }; } if (hdr) { return { preset: base.preset === "ultrafast" ? "fast" : base.preset, quality: base.quality, codec: "h265", pixelFormat: "yuv420p10le", hdr, }; } return { ...base, pixelFormat: chromaSubsampling === "444" ? "yuv444p" : "yuv420p" }; } // Re-export GPU utilities so existing consumers that import from chunkEncoder still work. export { detectGpuEncoder, getCachedGpuEncoder, type GpuEncoder } from "../utils/gpuEncoder.js"; /** The `lockGopForChunkConcat` / `gopSize` pair, shared by every encoder entry point. */ export interface LockedGopOptions { lockGopForChunkConcat?: boolean; gopSize?: number; } /** * Integer GOP length, or `null` when no lock was requested. Throws on a lock * with an invalid size — a silent fallback ships open-GOP output that only * surfaces later as a broken playback seam. */ export function resolveLockedGopSize(options: LockedGopOptions): number | null { if (options.lockGopForChunkConcat !== true) return null; if ( typeof options.gopSize !== "number" || !Number.isFinite(options.gopSize) || options.gopSize <= 0 ) { throw new Error( `[chunkEncoder] lockGopForChunkConcat=true requires a positive integer gopSize (received ${String(options.gopSize)})`, ); } return Math.floor(options.gopSize); } /** * Closed-GOP / forced-keyframe args for libx264 / libx265, so an orchestrator * can concat chunks with `-c copy` or cut the stream into segments with * `-f hls -c copy`. Without them the encoder picks its own keyframes and a * boundary may not land on an independently decodable IDR. */ export function appendLockedGopArgs(args: string[], gopSize: number): void { args.push( "-g", String(gopSize), "-keyint_min", String(gopSize), "-sc_threshold", "0", "-force_key_frames", `expr:eq(mod(n,${gopSize}),0)`, ); } /** * The `-x264-params` / `-x265-params` fragment that bakes the IDR cadence into * the encoder itself — `-force_key_frames` alone still permits mini-GOPs with * open-GOP references. `repeat-headers=1` keeps each boundary self-contained. */ export function lockedGopCodecParams(codec: "h264" | "h265", gopSize: number): string { const shared = "scenecut=0:open-gop=0:repeat-headers=1"; return codec === "h264" ? shared : `keyint=${gopSize}:min-keyint=${gopSize}:${shared}`; } /** Frames per keyframe interval: the nearest whole frame, never below one. */ export function keyframeIntervalToGopSize(fps: Fps, seconds: number): number { return Math.max(1, Math.round(fpsToNumber(fps) * seconds)); } const BITRATE_PATTERN = /^(\d+(?:\.\d+)?)([kKmMgG]?)$/; function bitrateToBitsPerSecond(value: string): number { const match = BITRATE_PATTERN.exec(value); if (!match) throw new Error(`[chunkEncoder] invalid bitrate ${JSON.stringify(value)}`); const unit = match[2]!.toLowerCase(); const scale = { g: 1_000_000_000, m: 1_000_000, k: 1_000 }[unit] ?? 1; return Number(match[1]) * scale; } /** `-maxrate` / `-bufsize` for the VBV cap, written once for both arg builders. Buffer defaults to 2x. */ export function appendRateCapArgs( args: string[], options: { codec?: string; maxBitrate?: string; bufferSize?: string }, ): void { const { maxBitrate, bufferSize } = options; if (maxBitrate === undefined) { if (bufferSize !== undefined) throw new Error("[chunkEncoder] bufferSize requires maxBitrate"); return; } const codec = options.codec ?? "h264"; if (codec !== "h264" && codec !== "h265") { throw new Error(`[chunkEncoder] maxBitrate is not supported for codec ${codec}`); } const cap = bitrateToBitsPerSecond(maxBitrate); const buffer = bufferSize !== undefined ? bitrateToBitsPerSecond(bufferSize) : cap * 2; if (cap <= 0 || buffer <= 0) { throw new Error("[chunkEncoder] maxBitrate and bufferSize must be positive"); } args.push("-maxrate", String(Math.round(cap)), "-bufsize", String(Math.round(buffer))); } export function buildEncoderArgs( options: EncoderOptions, inputArgs: string[], outputPath: string, gpuEncoder: GpuEncoder = null, nvencPresets?: ReadonlySet, ): string[] { const { fps, codec = "h264", preset = "medium", quality = 23, bitrate, pixelFormat = "yuv420p", vp9CpuUsed, useGpu = false, } = options; // libx264 cannot encode HDR. If a caller passes hdr with codec=h264 we'd // produce a "half-HDR" file (BT.2020 container tags but a BT.709 VUI block // inside the bitstream) which confuses HDR-aware players. Strip hdr and // log a warning so the caller picks h265 (the SDR-tagged output is honest). if (options.hdr && codec === "h264") { console.warn( "[chunkEncoder] HDR is not supported with codec=h264 (libx264 has no HDR support). " + "Stripping HDR metadata and tagging output as SDR/BT.709. Use codec=h265 for HDR output.", ); options = { ...options, hdr: undefined }; } // Without -xerror, ffmpeg ends the video at the first frame file it cannot read and still exits 0. const args: string[] = ["-xerror", ...inputArgs, "-r", fpsToFfmpegArg(fps)]; const shouldUseGpu = useGpu && gpuEncoder !== null; appendRateCapArgs(args, options); if (codec === "h264" || codec === "h265") { if (shouldUseGpu) { const encoderName = getGpuEncoderName(gpuEncoder, codec); args.push("-c:v", encoderName); switch (gpuEncoder) { case "nvenc": args.push("-preset", mapPresetForGpuEncoder("nvenc", preset, nvencPresets)); if (bitrate) args.push("-b:v", bitrate); else args.push("-cq", String(quality)); break; case "videotoolbox": args.push( ...buildVideoToolboxRateControlArgs({ bitrate, width: options.width, height: options.height, fps: fpsToNumber(fps), quality, }), ); break; case "vaapi": args.unshift("-vaapi_device", "/dev/dri/renderD128"); args.push("-vf", "format=nv12,hwupload"); if (bitrate) args.push("-b:v", bitrate); else args.push("-qp", String(quality)); break; case "qsv": args.push("-preset", mapPresetForGpuEncoder("qsv", preset)); if (bitrate) args.push("-b:v", bitrate); else args.push("-global_quality", String(quality)); break; case "amf": if (bitrate) args.push("-b:v", bitrate); else args.push("-rc", "cqp", "-qp_i", String(quality), "-qp_p", String(quality)); break; } // Same B-frame story as the SW branch below — nvenc/amf emit B-frames // by default (qsv via b_strategy, vaapi too), and the negative-DTS // freeze hits the same downstream players. The unconditional // `-avoid_negative_ts make_zero` near the bottom of this function // covers the mux level, but we belt-and-suspenders the encoder too // so even tools that consume the chunk file directly (without going // through our mux step) play correctly. videotoolbox doesn't accept // `-bf` so it's skipped — videotoolbox h264 also doesn't emit // negative DTS in practice on macOS Sonoma+. if ( codec === "h264" && (gpuEncoder === "nvenc" || gpuEncoder === "qsv" || gpuEncoder === "vaapi" || gpuEncoder === "amf") ) { args.push("-bf", "0"); if (gpuEncoder === "qsv") { args.push("-b_strategy", "0"); } } } else { const encoderName = codec === "h264" ? "libx264" : "libx265"; args.push("-c:v", encoderName, "-preset", preset); appendSoftwareEncoderThreadsArg(args, encoderName); if (bitrate) args.push("-b:v", bitrate); else args.push("-crf", String(quality)); // Closed-GOP / forced-keyframe args so an external orchestrator can // ffmpeg-concat chunk files with `-c copy`. See `appendLockedGopArgs`. const gop = resolveLockedGopSize(options); const lockGop = gop !== null; if (gop !== null) appendLockedGopArgs(args, gop); // Disable B-frames. Standard h264 with B-frames produces negative DTS // at the start of the stream (the first B-frame's decode order is // "before" the first I-frame's presentation time). VS Code's video // preview, several browser