Title: 비디오 플레이어를 망가뜨리지 않고 캐스팅 기능 추가하기

브라우저에서 TV로 비디오를 캐스팅하는 것은 간단해 보이지만, 대부분의 커스텀 HTML5 플레이어는 이를 시도하는 순간 제대로 작동하지 않습니다. 최근의 한 개발자 가이드에서는 토큰 만료, CORS 차단, 도달할 수 없는 호스트, MSE-blob 함정이라는 네 가지 숨겨진 실패 지점을 나열하고, 각각을 어떻게 우회할 수 있는지 정확히 보여줍니다.

왜 캐스팅이 커스텀 플레이어에서 문제를 일으키는가

Cast 버튼을 누르면, TV는 사용자의 JavaScript 플레이어를 실행하지 않습니다. 대신 전달받은 스트림 URL을 가져와 자체 펌웨어로 미디어를 재생합니다. 오버레이, 분석 핑(analytics pings), 적응형 비트레이트(adaptive-bitrate) 로직은 브라우저에 그대로 남아 있습니다. 만약 TV가 동일한 조건에서 동일한 URL을 가져올 수 없다면, 콘솔에 명확한 오류가 표시되지 않은 채 재생이 중단되는 경우가 많습니다.

네 가지 주요 원인

  • Token expiry (토큰 만료) – 수명이 짧은 보안 토큰은 브라우저에서는 잘 작동합니다. 하지만 TV는 해당 스트림을 90분 동안 유지할 수도 있습니다. 토큰이 만료되면 비디오 재생이 중단됩니다. 캐스팅 세션에는 더 긴 유효 기간을 가진 토큰을 발급하세요.
  • CORS errors (CORS 오류) – CORS는 어떤 도메인이 리소스를 요청할 수 있는지 결정합니다. TV는 별도의 오리진(origin)으로 간주되므로, 비디오 서버가 페이지의 도메인만 화이트리스트에 등록해 두었다면 브라우저에서는 동일한 URL이 작동하더라도 TV의 요청은 차단됩니다.
  • Unreachable hosts (도달할 수 없는 호스트) – 개발 환경에서는 종종 localhost, 내부 호스트 이름 또는 사설 IP 범위를 사용합니다. TV는 다른 네트워크 세그먼트에 위치하므로 이러한 주소를 해석하거나 라우팅할 수 없으며, 이는 아무런 메시지 없는 실패로 이어집니다.
  • The MSE trap (MSE 함정) – Media Source Extensions (MSE)를 사용하면 브라우저가 청크(chunk)를 실시간으로 결합할 수 있으며, 이 과정에서 비디오가 blob: URL로 노출되는 경우가 많습니다. hls.js와 같은 라이브러리는 적응형 스트리밍을 위해 이러한 blob을 생성합니다. TV는 blob을 가져올 수 없으며, 실제 매니페스트(예: .m3u8 또는 .mpd) URL이 필요합니다. 캐스트 대화 상자를 호출하기 전에 소스를 실제 매니페스트 URL로 교체하세요.

단계별 체크리스트

  1. 캐스팅 지원 여부 감지 – Chrome의 경우 Remote Playback API를, Safari의 경우 WebKit 이벤트를 사용하세요. 이를 통해 브라우저가 재생 권한을 넘겨줄 수 있는지 확인할 수 있습니다.
  2. 연결 상태 모니터링 – 버튼 클릭이 안정적인 연결을 보장한다고 가정하지 마세요. Remote Playback 객체의 connecting, connected, disconnect 이벤트를 구독하세요. TV를 신뢰할 수 있는 상태(source of truth)로 간주하고, connected 이벤트를 받은 후에만 UI를 업데이트하세요.
  3. 수명이 긴 직접 URL로 교체 – remotePlayback.prompt()를 호출하기 전에, 비디오 요소의 src를 TV가 가져올 수 있는 매니페스트 URL로 교체하세요. 로컬 재생을 위해서는 기존의 blob 기반 소스를 유지하되, 캐스팅 세션에서만 교체하여 사용합니다.
  4. 최소 기능 테스트로 검증 – JavaScript 없이 매니페스트 URL을 가리키는 단일 <video> 태그만 있는 단순한 HTML 페이지를 만들어 한 시간 동안 실행해 보세요. 만약 비디오가 중단된다면, 해당 스트림은 TV에서도 실패할 것입니다. 캐스트 버튼을 추가하기 전에 토큰 유효 기간, CORS 헤더 또는 호스트 접근성을 먼저 해결하세요.

개발자가 얻을 수 있는 이점

플레이어의 나머지 기능을 망가뜨리지 않고 신뢰할 수 있는 캐스트 버튼을 추가할 수 있습니다.

요약

캐스팅은 커스텀 비디오 플레이어를 위한 플러그 앤 플레이(plug-and-play) 기능이 아닙니다. 재생 환경을 완전히 다른 곳으로 넘겨주는 작업입니다. 수명이 길고 CORS가 승인된 URL을 제공하고, blob 참조를 피하며, TV의 연결 이벤트를 모니터링함으로써, 플레이어 전체를 망가뜨리는 대신 안정적으로 작동하는 캐스트 버튼을 추가할 수 있습니다.