Intel QSV

Intel Quick Sync Video (QSV) is Intel’s proprietary hardware video acceleration API, built on top of the Intel Media SDK (now oneVPL). QSV is Intel-only. The QSV runtime in the Sovereign image supports Tiger Lake (11th-generation Core) and newer Intel GPUs, integrated or discrete, including Alder Lake-N, Iris Xe and Arc. An older Intel iGPU fails the QSV probe; from Broadwell onwards it still transcodes on the GPU through VAAPI.

In Sovereign, QSV runs a full hardware pipeline (hardware decode and hardware encode) whenever a matching QSV decoder is available for the source codec and the GPU’s scaler passed its startup check, and falls back to hardware encode with software decode otherwise. A downscale stays on the GPU in the full pipeline. Deinterlacing and padding the frame can’t run there, so a transcode that needs either decodes in software and still encodes on the GPU. HDR conversion is covered below. The host must be running Linux with the Intel i915 kernel driver loaded; the Intel Media Driver (iHD) userspace runtime ships inside the Sovereign image. The iGPU render device (/dev/dri/renderD128) must be accessible inside the container.

You can verify QSV is working from inside the container with:

ffmpeg -f lavfi -i nullsrc -t 1 -vf scale=320:240 -c:v h264_qsv -f null -

---

Giving the Container the GPU

Docker

You can share the device in one of two ways. Sharing the whole /dev/dri directory is simpler; sharing just the render node is more restrictive.

Option A - share the entire /dev/dri directory

docker run --name sovereign \
  --device /dev/dri:/dev/dri \
  -v sovereign-data:/sovereign-data \
  -v /path/to/media:/media:ro \
  -p 5000:5000 \
  --env-file sovereign.env \
  <sovereign-image>:<version>

Option B - share only the render node

Use this to limit the container to a single device. Replace renderD128 with the output of ls /dev/dri on the host.

docker run --name sovereign \
  --device /dev/dri/renderD128:/dev/dri/renderD128 \
  -v sovereign-data:/sovereign-data \
  -v /path/to/media:/media:ro \
  -p 5000:5000 \
  --env-file sovereign.env \
  <sovereign-image>:<version>

Caution

Sovereign runs as a non-root user inside the container, so it needs permission to open the render device. If the node is exposed as root:render 0660, grant the container the render group by adding --group-add 44 to the command, with 44 replaced by the host’s render group GID (find it with getent group render or stat -c '%g' /dev/dri/renderD128).

If the render node is world-accessible (crw-rw-rw-, mode 666) no group membership is needed.

Docker Compose

You can share the device in one of two ways. Sharing the whole /dev/dri directory is simpler; sharing just the render node is more restrictive.

Option A - share the entire /dev/dri directory

compose.yaml

services:
  server:
    image: <sovereign-image>:<version>
    env_file:
      - sovereign.env
    ports:
      - 5000:5000
    devices:
      - /dev/dri:/dev/dri
    volumes:
      - sovereign-data:/sovereign-data
      - /path/to/media:/media:ro

volumes:
  sovereign-data:

Option B - share only the render node

Use this to limit the container to a single device. Replace renderD128 with the output of ls /dev/dri on the host.

compose.yaml

services:
  server:
    image: <sovereign-image>:<version>
    env_file:
      - sovereign.env
    ports:
      - 5000:5000
    devices:
      - /dev/dri/renderD128:/dev/dri/renderD128
    volumes:
      - sovereign-data:/sovereign-data
      - /path/to/media:/media:ro

volumes:
  sovereign-data:

Caution

Sovereign runs as a non-root user inside the container, so it needs permission to open the render device. If the node is exposed as root:render 0660, grant the container the render group with group_add (find the host GID with getent group render or stat -c '%g' /dev/dri/renderD128):

services:
  server:
    # ...
    devices:
      - /dev/dri:/dev/dri
    group_add:
      - '44' # replace with the host's `render` group GID

If the render node is world-accessible (crw-rw-rw-, mode 666) no group membership is needed.

Kubernetes

A container can only open the render device (/dev/dri/renderD128) if that device is on the container’s device cgroup allowlist. There are two ways to grant that access; pick one.

Danger

A hostPath mount of /dev/dri doesn’t work. A hostPath volume bind-mounts the device file into the pod but does not add it to the container’s device cgroup, so opening it fails with Operation not permitted even when the node exposes it world-readable (crw-rw-rw-, mode 666). The only sign is that Sovereign finds no working encoders and falls back to software transcoding. Use one of the two options below instead.

Option A - Intel GPU Device Plugin (recommended)

Install the Intel GPU Device Plugin in the cluster. It advertises the GPU as a schedulable resource and configures the device cgroup and permissions for you, with no elevated privileges. Then request the i915 resource:

containers:
  - name: sovereign
    image: <sovereign-image>:<version>
    resources:
      limits:
        gpu.intel.com/i915: 1
    envFrom:
      - secretRef:
          name: sovereign-secrets

Note

The same gpu.intel.com/i915 resource is used for both QSV and VAAPI. Sovereign probes and selects whichever API has working encoders at startup.

Option B - privileged container

If you can’t install the device plugin, run the container privileged and expose /dev/dri. A privileged container bypasses the device cgroup entirely. This grants broad host access, so prefer Option A for production.

containers:
  - name: sovereign
    image: <sovereign-image>:<version>
    securityContext:
      privileged: true
    envFrom:
      - secretRef:
          name: sovereign-secrets
    volumeMounts:
      - name: dri
        mountPath: /dev/dri
volumes:
  - name: dri
    hostPath:
      path: /dev/dri

Note

Either way, the pod has to be scheduled on a node that has the Intel GPU (with the i915 kernel module loaded). Use a nodeSelector or node affinity rule to target those nodes; the Intel device plugin also labels capable nodes. The iHD userspace driver ships inside the Sovereign image, so it doesn’t need to be installed on the node.

---

Supported Codecs

Codec	Encoder	Notes
H.264	h264_qsv	Tiger Lake or newer
H.265	hevc_qsv	Tiger Lake or newer
AV1	av1_qsv	Requires Intel Arc (Alchemist), Meteor Lake or newer

---

HDR Tone Mapping

QSV can’t convert HDR to SDR on the GPU. When an HDR title has to be converted for a client that can’t display it, Sovereign hands that session to VAAPI on the same GPU instead, whose tone-map does run there. The device setup above exposes both, so nothing extra is needed. If VAAPI can’t tone-map on this GPU either, the conversion runs on the CPU.

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