diff --git a/docs/general/administration/hardware-acceleration.md b/docs/general/administration/hardware-acceleration.md deleted file mode 100644 index 1ea4a9c7..00000000 --- a/docs/general/administration/hardware-acceleration.md +++ /dev/null @@ -1,692 +0,0 @@ ---- -uid: admin-hardware-acceleration -title: Hardware Acceleration ---- - -# Hardware Acceleration - -Jellyfin supports [hardware acceleration (HWA) of video encoding/decoding using FFMpeg](https://trac.ffmpeg.org/wiki/HWAccelIntro). -FFMpeg and Jellyfin can support multiple hardware acceleration implementations such as Intel Quicksync (QSV), AMD AMF and NVIDIA NVENC/NVDEC through Video Acceleration APIs. - -- [VA-API](https://en.wikipedia.org/wiki/Video_Acceleration_API) is a Video Acceleration API that uses [libva](https://github.com/intel/libva/blob/master/README.md) to interface with local drivers to provide HWA. -- [QSV](https://trac.ffmpeg.org/wiki/Hardware/QuickSync) uses a modified (forked) version of VA-API and interfaces it with [libmfx](https://github.com/intel/media-driver/blob/master/README.md) and their proprietary drivers [(list of supported processors for QSV)](https://ark.intel.com/content/www/us/en/ark.html#@Processors). - -| OS | Recommended HW Acceleration | -| ------- | --------------------------- | -| Linux | QSV, NVENC, AMF, VA-API | -| Windows | QSV, NVENC, AMF | -| MacOS | VideoToolbox | -| RPi | V4L2 | - -[Graphics Cards comparison using HWA](https://www.elpamsoft.com/?p=Plex-Hardware-Transcoding) - -Based on hardware vendor: - -| Vendor | Supported HW Acceleration | -| ------ | ------------------------- | -| NVIDIA | NVENC | -| AMD | AMF, VA-API | -| Intel | QSV, VA-API | -| Apple | VideoToolbox | -| RPi | V4L2 | - -## Enabling Hardware Acceleration - -Hardware acceleration options can be found in the Admin Dashboard under the **Transcoding** section of the **Playback** tab. -Select a valid hardware acceleration option from the drop-down menu, indicate a device if applicable, and check `Enable hardware encoding` to enable encoding as well as decoding, if your hardware supports this. - -The hardware acceleration is available immediately for media playback. No server restart is required. - -On Linux you can check available GPU using: - -```sh -lspci -nn | grep -Ei "3d|display|vga" -``` - -or using `lshw`: - -```sh -lshw -C display -``` - -## H.264 / AVC 10-bit videos - -The hardware decoding of H.264 10-bit aka High10 profile video is not supported by any Intel, AMD or NVIDIA GPU. - -Please consider upgrading these videos to HEVC 10-bit aka Main10 profile if you want to offload your CPU usage during transcoding. - -## Intel Gen9 and Gen11+ iGPUs - -:::note - -The Intel [Guc/Huc firmware](https://01.org/linuxgraphics/downloads/firmware) must be enabled for optional Low-Power encoding (pre-Gen11 only supports Low-Power H.264). - -::: - -Instructions: - -- ArchLinux: [Arch Wiki](https://wiki.archlinux.org/title/intel_graphics#Enable_GuC_/_HuC_firmware_loading) -- Debian/Ubuntu: [Brainiarc7's gist](https://gist.github.com/Brainiarc7/aa43570f512906e882ad6cdd835efe57) - -:::caution - -For **Jasper Lake** and **Elkhart Lake** chips (such as `N5095`, `N6005` and `J6412`), Low-Power encoding **must** be enabled. -There's a known kernel issue on these chips in **linux 5.15** that comes with Ubuntu 22.04 LTS preventing you from using Low-Power. You may need to upgrade kernel for this. -The linux-firmware support is **not included** in Ubuntu 20.04.3 LTS. -Any Ubuntu from 21.10 **does include** the required drivers. - -::: - -## Supported Acceleration Methods - -:::info - -In Jellyfin 10.8 full hardware-accelerated filtering (scaling, deinterlacing, tone-mapping and subtitle burn-in) on Intel, AMD and NVIDIA hardware are available. - -**jellyfin-ffmpeg version 4.4.1-2 or higher is required**, using an older or original version of FFmpeg may disable some hardware filtering improvements. - -::: - -### VA-API - -:::note - -Intel iGPU and AMD GPU only. - -::: - -A List of supported codecs for VA-API can be found [on the Archlinux wiki](https://wiki.archlinux.org/index.php/Hardware_video_acceleration#Comparison_tables). - -:::caution - -As of **Jellyfin 10.8** the official Docker image uses Debian 11 which has a compatible version of Mesa for **AMD GPU HEVC** decoding. - -Earlier images do not provide a compatible version of Mesa. - -::: - -### Hardware acceleration on Raspberry Pi 3 and 4 - -:::caution - -As of **Jellyfin 10.8** hardware acceleration on Raspberry Pi via `OpenMAX OMX` was dropped and is no longer available. - -This decision was made because Raspberry Pi is currently migrating to a `V4L2` based hardware acceleration, which is already available in Jellyfin but does not support all features other hardware acceleration methods provide due to lacking support in FFmpeg. -Jellyfin will fallback to software de- and encoding for those usecases. - -The current state of hardware acceleration support in FFmpeg can be checked on the [rpi-ffmpeg repository](https://github.com/jc-kynesim/rpi-ffmpeg). - -::: - -### NVIDIA NVENC - -:::note - -**Minimum required driver version since Jellyfin 10.8:** - -- **Linux:** 470.57.02 -- **Windows:** 471.41 - -::: - -Not every card has been tested. - -If you want more than three parallel transcoding streams on a consumer (non-Quadro) NVIDIA card, you can use [this patch](https://github.com/keylase/nvidia-patch) to remove the limit. -The patch is recommended for Linux and Windows but may break in the future, so check the compatible driver versions before applying it. - -On Linux use `nvidia-smi` to check driver and GPU card version. - -**Useful links:** - -- [Official list of supported codecs for recent NVIDIA Graphics Cards](https://developer.nvidia.com/video-encode-and-decode-gpu-support-matrix-new). -- [Official NVIDIA ffmpeg development docs](https://developer.nvidia.com/ffmpeg). - -### AMD AMF - -:::note - -AMF is available on Windows and Linux. - -::: - -:::caution - -As of **Jellyfin 10.8** full OpenCL based hardware filtering in AMF is supported on Windows 10 and newer. - -AMD has not implemented the Vulkan based HW decoder and scaler in ffmpeg, the decoding speed may not be as expected on Linux. - -The closed source driver `amdgpu-pro` is required when using AMF on Linux. - -::: - -:::tip - -Starting with Zen 4 (7000 series), all AMD desktop CPUs have integrated graphics. Most AMD desktop Zen CPUs older than Zen 4 **do not** come with integrated graphics. You will need a dedicated GPU for these older CPUs, unless it is suffixed with a _G_ or _GE_ in model name. - -::: - -### Intel QuickSync - -:::note - -Intel QuickSync (QSV) is derived from VA-API on Linux and D3D11VA on Windows, which can utilize Intel's fixed function hardware and EU(execution units) to do video encoding, decoding and processing. - -::: - -:::info - -To use QSV on Linux with recent Intel iGPUs the **nonfree [Intel media driver](https://github.com/intel/media-driver)** is required for full hardware acceleration. -If you are using `jellyfin-ffmpeg` version 4.4.1-2 or higher it is included and you do not need to install it separately. -Broadwell or newer generation is required for QSV on Linux, otherwise you have to use VA-API. - -::: - -**Useful links:** - -- [Official list of supported codecs for recent Intel Graphics Cards](https://www.intel.com/content/www/us/en/develop/documentation/media-capabilities-of-intel-hardware/top.html). -- [Intel QSV Benchmarks on Linux](https://www.intel.com/content/www/us/en/architecture-and-technology/quick-sync-video/quick-sync-video-installation.html) - ---- - -:::tip - -If your Jellyfin server does not support hardware acceleration, but you have another machine that does, you can leverage [rffmpeg](https://github.com/joshuaboniface/rffmpeg) to delegate the transcoding to another machine. -Currently Linux-only and requires SSH between the machines, as well as shared storage both for media and for the Jellyfin data directory. - -::: - -## Common setups - -Each hardware acceleration type, as well as each Jellyfin installation type, has different prerequisites for enabling hardware acceleration. -It is always best to consult [the FFMpeg documentation](https://trac.ffmpeg.org/wiki/HWAccelIntro) on the acceleration type you choose for the latest information. - -### Hardware acceleration on Docker (Linux) - -:::note - -These are general instructions, for more specific instructions please check the next sections! - -::: - -In order to use hardware acceleration in Docker, the devices must be passed to the container. -To see what video devices are available, you can run `sudo lshw -c video` or `vainfo` on your machine. -VA-API may require the `render` group added to the docker permissions. -The `render` group id can be discovered in `/etc/group` such as `render:x:122:`. - -You can use `docker run` to start the server with the required permissions and devices. -An example command is shown below. - -```sh -docker run -d \ - --volume /path/to/config:/config \ - --volume /path/to/cache:/cache \ - --volume /path/to/media:/media \ - --user 1000:1000 \ - --group-add="122" \ # Change this to match your system and remove this comment - --net=host \ - --restart=unless-stopped \ - --device /dev/dri/renderD128:/dev/dri/renderD128 \ - --device /dev/dri/card0:/dev/dri/card0 \ - jellyfin/jellyfin -``` - -Alternatively, you can use docker-compose with a configuration file so you don't need to run a long command every time you restart your server. - -```yaml -version: '3' -services: - jellyfin: - image: jellyfin/jellyfin - user: 1000:1000 - group_add: - - "122" - network_mode: 'host' - volumes: - - /path/to/config:/config - - /path/to/cache:/cache - - /path/to/media:/media - devices: - # VAAPI Devices (examples) - - /dev/dri/renderD128:/dev/dri/renderD128 - - /dev/dri/card0:/dev/dri/card0 -``` - -### VA-API hardware acceleration on Kubernetes (Linux) - -These instructions follow the same principles as for the Docker (see the section above), with one small change that your -container within the pod must run as privileged. The devices in Kubernetes are added as a host path mounts, they -are not separated into separate volumes and devices as in the Docker. - -```yaml -# Example of an incomplete deployment spec -apiVersion: apps/v1 -kind: Deployment -metadata: ... -spec: - template: - metadata: ... - spec: - securityContext: - runAsUser: 1000 # Similar to "user: 1000:1000" on Docker - runAsGroup: 1000 - supplementalGroups: - - 122 # Change this to match your "render" system group and remove this comment - - 44 # Chnage this to match your "video" system group and remove this comment - containers: - - name: "jellyfin" - image: ... - ports: ... - env: ... - securityContext: - privileged: true # Container must run as privileged inside of the pod - volumeMounts: - - name: "render-device" - mountPath: "/dev/dri/renderD128" - - name: "card-device" - mountPath: "/dev/dri/card0" - volumes: - - name: "render-device" - hostPath: - path: "/dev/dri/renderD128" - - name: "card-device" - hostPath: - path: "/dev/dri/card0" -``` - -When the pod starts, you can verify that the VA-API is available by executing: - -```sh -kubectl exec your_jellyfin_pod_name_here -- /usr/lib/jellyfin-ffmpeg/vainfo -``` - -If you get "error: failed to initialize display" then double check that the "supplementalGroups" are correct. - -### NVIDIA hardware acceleration on Docker (Linux) - -In order to achieve hardware acceleration using Docker, several steps are required. - -Prerequisites: - -- GNU/Linux x86_64 with kernel version > 3.10 -- Docker >= 19.03 -- NVIDIA GPU with Architecture > Fermi (2.1) -- NVIDIA drivers >= 361.93 -- [NVIDIA Container Toolkit](https://docs.nvidia.com/datacenter/cloud-native/container-toolkit/install-guide.html#getting-started) needs to be installed - -Follow the instructions in the link above to install the NVIDIA Container Toolkit for your Linux distribution. - -Start your container by adding this parameter: - -```sh ---gpus all \ -``` - -A complete run command would look like this: - -```sh -docker run -d \ - --name=jellyfin \ - --gpus all \ - -p 8096:8096 \ - -p 8920:8920 \ - -v /config:/config \ - -v /media:/media \ - -v /cache:/cache \ - --restart unless-stopped \ - jellyfin/jellyfin -``` - -Or with docker-compose >1.28, add the `deploy` section to your Jellyfin service: - -```yaml -services: - jellyfin: - image: jellyfin/jellyfin - # ... your Jellyfin config - deploy: - resources: - reservations: - devices: - - capabilities: [gpu] -``` - -There are some special steps when running with the following option: - -```sh ---user 1000:1000 -``` - -You may need to add this user to the video group on your host machine: - -```sh -usermod -aG video -``` - -Once the container is started you can again validate access to the host resources: - -```sh -docker exec -it jellyfin nvidia-smi -``` - -If you get driver information, everything is fine but if you get an error like `couldn't find libnvidia-ml.so library in your system` you need to run the following command: - -```sh -docker exec -it jellyfin ldconfig -``` - -After that, you should ensure the NVIDIA driver loads correctly. - -:::note - -The official Jellyfin Docker image already sets the required environment variables to allow access to the GPUs via the NVIDIA container runtime. -If you are building your own image don't forget to include `NVIDIA_DRIVER_CAPABILITIES=all` and `NVIDIA_VISIBLE_DEVICES=all` into your container's environment. - -::: - -### VA-API hardware acceleration on Debian/Ubuntu - -Configuring VA-API on Debian/Ubuntu requires some additional configuration to ensure permissions are correct. - -1. Configure VA-API for your system by following the documentation of your OS and/or vendor. - Verify that a `render` device is now present in `/dev/dri`, and note the permissions and group available to write to it, in this case `render`: - - ```sh - $ ls -l /dev/dri - total 0 - drwxr-xr-x 2 root root 100 Apr 13 16:37 by-path - crw-rw---- 1 root video 226, 0 Apr 13 16:37 card0 - crw-rw---- 1 root video 226, 1 Apr 13 16:37 card1 - crw-rw---- 1 root render 226, 128 Apr 13 16:37 renderD128 - ``` - - :::note - - On some releases, the group may be `video` or `input` instead of `render`. - - ::: - -2. Make sure that `jellyfin-ffmpeg` version 4.4.1-2 or higher is installed. - -3. Check the output of `/usr/lib/jellyfin-ffmpeg/vainfo`. - -4. Add the Jellyfin service user to the above group to allow Jellyfin's FFMpeg process access to the device, and restart Jellyfin. - - ```sh - sudo usermod -aG render jellyfin - sudo systemctl restart jellyfin - ``` - -5. Configure VA-API acceleration in the `Transcoding` page of the Admin Dashboard. - Enter the `/dev/dri/renderD128` device above as the `VA API Device` value. - -6. Watch a movie, and verify that transcoding is occurring by watching the `ffmpeg-transcode-*.txt` logs under `/var/log/jellyfin` and using `radeontop` (AMD only) or similar tools. - -### Intel QuickSync (QSV) hardware acceleration on Debian/Ubuntu - -1. QSV is based on VA-API device on Linux, so please confirm whether you have completed the VA-API configuration first. - -2. Make sure that `jellyfin-ffmpeg` version 4.4.1-2 or higher is installed (it ships the current version of `intel-media-driver (iHD)` which is required for QSV). - -3. Verify that the iHD driver is properly loaded and recognizes your iGPU. - - ```sh - sudo /usr/lib/jellyfin-ffmpeg/vainfo | grep iHD - ``` - -4. Configure QSV acceleration in the `Transcoding` page of the Admin Dashboard. - -5. Watch a movie, and verify that transcoding is occurring by watching the `ffmpeg-transcode-*.txt` logs under `/var/log/jellyfin` and using `intel_gpu_top` (can be installed with the `intel-gpu-tools` package). - -### VA-API and QSV hardware acceleration on LXC or LXD container - -:::caution - -This has been tested with LXC 3.0 and may or may not work with older versions. - -::: - -Follow the steps above to add the jellyfin user to the `video` or `render` group, depending on your circumstances. - -1. Install the required drivers on the host OS - -2. Add your GPU to the container. - - ```sh - lxc config device add gpu gpu gid= - ``` - -3. Make sure you have the required devices within the container: - - ```sh - $ lxc exec jellyfin -- ls -l /dev/dri - total 0 - crw-rw---- 1 root video 226, 0 Jun 4 02:13 card0 - crw-rw---- 1 root video 226, 0 Jun 4 02:13 controlD64 - crw-rw---- 1 root video 226, 128 Jun 4 02:13 renderD128 - ``` - -4. Configure Jellyfin to use video acceleration and point it at the right device if the default option is wrong. - -5. Try and play a video that requires transcoding and run the following, you should get a hit. - - ```sh - ps aux | grep ffmpeg | grep accel - ``` - -6. You can also try playing a video that requires transcoding, and if it plays you're good. - -Useful resources: - -- [LXD Documentation - GPU instance configuration](https://github.com/lxc/lxd/blob/master/doc/instances.md#type-gpu) -- [NVIDIA CUDA inside a LXD container](https://stgraber.org/2017/03/21/cuda-in-lxd/) - -### VA-API and QSV hardware acceleration on LXC on Proxmox - -:::info - -Jellyfin needs to run in a **privileged** LXC container. -You can convert an existing unprivileged container to a privileged container by taking a backup and restoring it as priviledged. - -::: - -1. Install the required drivers on the Proxmox host - -2. Add your GPU to the container by editing `/etc/pve/lxc/.conf` (you may need to change the GIDs in the examples below to match those used on you host). - - :::caution - - This has been tested on `Proxmox VE 7.1` - on previous versions you may need to change `cgroup2` to `cgroup`. - - ::: - - Intel iGPU: - - ```conf - lxc.cgroup2.devices.allow: c 226:0 rwm - lxc.cgroup2.devices.allow: c 226:128 rwm - lxc.mount.entry: /dev/dri/card0 dev/dri/card0 none bind,optional,create=file - lxc.mount.entry: /dev/dri/renderD128 dev/dri/renderD128 none bind,optional,create=file - ``` - - NVidia GPU: - - ```conf - lxc.cgroup2.devices.allow: c 195:* rwm - lxc.cgroup2.devices.allow: c 243:* rwm - lxc.mount.entry: /dev/nvidia0 dev/nvidia0 none bind,optional,create=file - lxc.mount.entry: /dev/nvidiactl dev/nvidiactl none bind,optional,create=file - lxc.mount.entry: /dev/nvidia-uvm dev/nvidia-uvm none bind,optional,create=file - lxc.mount.entry: /dev/nvidia-modeset dev/nvidia-modeset none bind,optional,create=file - lxc.mount.entry: /dev/nvidia-uvm-tools dev/nvidia-uvm-tools none bind,optional,create=file - ``` - -3. Shutdown and start your container. - -4. Install the required drivers in your container. - -5. Add the jellyfin user to the `video`, `render` and/or `input` groups depending on who owns the device inside the container. - -6. Configure Jellyfin to use hardware acceleration and point it at the right device if the default option is wrong. - -7. Try and play a video that requires transcoding and run the following, you should get a hit. - - ```sh - ps aux | grep ffmpeg | grep accel - ``` - -8. You can also try playing a video that requires transcoding, and if it plays you're good. - -### AMD AMF encoding on Ubuntu 18.04 or 20.04 LTS - -1. Download the `amdgpu-pro` closed source installer script at [amd.com](https://www.amd.com/en/support) - - ```bash - sudo dpkg -i /path/to/amdgpu-pro.deb; apt update - ``` - -2. Then install the Pro variant with AMF - - ```bash - sudo amdgpu-install -y --usecase=workstation,amf --vulkan=pro --opencl=rocr,legacy --accept-eula --no-32 - ``` - - :::info - - If your Ubuntu is 32 bit, please remove `--no-32`. Otherwise, on 64 bit the installer will error. Further documentation can be found at [amdgpu-install.readthedocs.io](https://amdgpu-install.readthedocs.io/en/latest/) - - ::: - -3. Check if `jellyfin-ffmpeg` contains `h264_amf` encoder: - - ```bash - $ cd /usr/lib/jellyfin-ffmpeg/ - $ ./ffmpeg -encoders | grep h264_amf - V..... h264_amf AMD AMF H.264 Encoder (codec h264) - ``` - - :::note - - If not available, update your `jellyfin-ffmpeg` to the latest version and try again. - - ::: - -4. Choose AMD AMF video acceleration in Jellyfin and check the `Enable hardware encoding` option. - -5. Watch a movie, then verify that `h264_amf` encoder is working by watching the `ffmpeg-transcode-*.txt` transcoding logs under `/var/log/jellyfin` and using `radeontop` or similar tools. - -### AMD AMF encoding on Arch Linux - -AMD does not provide official `amdgpu-pro` driver support for Arch Linux, but fortunately, a third-party packaged `amdgpu-pro-installer` is provided in the archlinux user repository. - -1. Clone [this repository](https://aur.archlinux.org/pkgbase/amdgpu-pro-installer/) using `git`. - - ```bash - git clone https://aur.archlinux.org/amdgpu-pro-installer.git - ``` - -2. Enter that folder and make the installation package and install it. - - ```bash - cd amdgpu-pro-installer - makepkg -si - ``` - -3. Go to step 3 of [Configuring AMD AMF encoding on Ubuntu 18.04 or 20.04 LTS](#amd-amf-encoding-on-ubuntu-1804-or-2004-lts) above. - -### OpenCL / CUDA / Intel VPP Tone-Mapping - -Hardware based HDR10/HLG/DoVi tone-mapping with NVIDIA NVENC, AMD AMF, Intel QSV and VA-API is done through OpenCL or CUDA. DoVi Profile 5 and 8 tone-mapping requires `jellyfin-ffmpeg` version 5.0.1-5 or higher. - -Intel hardware based VPP HDR10 tone-mapping is supported on Intel QSV and VA-API on Linux. -VPP is prefered when both two tone-mapping options are checked on Intel. - -| OS/Platform | NVIDIA NVENC | AMD AMF | Intel QSV | Intel VA-API | AMD VA-API | Software | -| ----------- | ------------ | ------- | --------- | ------------ | ---------- | -------- | -| Linux | ✔️ | ✔️ | ✔️ | ✔️ | ✔️ | WIP | -| Windows | ✔️ | ✔️ | ✔️ | N/A | N/A | WIP | -| Docker | ✔️ | ✔️ | ✔️ | ✔️ | ✔️ | WIP | - -:::note - -Tone-mapping on Windows with Intel QSV and AMD AMF requires Windows 10 or newer. - -::: - -:::info - -Make sure the hardware acceleration is well configured before configuring tone-mapping with this instructions. - -::: - -1. **On Windows:** Install the latest NVIDIA, AMD or Intel drivers. - -2. **On Linux or Docker:** - - - For **NVIDIA cards** no further configuration is necessary. - - For **AMD cards**, install `amdgpu-pro` with opencl arguments (see [Configuring AMD AMF encoding on Ubuntu 18.04 or 20.04 LTS](#amd-amf-encoding-on-ubuntu-1804-or-2004-lts) for more details): - - ```sh - sudo ./amdgpu-pro-install -y --opencl=pal,legacy - sudo usermod -aG video $LOGNAME - sudo usermod -aG render $LOGNAME - ``` - - - For **Intel iGPUs**, you have two types of tone-mapping methods: OpenCL and VPP. The latter one does not support fine tuning options. - - **OpenCL:** Follow the instructions from [intel-compute-runtime](https://github.com/intel/compute-runtime/releases). - If you are using the official Docker image or the one from linuxserver this step can be skipped. - - **VPP:** Make sure `jellyfin-ffmpeg` 4.4.1-2 or higher is installed. - Previous versions did not ship `intel-media-driver` thus it was required to be installed manually. - - - When running on docker, the **privileged** flag is required for the OpenCL device to be recognized. - You can do this by adding `--privileged` to your docker command or `privileged: true` to your docker compose file. - - :::caution - - Tone-mapping on Intel VA-API and QSV **requires an iGPU that supports 10-bit decoding**, such as i3-7100 or J4105. - - ::: - - :::info - - Do **not use** the `intel-opencl-icd` package from your distro's repository since they were not built with `RELEASE_WITH_REGKEYS` enabled, which is required for P010 pixel interop flags. - - ::: - -3. **Debugging:** Check the OpenCL device status. You will see corresponding vendor name if it goes well. - - - Use `clinfo`: Install `clinfo` before using it. `sudo apt install -y clinfo` on Debian/Ubuntu or `sudo pacman -Sy clinfo` on Arch. Then `sudo clinfo`. - - - Use `jellyfin-ffmpeg`: `/usr/lib/jellyfin-ffmpeg/ffmpeg -v debug -init_hw_device opencl` - -## Verifying Transcodes - -To verify that you are using the proper libraries, run this command against your transcoding log. -This can be found at `Admin Dashboard > Logs`, and `/var/log/jellyfin` if installed via the apt repository. - -```sh -grep -A2 'Stream mapping:' /var/log/jellyfin/ffmpeg-transcode->.log -``` - -This returned the following results. - -```data -... -Stream mapping: -Stream #0:0 -> #0:0 (hevc (native) -> h264 (h264_qsv)) -Stream #0:1 -> #0:1 (aac (native) -> mp3 (libmp3lame)) -... -``` - -`Stream #0:0` used software (VAAPI Decode can also say native) to decode HEVC and used HWA to encode. - -```data -... -Stream mapping: -Stream #0:0 -> #0:0 (h264 (hevc_qsv) -> h264 (h264_qsv)) -Stream #0:1 -> #0:1 (flac (native) -> mp3 (libmp3lame)) -... -``` - -`Stream #0:0` used HWA for both. `hevc_qsv` to decode and `h264_qsv` to encode. diff --git a/docs/general/administration/hardware-acceleration/amd-hwa-tutorial.md b/docs/general/administration/hardware-acceleration/amd-hwa-tutorial.md new file mode 100644 index 00000000..10099983 --- /dev/null +++ b/docs/general/administration/hardware-acceleration/amd-hwa-tutorial.md @@ -0,0 +1,631 @@ +--- +uid: admin-hardware-acceleration-amd +title: HWA Tutorial On AMD GPU +--- + +# HWA Tutorial On AMD GPU + +This tutorial guides you setting up full video hardware acceleration on AMD integrated GPU and discrete GPU via AMF and VA-API. + + + +## Acceleration Methods + +Hardware accelerated transcoding is supported on AMD GPUs since GCN architecture. + +On Windows **AMF** is the only available method. + +On Linux there are two methods: + +- **VA-API** - Prefered on all GPUs, full acceleration on Vega+ GPUs, open source. + +- **AMF** - Not recommended, limited support, hardware encoder only, closed source. + + + +The [AMF](https://github.com/GPUOpen-LibrariesAndSDKs/AMF) interface on Windows is based on DXVA/D3D11VA but on Linux it is based on their Pro Vulkan and OpenCL stack, which is a closed source solution. We only provide full hardware acceleration for it on Windows. + + + +The VA-API interface on Linux is an open source implementation. This open driver stack embraces Intel's [Libva](https://github.com/intel/libva) standard and exposes their video hardware via the [Mesa](https://gitlab.freedesktop.org/mesa/mesa) Gallium RadeonSI driver. And thanks to the developers of RADV Vulkan driver, we can interop between the VA-API and Vulkan on Vega+ GPUs, which make it possible for us to use Vulkan compute to achieve full hardware acceleration on Linux. + + + +:::note + +Unlike NVIDIA NVENC, there is no concurrent encoding sessions limit on AMD GPU. + +AMF and VA-API support headless server on both Windows and Linux, which means a connected monitor is not required. + +::: + + + +## Tone-mapping Methods + +Hardware accelerated HDR/DV to SDR tone-mapping is supported on **all AMD GPUs that have HEVC 10-bit decoding**. + +There are two methods can be used on Windows and/or Linux, here's the pros and cons of them: + +1. **OpenCL** + + - Pros - Supports Dolby Vision P5, detailed fine-tuning options, widely supported hardware. + + - Cons - The Pro or ROCm OpenCL runtime need to be manually installed on Linux. No zero-copy support on Linux. + +2. **Vulkan** + + - Pros - Supports Dolby Vision P5, libplacebo renderer, ROCm OpenCL runtime is not required. + + - Cons - Linux only, zero-copy only supports Vega+ GPUs for the time being. + + + +## Select GPU Hardware + +:::caution + +Most AMD dGPU comes with video encoders but be careful with certain models - RX 6400/6500 series, which don't have video encoder. + +::: + +AMD Ryzen APU (G/GE/H/HS/HX suffixed models) and Zen 4 based processors have integrated graphics. + +Best to check the video codec support via the [AMD product specifications](https://www.amd.com/en/products/specifications) before buying a GPU for hardware acceleration. + +### Transcode H.264 + +AVC / H.264 8-bit is still widely used due to its excellent compatibility. All AMD GPUs that support AMF or VA-API can decode and encode it. + +- **Decoding & Encoding H.264 8-bit** - Any AMD GPU that supports AMF or VA-API + + + +### Transcode HEVC + +HEVC / H.265 remains the first choice for storing 4K 10-bit, HDR and Dolby Vision video. It has mature software encoder [x265 and documentation](https://x265.readthedocs.io/en/master/) support, as well as the widely implemented hardware codecs in most GPUs released after 2016. + +The HEVC support on AMD is complicated: + +- **Decoding HEVC 8-bit** - Radeon R9 Fury and newer (Fiji) + +- **Encoding HEVC 8-bit** - Radeon RX 400 series (Polaris) and newer + +- **Decoding HEVC 10-bit** - Radeon RX 400 series (Polaris) and newer + +- **Encoding HEVC 10-bit** - Ryzen 4000 series APU (Renoir), Radeon RX 5700 series (Navi 1x) and newer + +:::note + +Note that even though the RX 400 series have HEVC 10-bit decoding support but it doesn't support DRM-Vulkan format modifier, which means full hardware acceleration is not possible for these cards on Linux. Vega and newer GPU is recommended on Linux. + +::: + + + +### Transcode AV1 + +AV1 is a royalty-free, future-proof video codec. It saves storage space and network bandwidth a lot. The downside is that decoding and encoding them are very stressful for your CPU. But hardware acceleration makes it possible to transcode to AV1 streams on the fly. AV1 encoding support in Jellyfin is planned in the future. + +AMD added support for AV1 acceleration in their latest GPUs: + +- **Decoding AV1 8/10-bit** - Radeon RX 6000 series (Navi 2x) and newer (except RX 6400/6500) + +- **Encoding AV1 8/10-bit** - Ryzen 7000 mobile APU, Radeon RX 7000 series (Navi 3x) and newer + + + +### Transcode Other Codecs + +Please refer to these links: + +- [X.org RadeonFeature](https://www.x.org/wiki/RadeonFeature/) + +- [GitHub - GPUOpen-LibrariesAndSDKs/AMF](https://github.com/GPUOpen-LibrariesAndSDKs/AMF) + + + +### Speed And Quality + +Due to the lack of B-frame support, the encoding quality of AMD H.264 encoder has been unsatisfactory. Although RX 6000/VCN3.0 brings back the B-frame support, the quality improvement is not much. + +AMD HEVC encoder is far better than AMD H.264 encoder, and the new AMD AV1 encoding support on RX 7000/VCN4.0 seems to be the savior of AMD encoding quality. Although they are currently no match for Intel QSV and NVIDIA NVENC. Plus the VCN4.0 drastically improved the encoding speed. + + + +Encoding speed and quality: + +- VCN4(RX 7000) > VCN3/VCN2(RX 6000/RX 5000/Renoir) > VCN1/VCE(Raven/Picasso/GCN GPUs) + + + +## Windows Setups + +Windows 10 64-bit and newer is recommeded. **AMF is not available in Windows Docker and WSL/WSL2.** + +### Configure On Windows Host + +1. Wipe the old driver with [DDU](https://www.wagnardsoft.com/) if you upgraded from a pre-GCN AMD GPU without doing a fresh installation. + +2. Clean install the latest driver from [AMD Drivers and Support](https://www.amd.com/en/support). + +3. Don't allow the GPU to be preempted by the Windows Remote desktop session. + + - Type `gpedit.msc` in Win+R shortcut key dialog and run to open the "Local Group Policy Editor". + + - Navigate in the left tree **[Computer Configuratoin > Administrative Templates > Windows Components]** + + - Here you can find **[Remote Desktop Services > Remote Desktop Session Host > Remote Session Environment]** + + - On the right side, double click the **[Use hardware graphics adapters for all Remote Desktop Services sessions]** + + - Set **[Disabled]** in the pop-up dialog window and click **[OK]**, reboot the system. + + ![Remote desktop GPU setup](/images/docs/hwa-gpedit-mstsc.png) + +3. Enable AMF in Jellyfin and uncheck the unsupported codecs. + + + +### Verify On Windows + +1. Play a video in Jellyfin web client and trigger a video transcoding by setting a lower resolution or bitrate. + +2. Open the "Task Manager" and navigate to the GPU page. + +3. Check the occupancy of the engines as follows. + Duplicate engine name indicates the GPU may have multiple video engines. + + - **3D** - 2D/3D engine or GPGPU workload + + - **Copy** - Blitter/Copy engine workload + + - **Video Codec** - Video decoder or encoder workload + + - **Video Decode** - Video decoder workload + + - **Video Encode** - Video encoder workload + + - **Compute** - GPGPU workload + + ![Verify AMD On Windows](/images/docs/hwa-amd-taskmgr.png) + +## Linux Setups + +Linux 64-bit distribution is required. **The supported GPU varies by kernel and firmware versions.** + +### Known Issues And Limitations + +:::caution + +Some Linux distros intentionally disabled the H.264 and HEVC codecs from the Mesa VA-API driver. + +::: + +Known affected distros: + +- [Fedora](https://www.phoronix.com/news/Fedora-Disable-Bad-VA-API) + +- [OpenSUSE](https://www.webpronews.com/fedora-and-opensuse-disable-gpu-accelerated-video-over-patent-concerns/) + +- [Manjaro](https://forum.manjaro.org/t/stable-update-2022-12-06-kernels-mesa-plasma-cinnamon-nvidia-libreoffice-pipewire-virtualbox/128453) + +This prevents you from using the AMD VA-API transcoding **on host system**. + +You can use our Docker image instead or install thirt-party Mesa driver package. + +Alternatively, rebuild the Mesa driver with these options added to restore the stripped hardware codecs: + +```shell +-D video-codecs=vc1dec,h264dec,h264enc,h265dec,h265enc +``` + + + +### Configure On Linux Host + +#### Debian And Ubuntu Linux + +The `jellyfin-ffmpeg5` deb package required by Jellyfin 10.8 comes with all necessary user mode Mesa drivers. + +Besides that you only need to install the OpenCL runtime (optional for Vega+ in Jellyfin 10.9+) and configure the the permission of `jellyfin` user. + +:::note + +Root permission is required. + +::: + +1. Assuming you have added the jellyfin repository to your apt source list and installed the `jellyfin-server` and `jellyfin-web`. + +2. Install the `jellyfin-ffmpeg5` package. Remove the deprecated `jellyfin` meta package if it breaks the dependencies: + + ```shell + # apt update && apt install -y jellyfin-ffmpeg5 + ``` + +3. Make sure at least one `renderD*` device exists in `/dev/dri`. Otherwise upgrade your kernel or enable the iGPU in the BIOS. + Note the permissions and group available to write to it, in this case it is `render` and `video`: + + ```shell + $ ls -l /dev/dri + + total 0 + drwxr-xr-x 2 root root 120 Mar 5 05:15 by-path + crw-rw----+ 1 root video 226, 0 Mar 5 05:15 card0 + crw-rw----+ 1 root video 226, 1 Mar 5 05:15 card1 + crw-rw----+ 1 root render 226, 128 Mar 5 05:15 renderD128 + crw-rw----+ 1 root render 226, 129 Mar 5 05:15 renderD129 + ``` + +4. Add the `jellyfin` user to the `render` and `video` group, then restart `jellyfin` service: + + :::note + + On some releases, the group may be `input`. + + ::: + + ```shell + # usermod -aG render jellyfin + # usermod -aG video jellyfin + # systemctl restart jellyfin + ``` + +5. Install the ROCm OpenCL runtime on host: + + ```shell + # apt update && apt install -y curl gpg + # curl -fsSL https://repo.radeon.com/rocm/rocm.gpg.key | gpg --dearmor -o /etc/apt/keyrings/rocm.gpg + # cat <> /etc/profile" + ``` + +6. Check the supported VA-API codecs: + + :::note + + `Mesa Gallium driver` indicates VA-API interface is supported. + + ::: + + ```shell + $ /usr/lib/jellyfin-ffmpeg/vainfo --display drm --device /dev/dri/renderD128 + + libva info: VA-API version 1.17.0 + libva info: Trying to open /usr/lib/jellyfin-ffmpeg/lib/dri/radeonsi_drv_video.so + libva info: Found init function __vaDriverInit_1_17 + libva info: va_openDriver() returns 0 + Trying display: drm + vainfo: VA-API version: 1.17 (libva 2.17.0) + vainfo: Driver version: Mesa Gallium driver 23.1.0-devel for AMD Radeon RX Vega (vega10, LLVM 15.0.7, DRM 3.49, 6.1.14-1) + vainfo: Supported profile and entrypoints + ... + ``` + +7. Check the OpenCL runtime status: + + ```shell + $ /usr/lib/jellyfin-ffmpeg/ffmpeg -v debug -init_hw_device opencl=ocl:.0,device_vendor="Advanced Micro Devices" + + [AVHWDeviceContext @ 0x55d3ea4bfd00] 1 OpenCL platforms found. + [AVHWDeviceContext @ 0x55d3ea4bfd00] 1 OpenCL devices found on platform "AMD Accelerated Parallel Processing". + [AVHWDeviceContext @ 0x55d3ea4bfd00] 0.0: AMD Accelerated Parallel Processing / gfx900:xnack- + ... + ``` + +8. Check the Vulkan runtime status: + + ```shell + $ /usr/lib/jellyfin-ffmpeg/ffmpeg -v debug -init_hw_device drm=dr:/dev/dri/renderD128 -init_hw_device vulkan@dr + + [AVHWDeviceContext @ 0x557f13a57bc0] GPU listing: + [AVHWDeviceContext @ 0x557f13a57bc0] 0: AMD Radeon RX Vega (RADV VEGA10) (discrete) (0x687f) + [AVHWDeviceContext @ 0x557f13a57bc0] 1: llvmpipe (LLVM 15.0.7, 256 bits) (software) (0x0) + [AVHWDeviceContext @ 0x557f13a57bc0] Device 0 selected: AMD Radeon RX Vega (RADV VEGA10) (discrete) (0x687f) + [AVHWDeviceContext @ 0x557f13a57bc0] Queue families: + [AVHWDeviceContext @ 0x557f13a57bc0] 0: graphics compute transfer sparse (queues: 1) + [AVHWDeviceContext @ 0x557f13a57bc0] 1: compute transfer sparse (queues: 4) + [AVHWDeviceContext @ 0x557f13a57bc0] Using device extension VK_KHR_push_descriptor + [AVHWDeviceContext @ 0x557f13a57bc0] Using device extension VK_KHR_sampler_ycbcr_conversion + [AVHWDeviceContext @ 0x557f13a57bc0] Using device extension VK_KHR_synchronization2 + [AVHWDeviceContext @ 0x557f13a57bc0] Using device extension VK_KHR_external_memory_fd + [AVHWDeviceContext @ 0x557f13a57bc0] Using device extension VK_EXT_external_memory_dma_buf + [AVHWDeviceContext @ 0x557f13a57bc0] Using device extension VK_EXT_image_drm_format_modifier + [AVHWDeviceContext @ 0x557f13a57bc0] Using device extension VK_KHR_external_semaphore_fd + [AVHWDeviceContext @ 0x557f13a57bc0] Using device extension VK_EXT_external_memory_host + ... + ``` + +9. If you wish to use the second GPU, change `renderD128` to `renderD129` in the Jellyfin dashboard. + +10. Enable VA-API in Jellyfin and uncheck the unsupported codecs. + + + +#### Linux Mint + +Linux Mint use Ubuntu as its package base. + +You can follow the configuration steps of [Debian And Ubuntu Linux](/docs/general/administration/hardware-acceleration/amd-hwa-tutorial#debian-and-ubuntu-linux) but install all Jellyfin packages `jellyfin-server`, `jellyfin-web` and `jellyfin-ffmpeg5` manually from the [Jellyfin Server Releases Page](https://repo.jellyfin.org/releases/server/). Also make sure you choosed the correct codename by following the [official version maps](https://linuxmint.com/download_all.php). + + + +#### Arch Linux + +AUR `jellyfin-ffmpeg`, `jellyfin-ffmpeg5*` packages and future ffmpeg versions are maintained by Jellyfin team. + +:::note + +Root permission is required. + +::: + +1. Make and install the AUR [`jellyfin-ffmpeg5-bin`](https://aur.archlinux.org/packages/jellyfin-ffmpeg5-bin), then change the ffmpeg path in Jellyfin dashboard to `/usr/lib/jellyfin-ffmpeg/ffmpeg`: + + ```shell + $ cd ~/ + $ git clone https://aur.archlinux.org/jellyfin-ffmpeg5-bin.git + $ cd jellyfin-ffmpeg5-bin + $ makepkg -si + ``` + +2. User mode Mesa drivers and the ROCm OpenCL runtime are required to be manually installed for VA-API: + + - [libva-mesa-driver](https://archlinux.org/packages/extra/x86_64/libva-mesa-driver/) + + - [vulkan-radeon](https://archlinux.org/packages/extra/x86_64/vulkan-radeon/) + + - [rocm-opencl-runtime](https://archlinux.org/packages/community/x86_64/rocm-opencl-runtime/) + + ```shell + # pacman -Sy libva-mesa-driver vulkan-radeon rocm-opencl-runtime + # sh -c "echo ROC_ENABLE_PRE_VEGA=1 >> /etc/profile" + ``` + +3. Check the VA-API codecs: + + ```shell + # pacman -Sy libva-utils + $ vainfo --display drm --device /dev/dri/renderD128 + ``` + +4. Check the OpenCL runtime status: + + ```shell + $ /usr/lib/jellyfin-ffmpeg/ffmpeg -v debug -init_hw_device opencl=ocl:.0,device_vendor="Advanced Micro Devices" + ``` + +5. Check the Vulkan runtime status: + + ```shell + $ /usr/lib/jellyfin-ffmpeg/ffmpeg -v debug -init_hw_device drm=dr:/dev/dri/renderD128 -init_hw_device vulkan@dr + ``` + +6. Check to the rest parts of [Debian And Ubuntu Linux](/docs/general/administration/hardware-acceleration/amd-hwa-tutorial#debian-and-ubuntu-linux). + + + +#### Other Distros + +We provide **portable** [jellyfin-ffmpeg](https://github.com/jellyfin/jellyfin-ffmpeg) binaries for distros that don't have a regular maintainer. + +They can be downloaded from one of these links: + +- [Jellyfin repository](https://repo.jellyfin.org/releases/ffmpeg/) + +- [Releases · jellyfin/jellyfin-ffmpeg · GitHub](https://github.com/jellyfin/jellyfin-ffmpeg/releases) + +:::note + +Minimum requirements for glibc and Linux versions: + +- x86_64 / amd64 - glibc >= 2.23, Linux >= 4.4 (most distros released in 2016 and later) + +::: + +Extract and install it to the correct path, change the ffmpeg path in Jellyfin dashboard to match it: + +```shell +$ cd ~/ +$ mkdir -p jellyfin-ffmpeg +$ wget https://repo.jellyfin.org/releases/ffmpeg//jellyfin-ffmpeg__portable_linux64-gpl.tar.xz +$ tar -xvf jellyfin-ffmpeg__portable_linux64-gpl.tar.xz -C jellyfin-ffmpeg +# mv jellyfin-ffmpeg /usr/lib +$ ldd -v /usr/lib/jellyfin-ffmpeg/ffmpeg +``` + +Install other necessary Intel driver packages and their dependencies that contain these key words: + +- Mesa libva vaapi driver - RadeonSI + +- Mesa vulkan driver - RADV + +- ROCm OpenCL runtime - OpenCL + + + +### Configure With Linux Virtualization + +#### Official Docker + +The official Docker image comes with all necessary user mode Mesa drivers. + +What you need to do is install the OpenCL runtime and pass the host's `render`group id to Docker and modify the configurations to meet your requirements. + +:::note + +Note that as of **Jellyfin 10.8** the official Docker image uses Debian 11 which has a compatible version of Mesa for **AMD GPU HEVC** decoding. + +Earlier images may not provide a compatible version of Mesa. + +::: + +:::note + +Root permission is required. + +::: + +1. Query the `render` and `video` groups id on the host system and use it in Docker cli or docker-compose file: + + :::note + + On some releases, the group may be `input`. + + ::: + + ```shell + $ getent group render | cut -d: -f3 + $ getent group video | cut -d: -f3 + ``` + +2. Use Docker command line **or** use docker-compose: + + - Example command line: + + ```shell + $ docker run -d \ + --name=jellyfin \ + --volume /path/to/config:/config \ + --volume /path/to/cache:/cache \ + --volume /path/to/media:/media \ + --user 1000:1000 \ + --group-add="122" \ # Change this to match your "render" host group id and remove this comment + --group-add="123" \ # Change this to match your "video" host group id and remove this comment + --net=host \ + --restart=unless-stopped \ + --device /dev/dri/renderD128:/dev/dri/renderD128 \ + --device /dev/dri/card0:/dev/dri/card0 \ + --device /dev/dri/kfd:/dev/dri/kfd \ + --env ROC_ENABLE_PRE_VEGA=1 \ + jellyfin/jellyfin + ``` + + - Example docker-compose (version 3) configuration file written in YAML: + + ```yaml + version: '3' + services: + jellyfin: + image: jellyfin/jellyfin + user: 1000:1000 + group_add: + - "122" # Change this to match your "render" host group id and remove this comment + - "123" # Change this to match your "video" host group id and remove this comment + network_mode: 'host' + volumes: + - /path/to/config:/config + - /path/to/cache:/cache + - /path/to/media:/media + devices: + - /dev/dri/renderD128:/dev/dri/renderD128 + - /dev/dri/card0:/dev/dri/card0 + - /dev/dri/kfd:/dev/dri/kfd + environment: + - ROC_ENABLE_PRE_VEGA=1 + ``` + +3. Get into the Docker container and install the ROCm OpenCL runtime: + + ```shell + # docker exec -u root -it jellyfin bash + $ apt update && apt install -y curl gpg + $ curl -fsSL https://repo.radeon.com/rocm/rocm.gpg.key | gpg --dearmor -o /etc/apt/keyrings/rocm.gpg + $ cat < Administrative Templates > Windows Components]** + + - Here you can find **[Remote Desktop Services > Remote Desktop Session Host > Remote Session Environment]** + + - On the right side, double click the **[Use hardware graphics adapters for all Remote Desktop Services sessions]** + + - Set **[Disabled]** in the pop-up dialog window and click **[OK]**, reboot the system. + + ![Remote desktop GPU setup](/images/docs/hwa-gpedit-mstsc.png) + +3. Enable QSV in Jellyfin and uncheck the unsupported codecs. + + + +### Verify On Windows + +1. Play a video in Jellyfin web client and trigger a video transcoding by setting a lower resolution or bitrate. + +2. Open the "Task Manager" and navigate to the GPU page. + +3. Check the occupancy of the engines as follows. + + :::note + + Duplicate engine name indicates the GPU may have multiple MFX video engines. + + ::: + + - **3D** - 2D/3D engine, QSV VPP or GPGPU workload + + - **Copy** - Blitter/Copy engine workload + + - **Video Decode** - QSV decoder or encoder workload + + - **Video Processing** - QSV VPP processor workload + + - **Compute** - GPGPU or QSV VPP workload (only available on ARC / DG2+) + + ![Verify Intel On Windows](/images/docs/hwa-intel-taskmgr.png) + +## Linux Setups + +Linux 64-bit distribution is required. **The supported GPU varies by kernel and firmware versions.** + +### Known Issues And Limitations + +:::caution + +There are some known upstream kernel and firmware issues that can affect the Intel hardware transcoding. Some of them can be fixed by upgrading your Linux distro, kernel and firmware packages, or editing the needed kernel parameters. + +::: + +1. Intel Gen 11 [**Jasper Lake**](https://ark.intel.com/content/www/us/en/ark/products/codename/128823/products-formerly-jasper-lake.html) and [**Elkhart Lake**](https://ark.intel.com/content/www/us/en/ark/products/codename/128825/products-formerly-elkhart-lake.html) platforms (e.g. N5095, N5105, N6005, J6412) have quirks when using video encoders on Linux. The [Low-Power Encoding](/docs/general/administration/hardware-acceleration/intel-hwa-tutorial#low-power-encoding) mode MUST be configured and enabled for doing the correct VBR or CBR bitrate control that is required by the Jellyfin on the fly video streaming. + + - Ticket: https://gitlab.freedesktop.org/drm/intel/-/issues/8080 + +2. The default kernel 5.15 that comes with Ubuntu 22.04 LTS has a regression on Intel Gen 11 graphics (ICL, JSL and EHL) that prevent you from using the Low-Power encoding mode. Linux 5.16+ is not affected. + + - Ticket: https://gitlab.freedesktop.org/drm/intel/-/issues/4067 + + - Fixed by: [drm/i915/gen11: Moving WAs to icl_gt_workarounds_init()](https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/commit/?id=52255ef662a5d490678fbad64a735f88fcba564d) + +3. The kernel range from 5.18 to 6.1.3 have an issue that locks up and resets the i915 kernel driver when using OpenCL based HDR/DV tone-mapping. Linux 5.18-, 6.0.18+, 6.1.4+ are not affected. + + - Ticket: https://gitlab.freedesktop.org/drm/intel/-/issues/7627 + + - Fixed by: [drm/i915: improve the catch-all evict to handle lock contention](https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/commit/?id=3f882f2d4f689627c1566c2c92087bc3ff734953) + +4. The current Debian 11 and Ubuntu 22.04 LTS may not have the required GPU firmware for Intel 12th Gen processors and ARC GPU. + +5. The kernel support for Intel Gen 12 TGL graphics is incompletet before Linux 5.9. + +6. The kernel support for Intel Gen 12 DG1 is incomplete in upstream. Intel DKMS and custom iHD driver are required. + +7. The kernel support for Intel Gen 12 ADL graphics is incomplete before Linux 5.17. + +8. The kernel support for Intel Gen 12.5 DG2 / ARC A-series is incomplete before Linux 6.2. + + + +### Configure On Linux Host + +#### Debian And Ubuntu Linux + +The `jellyfin-ffmpeg5` deb package required by Jellyfin 10.8 comes with all necessary user mode Intel media drivers. + +Besides that you only need to install the OpenCL runtime and configure the the permission of `jellyfin` user. + +:::note + +Root permission is required. + +::: + +1. Assuming you have added the jellyfin repository to your apt source list and installed the `jellyfin-server` and `jellyfin-web`. + +2. Install the `jellyfin-ffmpeg5` package. Remove the deprecated `jellyfin` meta package if it breaks the dependencies: + + ```shell + # apt update && apt install -y jellyfin-ffmpeg5 + ``` + +3. Make sure at least one `renderD*` device exists in `/dev/dri`. Otherwise upgrade your kernel or enable the iGPU in the BIOS. + + :::note + + Note the permissions and group available to write to it, in this case it is `render`: + + ::: + + ```shell + $ ls -l /dev/dri + + total 0 + drwxr-xr-x 2 root root 120 Mar 5 05:15 by-path + crw-rw----+ 1 root video 226, 0 Mar 5 05:15 card0 + crw-rw----+ 1 root video 226, 1 Mar 5 05:15 card1 + crw-rw----+ 1 root render 226, 128 Mar 5 05:15 renderD128 + crw-rw----+ 1 root render 226, 129 Mar 5 05:15 renderD129 + ``` + +4. Add the `jellyfin` user to the `render` and `video` group, then restart `jellyfin` service: + + :::note + + On some releases, the group may be `video` or `input` instead of `render`. + + ::: + + ```shell + # usermod -aG render jellyfin + # usermod -aG video jellyfin + # systemctl restart jellyfin + ``` + +5. Check the version of `intel-opencl-icd` thats the Linux distro provides: + + ```shell + $ apt policy intel-opencl-icd + + intel-opencl-icd: + Installed: (none) + Candidate: 22.14.22890-1 + ... + ``` + +6. If the version is newer than `22.xx.xxxxx` just install it. Otherwise install from [Intel compute-runtime repository](https://github.com/intel/compute-runtime/releases). + + ```shell + # apt install -y intel-opencl-icd + ``` + +7. Check the supported QSV / VA-API codecs: + + :::note + + `iHD driver` indicates both QSV and VA-API interfaces are supported. + + `i965 driver` indicates only VA-API interface is supported, which should only be used on pre-Broadwell platforms. + + ::: + + ```shell + $ /usr/lib/jellyfin-ffmpeg/vainfo --display drm --device /dev/dri/renderD128 + + libva info: VA-API version 1.17.0 + libva info: Trying to open /usr/lib/jellyfin-ffmpeg/lib/dri/iHD_drv_video.so + libva info: Found init function __vaDriverInit_1_17 + libva info: va_openDriver() returns 0 + Trying display: drm + vainfo: VA-API version: 1.17 (libva 2.17.0) + vainfo: Driver version: Intel iHD driver for Intel(R) Gen Graphics - 23.1.2 (xxxxxxx) + vainfo: Supported profile and entrypoints + ... + ``` + +8. Check the OpenCL runtime status: + + ```shell + $ /usr/lib/jellyfin-ffmpeg/ffmpeg -v verbose -init_hw_device vaapi=va:/dev/dri/renderD128 -init_hw_device opencl@va + + [AVHWDeviceContext @ 0x55cc8ac21a80] 0.0: Intel(R) OpenCL HD Graphics / Intel(R) Iris(R) Xe Graphics [0x9a49] + [AVHWDeviceContext @ 0x55cc8ac21a80] Intel QSV to OpenCL mapping function found (clCreateFromVA_APIMediaSurfaceINTEL). + [AVHWDeviceContext @ 0x55cc8ac21a80] Intel QSV in OpenCL acquire function found (clEnqueueAcquireVA_APIMediaSurfacesINTEL). + [AVHWDeviceContext @ 0x55cc8ac21a80] Intel QSV in OpenCL release function found (clEnqueueReleaseVA_APIMediaSurfacesINTEL). + ... + ``` + +9. If you wish to use the second GPU, change `renderD128` to `renderD129` in the Jellyfin dashboard. + +10. Enable QSV or VA-API in Jellyfin and uncheck the unsupported codecs. + + + +#### Linux Mint + +Linux Mint use Ubuntu as its package base. + +You can follow the configuration steps of [Debian And Ubuntu Linux](/docs/general/administration/hardware-acceleration/intel-hwa-tutorial#debian-and-ubuntu-linux) but install all Jellyfin packages `jellyfin-server`, `jellyfin-web` and `jellyfin-ffmpeg5` manually from the [Jellyfin Server Releases Page](https://repo.jellyfin.org/releases/server/). Also make sure you choosed the correct codename by following the [official version maps](https://linuxmint.com/download_all.php). + + + +#### Arch Linux + +AUR `jellyfin-ffmpeg`, `jellyfin-ffmpeg5*` packages and future ffmpeg versions are maintained by Jellyfin team. + +:::note + +Root permission is required. + +::: + +1. Make and install the AUR [`jellyfin-ffmpeg5-bin`](https://aur.archlinux.org/packages/jellyfin-ffmpeg5-bin), then change the ffmpeg path in Jellyfin dashboard to `/usr/lib/jellyfin-ffmpeg/ffmpeg`: + + ```shell + $ cd ~/ + $ git clone https://aur.archlinux.org/jellyfin-ffmpeg5-bin.git + $ cd jellyfin-ffmpeg5-bin + $ makepkg -si + ``` + +2. User mode Intel media drivers and the OpenCL runtime are required to be manually installed for enabling QSV / VA-API: + + - [intel-media-driver](https://archlinux.org/packages/community/x86_64/intel-media-driver/) + + - [intel-media-sdk](https://archlinux.org/packages/community/x86_64/intel-media-sdk/) + + - [onevpl-intel-gpu](https://aur.archlinux.org/packages/onevpl-intel-gpu) + + - [intel-compute-runtime](https://archlinux.org/packages/community/x86_64/intel-compute-runtime/) + + - [libva-intel-driver](https://archlinux.org/packages/extra/x86_64/libva-intel-driver/) + +3. Check the QSV / VA-API codecs and the OpenCL runtime status: + + ```shell + # pacman -Sy libva-utils + $ vainfo --display drm --device /dev/dri/renderD128 + $ /usr/lib/jellyfin-ffmpeg/ffmpeg -v verbose -init_hw_device vaapi=va:/dev/dri/renderD128 -init_hw_device opencl@va + ``` + +4. Check to the rest parts of [Debian And Ubuntu Linux](/docs/general/administration/hardware-acceleration/intel-hwa-tutorial#debian-and-ubuntu-linux). + + + +#### Other Distros + +We provide **portable** [jellyfin-ffmpeg](https://github.com/jellyfin/jellyfin-ffmpeg) binaries for distros that don't have a regular maintainer. + +They can be downloaded from one of these links: + +- [Jellyfin repository](https://repo.jellyfin.org/releases/ffmpeg/) + +- [Releases · jellyfin/jellyfin-ffmpeg · GitHub](https://github.com/jellyfin/jellyfin-ffmpeg/releases) + +:::note + +Minimum requirements for glibc and Linux versions: + +- x86_64 / amd64 - glibc >= 2.23, Linux >= 4.4 (most distros released in 2016 and later) + +::: + +Extract and install it to the correct path, change the ffmpeg path in Jellyfin dashboard to match it: + +```shell +$ cd ~/ +$ mkdir -p jellyfin-ffmpeg +$ wget https://repo.jellyfin.org/releases/ffmpeg//jellyfin-ffmpeg__portable_linux64-gpl.tar.xz +$ tar -xvf jellyfin-ffmpeg__portable_linux64-gpl.tar.xz -C jellyfin-ffmpeg +# mv jellyfin-ffmpeg /usr/lib +$ ldd -v /usr/lib/jellyfin-ffmpeg/ffmpeg +``` + +Install other necessary Intel driver packages and their dependencies that contain these key words: + +- Intel media driver - iHD + +- Intel vaapi driver - i965 + +- Intel media sdk - MFX + +- Intel oneVPL-intel-gpu - VPL + +- Intel compute runtime - OpenCL + + + +### Configure With Linux Virtualization + +#### Official Docker + +The official Docker image comes with all necessary user mode Intel media drivers and the OpenCL runtime. + +What you need to do is pass the host's `render`group id to Docker and modify the configurations to meet your requirements. + +1. Query the `render` and `video` groups id on the host system and use it in Docker cli or docker-compose file. + + :::note + + On some releases, the group may be `input`. + + ::: + + ```shell + $ getent group render | cut -d: -f3 + ``` + +2. Use docker command line **or** use docker-compose: + + - Example command line: + + ```shell + $ docker run -d \ + --name=jellyfin \ + --volume /path/to/config:/config \ + --volume /path/to/cache:/cache \ + --volume /path/to/media:/media \ + --user 1000:1000 \ + --group-add="122" \ # Change this to match your "render" host group id and remove this comment + --group-add="123" \ # Change this to match your "video" host group id and remove this comment + --net=host \ + --restart=unless-stopped \ + --device /dev/dri/renderD128:/dev/dri/renderD128 \ + --device /dev/dri/card0:/dev/dri/card0 \ + jellyfin/jellyfin + ``` + + - Example docker-compose (version 3) configuration file written in YAML: + + ```yaml + version: '3' + services: + jellyfin: + image: jellyfin/jellyfin + user: 1000:1000 + group_add: + - "122" # Change this to match your "render" host group id and remove this comment + network_mode: 'host' + volumes: + - /path/to/config:/config + - /path/to/cache:/cache + - /path/to/media:/media + devices: + - /dev/dri/renderD128:/dev/dri/renderD128 + - /dev/dri/card0:/dev/dri/card0 + ``` + +3. If you wish to use the second GPU on your system, change `card0` to `card1` and `renderD128` to `renderD129`. + +4. For trying out the unstable build, change `jellyfin/jellyfin` to `jellyfin/jellyfin:unstable` on your own risk. + +5. Check the QSV and VA-API codecs: + + ```shell + $ docker exec -it jellyfin /usr/lib/jellyfin-ffmpeg/vainfo + ``` + +6. Check the OpenCL runtime status: + + ```shell + $ docker exec -it jellyfin /usr/lib/jellyfin-ffmpeg/ffmpeg -v verbose -init_hw_device vaapi=va -init_hw_device opencl@va + ``` + +7. Enable QSV or VA-API in Jellyfin and uncheck the unsupported codecs. + + + +#### Linuxserver.io Docker + +LSIO Docker images are maintained by [linuxserver.io](https://www.linuxserver.io/), please refer their docs from [GitHub - linuxserver/docker-jellyfin](https://github.com/linuxserver/docker-jellyfin). + +:::note + +The paths of Jellyfin config and data folders in the official and LSIO Docker images are different. So they cannot be easily exchanged. + +::: + + + +#### Kubernetes + +This follows the same principles as for the Docker, with one small change that your container within the pod much run as **privileged**. + +The devices in Kubernetes are added as a host path mounts, they are not separated into separate volumes as in the Docker. + +1. Example Kubernetes (API version 1) configuraton file written in YAML: + + ```yaml + # Example of an incomplete deployment spec + apiVersion: apps/v1 + kind: Deployment + metadata: ... + spec: + template: + metadata: ... + spec: + securityContext: + runAsUser: 1000 # Similar to "user: 1000:1000" on Docker + runAsGroup: 1000 + supplementalGroups: + - 122 # Change this to match your "render" host group id and remove this comment + - 44 # Chnage this to match your "video" host group id and remove this comment + containers: + - name: "jellyfin" + image: ... + ports: ... + env: ... + securityContext: + privileged: true # Container must run as privileged inside of the pod + volumeMounts: + - name: "render-device" + mountPath: "/dev/dri/renderD128" + - name: "card-device" + mountPath: "/dev/dri/card0" + volumes: + - name: "render-device" + hostPath: + path: "/dev/dri/renderD128" + - name: "card-device" + hostPath: + path: "/dev/dri/card0" + ``` + +2. When the pod starts, you can check the QSV and VA-API codecs. + + If you get `error: failed to initialize display` then double check that the `supplementalGroups` are correct. + + ```shell + $ kubectl exec -- /usr/lib/jellyfin-ffmpeg/vainfo + ``` + +3. Enable QSV or VA-API in Jellyfin and uncheck the unsupported codecs. + + + +#### LXC And LXD Container + +:::caution + +This has been tested with LXC 3.0 and may or may not work with older versions. + +::: + +1. Query the `render` and `video` group id on the host system. + + :::note + + On some releases, the group may be `input` instead of `render` and `video`. + + ::: + + ```shell + $ getent group render | cut -d: -f3 + $ getent group video | cut -d: -f3 + ``` + +2. Install the required drivers on the host system. + +3. Add your GPU to the container: + + ```shell + $ lxc config device add gpu gpu gid= + ``` + +4. Make sure you have the requied devices within the container: + + ```shell + $ lxc exec jellyfin -- ls -l /dev/dri + + total 0 + crw-rw---- 1 root video 226, 0 Jun 4 02:13 card0 + crw-rw---- 1 root video 226, 0 Jun 4 02:13 controlD64 + crw-rw---- 1 root video 226, 128 Jun 4 02:13 renderD128 + ``` + +5. Configure Jellyfin to use QSV or VA-API acceleration and change the default GPU renderD128 if necessary. + + + +#### LXC On Proxmox + +:::note + +Jellyfin needs to run in a **privileged** LXC container. + +An existing unprivileged container can be converted to a priviledged container by taking a backup and restoring it as priviledged. + +::: + +1. Install the required drivers on the Proxmox host. + +2. Add your GPU to the container by editing `/etc/pve/lxc/.conf`. + + You may need to change the GIDs in the examples below to match those used on your host. + + :::caution + + This has been tested on Proxmox VE 7.1 - on previous versions you may need to change `cgroup2` to `cgroup`. + + ::: + + ```conf + lxc.cgroup2.devices.allow: c 226:0 rwm + lxc.cgroup2.devices.allow: c 226:128 rwm + lxc.mount.entry: /dev/dri/card0 dev/dri/card0 none bind,optional,create=file + lxc.mount.entry: /dev/dri/renderD128 dev/dri/renderD128 none bind,optional,create=file + ``` + +3. Restart your container and install the required drivers in your container. + +4. Add `jellyfin` user to the `video`, `render` and/or `input` groups depending on who owns the device inside the container. + +5. Configure Jellyfin to use QSV or VA-API acceleration and change the default GPU `renderD128` if necessary. + + + +### Verify On Linux + +:::note + +Root permission is required. + +::: + +1. Install the `intel-gpu-tools` package, which is used for debugging Intel graphics driver on Linux. The name varies with different distros. + + - On Debian & Ubuntu: + + ```shell + # apt update && apt install -y intel-gpu-tools + ``` + + - On Arch Linux: + + ```shell + # pacman -Sy intel-gpu-tools + ``` + +2. Play a video in Jellyfin web client and trigger a video transcoding by setting a lower resolution or bitrate. + +3. Use `intel_gpu_tool` command to check the occupancy of the engines as follows: + + :::note + + Duplicate engine name indicates the GPU may have multiple MFX video engines. + + ::: + + - **Render/3D** - 2D/3D engine, QSV VPP or GPGPU workload + + - **Blitter** - Blitter/Copy engine workload + + - **Video** - QSV decoder or encoder workload + + - **VideoEnhance** - QSV VPP processor workload + + - **Compute** - GPGPU or QSV VPP workload (only available on ARC / DG2+) + + ```shell + # intel_gpu_tool + + intel-gpu-top: Intel Tigerlake (Gen12) @ /dev/dri/card0 - 86/ 349 MHz; 54% RC6 + 441 irqs/s + + ENGINES BUSY MI_SEMA MI_WAIT + Render/3D 19.86% |████████▊ | 0% 0% + Blitter 0.00% | | 0% 0% + Video 2.17% |█ | 0% 0% + VideoEnhance 3.52% |█▋ | 0% 0% + + PID NAME Render/3D Blitter Video VideoEnhance + ... + ``` + +## Low-Power Encoding + +Intel video encoders on Gen 9+ graphics support two encoding modes: + +- Low-Power / LP encoding (VDEnc + HuC) + +- non Low-Power / LP encoding (PAK + media kernel + VME) + +Low-Power encoding can offload the GPU usage with the help of the [HuC firmware](https://01.org/linuxgraphics/downloads/firmware). + +This can be useful for speeding up the OpenCL based HDR/DV tone-mapping. + +:::tip + +More detail information about Intel video hardware can be found [here](https://github.com/intel/media-driver#components-and-features). + +::: + + + +### LP Mode Hardware Support + +:::note + +Gen X refers to Intel graphics architechure instead of the CPU generation. (i.e. Gen 9 graphics ≠ 9th Gen processors) + +::: + +- Gen 9.x SKL+ graphics - Support non-LP and LP (H.264 only) encoding. + +- Gen 11 ICL graphics - Support both two encoding modes. + +- Gen 11 JSL/EHL graphics - Only support LP encoding mode. + +- Gen 12 TGL/DG1+ graphics - Support both two encodng modes. + +- Gen 12.5 DG2/ARC A-Series - Only support LP encoding mode. + +- Gen 12.7 MTL and newer - To be announced. + + + +### LP Mode System Support + +- Windows supports two modes by default. No additional configuration is required. + +- Linux supports two modes only on Gen 12 ADL+ by default. + + On older platforms LP mode can be configured manually by passing a parameter to the i915 kernel driver. + + + +### Configure And Verify LP Mode On Linux + +:::caution + +The setup is not necessary unless you are using an Intel **Jasper Lake** or **Elkhart Lake** processor, or you want faster OpenCL tone-mapping speed on Linux. This also applies to the bleeding edge hardware such as **12th Gen Intel processors**, **ARC GPU** and newer **but the step 3 and 4 should be skipped**. + +::: + +:::note + +Root permission is required. + +::: + +1. Install the latest linux firmware packages **on host system**. The name varies with different distros. + + - On Debian: + + ```shell + # apt update && apt install -y firmware-linux-nonfree + ``` + + - On Ubuntu: + + ```shell + # apt update && apt install -y linux-firmware + ``` + + - On Arch Linux: + + ```shell + # pacman -Sy linux-firmware + ``` + + - Pull firmwares from Linux repository directly: + + ```shell + $ cd ~/ + $ git clone --depth=1 https://git.kernel.org/pub/scm/linux/kernel/git/firmware/linux-firmware.git + # cp -r linux-firmware/i915 /usr/lib/firmware + ``` + +2. Add an i915 kernel parameter on host to enable GuC loading HuC firmware: + + ```shell + # mkdir -p /etc/modeprobe.d + # sh -c "echo 'options i915 enable_guc=2' >> /etc/modeprobe.d/i915.conf" + ``` + +3. Update the initramfs and grub. The commands varies with different distros. + + - On Debian & Ubuntu: + + ```shell + # update-initramfs -u && update-grub + ``` + + - On Arch Linux: + + ```shell + # mkinitcpio -P && update-grub + ``` + +4. Reboot the system and check the GuC & HuC status with the following commands, make sure there is no FAIL or ERROR in the outputs. + + ```shell + $ reboot + # dmesg | grep i915 + # cat /sys/kernel/debug/dri/0/gt/uc/guc_info + # cat /sys/kernel/debug/dri/0/gt/uc/huc_info + ``` + + On very old kernels (4.x) the last two commands can be like this: + + ```shell + # cat /sys/kernel/debug/dri/0/i915_guc_load_status + # cat /sys/kernel/debug/dri/0/i915_huc_load_status + ``` + +5. Now you can safely enable the Intel Low-Power encoder in Jellyfin dashboard. + +:::tip + +Extended readings for more distros: + +- [Intel graphics - ArchWiki](https://wiki.archlinux.org/title/intel_graphics) + +- [skylake-tuning-linux - GitHub](https://gist.github.com/Brainiarc7/aa43570f512906e882ad6cdd835efe57) + +::: diff --git a/docs/general/administration/hardware-acceleration/nvidia-hwa-tutorial.md b/docs/general/administration/hardware-acceleration/nvidia-hwa-tutorial.md new file mode 100644 index 00000000..d8cb2cf5 --- /dev/null +++ b/docs/general/administration/hardware-acceleration/nvidia-hwa-tutorial.md @@ -0,0 +1,471 @@ +--- +uid: admin-hardware-acceleration-nvidia +title: HWA Tutorial On NVIDIA GPU +--- + +# HWA Tutorial On NVIDIA GPU + +This tutorial guides you setting up full video hardware acceleration on NVIDIA GPU via NVENC. + + + +## Acceleration Methods + +Hardware accelerated transcoding is supported on NVIDIA GPUs since Maxwell architecture. + +On Windows and Linux **NVENC** is the only available method. + + + +The NVENC/NVDEC are the proprietary video codec APIs of NVIDIA GPU, which can be used with CUDA to achieve full hardware acceleration. + + + +:::caution + +Consumer targeted [Geforce and some entry-level Quadro](https://developer.nvidia.com/video-encode-and-decode-gpu-support-matrix-new) cards officially support **no more than 3 simultaneously encoding video streams**, regardless of the count of the cards installed, but this restriction can be circumvented by applying an [unofficial patch](https://github.com/keylase/nvidia-patch) to the NVIDIA Linux and Windows driver. + +::: + +:::note + +NVENC support headless server on both Windows and Linux, which means a connected monitor is not required. + +::: + + + +## Tone-mapping Methods + +Hardware accelerated HDR/DV to SDR tone-mapping is supported on **all NVIDIA GPUs that have HEVC 10-bit decoding**. + +On Windows and Linux **CUDA** is the only available tone-mapping method. It also supports Dolby Vision P5 and zero-copy. + + + +## Select GPU Hardware + +:::caution + +Most NVIDIA GPU comes with NVENC/NVDEC support but be **some low-end and mobile models (e.g. GT1030 and MX450)** are exceptions. + +::: + +Best to check the video codec support via the [NVIDIA GPU Codec Support Matrix](https://developer.nvidia.com/video-encode-and-decode-gpu-support-matrix-new) before buying a GPU for hardware acceleration. + +### Transcode H.264 + +AVC / H.264 8-bit is still widely used due to its excellent compatibility. All NVIDIA GPUs that support NVENC/NVDEC can decode and/or encode it. + +- **Decoding & Encoding H.264 8-bit** - Any NVIDIA GPU that supports NVENC/NVDEC + + + +### Transcode HEVC + +HEVC / H.265 remains the first choice for storing 4K 10-bit, HDR and Dolby Vision video. It has mature software encoder [x265 and documentation](https://x265.readthedocs.io/en/master/) support, as well as the widely implemented hardware codecs in most GPUs released after 2016. + +Maxwell+ GPU provide support for HEVC: + +- **Decoding & Encoding HEVC 8-bit** - Maxwell 2nd Gen (GM206) and newer + +- **Decoding HEVC 10-bit** - Maxwell 2nd Gen (GM206) and newer + +- **Encoding HEVC 10-bit** - Pascal and newer + +:::note + +Note that in Maxwell 2nd Gen series only the GM206 variants provide the HEVC 10-bit decoding support. + +Its sucessor Pascal has full support for HEVC 10-bit and improved speed and quality performance. + +::: + + + +### Transcode AV1 + +AV1 is a royalty-free, future-proof video codec. It saves storage space and network bandwidth a lot. The downside is that decoding and encoding them are very stressful for your CPU. But hardware acceleration makes it possible to transcode to AV1 streams on the fly. AV1 encoding support in Jellyfin is planned in the future. + +NVIDIA added support for AV1 acceleration in their latest GPUs: + +- **Decoding AV1 8/10-bit** - Ampere and newer + +- **Encoding AV1 8/10-bit** - Ada Lovelace and newer + + + +### Transcode Other Codecs + +Please refer to these links: + +- [NVIDIA GPU Codec Support Matrix](https://developer.nvidia.com/video-encode-and-decode-gpu-support-matrix-new) + +- [NVIDIA Hardware Transcoding Calculator](https://www.elpamsoft.com/?p=Plex-Hardware-Transcoding) + + + +### Speed And Quality + +Encoding quality: + +- H.264 & HEVC - Ada/Ampere/Turing > Turing TU117/Volta/Pascal > Maxwell + +- AV1 - Ada Lovelace only + +Decoding & Encoding speed in same generation: + +- Multiple NVENC/NVDEC models > Single NVENC/NVDEC models + +- High GPU clock speed models > Low GPU clock speed models + +- High memory bandwidth models > Low memory bandwidth models + + + +NVENC/NVDEC encoding performance tables: + +- [NVENC Performance - NVIDIA Docs](https://docs.nvidia.com/video-technologies/video-codec-sdk/nvenc-application-note/index.html#nvenc-performance) + +- [NVDEC Performance - NVIDIA Docs](https://docs.nvidia.com/video-technologies/video-codec-sdk/nvdec-application-note/index.html#nvdec-performance) + + + +## Windows Setups + +Windows 10 64-bit and newer is recommeded. **In Jellyfin 10.8 the minimum required NVIDIA driver version is 471.41**. + +### Configure On Windows Host + +1. Wipe the old driver with [DDU](https://www.wagnardsoft.com/) if you upgraded from a pre-Maxwell NVIDIA GPU without doing a fresh installation. + +2. Clean install the latest driver from [NVIDIA Driver Downloads](https://www.nvidia.com/Download/index.aspx). + +3. Enable NVENC in Jellyfin and uncheck the unsupported codecs. + + + +### Configure With Windows Virtualization + +NVIDIA Windows driver provides access to the NVENC/NVDEC and CUDA in Windows WSL2 and Docker. + +Refer to [Configure On Linux Host](/docs/general/administration/hardware-acceleration/nvidia-hwa-tutorial#configure-on-linux-host) and [Configure With Linux Virtualization](/docs/general/administration/hardware-acceleration/nvidia-hwa-tutorial#configure-with-linux-virtualization). + + + +### Verify On Windows + +1. Play a video in Jellyfin web client and trigger a video transcoding by setting a lower resolution or bitrate. + +2. Open the "Task Manager" and navigate to the GPU page. + +3. Check the occupancy of the engines as follows. + + - **3D** - 2D/3D engine or CUDA/GPGPU workload + + - **Copy** - Blitter/Copy engine workload + + - **Video Decode** - Video decoder workload + + - **Video Encode** - Video encoder workload + + - **Cuda** - CUDA/GPGPU workload + + ![Verify NVIDIA On Windows](/images/docs/hwa-nvidia-taskmgr.png) + +## Linux Setups + +Linux 64-bit distribution is required. **In Jellyfin 10.8 the minimum required NVIDIA driver version is 470.57.02**. + +### Configure On Linux Host + +#### Debian And Ubuntu Linux + +The `jellyfin-ffmpeg5` deb package required by Jellyfin 10.8 doesn't include any NVIDIA proprietary driver. + +So you have to install the NVIDIA driver from the distro and configure the the permission of `jellyfin` user. + +:::note + +Root permission is required. + +::: + +1. Assuming you have added the jellyfin repository to your apt source list and installed the `jellyfin-server` and `jellyfin-web`. + +2. Install the `jellyfin-ffmpeg5` package. Remove the deprecated `jellyfin` meta package if it breaks the dependencies: + + ```shell + # apt update && apt install -y jellyfin-ffmpeg5 + ``` + +3. Install the NVIDIA proprietary driver by following these links. Then install two extra packages for NVENC and NVDEC support: + + - On Debian: https://wiki.debian.org/NvidiaGraphicsDrivers + + ```shell + # apt update && apt install -y libnvcuvid1 libnvidia-encode1 + ``` + + - On Ubuntu: https://help.ubuntu.com/community/NvidiaDriversInstallation + + :::note + + You may need to add the driver version as the suffix of the package name. + + ::: + + ```shell + # apt update && apt install -y libnvidia-decode libnvidia-encode + ``` + +4. Check the NVIDIA GPU status by using `nvidia-smi`: + + ```shell + $ nvidia-smi + + +-----------------------------------------------------------------------------+ + | NVIDIA-SMI 470.161.03 Driver Version: 470.161.03 CUDA Version: 11.4 | + |-------------------------------+----------------------+----------------------+ + | 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:1C:00.0 Off | N/A | + | 0% 44C P0 N/A / 75W | 0MiB / 1998MiB | 0% Default | + | | | N/A | + +-------------------------------+----------------------+----------------------+ + ... + ``` + +5. Enable NVENC in Jellyfin and uncheck the unsupported codecs. + + + +#### Linux Mint + +Linux Mint use Ubuntu as its package base. + +You can follow the configuration steps of [Debian And Ubuntu Linux](/docs/general/administration/hardware-acceleration/nvidia-hwa-tutorial#debian-and-ubuntu-linux) but install all Jellyfin packages `jellyfin-server`, `jellyfin-web` and `jellyfin-ffmpeg5` manually from the [Jellyfin Server Releases Page](https://repo.jellyfin.org/releases/server/). Also make sure you choosed the correct codename by following the [official version maps](https://linuxmint.com/download_all.php). + + + +#### Arch Linux + +AUR `jellyfin-ffmpeg`, `jellyfin-ffmpeg5*` packages and future ffmpeg versions are maintained by Jellyfin team. + +:::note + +Root permission is required. + +::: + +1. Make and install the AUR [`jellyfin-ffmpeg5-bin`](https://aur.archlinux.org/packages/jellyfin-ffmpeg5-bin), then change the ffmpeg path in Jellyfin dashboard to `/usr/lib/jellyfin-ffmpeg/ffmpeg`: + + ```shell + $ cd ~/ + $ git clone https://aur.archlinux.org/jellyfin-ffmpeg5-bin.git + $ cd jellyfin-ffmpeg5-bin + $ makepkg -si + ``` + +2. Install the NVIDIA proprietary driver by following the link. Then install an extra package for NVENC and NVDEC support: + + - https://wiki.archlinux.org/title/NVIDIA#Installation + + ```shell + # pacman -Sy nvidia-utils + ``` + +3. Check the NVIDIA GPU status by using `nvidia-smi`: + + ```shell + $ nvidia-smi + ``` + +4. Enable NVENC in Jellyfin and uncheck the unsupported codecs. + + + +#### Other Distros + +We provide **portable** [jellyfin-ffmpeg](https://github.com/jellyfin/jellyfin-ffmpeg) binaries for distros that don't have a regular maintainer. + +They can be downloaded from one of these links: + +- [Jellyfin repository](https://repo.jellyfin.org/releases/ffmpeg/) + +- [Releases · jellyfin/jellyfin-ffmpeg · GitHub](https://github.com/jellyfin/jellyfin-ffmpeg/releases) + +:::note + +Minimum requirements for glibc and Linux versions: + +- x86_64 / amd64 - glibc >= 2.23, Linux >= 4.4 (most distros released in 2016 and later) + +::: + +Extract and install it to the correct path, change the ffmpeg path in Jellyfin dashboard to match it: + +```shell +$ cd ~/ +$ mkdir -p jellyfin-ffmpeg +$ wget https://repo.jellyfin.org/releases/ffmpeg//jellyfin-ffmpeg__portable_linux64-gpl.tar.xz +$ tar -xvf jellyfin-ffmpeg__portable_linux64-gpl.tar.xz -C jellyfin-ffmpeg +# mv jellyfin-ffmpeg /usr/lib +$ ldd -v /usr/lib/jellyfin-ffmpeg/ffmpeg +``` + +Install NVIDIA proprietary driver packages and their dependencies that contain these key words: + +- NVIDIA NVDEC CUVID - DECODE + +- NVIDIA NVENC - ENCODE + + + +### Configure With Linux Virtualization + +#### Official Docker + +The official Docker image doesn't include any NVIDIA proprietary driver. + +So you have to install the NVIDIA driver and NVIDIA Container Toolkit on host to allow Docker access your GPU. + +:::note + +Root permission is required. + +::: + +1. Install the NVIDIA proprietary driver on host. See above instructions. + +2. Install the NVIDIA Container Toolkit on host by following the link: + + - https://docs.nvidia.com/datacenter/cloud-native/container-toolkit/install-guide.html#installation-guide + +3. Use Docker command line **or** use docker-compose: + + - Example command line: + + ```shell + $ docker run -d \ + --name=jellyfin \ + --volume /path/to/config:/config \ + --volume /path/to/cache:/cache \ + --volume /path/to/media:/media \ + --user 1000:1000 \ + --net=host \ + --restart=unless-stopped \ + --runtime=nvidia \ + --gpus all \ + jellyfin/jellyfin + ``` + + - Example docker-compose (version 3) configuration file written in YAML: + + ```yaml + version: '3' + services: + jellyfin: + image: jellyfin/jellyfin + user: 1000:1000 + network_mode: 'host' + volumes: + - /path/to/config:/config + - /path/to/cache:/cache + - /path/to/media:/media + runtime: nvidia + deploy: + resources: + reservations: + devices: + - capabilities: [gpu] + ``` + +4. Add your username to the video group: + + ```shell + # usermod -aG video $USER + ``` + +5. Update configure dynamic links and restart the Docker service: + + ```shell + $ docker exec -it jellyfin ldconfig + # systemctl restart docker + ``` + +6. Check the NVIDIA GPU status by using `nvidia-smi`: + + ```shell + $ docker exec -it jellyfin nvidia-smi + ``` + +7. For trying out the unstable build, change `jellyfin/jellyfin` to `jellyfin/jellyfin:unstable` on your own risk. + +8. Enable NVENC in Jellyfin and uncheck the unsupported codecs. + + + +:::note + +Note that the official Jellyfin Docker image already set the required environment variables for NVIDIA GPUs. If you are building your own image don't forget the add two extra environment variables into the Docker configs. + +- `NVIDIA_DRIVER_CAPABILITIES=all` + +- `NVIDIA_VISIBLE_DEVICES=all` + +::: + + + +#### Linuxserver.io Docker + +LSIO Docker images are maintained by [linuxserver.io](https://www.linuxserver.io/), please refer their docs from [GitHub - linuxserver/docker-jellyfin](https://github.com/linuxserver/docker-jellyfin). + +:::note + +The paths of Jellyfin config and data folders in the official and LSIO Docker images are different. So they cannot be easily exchanged. + +::: + + + +#### Other Virtualizations + +Other Virtualizations are not verified and may or may not work on NVIDIA GPU. + +Refer to the [HWA Tutorial On Intel GPU - Configure With Linux Virtualization](/docs/general/administration/hardware-acceleration/intel-hwa-tutorial#configure-with-linux-virtualization) for more information. + + + +### Verify On Linux + +1. Play a video in Jellyfin web client and trigger a video transcoding by setting a lower resolution or bitrate. + +2. Use `nvidia-smi` command to check the occupancy of the NVIDIA GPU and the VRAM usage of each jellyfin-ffmpeg process: + + ```shell + $ nvidia-smi + + +-----------------------------------------------------------------------------+ + | NVIDIA-SMI 470.161.03 Driver Version: 470.161.03 CUDA Version: 11.4 | + |-------------------------------+----------------------+----------------------+ + | 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:1C:00.0 Off | N/A | + | 43% 44C P2 36W / 75W | 274MiB / 1998MiB | 68% Default | + | | | N/A | + +-------------------------------+----------------------+----------------------+ + +-----------------------------------------------------------------------------+ + | Processes: | + | GPU GI CI PID Type Process name GPU Memory | + | ID ID Usage | + |=============================================================================| + | 0 N/A N/A 4024 G /usr/lib/xorg/Xorg 63MiB | + | 0 N/A N/A 5837 C /usr/lib/jellyfin-ffmpeg/ffmpeg 195MiB | + +-----------------------------------------------------------------------------+ + ``` diff --git a/static/images/docs/hwa-amd-taskmgr.png b/static/images/docs/hwa-amd-taskmgr.png new file mode 100644 index 00000000..5f69b01f Binary files /dev/null and b/static/images/docs/hwa-amd-taskmgr.png differ diff --git a/static/images/docs/hwa-gpedit-mstsc.png b/static/images/docs/hwa-gpedit-mstsc.png new file mode 100644 index 00000000..de60a139 Binary files /dev/null and b/static/images/docs/hwa-gpedit-mstsc.png differ diff --git a/static/images/docs/hwa-intel-taskmgr.png b/static/images/docs/hwa-intel-taskmgr.png new file mode 100644 index 00000000..81f900e5 Binary files /dev/null and b/static/images/docs/hwa-intel-taskmgr.png differ diff --git a/static/images/docs/hwa-nvidia-taskmgr.png b/static/images/docs/hwa-nvidia-taskmgr.png new file mode 100644 index 00000000..5cec52cf Binary files /dev/null and b/static/images/docs/hwa-nvidia-taskmgr.png differ