Jellyfin 12.0 정식 출시: 버전 번호 건너뛴 이유부터 업그레이드 전 필수 체크리스트까지

한눈에 보는 요약

Jellyfin이 10.12.0이 아닌 12.0이라는 이름으로 새 안정 버전을 내놓았습니다. 이름만 바뀐 게 아니라, 10.11에서 진행한 데이터베이스 전환을 발판 삼아 라이브러리 탐색 성능을 끌어올리고 두 가지 큰 기능(에피소드 다중 버전, 서버 내장 도서·만화 지원)을 추가한 릴리스입니다.

핵심만 먼저 정리하면 이렇습니다.

성능: 재생목록·컬렉션 항목을 개별 DB 행으로 저장 → 큰 목록에서 개수 조회·페이지네이션·항목 편집이 빨라짐
기능: 에피소드 다중 버전 그룹화, Bookshelf 플러그인 기능의 서버 통합
UI: 데스크톱·모바일 기본 레이아웃이 Modern으로 전환
미디어 처리: FFmpeg 8.1 기반, Dolby Vision·자막·기기 호환성 개선
주의: 보안 수정 포함이지만 호환성이 깨지는 변경이 많음 — 백업 없이 올리면 곤란해집니다

업그레이드는 10.10.7 또는 10.11.x에서만 지원합니다. 그보다 오래된 버전이라면 먼저 10.10.7로 올린 뒤 12.0으로 가야 합니다.

1. 업그레이드 전 반드시 확인할 것

이번 릴리스는 "일단 올리고 문제 생기면 롤백"이 통하지 않습니다. 첫 실행 시 데이터베이스 스키마 변경과 데이터 재작성이 일어나기 때문입니다.

백업은 선택이 아니라 필수

Jellyfin 서버를 중지합니다.
데이터·설정 디렉터리를 전체 수동 백업합니다.
그 다음에 업그레이드를 진행합니다.

마이그레이션이 시작된 뒤에는 절대 서버를 중지하면 안 됩니다. 중간에 끊으면 데이터가 어중간한 상태로 남습니다.

팁: --mode MigrateSystem 옵션으로 실행하면 Jellyfin의 나머지 기능을 켜지 않고 마이그레이션만 수행한 뒤 종료합니다. 서비스 중단 시간을 통제하고 싶다면 유용합니다.

사용자 이름 대소문자 충돌 확인

12.0부터 사용자 이름의 대소문자 구분이 사라집니다. 그래서 대소문자만 다른 계정(예: daniel과 Daniel)이 둘 다 있으면 DB 마이그레이션 자체가 실패합니다. 업그레이드 전에 반드시 정리하세요. 대신 이제 사용자 이름의 대소문자를 변경하는 것 자체는 가능해졌습니다.

서드파티 플러그인은 미리 제거

10.11용 플러그인은 12.0에서 로드되지 않습니다.
서드파티 플러그인은 업그레이드 전에 제거하고, 제작자가 .NET 10 대상으로 재빌드한 버전을 기다려야 합니다.
공식 플러그인은 이미 12.0 지원을 마쳤습니다.

구형 클라이언트 호환성 단절

/emby/, /mediabrowser/ 레거시 경로가 제거되었습니다.
사용 중단 예정이던 로그인 방식은 기존 서버에서도 비활성화됩니다.

오래된 클라이언트 앱을 쓰고 있다면 미리 업데이트 가능 여부를 확인해 두는 편이 좋습니다.

업그레이드 후 전체 라이브러리 스캔

업그레이드가 끝나면 전체 라이브러리 스캔이 필수이고, 이 첫 스캔은 평소보다 훨씬 오래 걸립니다. 모든 항목을 디스크 파일과 대조하면서 이전 버전의 잔여 데이터와 잘못된 분류를 정리하기 때문입니다.

스캔 도중에는 이런 현상이 나타날 수 있는데, 정상입니다.

자동으로 묶여 있던 대체 버전 연결이 업그레이드 중 삭제되어, 스캔 전까지는 일부 버전이 사라진 것처럼 보임 (직접 병합한 버전은 해당 없음)
일부 영화가 새로 추가된 항목처럼 표시됨

2. 왜 10.12가 아니라 12.0인가

기존 명명 방식대로라면 10.12.0이 되었을 버전입니다. 하지만 이번엔 12.0을 쓰고, 서버가 보고하는 버전 문자열은 12.0.0입니다. 클라이언트나 배포 자동화 도구를 운영한다면 버전 파싱 로직과 API 변경을 함께 점검해야 합니다.

데이터베이스 구조 변경이 만든 성능 개선

가장 실질적인 변화는 저장 구조입니다.

| 구분 | 이전 | 12.0 | |---|---|---| | 저장 방식 | 부모 객체 안의 큰 목록 하나 | 항목마다 개별 DB 행 | | 개수 확인 | 전체 목록을 읽고 풀어야 함 | 행 개수만 계산 | | 한 페이지 조회 | 전체 목록 로드 | 해당 페이지만 조회 | | 항목 추가·삭제 | 목록 전체 재작성 | 나머지 목록 손대지 않음 |

덕분에 Continue Watching, Next Up, 다시 보기, 음악 Latest Media, 아티스트 조회, 폴더 시청 개수 조회가 빨라졌습니다. 목록이 클수록 체감 폭이 큽니다.

그 외에도,

대량 삭제가 중간에 실패하던 문제 수정
무거운 DB 유지보수 작업이 라이브러리 스캔과 동시에 실행되지 않도록 변경 → 자원 경쟁 완화

다만 한 가지 짚어둘 점은, 이번 최적화의 대상은 "라이브러리 읽기" 라는 것입니다. 스캐너 자체의 속도 개선은 이번 목표가 아니었습니다. 첫 실행의 마이그레이션 시간도 라이브러리 크기와 그동안 쌓인 잘못된 데이터의 양에 따라 크게 달라집니다.

3. 새 기능: 에피소드 다중 버전과 도서·만화 지원

에피소드에도 대체 버전 그룹화

지금까지 영화에만 있던 기능이 에피소드로 확장됐습니다.

방송판·확장판을 하나로 묶기
같은 에피소드의 1080p·4K 파일을 하나로 묶기
이어보기 위치는 실제로 시청하던 버전을 따라감

버전 연결의 저장 구조가 바뀌면서 자동 연결을 디스크 파일로부터 재구성해야 하고, 이것이 앞서 말한 업그레이드 후 스캔이 필요한 이유이기도 합니다.

Bookshelf 기능의 서버 통합

Bookshelf 플러그인의 주요 기능이 서버로 들어왔습니다. 이제 플러그인 없이도 도서 메타데이터를 읽습니다.

지원 범위는 이렇습니다.

메타데이터 파일: OPF, ComicInfo 파일, ComicBookInfo 주석
표지: EPUB 및 지원하는 모든 만화 압축 형식의 포스터 생성, 오디오북 외부 표지
파일명 파싱: 도서에서 이름·순번·연도·시리즈, 만화에서 권·장 번호
추가 정보: 만화 압축 파일·PDF의 페이지 수, 오디오북 챕터, ISBN 외부 ID와 링크

Bookshelf 플러그인 자체는 사용 중단 예정이며, 기능은 서버 또는 별도의 GoogleBooks·ComicVine 공급자로 이전됩니다. 새로 나온 OpenLibrary 플러그인이 메타데이터와 이미지를 제공합니다.

읽기 경험도 함께 손봤습니다.

웹 도서 라이브러리에 Modern 레이아웃과 보기 유형·페이지 구분·Authors·Collections·Folders 탭 추가
도서에 작가 정보 표시, 작가 페이지에 해당 작가의 도서와 오디오북 표시
모든 도서 유형의 읽기 화면·전체 화면 동작 통일, PDF 스와이프 탐색 지원
전자책 진행률 표시 복구, 순번·출간일 정렬과 EPUB 글꼴 크기 선택 개선
iOS 오디오북 백그라운드 재생 지원

4. 추천·검색 확장, 그리고 Modern이 기본이 되다

라이브러리별 추천 공급자 선택

추천·유사 항목 데이터 공급자를 메타데이터 공급자와 같은 설정 위치에서 라이브러리별로 고를 수 있습니다. 영화와 음악에 서로 다른 공급자를 쓰는 것도 가능합니다.

특히 서버에 포함된 ListenBrainz를 음악 라이브러리에 지정하면, 태그 매칭이 아니라 실제 청취 데이터에 기반한 유사 아티스트 추천을 받을 수 있습니다.

검색 플러그인 확장

검색 플러그인이 Jellyfin 자체 결과 옆에 별도의 검색 결과를 추가할 수 있게 됐습니다. 외부 검색을 붙이려고 서버를 포크할 필요가 없어진 셈입니다. 개발자용 상세 정보는 릴리스 노트에 정리되어 있습니다.

Modern이 기본 레이아웃으로

실험적 화면이던 Modern이, 별도 선택을 하지 않은 데스크톱·모바일 사용자의 기본 레이아웃이 되었습니다. 이전 화면은 Legacy로 남고, TV는 기존 앱의 TV 레이아웃을 계속 사용합니다.

Dark·Light·WMC·Blue Radiance·Apple TV·Purple Haze 테마가 CSS 변수 기반 공통 테마로 전환 → 사용자 정의 테마 제작자는 점검 필요
라이브러리 도구 모음을 앱 바에 통합하고 고정 라이브러리 헤더 적용
모든 라이브러리에 Collections·Playlists 탭 제공, 항목 상세에도 컬렉션 표시
Music Videos·Mixed Media·Collections and Playlists·Books 보기 갱신, Home Videos·Photos에 기본 탭 옵션과 폴더 보기 추가
오디오·자막 언어 필터, Reset Filters 버튼, 스튜디오 검색 추가

5. 사용자가 바로 체감할 변경점

동작이 달라지는 부분들이라 미리 알아두면 당황할 일이 줄어듭니다.

자막 설정이 라이브러리별로 관리됩니다. 기존의 서버 공통 옵션은 없어졌습니다.
정렬 기준이 일관되게 바뀌면서 일부 라이브러리의 항목 순서가 달라질 수 있습니다.
저해상도 포스터는 원본 크기 이상으로 확대하지 않습니다 → 작지만 더 선명하게 보입니다.
.ogg는 이제 비디오가 아닌 오디오로 취급되며, 기존 .ogg 비디오는 다음 스캔 때 재분류됩니다.
심볼릭 링크 미디어는 스캔 시점이 아니라 재생 시점에 링크를 따라갑니다.

재생 화면도 여러 곳이 좋아졌습니다.

계속 시청 여부 확인 추가, , · . 키로 프레임 단위 탐색
탐색 막대 미리보기에 챕터 이름 표시, 재생 정보 오버레이는 더 작으면서 더 많은 정보 제공
폴더를 재생 완료로 표시 가능, Upcoming 화면과 시리즈 라이브러리의 Play All·Shuffle 버튼 개선
사진 보기·독서 중에는 화면 보호기 억제, Modern에서 화면 보호기 시간·사진 슬라이드쇼 지연 시간 조정 가능
여러 역할을 맡은 제작진은 카드 하나로 통합, TV 프로그램 창작자를 상세 페이지에 표시
브라우저 캐시 확대로 방문했던 화면이 더 빨리 열리고, 고해상도 화면에서 이미지가 흐리던 문제 수정
게임 컨트롤러 탐색, 비라틴 문자 키보드 단축키, 리모컨 되감기·빨리 감기 개선

6. 관리자를 위한 변화

서버를 직접 운영한다면 반가울 항목들입니다.

운영·모니터링

로그 실시간 추적과 Activity 페이지 정렬·필터링 지원
시작 화면에 버전과 활동 정보 표시
클라이언트가 응답 언어를 지정 가능, 데이터베이스 파일을 기본 경로 외의 위치에 배치 가능
비활성화한 플러그인이 재시작 후 다시 활성화되지 않음 (오랜 골칫거리였죠)

백업

캐시 디렉터리에 CACHEDIR.tag 추가 → 백업 도구가 캐시를 제외 가능
손상된 레코드 하나 때문에 백업 전체가 실패하지 않도록 변경
백업 복원 전, 그리고 라이브러리 스캔 중 백업 시작 전에 경고 표시
DB 최적화 작업이 실행 시와 종료 시에 분석 및 vacuum 수행

라이브러리 관리

컬렉션·재생목록을 라이브러리별로 필터링
Metadata Manager에서 모든 사용자에게 적용되는 재생목록 라이브러리 이미지 설정, 재생목록에 중복 트랙 허용
인물 검색 필터, 작품 원어 오디오 우선 선택 옵션 추가
Refresh People 작업이 삭제된 인물을 정리하고 이미지 없는 인물의 업데이트를 확인

Live TV

가이드 가져오기와 재생 호환성 개선
XMLTV 배경 이미지·에피소드 썸네일 가져오기, 변경 없는 프로그램은 건너뛰어 반복 갱신 비용 절감
클라이언트에서 접근할 수 없는 서버 로컬 스트리밍 URL을 반환하지 않음
EPG가 SchedulesDirect API 오류 코드를 반영해 잠금 방지
지원 클라이언트에서 HDHomeRun은 직접 재생, M3U 튜너는 직접 재생 대신 리먹싱을 기본으로 사용

메타데이터 인식 확장

영화의 TVDB ID, AudioDb 아티스트 검색, 음악 파일의 ReplayGain 앨범 게인, 파일명의 WEB-DL 태그 지원, MusicBrainz 조회 복원력 개선
시즌·에피소드 폴더 이름에 공급자 ID 지정 가능
공급자 ID 파싱에 기존 대괄호 외에 중괄호·소괄호 지원, tvdbid·imdbid·tmdbid의 별칭으로 tvdb·imdb·tmdb 허용

7. 트랜스코딩과 기기 호환성

FFmpeg 8.1로 전환하면서 하드웨어 가속 경로가 두루 개선됐습니다.

CUDA 전치, OCL 스케일링, Mali GPU의 OCL 톤 매핑 성능 최적화
HLG 톤 매핑에 BT.2446 Method B의 EOTF 사용
Dolby Vision Profile 5용 규격 준수 dvh1 HLS 변형으로 기기 호환성 개선
비디오 트랜스코딩 + 오디오 리먹싱을 함께 할 때 발생하던 HLS 음성·영상 동기화 문제 수정

자막 처리도 눈에 띕니다.

SubtitleEdit를 통해 자막을 기록 → 기존 SSA→ASS 변환에서 생기던 스타일 손실 회피
VobSub 지원, 트랜스코딩 시 외부 자막의 MKS 삽입, 자막 추출 제한 시간 설정 추가
리먹싱 중에도 클라이언트가 이미지 기반 자막을 렌더링 가능

플랫폼별 지원 확대는 이렇습니다.

webOS 25 이상에서 MKV의 Dolby Vision 지원
TV 클라이언트에서 AV1 직접 스트리밍
Tizen에서 아나모픽 영상 직접 재생
iOS에서 화면을 끈 상태의 백그라운드 재생 지원, 오디오 정규화가 음높이·속도에 영향을 주던 문제 수정
회전 영상을 처리하지 못하는 Android TV 기기 프로필 옵션 추가
Trickplay는 스캔 시 기존 파일을 재사용하고 인터레이스 영상의 중복 생성을 방지

업그레이드 후 점검 체크리스트

[ ] 웹 화면이 이상하면 강력 새로고침 또는 웹 캐시 삭제
[ ] 전체 라이브러리 스캔 완료까지 대기 (평소보다 오래 걸림)
[ ] 사라진 것처럼 보이는 대체 버전이 스캔 후 복구됐는지 확인
[ ] 제거해 둔 서드파티 플러그인의 12.0 대응 빌드 확인
[ ] 사용 중인 클라이언트 앱들의 정상 로그인·재생 확인
[ ] 버그 신고 시에는 제목에 [12.0] 접두사를 붙이고, 막히면 지원 채팅 활용

마치며

정리하면 12.0은 성능 기반을 다지고 큰 기능 두 개를 얹은 릴리스입니다. 다만 DB 재작성, 플러그인 재빌드, 레거시 경로 제거처럼 한 번은 손이 가야 하는 변경이 함께 들어왔습니다.

그래도 보안 수정이 포함되어 있으므로, 프로젝트 측은 이전 버전에 머무르기보다 준비가 되는 대로 업그레이드할 것을 권장합니다. 백업만 제대로 해두고, 첫 스캔이 오래 걸린다는 점만 감안한다면 넘어갈 만한 릴리스입니다.

원문: https://news.hada.io/topic?id=33355