Jellyfin 미디어 서버의 Jellyscrub 플러그인을 활용한 크로스 플랫폼 트릭플레이 구현 및 최적화

Jellyscrub 아키텍처 및 핵심 메커니즘

Jellyscrub은 Jellyfin 미디어 서버 환경에서 비디오 타임라인 탐색 시 발생할 수 있는 버퍼링 지연을 해소하기 위해 설계된 트릭플레이(Trickplay) 솔루션입니다. 이 플러그인은 Roku의 .bif 포맷을 활용하여 고밀도 키프레임 미리보기 파일을 생성하며, Cloudflare와 같은 리버스 프록시 환경에서도 지연 없는 썸네일 렌더링을 보장합니다.

설치 및 스크립트 주입 프로세스

플러그인 매니저를 통한 기본 설치 후, 클라이언트 측 UI에 트릭플레이 오버레이를 렌더링하기 위해 프론트엔드 스크립트 주입이 필요합니다.

  1. Jellyfin 대시보드의 플러그인 카탈로그에 커스텀 매니페스트 URL을 등록합니다.
  2. Jellyscrub 패키지를 설치하고 서버 데몬을 재시작하여 백엔드 서비스를 활성화합니다.
  3. 서버는 index.html 템플릿에 클라이언트 스크립트 엔드포인트를 자동으로 주입하려고 시도합니다.
  4. 브라우저의 로컬 스토리지와 서비스 워커 캐시를 초기화하여 최신 UI 리소스를 로드합니다.

수동 스크립트 주입 로직 재구성

파일 시스템 권한 제약이나 Docker 컨테이너의 읽기 전용 마운트로 인해 자동 주입이 실패할 경우, index.html의 <body> 태그 종료 직전에 다음 동적 로더 스크립트를 삽입하여 엔드포인트를 바인딩할 수 있습니다.

<script>
  document.addEventListener('DOMContentLoaded', function() {
    // 베이스 경로 동적 추출 (리버스 프록시 및 서브디렉토리 환경 대응)
    const pathSegments = window.location.pathname.split('/');
    pathSegments.pop();
    const basePath = pathSegments.join('/') || '';
    
    const trickplayLoader = document.createElement('script');
    trickplayLoader.dataset.module = 'jellyscrub-ui';
    trickplayLoader.dataset.release = '2.1.0';
    trickplayLoader.async = true;
    trickplayLoader.src = `${basePath}/Trickplay/ClientScript`;
    
    document.body.appendChild(trickplayLoader);
  });
</script>

크로스 플랫폼 클라이언트 연동

트릭플레이 데이터는 서버에서 중앙 집중식으로 처리되지만, 각 클라이언트 플랫폼의 렌더링 엔진에 맞는 설정이 필요합니다.

  • 웹 클라이언트: 관리자의 라이브러리 스캔 주기 설정에 따라 백그라운드에서 FFmpeg를 호출하여 BIF 파일을 인코딩합니다. 하드웨어 가속(HWAccel)이 활성화된 환경에서는 VAAPI 또는 NVENC를 활용하여 인코딩 부하를 분산시킵니다.
  • 데스크톱 (Jellyfin Media Player): 클라이언트 설정의 플러그인 호환성 섹션에서 트릭플레이 모듈을 명시적으로 활성화해야 합니다. macOS 및 Linux 환경에서는 Wayland/X11 디스플레이 서버와의 호환성을 위해 최신 버전의 JMP 사용을 권장합니다.
  • 모바일 (iOS/Android): 모바일 네트워크 환경에서의 데이터 과소비를 방지하기 위해, 서버 설정에서 미리보기 해상도를 320px 이하로 제한하고 적응형 비트레이트 스트리밍과 연동하는 것이 효율적입니다.

Jellyfin 10.9.0 네이티브 트릭플레이로의 마이그레이션

Jellyfin 코어 버전 10.9.0부터 트릭플레이 기능이 네이티브로 통합되면서, Jellyscrub의 역할은 기존 .bif 아카이브를 Jellyfin의 새로운 메타데이터 구조로 변환하는 마이그레이션 도구로 전환되었습니다.

기존 구조:
/media/movies/Inception (2010)/
├── Inception.mkv
└── Inception.bif

마이그레이션 후 (네이티브 구조):
/metadata/trickplay/
└── [ItemID]/
    └── 320/
        └── 0.jpg ... N.jpg

플러그인 업데이트 후 서버를 재시작하면, 백그라운드 스케줄러가 기존 BIF 파일을 감지하여 네이티브 JPEG 시퀀스로 자동 디코딩 및 재패키징합니다.

시스템 리소스 및 스토리지 최적화

트릭플레이 미리보기 생성은 I/O 및 CPU 집약적인 작업이므로, 서버의 하드웨어 사양에 맞춰 스로틀링(Throttling) 정책을 수립해야 합니다.

미디어 러닝타임 추출 간격 타겟 해상도 예상 스토리지 점유율
90분 10초 320x180 ~6MB
120분 10초 320x180 ~8MB
90분 5초 640x360 ~28MB

대규모 라이브러리의 경우, 실시간 스캔 대신 크론(Cron) 기반의 야간 일괄 처리 작업을 구성하여 실시간 트랜스코딩 리소스와의 충돌을 방지하십시오.

운영 환경 트러블슈팅

  • FFmpeg 파이프라인 실패: 서버 로그에서 Exit code 1이 발생할 경우, HDR10 콘텐츠에 대한 톤 매핑(Tone-mapping) 필터가 누락되었거나 FFmpeg 빌드에 OpenCL/CUDA 지원이 컴파일되지 않았을 수 있습니다.
  • Docker 볼륨 마운트 오류: PUID 및 PGID 환경 변수가 호스트의 미디어 디렉토리 소유권과 일치하지 않으면 BIF 파일 쓰기 작업이 거부됩니다. chmod 및 chown 명령어를 통해 ACL을 재조정하십시오.
  • 프록시 캐시 오염: Nginx나 Traefik을 사용할 경우, /Trickplay/ 엔드포인트에 대해 Cache-Control: no-store 헤더를 우회하도록 설정해야 최신 썸네일 데이터가 클라이언트에 전달됩니다.

태그: Jellyfin Jellyscrub Trickplay ffmpeg BIF

10월 26일 15:06에 게시됨