Hardware Acceleration

Sovereign automatically uses GPU hardware codecs when they’re available to the container. Detection and selection need no configuration; you only need to expose your GPU device to the container in the way your platform requires.

---

How Detection Works

At startup, Sovereign probes the GPUs and video codecs available to the container. It keeps the result until the process exits and reuses it for every playback decision, so you pay the cost once rather than per session.

Sovereign doesn’t take a codec’s presence in the container’s list as proof that it works. It runs every candidate hardware encoder and decoder against a tiny sample clip and only uses the ones that succeed. So a codec your GPU advertises can still be reported as not working: a missing driver library, or a device that was never exposed to the container, shows up here instead of as a failed playback later.

The probe then checks the pieces a transcode combines. It tests whether each H.265 and AV1 encoder can produce 10-bit output, which decides whether an HDR title can stay HDR through a transcode. It runs the GPU’s scaling and HDR tone-mapping filters on this driver, because a driver can list a filter it doesn’t implement. Last, it runs every complete encode path a session could take, end to end, and decodes the result back. A path that fails any of these is never chosen.

If a transcode still fails to start on the GPU, Sovereign logs the failure, retries that start once with the next option, and stops offering the failed one until the server restarts.

Alongside the codec results, Sovereign records an inventory of the GPUs it can see, tagged as discrete, integrated, or virtual. It recognises the virtual display adapters that hypervisors present and ignores them for encoding. Where the vendor tooling is present, it also captures the driver version, VRAM, and compute capability.

A summary is written to the server log at Information level once the probe finishes:

GPU capability probe complete: 11 encoder(s), 20 decoder(s) probed
Detected Discrete GPU: NVIDIA GeForce RTX 4090 (driver 550.54.14, 24564 MB VRAM)
Working encoders: h264_nvenc, hevc_nvenc, av1_nvenc
Working decoders: av1_cuvid, h264_cuvid, hevc_cuvid
10-bit capable encoders: hevc_nvenc, av1_nvenc
FFmpeg 8.1.3: 94 filter(s), 40 encoder(s), 98 decoder(s) listed
Working hardware filters: libplacebo_cuda

You can browse the same results in the app on the GPU Capabilities admin page, including the failure reason for anything that didn’t work, the result of each encode path, and any option excluded since startup. If the probe can’t complete at all, an error is logged and the server carries on with software-only transcoding.

---

How Acceleration is Selected

When a client starts playback, Sovereign picks the cheapest strategy that the source file, the probe result, and the client’s declared codec support all allow:

1. Direct Play - the source is already in a container and codec pair the client can handle, so the video and audio are repackaged into HLS segments without re-encoding. Sovereign packages segments as fMP4, so VP9 and AV1 sources are direct-playable on clients that support them.
2. Hardware transcode - an available GPU encoder is used, preferring H.264 output over H.265 and AV1 for compatibility. NVENC is preferred, then QSV, then VAAPI, except that a transcode converting HDR to SDR goes to whichever of them can do the conversion on the GPU. Where a matching hardware decoder also works, decode runs on the GPU as well. H.265 or AV1 is emitted instead only when the client decodes that codec at a higher resolution than it decodes H.264, so the picture isn’t downscaled, and only from a hardware encoder. H.265 comes first; AV1 is used where the client can’t take H.265 or the GPU has no H.265 encoder. Neither is ever encoded in software.
3. Software transcode - the fallback when no hardware path is usable. The only software video encoder Sovereign uses is H.264, so a software transcode always emits H.264, with an audio codec the client supports.

The summary above covers how an encoder is chosen. The full set of checks that decides whether a transcode is needed in the first place, including bit depth and frame geometry, is on the Transcoding page, along with the reason recorded for every session.

Acceleration Modes

The selected path is recorded and logged as one of four modes:

Mode	Description
None	No video encoder runs, because the video is copied rather than re-encoded (Direct Play and Remux)
Software	Software decode and software encode
HardwareEncoding	Software decode with hardware encode, when no matching hardware decoder works or the transcode needs a filter the GPU pipeline can’t run
HardwarePipeline	Full hardware pipeline, with decode and encode both on the GPU

Whichever encoder is selected, the quality and peak bandwidth of a transcode are governed by the Video Quality settings, which apply equally to software and hardware encoders.

---

Platform Setup

See the platform-specific pages for exact container configuration:

• NVIDIA - NVENC encode and CUVID decode via the NVIDIA Container Toolkit
• Intel QSV - Intel Quick Sync Video on Docker and Kubernetes
• VAAPI - Intel and AMD hardware encoding via the VA-API Linux interface

For which card to actually buy, and how much CPU to pair with it, see System Requirements.

---

Troubleshooting

These are the failure reasons the probe reports for an encoder, decoder or hardware filter, what causes each one, and how to fix it.

Message	Root Cause	Resolution
NVIDIA encode/decode libraries are not available in the container	libnvidia-encode or libnvcuvid couldn’t be loaded	Add video to the Docker device capability (capabilities: [gpu, video]), or ensure the NVIDIA Container Toolkit is installed correctly
The GPU hardware does not support this codec	GPU generation too old for the requested codec (e.g. AV1 requires RTX 40-series)	Use a newer GPU, or accept that only H.264/H.265 NVENC will be available
Intel Quick Sync Video (QSV) is not available	No Intel GPU that QSV supports was found	Expose the /dev/dri device. QSV needs a Tiger Lake (11th-generation Core) or newer Intel GPU; an older one is used through VAAPI instead
VAAPI is only supported on Linux with VA-API compatible GPU drivers	Container or host isn’t Linux, or VA-API drivers are missing	VAAPI is Linux-only; ensure the i915, xe or amdgpu kernel driver is loaded and /dev/dri is exposed
The VAAPI driver does not implement HDR tone-mapping	AMD’s VA-API driver has no tone-map of its own	Expected on AMD. Sovereign tone-maps over Vulkan instead where that passed; see VAAPI
No Vulkan driver in the image serves this GPU	The image’s Vulkan drivers cover AMD and Intel GPUs only	HDR titles are tone-mapped on the CPU on this host; everything else is unaffected
No compatible hardware device was found	Device not exposed to the container	Verify --device /dev/dri:/dev/dri (VAAPI) or --gpus all (NVIDIA) is correctly set

If no hardware encoder works, Sovereign falls back to software transcoding on its own. The startup log lines summarise what it detected.