NVIDIA

NVIDIA acceleration uses NVENC for hardware encoding and CUVID for hardware decoding. The NVIDIA Container Toolkit has to be installed on the host before you can expose a GPU to the container.

---

Giving the Container the GPU

Docker

docker run --name sovereign \
  --gpus all \
  -e NVIDIA_DRIVER_CAPABILITIES=compute,video,utility,graphics \
  --device-cgroup-rule 'c 195:* rmw' \
  -v sovereign-data:/sovereign-data \
  -v /path/to/media:/media:ro \
  -p 5000:5000 \
  --env-file sovereign.env \
  <sovereign-image>:<version>

Docker Compose

compose.yaml

services:
  server:
    image: <sovereign-image>:<version>
    env_file:
      - sovereign.env
    ports:
      - 5000:5000
    volumes:
      - sovereign-data:/sovereign-data
      - /path/to/media:/media:ro
    deploy:
      resources:
        reservations:
          devices:
            - driver: nvidia
              capabilities: [gpu, video, utility, graphics]

volumes:
  sovereign-data:

Kubernetes

Install the NVIDIA Device Plugin in your cluster, then add a resource limit to the container spec:

containers:
  - name: sovereign
    image: <sovereign-image>:<version>
    resources:
      limits:
        nvidia.com/gpu: 1
    env:
      - name: NVIDIA_DRIVER_CAPABILITIES
        value: compute,video,utility,graphics
    envFrom:
      - secretRef:
          name: sovereign-secrets

Note

You only need one GPU. Setting nvidia.com/gpu: 1 grants access to a single GPU and makes NVENC and CUVID available inside the container.

Caution

The video capability is required alongside gpu. Without it, the NVIDIA encode libraries (libnvidia-encode) aren’t accessible and the probe reports the NVENC encoders as not working.

The graphics capability mounts the NVIDIA Vulkan driver, which Sovereign uses to tone-map HDR titles on the GPU. Without it, HDR to SDR conversion runs on the CPU, and a 4K HDR title can fall below real time on a modest processor. Everything else works either way. See HDR Tone Mapping below. The utility capability mounts nvidia-smi, which is where the driver version and VRAM in the probe summary come from; without it the GPU is still used, just reported with less detail.

---

Supported Codecs

Codec	Encoder	Decoder	Notes
H.264	h264_nvenc	h264_cuvid	Supported on all Kepler+ GPUs
H.265	hevc_nvenc	hevc_cuvid	Supported on Maxwell 2nd gen+ GPUs
AV1	av1_nvenc	av1_cuvid	Encode needs RTX 40-series (Ada) or newer; decode RTX 30-series (Ampere) or newer

---

HDR Tone Mapping

When a client can’t display HDR, Sovereign converts the picture to SDR. On an NVIDIA GPU it decodes with CUDA, tone-maps with libplacebo over Vulkan, and encodes with NVENC, so the conversion stays on the GPU. That path needs the graphics driver capability shown above.

The GPU takes the tone-map and any downscale that goes with it. A transcode that also has to deinterlace the source, pad the frame or correct its pixel shape tone-maps on the CPU instead. This path also applies a Dolby Vision Profile 5 file’s reshaping data, which the CPU conversion can’t, so those titles convert with the right colours.

At startup Sovereign runs the whole path once on a short HDR clip. The result is the libplacebo_cuda row under the CUDA tab of the GPU Capabilities admin page. When it fails, usually with VK_ERROR_INITIALIZATION_FAILED because the Vulkan driver isn’t mounted, HDR titles are tone-mapped on the CPU instead.

Note

Docker Desktop on Windows doesn’t expose the NVIDIA Vulkan driver to containers, whatever capabilities you request, so this path is only available on a Linux host.

See Hardware Acceleration Overview for the full detection and troubleshooting reference.