Shaka Player 파헤치기 - 5.0.0 Changelog 분석#

Shaka Player 5.0.0은 v5 라인의 시작점이자, v4에서 예고했던 정리를 실행한 메이저 릴리스입니다. 이 글에서는 체인지로그와 공식 업그레이드 가이드, 주요 PR을 근거로 무엇이 사라지고 바뀌었는지, 그리고 업그레이드할 때 무엇을 고쳐야 하는지 정리합니다.

#릴리스 개요

5.0.0은 2026년 2월 6일에 배포되었습니다. 체인지로그에는 새 기능 109건, 버그 수정 187건, 성능 개선 24건이 올라 있고, Breaking Change로 표시된 항목은 22건입니다.

Shaka Player는 v3부터 시맨틱 버저닝을 따릅니다. 업그레이드 가이드는 같은 메이저 안에서의 업그레이드는 하위 호환되어야 한다고 설명합니다. 즉 애플리케이션 수정이 필요한 변경은 이런 메이저 버전에 모이고, 5.0.0이 v5 라인에서 그 역할을 맡았습니다.

#제거된 기능

MSS 콘텐츠나 위 자막 포맷을 사용 중이라면 5.0으로 올리기 전에 대체 경로를 마련해야 합니다.

#설정과 API 마이그레이션

업그레이드 가이드의 v5.0 항목 중 영향이 넓은 변경을 추렸습니다.

#설정 변경

라이브 동기화 설정은 다음처럼 객체 형태로 옮겨야 합니다.

1player.configure({
2  streaming: {
3    liveSync: {
4      enabled: true,
5      targetLatency: 3,
6    },
7  },
8});

#Player API 변경

#시작 위치 지정 방식

#9668 이후로는 시작 과정에서 미디어 요소의 currentTime을 직접 바꿀 수 없습니다. PR 설명에 따르면 streaming 이벤트에서 currentTime을 수정하던 방식 대신, canupdatestarttime 이벤트에서 updateStartTime을 호출해야 합니다.

1player.addEventListener('canupdatestarttime', () => {
2  player.updateStartTime(120);
3});

#자막 트랙 선택과 표시 방식 단순화

v4까지는 자막 트랙을 선택하는 것과 자막을 보이게 하는 것이 별개의 동작이었습니다. #9048은 이 구분을 없애는 방향의 변경이고, #9664가 setTextTrackVisibility를 공개 API에서 제거했습니다.

1// 자막 켜기: 트랙을 선택하면 표시까지 내부에서 처리합니다.
2player.selectTextTrack(track);
3
4// 자막 끄기
5player.selectTextTrack(null);

autoShowText도 함께 사라졌습니다. 업그레이드 가이드에 따르면 초기 자막 트랙은 preferredTextLanguage와 preferredTextRole로만 결정합니다. 강제 자막은 #9497에서 기본으로 자동 처리되도록 바뀌었고 설정으로 조정할 수 있습니다.

#플러그인과 광고 인터페이스 변경

커스텀 플러그인을 쓰고 있다면 다음을 확인해야 합니다.

• TextDisplayer: configure() 구현이 필수이고, enableTextDisplayer는 제거되었습니다. 내장 디스플레이어의 생성자는 shaka.Player 인스턴스를 유일한 인자로 받습니다(#9515). SimpleTextDisplayer는 NativeTextDisplayer로 대체되었습니다.
• TextParser: setManifestType() 구현이 필수이고, setSequenceMode는 제거되었습니다.
• Transmuxer: transmux()에 매개변수 3개가 추가되었습니다.

AdManager도 #9357로 단순해졌습니다.

• initClientSide, initServerSide, initMediaTailor, initInterstitial이 제거되고 필요할 때 자동으로 초기화됩니다.
• 컨테이너는 새로운 setContainers로 지정합니다.
• 모든 메서드에서 video, player 매개변수가 제거되었습니다.
• onDashTimedMetadata가 제거되었습니다.

#UI 기본 동작 변경

Shaka UI를 그대로 쓰는 서비스는 코드를 고치지 않아도 화면이 달라질 수 있습니다.

#주요 새 기능

• 네이티브 챕터(#9208): 네이티브 챕터 지원이 추가되었습니다. HLS의 com.apple.hls.chapters와 라이브 챕터 지원도 함께 추가되었습니다.
• 자동 자막(#9123): Web Speech API와 Translator API를 사용합니다. PR 설명대로 Chrome만 지원하는 실험 기능이며 기본 비활성화입니다.
• MoQ 실험 지원(#9409): MoQT draft-14와 WARP/MSF draft-1을 추가했습니다. 기본 빌드에는 포함되지 않습니다.
• SVTA2053-2(#9172): SSAI, SGAI와 함께 동작하는 광고 추적용 매니저가 추가되었습니다.
• retryLicensing()(#9638, 이슈 #1772): 라이선스 요청이 실패한 뒤 앱이 재시도할 수 있습니다. EME에서 generateRequest()는 세션당 한 번만 호출할 수 있어, 기존 세션을 닫고 같은 initData로 새 세션을 만드는 방식입니다.
• MSE 에러 시 스트림 비활성화(#9097): 에러 처리 글에서 본 대체 스트림 전환 경로의 일부입니다.
• streaming.stopFetchingOnPause(#9567): 일시정지 중 새 세그먼트 요청을 멈춥니다.
• HLS AES-256-GCM(#9562)

#5.0.x 패치의 주요 수정

패치는 5.0.28(7월 27일)까지 이어졌고, 체인지로그 기준 버그 수정 124건과 성능 개선 41건이 있습니다. 대부분 이후 라인과 공유됩니다.

성능 개선은 GC 압력을 줄이는 작업이 많습니다. HLS 태그와 VTT 파싱의 배열 할당 제거(5.0.8), SegmentIndex 이진 탐색(5.0.9)이 대표적입니다. 저사양 TV 환경을 겨냥한 흐름은 이후 5.2까지 이어집니다.

#마치며, 업그레이드 체크리스트

• MSS 또는 LRC, SBV, SSA 자막을 사용하지 않는지 확인
• new shaka.Player(video)를 attach() 방식으로 변경
• streaming.liveSync* 설정을 객체로 변경, networking.* 이동 반영
• setTextTrackVisibility를 selectTextTrack(null)로 변경, autoShowText 제거
• getAudioLanguages, selectAudioLanguage, getChapters를 새 API로 변경
• 시작 위치를 canupdatestarttime과 updateStartTime으로 지정
• 커스텀 TextDisplayer, TextParser, Transmuxer 플러그인 수정
• AdManager의 init* 호출 제거, setContainers 적용
• Shaka UI의 버튼 구성과 컨텍스트 메뉴 동작 확인