Як налаштувати Jellyfin з hardware transcoding в Docker на Intel Quick Sync

Що має працювати на хості до запуску контейнера

До старту Jellyfin хостова система повинна віддавати Intel GPU через /dev/dri. Якщо каталогу або вузлів пристроїв немає, у контейнер передавати нічого. Тоді Jellyfin hardware transcoding не запуститься незалежно від налаштувань у веб-інтерфейсі.

Перевірка проста:

ls -l /dev/dri
lspci | grep -i vga
uname -a

На Intel зазвичай потрібен робочий DRM-стек у ядрі Linux. Для більшості дистрибутивів цього достатньо з коробки, але в мінімальних серверних збірках часто бракує користувацьких бібліотек для VAAPI. Саме тут багато хто даремно шукає проблему в Docker, хоча контейнер лише успадковує стан хоста.

Ще один практичний момент: якщо на хості вже крутиться Plex, Frigate або інший контейнер, що активно використовує той самий iGPU, Quick Sync не ламається автоматично, але під навантаженням починається конкуренція за відеодвигун. Для одного-двох паралельних стрімів це терпимо. Далі краще дивитися на реальну телеметрію, а не на сам факт наявності iGPU.

Docker Compose з доступом до /dev/dri

У контейнер треба передати пристрій /dev/dri і не зламати права доступу. Найпростіше – пробросити вузол пристрою та додати контейнер до групи, яка має доступ до рендер-пристрою. Без цього Jellyfin бачить опцію апаратного транскодування, але реально не може відкрити пристрій.

services:
  jellyfin:
    image: jellyfin/jellyfin
    container_name: jellyfin
    network_mode: bridge
    ports:
      - "8096:8096"
    volumes:
      - ./config:/config
      - ./cache:/cache
      - /srv/media:/media:ro
    devices:
      - /dev/dri:/dev/dri
    group_add:
      - "44"
      - "109"
    restart: unless-stopped

Числа в group_add – не універсальні. На одному хості render матиме один GID, на іншому інший. Їх треба звіряти локально:

getent group render
getent group video
ls -l /dev/dri

Якщо контейнер запускається не від root, права стають ще важливішими. У такій схемі краще спочатку добитися доступу до /dev/dri, а вже потім закручувати гайки через PUID, PGID або кастомного користувача. Інакше діагностика перетворюється на полювання на два різні класи помилок одразу.

Де вмикається Jellyfin hardware transcoding

Після старту контейнера Jellyfin hardware transcoding вмикається вже у веб-інтерфейсі сервера. Потрібно перейти в налаштування відтворення і вибрати Intel-сумісний метод апаратного прискорення. На Linux найчастіше це VAAPI; залежно від збірки та середовища може бути доступний і QSV.

Практичне правило просте: якщо контейнер стабільно бачить /dev/dri/renderD*, починати варто з VAAPI. QSV інколи працює не гірше, але в Docker-сценаріях додатковий шар абстракції рідко щось спрощує. У homelab VAAPI зазвичай дає коротший шлях до робочого результату.

Увімкнути потрібно не все підряд, а лише ті кодеки й операції, які реально підтримує хостовий iGPU. Надмірно агресивний набір галочок часто призводить до дивних падінь на окремих файлах: один H.264 потік іде нормально, наступний HEVC з субтитрами – вже ні. Коли потрібна стабільність, краще почати з базового набору, потім розширювати.

Як перевірити, що Intel Quick Sync справді працює

Ознака коректної роботи – під час відтворення сервер не забиває CPU, а в логах і на рівні процесів видно використання GPU-шляху. Перевіряти краще на файлі, який точно змусить сервер транскодувати відео, а не робити direct play.

1. Запустити відтворення файлу з клієнта, який не підтримує початковий формат або обмежений бітрейтом.
2. Відкрити dashboard Jellyfin і перевірити, що потік позначено як transcoding.
3. На хості подивитися завантаження CPU і GPU.

docker logs -f jellyfin
top
intel_gpu_top

Якщо intel_gpu_top показує активність відеодвигуна, а CPU не впирається в стелю, Jellyfin hardware transcoding працює як треба. Коли CPU росте, а GPU мовчить, сервер або впав у software transcoding, або зламався на проміжному етапі – наприклад, декодить апаратно, але кодує вже процесором.

Окремо варто перевірити сценарій із субтитрами. Саме тут багато акуратних конфігів раптом втрачають сенс: burn-in субтитрів часто тягне зайву обробку, і частина навантаження повертається на CPU. Для компактного homelab-сервера це різниця між одним стабільним потоком і кількома.

Чому /dev/dri є, але транскодування не працює

Наявність /dev/dri в контейнері ще не гарантує успіху. Типові проблеми – неправильні права, відсутні бібліотеки VAAPI в образі, конфлікт між користувачем контейнера і групою render, або невідповідний метод прискорення в налаштуваннях самого Jellyfin.

Проблема з правами доступу

Найчастіший сценарій: контейнер бачить вузли пристроїв, але не може їх відкрити.

docker exec -it jellyfin sh
ls -l /dev/dri
id

Якщо користувач усередині контейнера не входить у групу з доступом до renderD*, Jellyfin hardware transcoding не підніметься.

Проблема не в Docker, а в хості

Коли драйверний стек на хості поламаний, контейнер це не виправить. Особливо часто таке буває після оновлень ядра, міграції на нову платформу або при спробі запускати сервер у віртуалці без коректного passthrough iGPU.

Невдалий профіль транскодування

Не всі формати однаково добре проходять через Intel Quick Sync. Додаються субтитри, HDR-to-SDR tone mapping, нестандартний контейнер – і сервер раптом переключається на змішаний режим. Формально апаратне прискорення увімкнене, фактично виграш мінімальний.

Де межа цього підходу в homelab

Для домашнього медіасервера Intel Quick Sync у Docker закриває типовий сценарій дуже добре: кілька клієнтів, різні профілі відтворення, мінімум ручного тюнінгу. Але це рішення не безмежне. Коли бібліотека важка, клієнти постійно тягнуть 4K, а частина потоку йде з burn-in субтитрів, вузьким місцем стає вже не Docker, а сам iGPU.

Тут корисно дивитися не на рекламну обіцянку апаратного кодування, а на реальний профіль медіатеки. Якщо більшість клієнтів підтримує direct play, Jellyfin hardware transcoding потрібен радше як страховка. Якщо ж сервер постійно змінює кодек, бітрейт і контейнер, тоді вибір CPU та покоління Intel graphics починає важити більше, ніж акуратність compose-файлу.

У невеликому homelab цей підхід виправданий. Для більш агресивного сценарію іноді простіше зменшити кількість транскодувань на рівні бібліотеки, ніж нескінченно тюнити контейнер.

Офіційні сторінки

Для звірки налаштувань і актуальної поведінки сервера варто тримати під рукою офіційний сайт Jellyfin і репозиторій контейнерних образів jellyfin/jellyfin.