Skip to main content

Hardware Transcoding [Experimental]

This feature allows you to use a GPU to accelerate transcoding and reduce CPU load. Note that hardware transcoding is much less efficient for file sizes. As this is a new feature, it is still experimental and may not work on all systems.

Supported APIs​

  • NVENC (NVIDIA)
  • Quick Sync (Intel)
  • RKMPP (Rockchip)
  • VAAPI (AMD / NVIDIA / Intel)

Limitations​

  • The instructions and configurations here are specific to Docker Compose. Other container engines may require different configuration.
  • Only Linux and Windows (through WSL2) servers are supported.
  • WSL2 does not support Quick Sync.
  • Raspberry Pi is currently not supported.
  • Two-pass mode is only supported for NVENC. Other APIs will ignore this setting.
  • Only encoding is currently hardware accelerated, so the CPU is still used for software decoding and tone-mapping.
  • Hardware dependent
    • Codec support varies, but H.264 and HEVC are usually supported.
      • Notably, NVIDIA and AMD GPUs do not support VP9 encoding.
    • Newer devices tend to have higher transcoding quality.

Prerequisites​

NVENC​

  • You must have the official NVIDIA driver installed on the server.
  • On Linux (except for WSL2), you also need to have NVIDIA Container Runtime installed.

QSV​

  • For VP9 to work:
    • You must have a 9th gen Intel CPU or newer
    • If you have an 11th gen CPU or older, then you may need to follow these instructions as Low-Power mode is required
    • Additionally, if the server specifically has an 11th gen CPU and is running kernel 5.15 (shipped with Ubuntu 22.04 LTS), then you will need to upgrade this kernel (from Jellyfin docs)

Setup​

Basic Setup​

  1. If you do not already have it, download the latest hwaccel.transcoding.yml file and ensure it's in the same folder as the docker-compose.yml.
  2. In the docker-compose.yml under immich-microservices, uncomment the extends section and change cpu to the appropriate backend.
  • For VAAPI on WSL2, be sure to use vaapi-wsl rather than vaapi
  1. Redeploy the immich-microservices container with these updated settings.
  2. In the Admin page under Video transcoding settings, change the hardware acceleration setting to the appropriate option and save.

All-In-One - Unraid Setup​

NVENC - NVIDIA GPUs​
  1. In the container app, add this environmental variable: Key=NVIDIA_VISIBLE_DEVICES Value=all
  2. While still in the container app, change the container from Basic Mode to Advanced Mode and add the following parameter to the Extra Parameters field: --runtime=nvidia
  3. Restart the container app.
  4. Continue to step 4 of "Basic Setup".
Other APIs​

Unraid does not currently support multiple Compose files. As an alternative, you can "inline" the relevant contents of the hwaccel.transcoding.yml file into the immich-microservices service directly.

For example, the qsv section in this file is:

devices:
  - /dev/dri:/dev/dri

You can add this to the immich-microservices service instead of extending from hwaccel.transcoding.yml. Once this is done, you can continue to step 3 of "Basic Setup".

Tips​

  • You may want to choose a slower preset than for software transcoding to maintain quality and efficiency
  • While you can use VAAPI with NVIDIA and Intel devices, prefer the more specific APIs since they're more optimized for their respective devices