Skip to main content

Design history

NVENC Quality Matched to CPU Encodes and GPU Driver Libraries Mounted​

Harness version 3.3.0 changes the GPUGPU: Graphics Processing UnitA processor with thousands of simple cores that run the same operation on many data elements in parallel. It was built to render graphics, and is now also used for general-purpose parallel work such as machine learning training and inference, scientific simulation, and video encoding. Cloud providers rent GPUs attached to virtual machines, with their own dedicated GPU memory.WikipediaGlossary encode scenarios and the image's GPU setup:

  • gpu_h264_encode and gpu_h265_encode now run NVENC with -preset p4 -rc vbr -cq 22 -b:v 0 instead of -preset p4 with the default rate control. -cq 22 was the closest match to the CPUCPU: Central Processing UnitThe general-purpose processor of a computer, which runs the operating system and programs. A CPU has one or more physical cores, and with SMT each core runs two or more hardware threads.WikipediaGlossary encodes at -crf 18; see NVENC CQ Sweep. The match is approximate, not exact.
  • The image sets NVIDIA_DRIVER_CAPABILITIES=compute,utility,video, so the NVIDIA Container ToolkitNVIDIA Container ToolkitA set of NVIDIA libraries and tools that lets containers use the NVIDIA GPUs of the host. It configures container runtimes such as Docker to make the GPU devices and driver libraries available inside a container.NVIDIA docsGlossary mounts the driver's NVENC and NVDEC libraries. Before this change, many production GPU runs skipped all GPU scenarios with Cannot load libnvcuvid.so.1.

FFmpeg Built Without --enable-nonfree​

build-ffmpeg.sh no longer passes --enable-nonfree. The NVIDIA options (--enable-cuvid, --enable-nvenc, and --enable-ffnvcodec) do not need it in FFmpegFFmpegA free, open-source collection of libraries and command-line tools to decode, encode, transcode, filter and stream audio and video. Its ffmpeg command converts between nearly all media formats, and its libraries, such as libavcodec, power many media players and services.`ffmpeg` docsGlossary 9 and later, and it would make the binary non-redistributable.

Audio Profiles: Opus, AAC, and MP3 Instead of Extra Vorbis Bitrates​

Moved from the previous README:

Multiple VorbisVorbisA royalty-free, lossy audio codec by the Xiph.Org Foundation, usually stored in Ogg files. It was designed as a free alternative to MP3 and AAC, and is used in games and streaming; Opus has largely replaced it for new uses.VorbisGlossary bitrates were dropped: on real hosts 96/160/320 kbps scored within ~±15%, so they did not separate instances. The suite now covers distinct lossy codecs professionals actually choose, plus FLAC.

Source: peak rates on aws/g5g.16xlarge (64 workers; inspector-data commit 47523b5, harnessharnessThe code that runs a benchmark tool. It prepares the inputs, starts the tool with fixed settings, often several times or in parallel, checks and collects the tool's output, and prints the results in one format. Its settings, not the tool's defaults, decide what the benchmark measures.WikipediaGlossary 3.0.0) and a corroborating aws/g6.24xlarge run under sc-scratch/attila/ffmpeg-evaluation/results/g6.24xlarge/.

Output Version 3: Raw Repetitions Only​

Moved from the previous README:

Version 3 intentionally removes all derived rollups.

There are no converted capacity units, peaks, recommendations, summary statistics, or duplicated realtime factors in the output. Consumers receive the source counts, wall-clock time, rates, worker outcomes, and finish spread for every repetition and can aggregate those measurements as needed.

Experiments That Informed the Design​

The following notes are moved from the previous README, with only punctuation adapted to the style manual.

NVENC CQ Sweep​

NVENC has no CRF. Preset p4 is FFmpegFFmpegA free, open-source collection of libraries and command-line tools to decode, encode, transcode, filter and stream audio and video. Its ffmpeg command converts between nearly all media formats, and its libraries, such as libavcodec, power many media players and services.`ffmpeg` docsGlossary's medium default. A CQ sweep on the pinned Tears of SteelTears of SteelA 2012 science-fiction short film by the Blender Foundation, made with open-source tools and released under CC BY 3.0. Its high-resolution footage is freely available, which makes it common test material for video codecs.Project pageGlossary H.264H.264A lossy video codec standardized in 2003, also called AVC. It is the most widely supported video format, used in Blu-ray, broadcast, streaming, and video calls. Common encoders are x264 and hardware encoders such as NVENC.SpecificationGlossary fixture (source.mp4, software decode into both encoders) was run on UpCloud GPU-32xCPU-160GB-2xRTXPRO6000 (2× RTX PRO 6000 Blackwell) to pick the closest constant-quality match to CPU -crf 18. Scales still differ by encoder family -- approximate parity, not bit-exact.

H.264 / H.265H.265Another name for HEVC, from the number of its standard.SpecificationGlossary encode vs source (CQ 18 vs CRF 18):

EncodeBytesBitrate (bps)SSIM All vs sourcePSNR avg
libx264 -crf 18 -preset medium1516583540360870.99377048.962137
h264_nvenc -preset p4 -rc vbr -cq 18 -b:v 02829083475311120.99542651.395851
libx265 -crf 18 -preset medium1169683931114610.99338348.895972
hevc_nvenc -preset p4 -rc vbr -cq 18 -b:v 02532928967424510.99517051.142542

GPU vs. CPU pairwise SSIM All: H.264 0.993345, H.265 0.993799.

H.264 NVENC CQ sweep vs libx264 -crf 18 (same fixture):

SettingBytesBitrate (bps)SSIM All vs sourceSSIM All vs CPU
CRF 18 (CPU)1516583540360870.993770n/a
CQ 1540578290108031860.9964670.993435
CQ 163660052297439390.9961730.993424
CQ 173262723186858690.9958610.993427
CQ 182829083475311120.9954260.993345
CQ 192493417066372650.9950190.993288
CQ 202183371358116270.9946080.993289
CQ 211914340650952190.9941950.993186
CQ 221665239444318790.9937000.993010
CQ 231455361938729880.9931810.992821
CQ 241259021133501500.9926070.992560

-cq 22 is closest to CRF 18 on SSIM-to-source (0.993700 vs 0.993770) and bitrate (4431879 vs 4036087). -cq 18 is higher quality at 1.87× the CPU bitrate. The GPU encode scenarios therefore use -cq 22.

Why 5 Seconds​

A study on a developer workstation (Intel Core i9-14900K, 24 cores / 32 threads, 62 GiB RAMRAM: Random-Access MemoryThe main memory of a computer, which holds the running programs and their data. It is much faster than disk storage, and its content is lost when the power is off.WikipediaGlossary, amd64, no NVIDIA GPU) ran every available CPU codec for five repetitions at 2, 5, and 10 second targets. At 5 seconds, the median coefficient of variation was 2.2%; seven of eight codecs were within 10% after the first three repetitions, and only H.264 decode requested extra runs. At 2 seconds only six of eight were within 10%. Runs of 10 seconds were less stable because ambient host load drift dominated, demonstrating that a longer sample does not fix an uncontrolled machine. NVIDIA scenarios were discovered but skipped because the study host had no CUDA GPU. The /tmp/ffmpeg-study-{2,5,10}.json outputs were not checked into the repo; only the summary above was kept.

A target of 5 seconds is therefore the shortest reliable default observed on the test host. Large machines do not automatically need longer runs: the per-worker count pilot scales media volume to keep wall time constant, so faster machines process more source data in those 5 seconds. Increase the duration only for especially noisy or externally shared hosts.

Worker Scaling on Large Instances​

The worker ladder is built from physical cores (SMT siblings collapsed via thread_siblings_list), not nproc. The design host was aws/g6.24xlarge (48 physical cores / 96 hyperthreads, 4× L4); formal results are under sc-scratch/attila/ffmpeg-evaluation/results/g6.24xlarge/. CPU scenarios measure 1, P/2, and P. If aggregate throughput at P is still at least 8% above P/2, one SMT probe at min(2P, logical) is added. Memory-bound work (H.264 decode) typically peaks at P/2 and skips the SMT point; that peak came from a dense worker sweep on the same host (best at 24 workers / ~11.2k fps), not from the saved [1, 48, 96] ladder. Compute-bound encode may keep the extra sample.

GPU scenarios measure 1 and G (one session per GPU), then double (2G, 4G, ...) until throughput falls or a session ceiling is hit. That finds the NVENC/NVDEC sweet spot without assuming eight sessions per GPU. Failed worker counts stop the search immediately.

Aggregate Timing Rationale​

Audio encoding does not scale one stream across many cores: neither libvorbis, libopus, libmp3lame, native AAC, nor FFmpeg's FLAC encoder advertises frame or slice threading useful for this workload. This benchmark therefore runs independent ffmpeg processes with one codec thread each, matching a batch transcoding service.

It never sums per-process speed= values, which would overstate capacity when workers start or finish at different times. Startup and teardown are included. FFmpeg documents both its benchmark options and machine-readable progress output; the harness uses its own group clock because FFmpeg only knows about one process.