Skip to main content

Hardware Acceleration

When you install OvenMediaEngine Enterprise with the distributed RPM/DEB package, hardware-accelerated video encoding is enabled automatically if a hardware-acceleration-capable device and its driver are present. Drivers can be reinstalled, updated, or removed after installation without affecting program execution. This section describes the supported versions and codecs, along with the methods for installing and verifying the drivers.

Supported OS, Drivers, and Codecs​

DeviceSupport OSDriver VersionDecoderEncoder
NVIDIAUbuntu 22.04 / 24.04 / 26.04, Rocky 9Driver 535+H.264, H.265, AV1 (Ampere+)H.264, H.265, AV1 (Ada Lovelace+)
Xilinx Alveo U30MAUbuntu 22.04 / 24.04Video SDK 3.0H.264, H.265H.264, H.265
NETINT Quadra VPUUbuntu 22.04 / 24.04 / 26.04, Rocky 9libxcoder V5.7.0+ (Quadra Release SW)H.264, H.265H.264, H.265, AV1

The table describes the deb and rpm packages, which are built against CUDA 12. The Docker GPU image (latest-gpu and the *-gpu tags) is built with CUDA 13 and requires an NVIDIA driver from the R580 branch or newer and a Turing (sm_75) or newer GPU; Pascal and Volta GPUs are not supported by that image.

note

On NVIDIA, AV1 support depends on the GPU generation: decoding requires Ampere or newer (except A100/A30) and encoding requires Ada Lovelace or newer. So an Ampere GPU can decode AV1 but cannot encode it.

On NETINT Quadra, AV1 is encode-only — there is no AV1 hardware decoding.

When a device cannot handle AV1, it falls back to the software codec.

Driver Installation​

NVIDIA Graphics Driver​

The contents of this section are based on the misc/install_nvidia_driver.sh script provided by OvenMediaEngine as Open-Source. The minimum required version is NVIDIA Driver 535. The CUDA Toolkit does not need to be installed separately, as OvenMediaEngine includes the CUDA runtime it requires. If installation issues arise, please refer to the Official NVIDIA Documentation.

Ubuntu Linux 22.04 / 24.04 / 26.04​

# Install prerequisites
sudo apt-get update
sudo apt-get install -y --no-install-recommends \
    apt-utils ca-certificates curl gnupg2 lshw \
    software-properties-common ubuntu-drivers-common

# Uninstall any previously installed NVIDIA driver and CUDA Toolkit packages, including
# pre-built kernel modules. The packages are enumerated so that cuda-keyring, which
# carries the NVIDIA repository itself, and the NVIDIA Container Toolkit stay installed.
PACKAGES=$(dpkg-query -W -f='${db:Status-Abbrev} ${binary:Package}\n' \
    'nvidia-*' 'cuda-*' 'libnvidia-*' 'nsight-*' \
    'linux-modules-nvidia-*' 'linux-objects-nvidia-*' 'linux-signatures-nvidia-*' 2>/dev/null \
    | awk '$1 != "un" && $2 != "cuda-keyring" && $2 !~ /^(nvidia-container-toolkit|libnvidia-container)/ {print $2}')
sudo apt-get remove -y --purge ${PACKAGES}
sudo apt-get autoremove -y

# Disable the nouveau driver if it is loaded (a reboot is required afterwards)
if lsmod | awk '{print $1}' | grep -qx nouveau; then
    sudo tee /etc/modprobe.d/blacklist-nouveau.conf > /dev/null <<EOF
blacklist nouveau
blacklist lbm-nouveau
options nouveau modeset=0
alias nouveau off
alias lbm-nouveau off
EOF
    sudo update-initramfs -u
    echo "nouveau disabled. Reboot and re-run this script to continue."
    exit 0
fi

# Register the official NVIDIA CUDA repository
# Replace 'ubuntu2204' with 'ubuntu2404' or 'ubuntu2604' to match your release.
# cuda-keyring installs the signing key, the repository entry and the apt pin at
# once. Ubuntu 26.04 requires it: apt 3.x no longer ships apt-key, and NVIDIA
# does not publish the legacy 3bf863cc.pub key under repos/ubuntu2604.
REPO_DIST=ubuntu2204
REPO_BASE=https://developer.download.nvidia.com/compute/cuda/repos/${REPO_DIST}/x86_64
curl -fsSLo cuda-keyring.deb ${REPO_BASE}/cuda-keyring_1.1-1_all.deb
sudo dpkg -i cuda-keyring.deb
rm -f cuda-keyring.deb
sudo apt-get update

# Install the NVIDIA driver (Ubuntu 22.04 / 24.04 on the GA kernel): DKMS build
# The headers of the running kernel and the compiler it was built with are required.
sudo apt-get install -y --no-install-recommends build-essential linux-headers-$(uname -r)
sudo apt-get install -y --no-install-recommends nvidia-driver-535

On Ubuntu 26.04, and on 24.04 with the HWE kernel (6.17 or 7.0), install the kernel modules Ubuntu pre-builds for your kernel instead of nvidia-driver-535. nvidia-driver-535 is a transitional package for the 580 series there, and the DKMS build it triggers fails on those kernels. The pre-built modules are signed, so they also load with Secure Boot enabled. Data center GPUs such as the T4, L4 and A10 use the -server packages shown first; GeForce and Quadro boards use the regular packages shown after them.

# Install the NVIDIA driver (Ubuntu 24.04 HWE kernel / 26.04): pre-built modules for the
# running kernel flavour (generic, aws, azure, gcp, ...) plus the user-space packages
# OvenMediaEngine needs. The headers are required: the module package links the .ko
# against them when it is installed.
FLAVOUR=$(uname -r | sed -E 's/^[0-9]+\.[0-9]+\.[0-9]+-[0-9]+-//')
sudo apt-get install -y --no-install-recommends build-essential linux-headers-$(uname -r) linux-headers-${FLAVOUR}
sudo apt-get install -y --no-install-recommends \
    linux-modules-nvidia-580-server-$(uname -r) linux-modules-nvidia-580-server-${FLAVOUR}
sudo apt-get install -y --no-install-recommends \
    nvidia-headless-no-dkms-580-server nvidia-utils-580-server \
    libnvidia-encode-580-server libnvidia-decode-580-server

For a GeForce or Quadro board the module and user-space packages lose the -server suffix. The user-space packages then have to be pinned to the Ubuntu archive build: the NVIDIA repository registered above ships nvidia-utils-580, libnvidia-encode-580 and friends under a higher apt priority, and a user space from a different build than the Ubuntu pre-built modules does not work.

# GeForce / Quadro: regular packages, user space pinned to the Ubuntu archive version
FLAVOUR=$(uname -r | sed -E 's/^[0-9]+\.[0-9]+\.[0-9]+-[0-9]+-//')
sudo apt-get install -y --no-install-recommends build-essential linux-headers-$(uname -r) linux-headers-${FLAVOUR}
sudo apt-get install -y --no-install-recommends \
    linux-modules-nvidia-580-$(uname -r) linux-modules-nvidia-580-${FLAVOUR}
# the user space must be the Ubuntu build of the driver version the module package was built from
REQUIRED=$(apt-cache show linux-modules-nvidia-580-$(uname -r) \
    | sed -nE 's/.*nvidia-kernel-common-580 \(>= ([0-9.]+)\).*/\1/p' | head -n 1)
VERSION=$(apt-cache madison nvidia-utils-580 | grep -v developer.download.nvidia.com \
    | awk -F'|' '{gsub(/ /, "", $2); print $2}' | grep "^${REQUIRED}-" | sort -V | tail -n 1 || true)
# empty VERSION (no matching Ubuntu build) installs the apt candidate, as the script does
sudo apt-get install -y --no-install-recommends \
    nvidia-headless-no-dkms-580${VERSION:+=${VERSION}} nvidia-utils-580${VERSION:+=${VERSION}} \
    libnvidia-encode-580${VERSION:+=${VERSION}} libnvidia-decode-580${VERSION:+=${VERSION}}
note

This is a headless installation: it contains no OpenGL or X.Org driver, which OvenMediaEngine does not need. Add libnvidia-gl-580-server (or libnvidia-gl-580) for a desktop session. The module metapackage follows the kernel metapackage and may install a newer kernel than the one running; if nvidia-smi cannot find the driver right after the installation, reboot once. The requirement is driver 535 or newer, and the CUDA runtime OvenMediaEngine needs is bundled in the package.

Rocky Linux 9​

# Install prerequisites
sudo dnf update -y
sudo dnf install -y epel-release dnf-plugins-core lshw

# Uninstall any previously installed NVIDIA driver and CUDA Toolkit packages
sudo dnf remove -y 'nvidia-driver*' 'cuda*' 'libnvidia*' 'nsight*'
sudo dnf module reset -y nvidia-driver
sudo dnf clean all

# Disable the nouveau driver if it is loaded (a reboot is required afterwards)
if lsmod | awk '{print $1}' | grep -qx nouveau; then
    sudo tee /etc/modprobe.d/blacklist-nouveau.conf > /dev/null <<EOF
blacklist nouveau
options nouveau modeset=0
EOF
    sudo dracut --force
    echo "nouveau disabled. Reboot and re-run this script to continue."
    exit 0
fi

# Register the official NVIDIA CUDA repository
OS_MAJOR=9
REPO_BASE=https://developer.download.nvidia.com/compute/cuda/repos/rhel${OS_MAJOR}/x86_64
sudo dnf config-manager --add-repo=${REPO_BASE}/cuda-rhel${OS_MAJOR}.repo
sudo dnf clean all

# Install the NVIDIA driver
sudo dnf module install -y nvidia-driver:535

Install and Check the Driver​

# nvidia-smi 
Wed Jul  3 23:30:00 2024       
+-----------------------------------------------------------------------------+
| NVIDIA-SMI 535.183.01   Driver Version: 535.183.01   CUDA Version: 12.2     |
|-------------------------------+----------------------+----------------------+
| GPU  Name        Persistence-M| Bus-Id        Disp.A | Volatile Uncorr. ECC |
| Fan  Temp  Perf  Pwr:Usage/Cap|         Memory-Usage | GPU-Util  Compute M. |
|                               |                      |               MIG M. |
|===============================+======================+======================|
|   0  NVIDIA GeForce ...  Off  | 00000000:0A:00.0 Off |                  N/A |
| 55%   33C    P8    10W / 120W |      2MiB /  3018MiB |      0%      Default |
|                               |                      |                  N/A |
+-------------------------------+----------------------+----------------------+                                                                  
+-----------------------------------------------------------------------------+
| Processes:                                                                  |
|  GPU   GI   CI        PID   Type   Process name                  GPU Memory |
|        ID   ID                                                   Usage      |
|=============================================================================|
|  No running processes found                                                 |
+-----------------------------------------------------------------------------+

XILINX Video SDK Driver​

The Xilinx Video SDK 3.0 driver officially supports Ubuntu, Red Hat Linux 7.8, and Amazon Linux 2. For detailed information, please refer to the Official Xilinx Documentation.

NETINT Quadra Driver​

NETINT Quadra VPU support is built on NETINT's native libxcoder library from the official Quadra Release SW package. Unlike the NVIDIA driver, OvenMediaEngine does not bundle or install the NETINT driver — the Quadra kernel driver and libxcoder (V5.7.0 or later) must be installed beforehand, following the NETINT Quadra Release SW documentation for your OS.

OvenMediaEngine loads libxcoder.so at runtime via dlopen() rather than linking it at build time. As a result, the same OvenMediaEngine Enterprise package runs on hosts with or without a Quadra card: when libxcoder.so or a card is absent, the NETINT backend simply reports zero devices and OvenMediaEngine falls back to another accelerator or the software codec.

After installing the Quadra Release SW, verify the card and driver with the tools that ship with libxcoder (installed under /usr/local/bin):

# List detected Quadra cards (GUID / model / firmware revision / device path)
$ ni_rsrc_list

# Real-time per-card view: LOAD / running instances / memory / temperature / power
$ ni_rsrc_mon

Verify Hardware Acceleration​

Once the RPM/DEB package and driver installation are complete, you need to verify that the drivers are correctly loaded and the Hardware-Accelerated Video Encoding is activated in OvenMediaEngine. This can be checked through the OvenMediaEngine's Log files.

$ cd /var/log/ovenmediaengine
$ cat ovenmediaengine.log | grep transcoder_gpu

[OvenMediaEngine:1234] TAG| transcoder_gpu.cpp:55   | Trying to check available hardware accelerators
[OvenMediaEngine:1234] TAG| transcoder_gpu.cpp:278  | NVIDIA. DeviceId(0), Name(NVIDIA GeForce GTX 1060 3GB), BusId(10), CudaId(0)
[OvenMediaEngine:1234] TAG| transcoder_gpu.cpp:60   | Supported NVIDIA accelerator. Number of devices(1)
[OvenMediaEngine:1234] TAG| transcoder_gpu.cpp:70   | No supported Xilinx Media accelerator
[OvenMediaEngine:1234] TAG| transcoder_gpu.cpp:490  | NETINT(QUADRA). DeviceId(0), GUID(0), Model(Quadra T1A), FwRev(590A)
[OvenMediaEngine:1234] TAG| transcoder_gpu.cpp:81   | Supported Netint VPU accelerator. Number of devices(1)

Configuration​

Enterprise-only configuration

The <HWAccels> configuration is an OvenMediaEngine Enterprise feature. In the Open-Source edition this option is deprecated and has been removed from the sample configuration files (Server.xml, Origin.xml) and the Transcode WebHook (hwaccels) schema. Use the <HWAccels> block shown below with OvenMediaEngine Enterprise (EnterpriseServer.xml).

To use hardware acceleration, add the <HWAccels> section under <OutputProfiles> and set <Enable> to true for the <Decoder> and/or <Encoder>. If a hardware codec is unavailable due to insufficient resources, it automatically falls back to a software codec.

<OutputProfiles>
    <HWAccels>
        <!-- 
        Setting for Hardware Modules.
            - nv : Nvidia Video Codec SDK
            - xma : Xilinx Media Accelerator
            - ni : Netint Quadra VPU

        You can use multiple modules by separating them with commas.
        For example, if you want to use xma and nv, you can set it as follows.

        <Modules>[ModuleName]:[DeviceId],[ModuleName]:[DeviceId],...</Modules>
        <Modules>nv:0,nv:1,xma:0</Modules>
        -->
        <Decoder>
                <Enable>true</Enable>
                <Modules>nv</Modules>
        </Decoder>
        <Encoder>
                <Enable>true</Enable>
                <Modules>nv</Modules>
        </Encoder>
    </HWAccels>
    
    <OutputProfile>
        ...
    </OutputProfile>
</OutputProfiles>

Set Modules per Encode​

The <Modules> in <HWAccels> applies to every encode. To use a different module or device for a specific encode, add <Modules> inside that <Video>. This value overrides the one in <HWAccels>.

Use the [ModuleName]:[DeviceId] format, and separate multiple modules with commas. They are tried in order, and the software codec is used if none are available.

<OutputProfile>
    <Encodes>
        <!-- Encode on NVIDIA device 0 -->
        <Video>
            <Modules>nv:0</Modules>
            ...
        </Video>
        <!-- Encode on NVIDIA device 1 -->
        <Video>
            <Modules>nv:1</Modules>
            ...
        </Video>
        <!-- Encode on NETINT Quadra card 0 -->
        <Video>
            <Modules>ni:0</Modules>
            ...
        </Video>
    </Encodes>
</OutputProfile>

Experiments​

Experimental

The options in this section are experimental. They may change or be removed in a future release, so use them with care in production.

CUDA Stream Priority​

<CUDAStreamPriority> raises or lowers the scheduling priority of the CUDA stream that OvenMediaEngine's transcoding pipeline (decoding, scaling, overlay) runs on, so its GPU work can be scheduled ahead of other work on the same device. The value is resolved against each GPU's own priority range and applies to all NVIDIA GPUs.

ValueMeaning
(unset)Keep the driver default.
loEach device's lowest priority.
hiEach device's highest priority.

Add it under <Server> → <Modules>:

<Modules>
    <CUDAStreamPriority>hi</CUDAStreamPriority>
</Modules>

On startup, the applied priority is logged per device:

[experimental] Set CUDA stream priority: 0 -> -5 (range low=0, high=-5)

Reference​