Docker에서 Jellyfin NVIDIA 하드웨어 트랜스코딩 설정
호스트 드라이버와 NVIDIA Container Toolkit부터 Docker Compose GPU 할당까지 4단계로 설정하고, NVENC와 NVDEC를 켠 뒤 nvidia-smi로 실제 트랜스코딩을 검증합니다.
구축할 내용
NVIDIA GPU에서 Jellyfin 하드웨어 트랜스코딩을 구성하는 과정은 정해진 순서에 따른 4단계이며, 마지막 단계에서만 Jellyfin 내부 설정을 변경한다. 호스트에서 드라이버를 로드하지 않았다면 컨테이너는 GPU를 볼 수 없다. 컨테이너에서 GPU를 볼 수 없다면 Jellyfin은 GPU를 사용할 수 없다. 이 순서대로 진행하면 각 오류를 확인할 위치가 명확해진다.
- 호스트에 NVIDIA 드라이버를 설치한 다음
nvidia-smi으로 확인한다. - Docker가 컨테이너에 GPU를 전달할 수 있도록 NVIDIA Container Toolkit을 설치한다.
docker-compose.yml에서 Jellyfin 서비스에 GPU를 할당한 다음 컨테이너에서 GPU가 보이는지 확인한다.- Jellyfin 자체의 재생 설정에서 NVENC와 NVDEC를 활성화한 다음 실제 재생에서 해당 기능이 사용되는지 확인한다.
NVENC (NVIDIA encoder)와 NVDEC (NVIDIA decoder)는 GPU 카드에 있는 고정 기능 블록이다. 이 블록은 CUDA (compute unified device architecture) 작업을 실행하는 셰이더 코어와 별도의 실리콘으로 구성된다. 이 분리가 이 구성을 사용하는 핵심 이유다. 소프트웨어 방식으로 여러 CPU 코어를 사용하는 스트림이 CPU 코어 1개의 일부와 GPU의 전용 하드웨어 블록만 사용하게 된다.
Direct play가 모든 트랜스코딩보다 우선하므로 먼저 확인해야 한다
이 설정을 구성하기 전에 단순히 제거할 수 있는 이유로 트랜스코딩이 발생하는지 확인한다. Jellyfin은 클라이언트가 파일을 원본 그대로 재생할 수 없을 때 트랜스코딩한다. 원인은 거의 항상 몇 가지 중 하나다. 비디오 코덱, 오디오 코덱, 컨테이너 형식, 이미지 기반 자막, 클라이언트가 요청한 bitrate 제한, 또는 클라이언트가 보고한 해상도나 기타 제약 조건이다.
Dashboard를 연 다음 Playback으로 이동하고, 무언가를 재생하는 동안 활성 세션을 확인한다. Direct playing으로 표시된 세션은 파일을 변경하지 않고 전송하므로 CPU를 거의 사용하지 않는다. Transcoding으로 표시된 세션에는 Jellyfin이 선택한 이유가 표시된다. 그 이유를 제거하면 GPU를 전혀 사용할 필요가 없다.
대부분의 트랜스코딩은 2가지 변경으로 제거할 수 있다. 클라이언트 앱의 화질을 Auto 또는 최댓값으로 설정한다. 클라이언트가 4 Mbps를 요청하면 파일이 어떤 코덱을 사용하든 20 Mbps 파일을 다시 인코딩해야 하기 때문이다. 그런 다음 브라우저 탭 대신 native client app을 사용한다. 브라우저는 사용자가 가진 플레이어 중 제약이 가장 많으며, 같은 TV의 native app에서는 동일한 파일이 Direct playing으로 재생되는 경우가 많다.
이미지 기반 자막은 클라이언트가 직접 렌더링할 수 없을 때만 비디오에 구워 넣어야 한다. Blu-ray rip의 PGS 자막과 DVD rip의 VOBSUB은 이미지이지만, 호환되는 클라이언트에서는 비디오를 다시 인코딩하지 않고 표시할 수 있다. Jellyfin의 Android integrated player는 PGS를 직접 지원한다. SRT의 텍스트 자막은 클라이언트가 지원하는 경우 별도로 전송된다. 자막 호환성 때문에 burn-in이 발생한다면 자막 트랙을 텍스트로 변환하는 것이 유용하다. 서버 측의 나머지 내용은 VPS에서 Jellyfin media server를 운영하는 가이드에서 설명한다.
대부분의 VPS 요금제에는 GPU가 없다
표준 VPS 요금제에는 GPU가 포함되지 않는다. 다른 계획을 세우기 전에 서버에서 다음을 실행한다.
lspci -nn | grep -Ei "3d|display|vga"일반적인 KVM VPS에서는 하이퍼바이저가 제공하는 가상 디스플레이 어댑터가 출력되거나, 유용한 정보가 전혀 출력되지 않는다. 이 장치로는 동영상을 인코딩할 수 없다. 실제 GPU는 제공업체가 물리 GPU를 인스턴스에 패스스루하거나 GPU 일부를 할당하는 경우에만 사용할 수 있으며, 이러한 요금제는 그에 맞게 가격이 책정된다. GPU VPS에 비용을 지불할 만한 워크로드는 무엇인가에서는 GPU가 필요한 경우와 그렇지 않은 경우를 설명한다.
GPU가 없다면 direct play를 목표로 하고 소프트웨어 트랜스코딩은 예외적인 경우로 간주한다. 단일 1080p H.264 소프트웨어 트랜스코딩은 부하가 크지만 CPU 코어 몇 개로 처리할 수 있다. 톤 매핑을 포함한 4K HDR 소프트웨어 트랜스코딩은 소형 VPS에서 실시간으로 처리할 수 없으므로, CPU 사용률이 100 percent에 고정된 상태에서 스트림이 끊긴다.
호스트에 NVIDIA 드라이버 설치
Jellyfin 10.11은 Linux 환경에서 최소 520.56.06 버전의 NVIDIA 드라이버를 요구합니다. 설치된 jellyfin-ffmpeg 빌드에 따라 더 최신 드라이버가 필요할 수 있으며, 드라이버의 NVENC API 버전이 너무 낮으면 트랜스코딩 로그에 최소 요구 사항이 기록됩니다. Ubuntu는 시스템에 적합한 패키지를 자동으로 선택하는 도우미 기능을 제공합니다.
sudo ubuntu-drivers list --gpgpu
sudo ubuntu-drivers install --gpgpu
sudo reboot--gpgpu 명령은 미디어 서버에 적합한 헤드리스 서버용 드라이버를 선택합니다. 서버에는 데스크톱 환경이 없기 때문입니다. 목록 출력 명령을 통해 사용 가능한 브랜치를 확인하고, 예를 들어 sudo ubuntu-drivers install --gpgpu nvidia:570-server와 같이 특정 브랜치를 지정할 수 있습니다. 예시에 적힌 브랜치명이 아니라 목록에 실제로 출력된 브랜치를 사용하십시오.
서버용 드라이버가 항상 nvidia-smi를 자동으로 설치하지는 않습니다. 선택한 브랜치에 맞는 유틸리티 패키지(예: sudo apt install nvidia-utils-570-server)를 설치한 뒤 드라이버 상태를 확인하십시오.
nvidia-smi정상적으로 설치되었다면 헤더에 드라이버 버전과 CUDA 버전이 표시되고 그래픽 카드의 모델명이 나열된 표가 출력됩니다. 프로세스 목록에는 Compute, Graphics 또는 Other GPU 리소스를 사용하는 프로세스가 표시됩니다. 정상적인 GPU라면 목록이 채워져 있을 수 있으며, 목록이 비어 있다면 GPU를 사용하는 프로세스가 없다는 의미입니다. 흔히 발생하는 오류는 두 가지입니다. nvidia-smi: command not found 오류는 드라이버가 아닌 유틸리티 패키지가 누락되었음을 의미합니다. NVIDIA-SMI has failed because it couldn't communicate with the NVIDIA driver 오류는 커널 모듈이 로드되지 않았음을 의미하며, 새로 설치한 직후라면 대부분 재부팅을 하지 않았거나 Secure Boot가 서명되지 않은 모듈 로드를 거부하는 경우입니다. lsmod | grep nvidia 명령으로 모듈이 존재하는지 확인하십시오. 만약 아무것도 출력되지 않고 sudo modprobe nvidia 명령이 Key was rejected by service 오류와 함께 실패한다면, Secure Boot가 모듈을 차단하고 있는 것입니다. Secure Boot 키 거부 해제 문서를 참조하여 펌웨어 상태를 확인하고, 머신 소유자 키(MOK)를 등록하거나 보안 부팅 적용을 해제하십시오.
NVIDIA Container Toolkit 설치
드라이버를 사용하면 호스트에서 GPU를 사용할 수 있다. 그러나 컨테이너에는 디바이스 노드와 드라이버 라이브러리가 없으므로 Docker가 GPU를 컨테이너에 전달하지 못한다. NVIDIA Container Toolkit은 컨테이너 시작 시 이 두 항목을 주입한다. 다음 명령은 Debian과 Ubuntu에 대한 NVIDIA의 공식 설치 절차를 따른다. NVIDIA의 최신 가이드에서는 버전 변수를 사용해 toolkit 패키지를 하나의 릴리스로 고정한다. 여기처럼 고정을 생략하면 저장소의 최신 릴리스가 설치된다.
curl -fsSL https://nvidia.github.io/libnvidia-container/gpgkey | sudo gpg --dearmor -o /usr/share/keyrings/nvidia-container-toolkit-keyring.gpg
curl -s -L https://nvidia.github.io/libnvidia-container/stable/deb/nvidia-container-toolkit.list | sed 's#deb https://#deb [signed-by=/usr/share/keyrings/nvidia-container-toolkit-keyring.gpg] https://#g' | sudo tee /etc/apt/sources.list.d/nvidia-container-toolkit.list
sudo apt-get update
sudo apt-get install -y nvidia-container-toolkit패키지를 설치하는 것만으로는 충분하지 않다. Docker에 해당 runtime이 존재한다고 알려야 한다.
sudo nvidia-ctk runtime configure --runtime=docker
sudo systemctl restart dockernvidia-ctk runtime configure은(는) /etc/docker/daemon.json에 nvidia runtime 항목을 기록한다. 이 단계에서 restart를 생략하는 경우가 많으며, 그러면 이 전체 구성에서 가장 흔한 오류가 발생한다. Jellyfin을 설정하기 전에 연결 구성을 테스트한다.
sudo docker run --rm --runtime=nvidia --gpus all ubuntu nvidia-smi호스트에서 출력한 것과 동일한 표가 출력되어야 한다. 대신 gpu capabilities가 있는 디바이스 드라이버를 선택할 수 없다는 오류가 발생하면 Docker daemon이 nvidia runtime을 인식하지 못하는 것이다. 이 경우 configure 명령을 다시 실행한 다음 daemon을 restart한다.
Docker Compose에서 Jellyfin 컨테이너에 GPU 할당하기
이것이 최신 Compose 형식이다. Jellyfin이 게시한 예제를 기반으로 하며, 2개의 NVIDIA 환경 변수를 명시적으로 작성한다.
services:
jellyfin:
image: jellyfin/jellyfin
container_name: jellyfin
user: 1000:1000
network_mode: host
restart: unless-stopped
environment:
- NVIDIA_VISIBLE_DEVICES=all
- NVIDIA_DRIVER_CAPABILITIES=all
volumes:
- /srv/jellyfin/config:/config
- /srv/jellyfin/cache:/cache
- /srv/media:/media:ro
runtime: nvidia
deploy:
resources:
reservations:
devices:
- driver: nvidia
count: all
capabilities: [gpu]컨테이너를 시작한 다음 컨테이너에 직접 확인을 요청한다.
docker compose up -d
docker compose exec jellyfin nvidia-smi컨테이너 내부에서 드라이버 표가 출력되면 GPU가 보이고 관리 라이브러리가 동작한다는 뜻이다. 비디오 라이브러리와 실제 트랜스코드는 별도로 확인해야 한다.
이 파일의 4줄은 설명이 필요하다. capabilities: [gpu]는 Compose 자체에 필요하다. 이 항목을 생략하면 Compose는 GPU 없이 서비스를 시작하지 않고 서비스를 거부한다. NVIDIA_DRIVER_CAPABILITIES=all도 중요하다. toolkit은 video capability가 요청된 경우에만 비디오 라이브러리를 컨테이너에 마운트하기 때문이다. 이 변수가 설정되지 않으면 기본값은 utility와 compute만 사용한다. 공식 Jellyfin 이미지는 이미 이 변수를 설정하므로, 해당 이미지에서는 다른 설정이 이 값을 덮어쓰지 못하도록 보호하는 역할을 한다. 자체 이미지를 빌드한다면 직접 추가해야 한다고 Jellyfin 문서에 설명되어 있다. video capability가 없으면 CUDA는 동작하지만 NVDEC는 동작하지 않으며, 트랜스코드 로그에는 Cannot load libnvcuvid.so.1가 기록된다. network_mode: host는 Jellyfin 자체 NVIDIA 예제에서 사용하는 설정이다. Jellyfin의 컨테이너 가이드에서는 host networking을 선택 사항으로 설명하지만, DLNA에는 필요하다. 대신 bridge 네트워크를 사용한다면 8096/tcp와 7359/udp auto-discovery 포트를 직접 publish해야 한다.
user: 1000:1000는 마지막 설정이며 GPU와는 관계가 없다. Jellyfin이 media mount에서 읽을 수 있는 파일을 결정한다. 여기서 값이 일치하지 않으면 권한 오류가 아니라 빈 라이브러리로 나타난다. PUID와 PGID가 컨테이너 사용자를 디스크의 파일에 매핑하는 방법에서 번호 체계를 설명한다. 이 번호는 이 서버에서 Docker Compose로 Sonarr 및 Radarr stack 실행하기를 함께 실행할 때 이미 설정한 번호와 같다.
대부분의 튜토리얼에서 여전히 runtime: nvidia를 사용하는 이유
오래된 형식은 대부분의 가이드에 등장하며, 잘못된 형식은 아니다. 이는 역사적인 이유 때문이다. 원래 nvidia-docker2 package는 nvidia이라는 OCI runtime을 등록했으며, 환경 변수 방식은 해당 runtime에서 NVIDIA_VISIBLE_DEVICES를 사용했다. 이 runtime은 --runtime=nvidia으로 선택하거나 Docker의 기본 runtime으로 지정할 수 있었다. Docker 19.03에서는 --gpus flag와 정식 device-request API가 추가되었다. Compose가 이를 지원하기까지는 더 오래 걸렸다. 지원이 추가된 뒤에는 device request가 deploy.resources.reservations.devices 아래에 배치되었다. 대부분의 사용자는 deploy가 Docker Swarm을 의미하던 시기에 이 키를 무시하는 데 익숙해져 있었다.
그 결과 현재는 두 형식이 모두 동작하며, Jellyfin이 공개한 예제에는 두 형식이 함께 포함되어 있다. runtime: nvidia를 유지해도 비용이 들지 않으며, 이전 Compose 버전에서도 파일이 동작한다. runtime: nvidia만 유지하고 deploy block을 제거하는 경우에도 NVIDIA_VISIBLE_DEVICES=all는 유지해야 한다. 이 레거시 방식은 환경 변수를 읽어 주입할 device를 결정하며, 대신 읽을 device request가 없기 때문이다.
Jellyfin에서 NVIDIA 하드웨어 트랜스코딩 활성화
지금까지의 설정만으로는 Jellyfin에 그래픽 카드를 사용하도록 지정되지 않았다. Dashboard에서 Playback으로 이동한 다음 Transcoding을 연다. Hardware acceleration을 Nvidia NVENC로 설정한다. Enable hardware encoding을 선택한다. 이 옵션을 선택하지 않으면 Jellyfin이 GPU에서 디코딩한 뒤 CPU에서 인코딩한다. 그러면 GPU 사용량이 표시되는데도 CPU가 계속 부하를 처리하는 혼란스러운 중간 상태가 된다.
Enable enhanced NVDEC decoder는 현재 NVDEC 경로와 이전 CUVID 경로 사이를 전환한다. 이 옵션은 켜 둔다. Dolby Vision을 처리할 때 NVDEC를 사용하려면 이 옵션이 반드시 켜져 있어야 한다.
Enable hardware decoding for에서는 그래픽 카드가 실제로 디코딩할 수 있는 코덱만 선택한다. 이 설정에서 실수가 자주 발생한다. AV1 디코더가 없는 그래픽 카드에서 AV1을 선택하면 하드웨어 디코딩을 요청한 뒤 Hardware is lacking required capabilities와 함께 실패할 수 있다. 지원되지 않는 항목을 선택해도 소프트웨어 디코딩으로 자동 전환된다는 보장은 없다.
페이지 전체에 적용되는 제약이 하나 더 있다. 하드웨어 가속은 번들로 제공되는 jellyfin-ffmpeg 빌드에서만 완전히 지원된다. Jellyfin 문서에서는 다른 경로에서 가져온 FFmpeg 바이너리를 사용하면 가속이 부분적으로만 동작한다고 경고한다. 따라서 FFmpeg 경로를 시스템 FFmpeg로 지정했다면 원래대로 되돌린다.
GPU 세대에서 디코딩하고 인코딩할 수 있는 코덱
다음은 Jellyfin이 NVENC와 NVDEC에 대해 문서화한 지원 범위입니다. 디코딩과 인코딩은 별개의 기능이므로, 그래픽 카드에 한쪽 기능만 있을 수 있습니다.
- H.264 8-bit: NVENC와 NVDEC를 모두 탑재한 모든 NVIDIA GPU에서 디코딩과 인코딩을 모두 지원합니다.
- HEVC 8-bit: Maxwell second generation (GM206) 이상에서 디코딩과 인코딩을 지원합니다.
- HEVC 10-bit: Maxwell second generation 이상에서 디코딩을 지원합니다. 다만 해당 세대에서는 GM206 변형만 지원하며, 인코딩은 Pascal 이상에서만 지원합니다.
- AV1: GA100 data center chip을 제외한 Ampere 이상에서 디코딩을 지원합니다. 단, NVIDIA의 디코더 표에는 AV1 디코딩을 지원하지 않는 Hopper도 기재되어 있습니다. 인코딩은 Ada Lovelace 이상에서 지원하며, Jellyfin에서는 10.9부터 지원합니다.
실제로 가장 문제가 되는 부분은 HEVC 10-bit의 지원 분리입니다. GM206 기반 Maxwell 카드는 GPU에서 4K HDR 파일을 디코딩할 수 있지만 10-bit 출력은 인코딩할 수 없습니다. 그러나 8-bit H.264와 8-bit HEVC 인코딩은 모두 지원합니다. 다른 Maxwell 칩은 하드웨어에서 HEVC 10-bit 디코딩을 전혀 지원하지 않습니다. Jellyfin은 클라이언트의 기능과 인코딩 설정에 따라 출력 코덱을 선택합니다. Jellyfin의 HEVC 트랜스코딩 경로는 8-bit Main 프로파일을 강제로 사용합니다. AV1 출력을 지원하는 클라이언트에만 AV1 출력을 선택해야 합니다.
톤 매핑이 조용히 GPU를 다시 포화시키는 이유
HDR(high dynamic range)을 SDR(standard dynamic range)로 변환하는 톤 매핑은 GPU 예산을 소진시키는 설정이다. 그 이유는 아키텍처에 있다. 디코딩은 NVDEC에서 실행된다. 인코딩은 NVENC에서 실행된다. 톤 매핑은 둘 다 사용하지 않는다. 톤 매핑은 셰이더 코어에서 실행되는 CUDA 필터다. 셰이더 코어는 컴퓨팅 작업을 처리하는 GPU의 범용 부분이다. 따라서 톤 매핑이 필요한 4K HDR 스트림은 디코더와 인코더를 사용하고, 여기에 셰이더까지 로드한다.
Jellyfin 문서에서는 HEVC 10-bit를 디코딩할 수 있는 모든 NVIDIA GPU에서 CUDA 톤 매핑을 사용할 수 있다고 설명한다. 따라서 4K에서 톤 매핑을 지속적으로 처리할 수 없는 카드에서도 해당 확인란이 표시되고 동작한다. 증상은 스트림이 시작된 뒤 버퍼링을 반복하고 안정되지 않는 것이다. 이때 nvidia-smi에서는 인코더 사용량이 거의 없는 것으로 표시된다.
따라서 셰이더 부하는 별도로 확인해야 한다.
nvidia-smi dmon -s u이 명령은 초당 1줄을 출력하며 sm, enc, dec을 별도 열로 표시한다. enc와 dec은 낮고 sm 수치가 높다면 고정 기능 블록이 아니라 셰이더가 원인일 가능성이 높다. 따라서 톤 매핑, 스케일링 또는 자막 번인이 주요 비용일 수 있다. 다만 이는 단서일 뿐 확정적인 증거는 아니다. NVIDIA는 GPU 사용률을 샘플링 기간 중 하나 이상의 커널이 실행된 시간의 비율로 정의한다. 따라서 수치가 높다는 것은 셰이더가 사용 중이었다는 뜻이지, 셰이더가 포화되었다는 뜻은 아니다. CUDA 경로는 Dolby Vision profile 5도 zero copy로 처리한다. zero copy가 없으면 필터 단계 사이에서 프레임이 system memory로 나갔다가 다시 돌아오기 때문이다. 이 왕복에는 모든 프레임마다 대역폭 비용이 발생한다.
consumer NVENC 세션 제한이 실제로 제한하는 것
이 차트의 데이터
[
{
"label": "GeForce RTX 5090",
"nvenc_engines": 3,
"max_encode_sessions": 12
},
{
"label": "GeForce RTX 4090",
"nvenc_engines": 2,
"max_encode_sessions": 12
},
{
"label": "GeForce RTX 4060",
"nvenc_engines": 1,
"max_encode_sessions": 12
}
]위 수치는 이 환경에서 측정한 값이 아니라, 2026년 10월 기준 NVIDIA가 공개한 매트릭스 수치다. NVIDIA 정책에 따라 한 시스템의 모든 GeForce 카드에서 동시에 실행할 수 있는 인코딩 세션 수는 모델과 관계없이 합산 12개로 제한된다. 이 제한은 실리콘이 아니라 드라이버에 적용된다. NVIDIA는 수년 동안 이 값을 여러 차례 상향했으므로 오래된 포럼 글보다 현재 매트릭스를 확인해야 한다. 카드에 따라 실제로 달라지는 부분은 엔진 수다. GeForce RTX 5090에는 3개의 NVENC 엔진이 있고, GeForce RTX 4060에는 1개가 있다. 엔진 수가 많으면 병렬 인코딩 처리량이 증가할 뿐, 세션 상한이 높아지는 것은 아니다.
이 제한은 Jellyfin 외부에서 실행되는 비디오 인코딩을 포함해 인코딩 세션 수를 계산한다. Direct play와 remuxing은 인코딩 세션을 열지 않는다. L4 같은 데이터 센터 카드는 같은 매트릭스에서 제한 없음으로 표시된다. 그러나 A100과 H100 같은 모델에는 NVENC 인코더가 없으므로 GPU VPS 요금제에서는 정확한 카드 모델을 확인해야 한다.
제한에 도달하면 트랜스코딩이 실패하고 FFmpeg 로그에 OpenEncodeSessionEx failed: out of memory (10)이 표시된다. 이 메시지는 메모리를 언급하지만, 세션 제한 거부에도 같은 코드가 표시된다. 따라서 VRAM 누수를 찾기 전에 동시 스트림 수를 확인해야 한다. 실제로는 대부분 세션 12개에 도달하기 훨씬 전에 톤 매핑 상한이나 업로드 대역폭 제한에 먼저 도달한다.
GPU가 transcoding을 수행하는지 확인하고 설정을 그대로 믿지 마십시오
저장된 설정은 증거가 아닙니다. transcoding을 강제로 수행하는 파일을 재생한 다음 3가지를 확인합니다.
- Dashboard를 열고 Playback으로 이동합니다. 활성 세션에 Transcoding이라고 표시되고 그 이유가 함께 나와야 합니다. Direct playing이라고 표시되면 transcoding이 수행되지 않는 것이므로 잘못된 파일을 테스트하고 있습니다.
- Dashboard를 열고 Logs로 이동한 다음 최신
FFmpeg.Transcodelog를 엽니다. 완전한 hardware transcode가 수행되면 명령줄에-hwaccel cuda와-hwaccel_output_format cuda가 표시됩니다. 또한h264_nvenc또는hevc_nvenc같은 NVENC encoder가 표시되거나, Ada Lovelace 이상에서는 AV1 NVENC encoder가 표시됩니다. 여기에libx264가 표시되면 설정 페이지의 주장과 관계없이 encode가 software에서 실행되고 있는 것입니다. NVENC encoder는 있지만-hwaccel cuda가 없으면 decode가 software에서 실행되는 상태입니다. - 재생을 계속하면서 host에서
nvidia-smi을 실행합니다./usr/lib/jellyfin-ffmpeg/ffmpeg의 process가 GPU memory를 할당한 상태로 표시되어야 하며,nvidia-smi dmon -s u에는 enc 및 dec column이 0이 아닌 값으로 표시되어야 합니다.
세 번째 확인은 container 내부가 아니라 host에서 실행합니다. container 내부에서 nvidia-smi을 실행하면 일반적으로 자체 namespace 외부의 process ID를 볼 수 없으므로 process list가 비어 있습니다. 반면 utilisation 수치는 정상적으로 표시됩니다. container 내부의 빈 process list는 오류가 아닙니다.
소프트웨어로 자동 전환되는 경우
Jellyfin은 하드웨어 인코딩이 비활성화되었거나 요청한 하드웨어 인코더를 사용할 수 없을 때 소프트웨어 인코더를 선택한다. 재생 중 하드웨어 경로에서 오류가 발생하면 스트림 자체가 실패할 수 있으므로, 모든 오류가 소프트웨어로 전환된다고 가정하지 말고 FFmpeg 로그를 확인한다.
트랜스코딩 로그의 Cannot load libnvcuvid.so.1는 동적 로더가 디코더 라이브러리를 로드하지 못했다는 의미다. 이 메시지만으로는 라이브러리가 마운트되었는지 확인할 수 없다. NVIDIA_DRIVER_CAPABILITIES=all와 컨테이너의 드라이버 라이브러리 및 동적 링크를 확인한다. 환경을 변경했다면 docker compose up -d으로 컨테이너를 다시 생성한다. 단순히 재시작하면 기존 설정이 유지된다.
h264_nvenc의 No capable devices found은 FFmpeg이 인코더 라이브러리에 도달했지만 사용할 수 있는 카드를 찾지 못했다는 의미다. docker compose exec jellyfin nvidia-smi를 다시 확인한 다음, 장치 및 인코더 기능 관련 오류가 있는지 앞선 로그 메시지를 확인한다.
GPU 사용량은 낮은데 CPU 사용량이 높다면 어떤 단계가 소프트웨어를 사용하는지 확인해야 한다. 사용 중인 GPU 세대가 디코딩할 수 없는 코덱의 선택을 해제한 다음 같은 파일을 다시 재생하고 FFmpeg 로그에서 -hwaccel cuda가 나타나는지 다시 확인한다. 해당 메시지가 나타나고 CPU 사용량도 여전히 높다면 Jellyfin이 GPU에서 처리하지 못하는 단계를 찾는다. 예를 들어 이미지 자막을 영상에 굽는 작업이 해당할 수 있다.
1080p는 정상인데 4K HDR 트랜스코딩이 시작된 후 멈춘다면 일반적으로 설치가 손상된 것이 아니라 tone mapping의 한계다. nvidia-smi dmon -s u에서 sm 열을 확인한 다음 tone mapping을 끈 상태로 같은 파일을 다시 재생한다. 스트림이 안정되면 tone mapping이 한계 원인이었던 것이다. 그런 다음 클라이언트가 요청하는 해상도를 낮추거나, 4K HDR 파일을 direct play할 수 있는 클라이언트에서 재생한다.
FAQ
NVENC를 활성화했는데도 Jellyfin이 CPU를 계속 사용하는 이유는 무엇입니까?
Dashboard, Logs에서 최신 FFmpeg.Transcode 로그를 확인합니다. libx264이 표시되면 인코딩이 소프트웨어로 실행 중입니다. -hwaccel cuda도 누락되어 있으면 명령에서 선택한 디코더를 확인하고 docker compose exec jellyfin nvidia-smi를 실행하여 GPU가 인식되는지 확인합니다. -hwaccel cuda이 libx264 옆에 표시되면 명령이 GPU 디코딩과 소프트웨어 인코딩을 요청한 상태입니다. Enable hardware encoding이 활성화되어 있는지, Jellyfin이 요청한 하드웨어 인코더를 감지하는지 확인합니다. 플래그만으로는 GPU 디코딩이 성공했다는 것을 확인할 수 없습니다. h264_nvenc이 -hwaccel cuda 없이 표시되면 파일의 코덱이 Enable hardware decoding for에서 선택되어 있는지 확인합니다. 카드가 디코딩할 수 없는 코덱을 선택하면 소프트웨어 폴백 대신 하드웨어 디코더 오류가 발생할 수 있습니다. 두 항목이 모두 있는데도 CPU 사용량이 높다면 자막 번인처럼 CPU에서 계속 처리되는 단계에서 부하가 발생하는 것입니다.
Docker Compose에서 runtime: nvidia 줄이 여전히 필요합니까?
deploy.resources.reservations.devices 블록과 최신 Docker Compose를 사용한다면 필요하지 않습니다. 이 블록은 최신 장치 요청 형식이며 동일한 작업을 수행합니다. runtime: nvidia은 nvidia-docker2 시절부터 사용된 이전 경로입니다. 현재도 작동하며 Jellyfin의 공식 게시 예제에도 두 방식이 모두 포함되어 있습니다. 두 방식을 모두 유지해도 문제는 없습니다. runtime: nvidia만 유지하는 경우에는 NVIDIA_VISIBLE_DEVICES=all도 유지해야 합니다. 해당 경로에는 읽어 올 장치 요청이 없으며 환경에서 장치 목록을 가져오기 때문입니다.
NVIDIA GPU 1개로 동시에 트랜스코딩할 수 있는 스트림 수는 몇 개입니까?
NVIDIA가 공개한 정책에 따르면 2026년 10월 기준으로 GeForce 카드는 시스템 전체에서 동시에 실행되는 인코딩 세션을 12개로 제한합니다. L4 같은 데이터 센터 카드는 제한 없음으로 분류되어 있으며, 일부 데이터 센터 모델에는 NVENC 인코더가 없습니다. 그러나 이 제한에 도달하기 전에 다른 요인으로 중단되는 경우가 대부분입니다. HDR에서 SDR로의 톤 매핑은 NVENC가 아니라 셰이더 코어에서 실행되므로 별도의 성능 제한이 추가됩니다. nvidia-smi dmon -s u로 직접 측정하고 세션 수가 아니라 sm 열을 모니터링합니다.
GPU가 없는 VPS에서 하드웨어 트랜스코딩을 사용할 수 있습니까?
사용할 수 없습니다. 인코딩에는 물리적 NVENC 블록이 필요하며, 일반 VPS에서 lspci -nn | grep -Ei "3d|display|vga"을 실행하면 하이퍼바이저가 제공하는 가상 디스플레이 어댑터만 표시됩니다. GPU가 없는 요금제에서는 트랜스코딩 자체를 없애는 것이 현실적인 방법입니다. 클라이언트의 화질 설정을 Auto로 높이고, 브라우저 대신 네이티브 클라이언트 앱을 사용합니다. 또한 이미지 기반 자막을 직접 렌더링하는 클라이언트를 사용하거나, 자막 호환성 때문에 번인이 필요하면 자막을 텍스트로 변환합니다.
1080p 트랜스코딩은 정상인데 4K HDR이 끊기는 이유는 무엇입니까?
두 작업은 GPU의 서로 다른 부분을 사용합니다. 1080p SDR 트랜스코딩은 주로 디코딩과 인코딩으로 구성됩니다. 카드가 해당 코덱을 지원하면 두 작업 모두 고정 기능 하드웨어에서 처리됩니다. 여기에 스트림에 필요한 스케일링, 디인터레이싱 또는 자막 번인이 추가됩니다. 4K HDR 스트림에는 셰이더 코어에서 실행되는 CUDA 필터인 톤 매핑과 훨씬 큰 프레임을 스케일링하는 작업이 추가됩니다. nvidia-smi dmon -s u에서 enc와 dec는 낮고 sm은 높은 것으로 표시된다면 이 원인일 가능성이 높습니다. 고정 기능 블록의 부하는 낮지만 셰이더가 바쁘기 때문입니다. 톤 매핑을 끈 상태로 파일을 재생하면 원인을 확인할 수 있습니다.