Skip to content
Stream
Hardware Acceleration

Hardware Acceleration

Engine can use CPU encoding, Intel Quick Sync Video (QSV), and NVIDIA NVENC when the release and host support them.

Before Enabling a Device

  • confirm the device is visible to the operating system;
  • install a driver compatible with the running kernel and hardware;
  • verify the Engine service account can open the device nodes;
  • verify the selected codec, pixel format, resolution, bit depth, and filter chain are supported;
  • keep a CPU or pass-through test profile for fault isolation.

Intel QSV

Confirm the Intel render device exists and that the required media runtime is loaded. Device selection uses the stable GPU index shown by Engine; it is not the display connector number.

Start with decode, scale, and encode on one device. Cross-device transfers or unsupported software filters can force extra copies and remove the expected performance benefit.

NVIDIA NVENC

Confirm nvidia-smi reports the GPU without driver errors and that the Engine process can access the encode device. The license counts independently addressable GPUs actually used by running transcodes; an NVIDIA A16 exposes four GPU devices.

NVENC session capacity, codec availability, and supported formats depend on the GPU model and driver. A licensed GPU-device count is an admission limit, not a promise of channels per GPU.

NVIDIA Driver Installation

Engine 1.0+

Engine provides a Linux x86_64 command-line installer for the NVIDIA driver versions included in its embedded NVENC support table. Run it as root. The support list means that Engine can patch the driver for its NVENC use; it does not guarantee that every listed driver can build against every kernel or support every GPU.

bin/web --nvidia-driver-supported
bin/web --nvidia-driver-install=auto
bin/web --nvidia-driver-install=595.58.03
bin/web --nvidia-driver-install=auto --yes

auto tests 595.58.03, 590.48.01, and 580.95.05 in that order. It downloads each candidate and its SHA-256 checksum from download.nvidia.com, verifies the package, and asks before installing missing build tools or the exact headers for the running kernel. A candidate is selected only after NVIDIA’s installer successfully builds a kernel-specific package. Engine tries the next candidate only when the build output proves a kernel API incompatibility; missing headers, compiler mismatch, Secure Boot, resource exhaustion, download failure, and unknown installer errors stop the operation instead.

After a candidate passes the build test, Engine asks for final confirmation. It stops an active graphical display manager, checks NVIDIA device and render nodes for other processes, and requires you to close any non-desktop GPU users. It then unloads existing NVIDIA or Nouveau modules in dependency order and runs the selected kernel-specific installer. Any graphical display manager stopped by the command is restarted when the operation exits, including after an error. Once formal installation starts, Engine never falls back to another driver because the host may contain partially changed kernel and user-space files.

--yes accepts both dependency installation and final driver installation without prompting. It does not bypass checksum verification, kernel-header checks, compiler compatibility checks, GPU-use checks, or Secure Boot and kernel-lockdown protection.

Downloaded installers and diagnostic logs are retained under /var/cache/xaccel-engine/nvidia-driver/. Build failures are labeled by cause, including headers_missing, compiler_mismatch, kernel_api_incompatible, nouveau_conflict, secure_boot_signing_required, and resource_exhausted.

Validation

Test the exact production resolution, frame rate, codec, filters, and output count. Monitor device utilization, memory, temperature, dropped frames, process restarts, and output timing for a sustained period. A short successful encode does not establish server capacity.