HTML5 플레이어 연동 가이드

개요

본 문서는 서비스 사이트의 웹 페이지에서 HTML5 플레이어를 이용해 멀티DRM(PlayReady, Widevine, FairPlay Streaming)으로 보호된 스트리밍 콘텐츠(DASH 또는 HLS)를 재생하는 방법을 설명합니다.

MPEG-DASH CENC 콘텐츠

Common Encryption 규격에 따라 암호화되어 PlayReady와 Widevine DRM으로 보호되는 DASH 방식의 스트리밍 콘텐츠입니다. 사용자의 브라우저에 따라 PlayReady(IE11, Edge) 또는 Widevine(Chrome, FireFox) DRM이 적용됩니다.

HLS FPS(FairPlay Streaming) 콘텐츠

SAMPLE AES 방식으로 암호화되어 FairPlay Streaming을 통해 보호되는 HTTP Live Streaming 콘텐츠입니다. 맥 OS X(10.10 이상)에서 구동되는 사파리 브라우저에 적용됩니다.

HTML5 플레이어에서 멀티DRM 라이선스를 발급받기 위해서는 PallyCon 클라우드와 고객사 서비스 사이트와의 연동을 통해 사용자 인증을 해야 하며, 라이선스 발급을 위한 멀티DRM 연동은 멀티DRM 네이티브 연동 가이드 문서를 참고하시기 바랍니다.

샘플 코드

Github 서비스를 통해 각종 HTML5 플레이어에 대한 DRM 연동 샘플 코드를 공유합니다. 샘플 코드에는 데모용 콘텐츠와 연동 데이터가 적용되어 있어 별도의 수정 없이도 DRM 콘텐츠의 재생을 확인해 볼 수 있습니다. (상용 플레이어의 경우 라이선스 키 설정 필요)

샘플코드 저장소 바로가기

기본 연동 방식

HTML5 플레이어의 PallyCon 멀티DRM 연동은 각 플레이어에서 제공하는 DRM 관련 API를 통해 PallyCon 라이선스 발급에 필요한 데이터(Custom Data 또는 토큰)를 Custom HTTP Header에 설정하는 방식으로 구현됩니다.

Widevine / PlayReady 설정

Widevine과 PlayReady DRM은 다음과 같이 라이선스 요청 URL과 Custom HTTP Header를 설정하여 연동할 수 있습니다. MPEG-DASH CENC를 지원하는 브라우저에서 실행되는 경우에, 각각의 해당 DRM 설정이 적용되어 DASH 콘텐츠를 재생하게 됩니다.

FairPlay Streaming 설정

FairPlay Streaming 연동을 위해서는 라이선스 요청 주소와 Custom HTTP Header 정보 외에 추가적인 API가 사용됩니다. 애플로부터 발급받는 FPS Deployment Package의 CERT 파일을 설정하기 위해 certificateURL 값을 설정하며, prepareContentId와 prepareCertificate API를 처리해 주어야 합니다.

본 문서에서 설명되지 않은 플레이어의 경우에도 EME(Encrypted Media Extension) 표준을 지원하는 플레이어라면 연동이 가능합니다. 아래 입력 값 설명과 플레이어 별 샘플 코드를 참고해 직접 연동하거나 헬프데스크로 문의해 주시기 바랍니다.

입력 값 설명

각 플레이어 별 연동 API 코드에 사용된 입력 값들에 대한 설명은 아래를 참고하시기 바랍니다.

Name	Value	Remarks
DASH_MANIFEST_URL (dashUri)	CENC 규격으로 패키징된 MPEG-DASH 콘텐츠의 manifest(mpd) 파일 URL	Widevine, PlayReady 공통으로 사용
SERVER_CERTIFICATE	Widevine server에서 발급 된 인증서	chrome58 버젼 이상의 브라우저에서 widevine 컨텐츠 재생 시 사용. 없을 경우 서버로 인증서를 요청 후 라이센스를 요청하게 됨.
PALLYCON_LA_URL (licenseUri)	PallyCon 클라우드 서비스의 라이선스 요청용 URL. `https://license-global.pallycon.com/ri/licenseManager.do`	동일한 주소로 Widevine, PlayReady, FairPlay 각각 설정.
CUSTOM_HEADER_NAME	LA URL로 라이선스 요청과 함께 전달될 Custom HTTP Header의 이름. `pallycon-customdata-v2` 사용
CUSTOM_HEADER_VALUE	라이선스 연동 방식에 따라 라이선스 토큰 또는 프록시 용 사용자 인증 데이터 값을 입력
HLS_PLAYLIST_URL (hlsUri)	FPS 규격으로 패키징된 HLS 콘텐츠의 playlist(m3u8) 파일 URL
PALLYCON_FPS_CERT_URL (fairplayCertUri)	FPS 인증서 데이터 URL. Base64 인코딩된 인증서 데이터를 응답함 `https://license-global.pallycon.com/ri/fpsKeyManager.do?siteId='Your_Site_ID'`	Site_ID는 PallyCon에서 발급된 서비스 사이트 ID(4byte)를 입력
PALLYCON_FPS_CERT_DER_URL (fairplayCertDerUri)	FPS 인증서 파일 URL. `.der` 형태의 인증서 파일을 응답함 `https://license-global.pallycon.com/ri/fpsCert.do?siteId='Your_Site_ID'`	Site_ID는 PallyCon에서 발급된 서비스 사이트 ID(4byte)를 입력

FPS 인증서 URL은 각 플레이어에서 지원하는 인증서 설정 방식에 따라 Base64 인코딩된 데이터 또는 인증서 파일 다운로드용 URL을 사용합니다. 자세한 사항은 플레이어 별 샘플 코드를 참조하시기 바랍니다.

Shaka 플레이어 연동

Shaka 플레이어는 HLS와 MPEG-DASH를 지원하는 HTML5 플레이어입니다. Widevine과 PlayReady를 통한 CENC 콘텐츠 재생과 FairPlay HLS 재생을 지원합니다. Shaka 플레이어에 대한 자세한 내용은 아래 링크들을 참조하시기 바랍니다.

Shaka 플레이어 github : https://github.com/google/shaka-player
Shaka 플레이어 온라인 가이드 : https://shaka-player-demo.appspot.com/docs/api/index.html
Shaka 플레이어 DRM Setup 가이드 : https://shaka-player-demo.appspot.com/docs/api/tutorial-drm-config.html

각각의 DRM 유형에 따른 Shaka 플레이어의 API 설정은 샘플 코드를 참고하시기 바랍니다.

커스텀 에러 처리

PallyCon 클라우드에서 HTML5 플레이어의 라이선스 요청을 처리하는 중에 에러가 발생하는 경우, 해당 에러 코드와 내용을 플레이어에서 확인할 수 있습니다. Shaka 플레이어 설정에서는 에러 처리를 위해 registerResponseFilter API를 사용합니다.

에러 처리 예제

player.getNetworkingEngine().registerResponseFilter(function(type, response) {
  // Alias some utilities provided by the library.
  if (type == shaka.net.NetworkingEngine.RequestType.LICENSE) {
    console.log(response.data.byteLength);
    var responseText = arrayBufferToString(response.data);
    console.log("response : " + responseText);
    if (responseText.indexOf('errorCode') > 0) {
      // this alert should be properly parsed and displayed for commercial use
      var errorCode = JSON.parse(responseText).errorCode;
      if("8002" != errorCode){
        alert("PallyCon Error : " + JSON.parse(responseText).message + "(" + JSON.parse(responseText).errorCode+ ")");
      }else{
        var message = JSON.parse(responseText).message;
        alert("Error : " + JSON.parse(message).MESSAGE + "(" + JSON.parse(message).ERROR + ")");
      }
    }
  }
});

registerResponseFilter는 Widevine과 PlayReady 모두에 적용되며, 실제 서비스에 적용 시에는 위 예제 코드를 활용하여 서비스에 적합한 방식으로 에러 처리를 해 주시기 바랍니다.

에러 코드 목록과 해당 메시지 내용은 멀티 DRM 라이선스 에러코드를 참조하시기 바랍니다.

Bitmovin 플레이어 연동

Bitmovin 플레이어는 HLS와 MPEG-DASH를 지원하는 HTML5 플레이어입니다. Bitmovin 플레이어에 대한 자세한 내용은 아래 링크들을 참조하시기 바랍니다.

Bitmovin 플레이어 홈페이지 : https://bitmovin.com/html5-player/
Bitmovin 플레이어 온라인 가이드 : https://bitmovin.com/docs/player
Bitmovin 플레이어 DRM Setup 가이드 : https://bitmovin.com/docs/player/tutorials/setup-the-bitmovin-player-with-multiple-drm-solutions

각각의 DRM 유형에 따른 Bitmovin 플레이어의 API 설정은 샘플 코드를 참고하시기 바랍니다.

커스텀 에러 처리

PallyCon 클라우드에서 HTML5 플레이어의 라이선스 요청을 처리하는 중에 에러가 발생하는 경우, 해당 에러 코드와 내용을 플레이어에서 확인할 수 있습니다. Bitmovin 플레이어 설정에서는 에러 처리를 위해 prepareLicense API를 사용합니다.

에러 처리 예제 (Widevine의 경우)

var conf = {
  ...
  source: {
    dash: 'https://d28giv01x4pn7o.cloudfront.net/tears_of_steel_720p/stream.mpd',
    drm: {
      widevine: {
        LA_URL: 'https://license-global.pallycon.com/ri/licenseManager.do',
        headers: {
          'pallycon-customdata-v2' : 'eyJkYXRhIjoibWJLV1NjSUNIU25WMjZQWFB4cGlDSmNsOHdJMHV1Qlc1cnFqU0hzV1BRSTM4ek1iZTcyZ3Q5TllZRXprRmFjUU5hVU8yRGZUb2l0YzZndXZ5RzJOWlE9PSIsInNpdGVfaWQiOiJERU1PIiwiZHJtX3R5cGUiOiJXaWRldmluZSJ9'
        },
        prepareLicense: function(licenseObj) {
          var license = {
            license: licenseObj.license
          };
          try {
            var pallyconObj = JSON.parse(String.fromCharCode.apply(null, licenseObj.license));
            if (pallyconObj && pallyconObj.errorCode && pallyconObj.message) {
              // this response is error, not valid widevine license
              console.log('ri error code : ' + pallyconObj.errorCode + ', message :', pallyconObj.message);

              var fullErrorMsg;
              if (parseInt(pallyconObj.errorCode) == 8002) {
                // getting the error from callback page
                var errorObj = JSON.parse(pallyconObj.message);
                if (errorObj && errorObj.ERROR && errorObj.MESSAGE) {
                  fullErrorMsg = 'RI errorCode : ' + pallyconObj.errorCode + '\nCallback ERROR: ' + errorObj.ERROR + '\nCallback MESSAGE: ' + errorObj.MESSAGE;
                }
              } else {
                // this error is from PallyCon RI
                fullErrorMsg = 'RI errorCode: ' + pallyconObj.errorCode + '\nRI message: ' + pallyconObj.message;
              }
              alert(fullErrorMsg);
            }
          } catch (e) {
            // this is valid license
            return license;
          }
      },
      ...
    }
  }
};

위 예제는 Widevine 라이선스 응답에 대한 처리를 보여주고 있으며, 필요 시 PlayReady와 FairPlay Streaming 항목의 prepareLicense API도 동일하게 처리해 주어야 합니다. 실제 서비스에 적용 시에는 위 예제 코드를 활용하여 서비스에 적합한 방식으로 에러 처리를 해 주시기 바랍니다.

에러 코드 목록과 해당 메시지 내용은 멀티 DRM 라이선스 에러코드를 참조하시기 바랍니다.

THEOplayer 플레이어 연동

THEOplayer는 Web, 모바일 앱, 스마트TV 등의 환경에서 HLS와 MPEG-DASH 재생을 지원하는 크로스플랫폼 비디오 플레이어입니다. Widevine과 PlayReady를 통한 DASH CENC 콘텐츠 보호와 FairPlay Streaming을 통한 HLS 콘텐츠 보호를 지원합니다. THEOplayer에 대한 자세한 내용은 아래 링크들을 참조하시기 바랍니다.

THEOplayer 홈페이지 : https://theoplayer.com/
THEOplayer 개발자 문서 : https://support.theoplayer.com/hc/en-us
THEOplayer DRM 연동 API : https://docs.theoplayer.com/how-to-guides/04-drm/15-pallycon.md

각각의 DRM 유형에 따른 THEOplayer의 API 설정은 샘플 코드를 참고하시기 바랍니다.

커스텀 에러 처리

PallyCon 클라우드에서 HTML5 플레이어의 라이선스 요청을 처리하는 중에 에러가 발생하는 경우, 해당 에러 코드와 내용을 플레이어에서 확인할 수 있습니다. THEOplayer 설정에서는 에러 처리를 위해 ‘contentprotectionerror’ Event Listener API를 사용합니다.

에러 처리 예제

player.addEventListener("contentprotectionerror", function(data){
    console.log( "error : " + data.error);
    console.log( "licenseAcquisitionMessage : " + data.licenseAcquisitionMessage );
    console.log( "licenseAcquisitionURL : " + data.licenseAcquisitionURL );
    console.log( "mediaTrackType : " + data.mediaTrackType );
    console.log( "status  : " + data.status );
    console.log( "statusText  : " + data.statusText );
    console.log( "type  : " + data.type );
);

Event Listener는 Widevine과 PlayReady 모두에 적용되며, 실제 서비스에 적용 시에는 위 예제 코드를 활용하여 서비스에 적합한 방식으로 에러 처리를 해 주시기 바랍니다.

에러 코드 목록과 해당 메시지 내용은 멀티 DRM 라이선스 에러코드를 참조하시기 바랍니다.

Radiant Media Player 연동

Radiant Media Player(RMP)는 웹, 모바일 및 OTT 비디오 앱을 쉽게 개발할 수 있게 해주는 현대적인 HTML5 비디오 플레이어입니다. Widevine과 PlayReady를 통한 DASH CENC 콘텐츠 보호와 FairPlay Streaming을 통한 HLS 콘텐츠 보호를 지원합니다. RMP에 대한 자세한 내용은 아래 링크들을 참조하시기 바랍니다.

RMP 홈페이지 : https://www.radiantmediaplayer.com/
RMP 개발자 문서 : https://www.radiantmediaplayer.com/docs/latest/quick-start.html
RMP DRM 연동 API : https://www.radiantmediaplayer.com/guides/working-with-pallycon.html

각각의 DRM 유형에 따른 Radiant Media Player의 API 설정은 샘플 코드를 참고하시기 바랍니다.

JW Player 연동

JW Player는 웹, 모바일 및 OTT 비디오 앱 개발을 지원하는 HTML5 비디오 플레이어입니다. Widevine과 PlayReady를 통한 DASH CENC 콘텐츠 보호와 FairPlay Streaming을 통한 HLS 콘텐츠 보호를 지원합니다. JW Player에 대한 자세한 내용은 아래 링크들을 참조하시기 바랍니다.

JW Player 홈페이지 : https://www.jwplayer.com/
JW Player 개발자 문서 : https://developer.jwplayer.com/jwplayer/docs
JW Player DRM 연동 API : https://developer.jwplayer.com/jwplayer/docs/jw8-enable-drm-through-the-web-player

각각의 DRM 유형에 따른 Radiant Media Player의 API 설정은 샘플 코드를 참고하시기 바랍니다.

VideoJS 플레이어 연동

VideoJS 플레이어는 HLS와 MPEG-DASH를 지원하는 HTML5 플레이어입니다. VideoJS 플레이어에 대한 자세한 내용은 아래 링크들을 참조하시기 바랍니다.

VideoJS 플레이어 홈페이지 : https://videojs.com/
VideoJS 플레이어 온라인 가이드 : https://docs.videojs.com/

VideoJS 플레이어의 멀티DRM 연동을 위해서는 아래 플러그인을 추가로 사용해야 합니다.

VideoJS Contrib EME 플러그인 : https://www.npmjs.com/package/videojs-contrib-eme/

각각의 DRM 유형에 따른 VideoJS 플레이어의 API 설정은 샘플 코드를 참고하시기 바랍니다.

Viblast 플레이어 연동

Viblast 플레이어는 HLS와 MPEG-DASH를 지원하며 P2P 방식의 콘텐츠 전송 기능을 지원하는 HTML5 플레이어입니다. Widevine과 PlayReady를 통한 CENC 콘텐츠 재생을 지원하지만, FairPlay DRM은 지원하지 않습니다. Viblast 플레이어에 대한 자세한 내용은 아래 링크들을 참조하시기 바랍니다.

Viblast 플레이어 홈페이지 : https://viblast.com/player/
Viblast 플레이어 온라인 가이드 : https://docs.viblast.com/player/
Viblast 플레이어 DRM 연동 가이드 : https://docs.viblast.com/player/drm-protection

각각의 DRM 유형에 따른 Viblast 플레이어의 API 설정은 샘플 코드를 참고하시기 바랍니다.

커스텀 에러 처리

PallyCon 클라우드에서 HTML5 플레이어의 라이선스 요청을 처리하는 중에 에러가 발생하는 경우, 해당 에러 코드와 내용을 플레이어에서 확인할 수 있습니다. Viblast 플레이어 설정에서는 에러 처리를 위해 ‘load’ Event Listener API를 사용합니다.

에러 처리 예제

var videoCheck = 0;
viblast('#player').setup({
  stream: 'https://d28giv01x4pn7o.cloudfront.net/tears_of_steel_720p/stream.mpd',
  widevine: {
    'licensing-server': 'https://license-global.pallycon.com/ri/licenseManager.do'
  },
  xhrBeforeSend: function(ev) {
    // filter out non-drm requests
    if (ev.method !== "POST") return;

    if (is_chrome_or_firefox) {
      ev.xhr.setRequestHeader('pallycon-customdata-v2', 'eyJkYXRhIjoibWJLV1NjSUNIU25WMjZQWFB4cGlDSmNsOHdJMHV1Qlc1cnFqU0hzV1BRSTM4ek1iZTcyZ3Q5TllZRXprRmFjUU5hVU8yRGZUb2l0YzZndXZ5RzJOWlE9PSIsInNpdGVfaWQiOiJERU1PIiwiZHJtX3R5cGUiOiJXaWRldmluZSJ9');
    }
    else {
      ev.xhr.setRequestHeader('pallycon-customdata-v2', 'eyJkYXRhIjoibWJLV1NjSUNIU25WMjZQWFB4cGlDSmNsOHdJMHV1Qlc1cnFqU0hzV1BRSTM4ek1iZTcyZ3Q5TllZRXprRmFjUU5hVU8yRGZUb2l0YzZndXZ5RzJOWlE9PSIsInNpdGVfaWQiOiJERU1PIiwiZHJtX3R5cGUiOiJQbGF5UmVhZHkifQ==');
    }
    ev.xhr.addEventListener('load', function() {
      if( 1 > videoCheck){
        var responseText = String.fromCharCode.apply(null, new Uint8Array(ev.xhr.response)); // assumes utf8
        if (responseText.indexOf('errorCode') > 0) {
          // this alert should be properly parsed and displayed for commercial use
          var errorCode = JSON.parse(responseText).errorCode;
          if("8002" != errorCode){
            alert("PallyCon Error : " + JSON.parse(responseText).message + "(" + JSON.parse(responseText).errorCode+ ")");
            //window.alert('No Rights. Server Response ' + responseText);
          } else {
            var message = JSON.parse(responseText).message;
            alert("Error : " + JSON.parse(message).MESSAGE + "(" + JSON.parse(message).ERROR + ")");
          }
        }
        videoCheck += 1;
      }
    });
  },
  ...
});

Load Event Listener는 Widevine과 PlayReady 모두에 적용되며, 실제 서비스에 적용 시에는 위 예제 코드를 활용하여 서비스에 적합한 방식으로 에러 처리를 해 주시기 바랍니다.

에러 코드 목록과 해당 메시지 내용은 멀티 DRM 라이선스 에러코드를 참조하시기 바랍니다.

마지막 업데이트 Aug 2, 2023