jellyfin/jellyfin.org
1
0
Fork 0
mirror of https://github.com/jellyfin/jellyfin.org.git synced 2026-09-03 04:10:04 +03:00
Code Issues Packages Projects Releases Wiki Activity

Hardware acceleration pages overhaul

Browse Source 
Signed-off-by: nyanmisaka <nst799610810@gmail.com>
This commit is contained in:
nyanmisaka
2023-03-13 00:08:45 +08:00
parent b0ab6bd324
commit a0770b5cbc
9 changed files with 2278 additions and 692 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/general/administration/hardware-acceleration.md
-692
View File
@@ -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 <user>
```
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 <container name> gpu gpu gid=<gid of your video or render group>
```
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/<container-id>.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-<random-id>>.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.
docs/general/administration/hardware-acceleration/amd-hwa-tutorial.md
+631
View File
@@ -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 <<EOF | sudo tee /etc/apt/sources.list.d/rocm.sources
Types: deb
URIs: https://repo.radeon.com/rocm/apt/latest
Suites: ubuntu
Components: main
Architectures: amd64
Signed-By: /etc/apt/keyrings/rocm.gpg
EOF
# apt update && apt install -y rocm-opencl-runtime
# sh -c "echo ROC_ENABLE_PRE_VEGA=1 >> /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/<VERSION>/jellyfin-ffmpeg_<VERSION>_portable_linux64-gpl.tar.xz
$ tar -xvf jellyfin-ffmpeg_<VERSION>_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 <<EOF | tee /etc/apt/sources.list.d/rocm.sources
Types: deb
URIs: https://repo.radeon.com/rocm/apt/latest
Suites: ubuntu
Components: main
Architectures: amd64
Signed-By: /etc/apt/keyrings/rocm.gpg
EOF
$ apt update && apt install -y rocm-opencl-runtime
$ exit
```
4. If you wish to use the second GPU on your system, change `card0` to `card1` and `renderD128` to `renderD129`.
5. For trying out the unstable build, change `jellyfin/jellyfin` to `jellyfin/jellyfin:unstable` on your own risk.
6. Check the VA-API codecs:
```shell
$ docker exec -it jellyfin /usr/lib/jellyfin-ffmpeg/vainfo --display drm --device /dev/dri/renderD128
```
7. Check the OpenCL runtime status:
```shell
$ docker exec -it jellyfin /usr/lib/jellyfin-ffmpeg/ffmpeg -v debug -init_hw_device opencl
```
8. Check the Vulkan runtime status:
```shell
$ docker exec -it jellyfin /usr/lib/jellyfin-ffmpeg/ffmpeg -v debug -init_hw_device vulkan
```
9. Enable 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.
- Third-party LSIO Docker mod [jellyfin-amd](https://github.com/linuxserver/docker-mods/pull/544) can be used for enabling the OpenCL tone-mapping.
:::
#### Other Virtualizations
Other Virtualizations are not verified and may or may not work on AMD 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
There is not reliable way to read the occupancy of the VCE/UVD/VCN engines on AMD GPU on Linux.
But you can still verify this by reading other engines with the `radeontop` tool.
:::note
Root permission is required.
:::
1. Install the `radeontop` package. The name varies with different distros.
- On Debian & Ubuntu:
```shell
# apt update && apt install -y radeontop
```
- On Arch Linux:
```shell
# pacman -Sy radeontop
```
2. Play a video in Jellyfin web client and trigger a video transcoding by setting a lower resolution or bitrate.
3. Use `radeontop` command to check the occupancy of 3D engines.
docs/general/administration/hardware-acceleration/index.md
+217
View File
@@ -0,0 +1,217 @@
---
uid: admin-hardware-acceleration
title: Hardware Acceleration
---
# Hardware Acceleration
Jellyfin server can offload the process of on the fly video transcoding with the help of integrated or discrete graphics card ([GPU](https://en.wikipedia.org/wiki/Graphics_processing_unit)), which is designed to be suitable for accelerating this workload very efficiently without needing to burn your CPU.
## Supported Acceleration Methods
Jellyfin server uses a modified version of [FFmpeg](http://ffmpeg.org/) as its transcoder, namely [jellyfin-ffmpeg](https://github.com/jellyfin/jellyfin-ffmpeg). It enables Jellyfin server to access the fixed-function video codecs, video processors and [GPGPU](https://en.wikipedia.org/wiki/General-purpose_computing_on_graphics_processing_units) computing interfaces provided by vendor and operating system of the installed GPU.
The supported and validated video [hardware acceleration (HWA)](https://trac.ffmpeg.org/wiki/HWAccelIntro) methods are:
- **Intel** Quick Sync Video (QSV)
- **NVIDIA** NVDEC/NVENC (NVENC)
- **AMD** Advancded Media Framework (AMF)
- **Intel/AMD** Video Acceleration API (VA-API, Linux only)
- **Apple** Video Toolbox (macOS only)
- **Raspberry Pi** Video4Linux2 (V4L2, Linux only)
## Full & Partial Acceleration
Transcoding pipeline usually has multiple stages, which can be simpified to:
- Video Decoding
- Video Deinterlacing (optional)
- Video Scaling & Format conversion (optional)
- Video HDR/DV Tone-mapping (optional)
- Video Subtitle burn-in (optional)
- Video Encoding
- Zero-copy in above stages
:::note
Some of these stages cannot be GPU accelerated due to the software, hardware or driver limitations.
Partial acceleration may result in slightly higher CPU usage and lower than expected transcoding FPS.
:::
Jellyfin 10.8 managed to support full acceleration on mainstream Intel, NVIDIA and AMD (Windows only) GPUs.
Jellyfin 10.9 enables full acceleration for AMD Vega and newer GPUs on Linux via VA-API and Vulkan interop.
Using our [jellyfin-ffmpeg](https://github.com/jellyfin/jellyfin-ffmpeg/releases) with Jellyfin is highly recommended, which has a `-Jellyfin` suffix in the version string.
```shell
$ /usr/lib/jellyfin-ffmpeg/ffmpeg
ffmpeg version 5.1.2-Jellyfin Copyright (c) 2000-2022 the FFmpeg developers
built with gcc 12.2.0 (crosstool-NG 1.25.0.90_cf9beb1)
...
```
:::caution
Using the ffmpeg binaries downloaded from else where will result in partial acceleration.
Jellyfin-ffmpeg usually ships with our deb package, official Docker images and Windows installers.
The only exception is when using portable installation or a unsupported distro you need to manually download and set it in Jellyfin.
:::
## Configure & Verify Hardware Acceleration
There are some preparations that need to be done before enabling the hardware acceleration.
The specific configuration steps may vary with different GPU vendors, installation methods, and operating systems.
On Linux you can check available GPU using `lspci` command:
```shell
$ lspci -nn | grep -Ei "3d|display|vga"
```
Or using `lshw` command:
```shell
$ lshw -C display
```
### Intel QSV & VA-API
Click [HWA Tutorial On Intel GPU](/docs/general/administration/intel-hwa-tutorial).
### AMD AMF & VA-API
Click [HWA Tutorial On AMD GPU](/docs/general/administration/amd-hwa-tutorial).
### NVIDIA NVENC
Click [HWA Tutorial On NVIDIA GPU](/docs/general/administration/nvidia-hwa-tutorial).
### Raspberry Pi V4L2
:::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 codecs 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).
:::
## Enable 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 the boxes in **Enable hardware decoding for** and **Hardware encoding options** 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.
## Remote Hardware Acceleration
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.
:::note
Currently Linux-only and requires SSH between the machines, as well as shared storage both for media and for the Jellyfin data directory.
:::
## Hardware Accelerated Tone-mapping
Hardware accelerated HDR10, HLG to SDR tone-mapping is supported in Jellyfin.
Dolby Vision (P5 & P8) to SDR tone-mapping is supported in Jellyfin 10.8 and requires jellyfin-ffmpeg 5.0.1-5 or newer.
:::note
Intel VPP HDR10 tone-mapping is supported on Intel QSV and VA-API on Linux.
VPP is prefered when both tone-mapping options are checked on Intel GPU.
:::
| OS/Platform | NVIDIA NVENC | AMD AMF | Intel QSV | Intel VA-API | AMD VA-API | Software |
| -------------- | ------------ | ------- | --------- | ------------ | ---------- | -------- |
| Windows | ✔️ | ✔️ | ✔️ | N/A | N/A | WIP |
| Windows Docker | ✔️ | N/A | N/A | N/A | N/A | WIP |
| Linux | ✔️ | ✔️ | ✔️ | ✔️ | ✔️ | WIP |
| Linux Docker | ✔️ | ✔️ | ✔️ | ✔️ | ✔️ | WIP |
## Tips For Hardware Acceleration
- Avoid H.264 / AVC 10-bit videos
:::tip
The hardware decoding of H.264 / AVC 10-bit (High 10 profile) video is not supported by any Intel, NVIDIA and AMD GPU.
Jellyfin will always fallback to software decoding for it. Consider upgrading such video to H.265 / HEVC 10-bit (Main 10 profile).
:::
- iGPU / APU Prefer dual-channel memory
:::tip
Integrated GPU takes up a portion of system memory as its video memory, which means using dual-channel memory can double the video memory bandwidth. This can be quite useful for compute intensive workloads such as hardware HDR/DV tone-mapping.
:::
- Use SSD or RamDisk for caching
:::tip
On modern GPUs the peak throughput of video transcoding can be limited by the I/O speed of your hard drives. In this case, SSD or RamDisk can be used for caching the transcoded termporary video segments.
:::
- Tune encoder presets to trade off quality for speed
:::tip
Hardware encoder presets can greatly affect encoding speed. You can lower this preset in the Jellyfin dashboard to sacrifice encoding quality to maximize speed, or raise the preset to optimize encoding quality on an overkill GPU.
:::
docs/general/administration/hardware-acceleration/intel-hwa-tutorial.md
+959
View File
@@ -0,0 +1,959 @@
---
uid: admin-hardware-acceleration-intel
title: HWA Tutorial On Intel GPU
---
# HWA Tutorial On Intel GPU
This tutorial guides you setting up full video hardware acceleration on Intel integrated GPU and ARC discrete GPU via QSV and VA-API.
## Acceleration Methods
Hardware accelerated transcoding is supported on most Intel GPUs.
On Windows **QSV** is the only available method.
On Linux there are two methods:
- **QSV** - Prefered on mainstream GPUs, for better performance
- **VA-API** - Required by pre-Broadwell legacy GPUs, for compatibility
Linux VA-API supports nearly all Intel GPUs.
Linux QSV [supported platforms](https://github.com/intel/media-driver#supported-platforms) are limited to:
- **BDW** (Broadwell)
- **SKL** (Skylake)
- **BXTx** (BXT: Broxton, APL: Apollo Lake, GLK: Gemini Lake)
- **KBLx** (KBL: Kaby Lake, CFL: Coffe Lake, WHL: Whiskey Lake, CML: Comet Lake, AML: Amber Lake)
- **ICL** (Ice Lake)
- **JSL** (Jasper Lake) / **EHL** (Elkhart Lake)
- **TGLx** (TGL: Tiger Lake, RKL: Rocket Lake, ADL-S/P/N: Alder Lake, RPL-S/P: Raptor Lake)
- **DG1**/**SG1**
- Alchemist(**DG2**)/ATSM
- Meteor Lake(**MTL**)
- Future platforms...
The QSV interface comes from Intel [OneVPL](https://github.com/oneapi-src/oneVPL) / [MediaSDK](https://github.com/Intel-Media-SDK/MediaSDK) is a high-level implementation based on Linux VA-API and Windows DXVA/D3D11VA, which gives better performance and more fine-tuning options on supported platforms.
QSV can be used together with VA-API and DXVA/D3D11VA for a more flexible hybrid transcoding pipeline.
:::note
Unlike NVIDIA NVENC, there is no concurrent encoding sessions limit on Intel iGPU and ARC dGPU.
QSV 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 Intel 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 OpenCL runtime sometimes need to be manually installed on Linux.
2. **QSV VPP**
- Pros - Lower power consumption, realized by Intel fixed-function LUT hardware.
- Cons - Poor tuning options, limited supported GPU models, currently only available on Linux.
## Select GPU Hardware
:::caution
Rule out the model of Intel processors that ending in "F", which means it has no integrated GPU.
:::
Best to check Quick Sync Video support via the [Intel ark website](https://ark.intel.com/content/www/us/en/ark.html) before buying a new GPU for hardware acceleration.
### Transcode H.264
AVC / H.264 8-bit is still widely used due to its excellent compatibility. All Intel GPUs that support QSV can decode and encode it.
- **Decoding & Encoding H.264 8-bit** - Any Intel GPU that supports Quick Sync Video (QSV)
### 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.
No exception for Intel GPUs:
- **Decoding & Encoding HEVC 8-bit** - Gen 9 Sky Lake (6th Gen Core) and newer
- **Decoding & Encoding HEVC 10-bit** - Gen 9.5 Kaby Lake (7th Gen Core), Apollo Lake, Gemini Lake (Pentium and Celeron) and newer
:::note
Note that the 6th Gen Core lacks 10-bit support, it's best to choose 7th Gen and newer processors, which usually have HD / UHD 6xx series iGPU.
:::
### 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.
Intel added support for AV1 acceleration in their latest GPUs:
- **Decoding AV1 8/10-bit** - Gen 12 Tiger Lake (11th Gen Core) and newer
- **Encoding AV1 8/10-bit** - Gen 12.5 DG2 / ARC A-series, Gen 12.7 Meteor Lake (14th?? Gen Core) and newer
### Transcode Other Codecs
Please refer to these links:
- [Intel Media Capabilities documentation](https://www.intel.com/content/www/us/en/develop/documentation/media-capabilities-of-intel-hardware/top.html)
- [Linux media-driver/iHD capabilities](https://github.com/intel/media-driver#decodingencoding-features)
- [Linux vaapi-driver/i965 capabilities](https://github.com/intel/intel-vaapi-driver/blob/master/README)
### Speed And Quality
Intel improves the speed and video quality of its fixed-function encoders between each generation of graphics architectures.
They can be divided into 4 tiers by their performance：
- **Entry-Level** - HD / UHD 500, 600, 605 and 61x
:::tip
These iGPUs usually come from mini PC boxes or Synology NAS and they can transcode HEVC 10-bit and apply tone-mapping filters. You can't expect much due to performance and power constraints, but it's still adequate for personal use.
:::
- **Mainstream** - HD / UHD 620, 630, Iris 640, 655 and the Gen 11 graphics
:::tip
These iGPUs have more computing power than entry-level, which makes them capable of multiple 4k HDR HEVC 10-bit transcoding at the same time. Note that the Gen 11 graphics has improved encoder quality over Gen 9 but not too much.
:::
- **High-Performance** - UHD 7xx series and Iris Xe graphics
:::tip
These GPUs use Gen 12 XeLP architecture with [significantly improved video quality and speed](https://github.com/intel/media-delivery/blob/master/doc/benchmarks/intel-iris-xe-max-graphics/intel-iris-xe-max-graphics.md). Models like the UHD 770 and Iris Xe feature a second MFX video engine, which enhances its concurrent transcoding capabilities.
:::
- **Hardcore** - ARC A-series discrete GPU
:::tip
ARC A-series GPU uses the latest Gen 12.5 XeHPG architecture, which continues to improve on the basis of XeLP, supports [AV1 hardware encoding and improved H.264 and HEVC encoding](https://github.com/intel/media-delivery/blob/master/doc/benchmarks/intel-data-center-gpu-flex-series/intel-data-center-gpu-flex-series.rst). This makes it competitive with the medium preset of the x264 and x265 software encoders. All ARC A-series GPU models comes with two MFX video engines.
:::
### OneVPL And MediaSDK
[OneVPL](https://github.com/oneapi-src/oneVPL) is a new QSV implementation to supersede [MediaSDK](https://github.com/Intel-Media-SDK/MediaSDK). Both provide Quick Sync Video (QSV) runtime.
Intel supports OneVPL on Gen 12+ graphics (11th Gen Core and newer processor, namly Tiger Lake & Rocket Lake).
:::note
The most notable difference is that OneVPL supports new AV1 hardware encoder on ARC GPU.
[FFmpeg 6.0](http://ffmpeg.org/download.html#release_6.0) enables OneVPL and this process is seamless for the end users.
:::
### ARC GPU Support
Jellyfin server 10.8.9+ and the latest jellyfin-ffmpeg5 support Intel ARC discrete GPU on both Windows and Linux 6.2+.
You only need to follow the [Windows Setups](/docs/general/administration/hardware-acceleration/intel-hwa-tutorial#windows-setups) and [Linux Setups](/docs/general/administration/hardware-acceleration/intel-hwa-tutorial#linux-setups) to configure and verify it.
:::tip
Tips for ARC GPU:
- [Reizeable-BAR](https://game.intel.com/story/intel-arc-graphics-resizable-bar/) is not mandatory for hardware acceleration, but it can affect the performance of VPP tone-mapping.
It's recommended to enable the Resizable-BAR if the processor, motherboard and BIOS support it.
- [ASPM](https://www.intel.com/content/www/us/en/support/articles/000092564/graphics.html) can be enabled in the supported BIOS, which greatly reduces the idle power consumption of the ARC GPU.
- Low-Power encoding is used by default on ARC GPU. **GuC & HuC firmware can be missing on non-rolling release distros**.
- Old kernel build configs [may not have the MEI modules enabled](https://gitlab.freedesktop.org/drm/intel/-/issues/7732), which is necessary for using ARC GPU on Linux.
:::
## Windows Setups
Windows 10 64-bit and newer is recommeded. **QSV 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-6th Gen Intel processor without doing a fresh installation.
2. Clean install the latest EXE or INF driver from [Intel download center](https://www.intel.com/content/www/us/en/download-center/home.html).
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 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/<VERSION>/jellyfin-ffmpeg_<VERSION>_portable_linux64-gpl.tar.xz
$ tar -xvf jellyfin-ffmpeg_<VERSION>_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 <JELLYFIN_POD_NAME> -- /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 <CONTAINER_NAME> gpu gpu gid=<GID_OF_HOST_RENDER_OR_VIDEO_GROUP>
```
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/<CONTAINER_ID>.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)
:::
docs/general/administration/hardware-acceleration/nvidia-hwa-tutorial.md
+471
View File
@@ -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/<VERSION>/jellyfin-ffmpeg_<VERSION>_portable_linux64-gpl.tar.xz
$ tar -xvf jellyfin-ffmpeg_<VERSION>_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 |
+-----------------------------------------------------------------------------+
```
static/images/docs/hwa-amd-taskmgr.png
BIN
View File
Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 75 KiB

static/images/docs/hwa-gpedit-mstsc.png
BIN
View File
Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 499 KiB

static/images/docs/hwa-intel-taskmgr.png
BIN
View File
Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 80 KiB

static/images/docs/hwa-nvidia-taskmgr.png
BIN
View File
Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 82 KiB