Web Player_WebRTC Players_Low Latency Streaming-Documentation

이 가이드는 저지연 WebRTC 플레이어를 웹 애플리케이션에 통합하는 전체 과정을 안내합니다.

제공된 데모 패키지를 시작점으로 사용하여, demo.html 파일이 어떻게 작동하는지 단계별로 설명드리니, 이를 바탕으로 귀하의 프로젝트에 자신 있게 적용하실 수 있습니다.

시작하기: 데모 패키지 다운로드

데모 패키지에는 즉시 시작할 수 있도록 완전하게 동작하는 예제와 필요한 모든 파일이 포함되어 있습니다.

여기에서 데모 패키지를 다운로드하세요

다운로드된 패키지에는 다음이 포함되어 있습니다:

demo.html: 모든 HTML과 JavaScript가 한 파일에 포함된 실용적인 예제 페이지입니다.
wsrtcplayer.min.js: 핵심 Software Development Kit (SDK)입니다.
css/ 폴더: 데모 페이지 스타일을 위한 main.css 및 rtc_main.css가 들어 있습니다.

제공된 데모 이해하기

demo.html 파일을 분석하여 SDK가 비디오 스트림을 재생하는 방식을 알아보겠습니다.

1단계: HTML 구조

demo.html 파일은 페이지의 시각적 요소를 구성합니다. 가장 중요한 부분은 다음과 같습니다:

<video> 요소: 비디오가 표시되는 부분입니다. JavaScript에서 이 요소를 제어할 수 있도록 고유한 id가 지정되어 있습니다.
컨트롤 버튼: 이 버튼들은 플레이어를 시작하거나 정지하는 데 사용됩니다.
SDK 스크립트 태그: 이 줄은 페이지에 player 라이브러리를 로드하여 사용할 수 있도록 합니다. 플레이어가 정상적으로 작동하기 위해 반드시 포함되어야 합니다.
인라인 스크립트 블록: 파일 하단의 <script> 블록에는 플레이어를 제어하는 모든 JavaScript 로직이 포함되어 있습니다.

2단계: JavaScript 로직 (`demo.html` 내부)

demo.html 하단의 <script> 태그 내부에는 플레이어를 제어하는 코드가 포함되어 있습니다. 주요 부분을 분석해 보겠습니다.

a. onEvent 콜백

먼저, onEvent라는 함수가 정의되어 있습니다. 이 함수의 목적은, 재생이 시작되거나 버퍼링이 발생하는 등 플레이어에서 발생하는 상태 업데이트를 수신하는 것입니다.

// 이 함수는 플레이어로부터 전달되는 모든 이벤트를 처리합니다.
function onEvent(type, data) {
  switch (type) {
    case 3: // 플레이어에서 발생한 사용자 정의 이벤트
      console.log("사용자 이벤트: " + data);
      break;
    case 2: // 서버의 SDP 응답이 수신되었습니다.
      console.log("SDP 응답 수신 완료.");
      break;
    case 1: // 버퍼링 또는 스톨링이 발생했습니다.
      console.log("버퍼링이 발생했습니다.");
      break;
    case 0: // 버퍼링 후 재생이 다시 시작됨
      console.log("재생이 다시 시작되었습니다.");
      break;
  }
}

b. Player 초기화 및 제어

다음으로, 코드에서는 “Play” 버튼을 설정합니다. playButton이 클릭되면 아래와 같은 순서로 동작합니다:

이전 플레이어 정리: 코드에서는 player 객체가 이미 존재하는지 확인한 후, player.destroy()를 호출하여 모든 리소스를 정리합니다. 사용자가 “Play” 버튼을 여러 번 클릭할 경우 오류를 방지하기 위한 중요한 단계입니다.
플레이어 옵션 정의: 새 option 객체를 생성하여 플레이어를 구성합니다.
플레이어 인스턴스 생성: window.wsrtcplayer.createWSRTCPlayer(option)이 호출됩니다. 이 함수는 SDK를 사용하여 새 플레이어 인스턴스를 생성합니다.
재생 시작: player.open(signal_url)을 호출하여 스트림에 연결하고 재생을 시작합니다.

데모 커스터마이징

제공된 demo.html 파일은 완전하고 정상적으로 동작하는 시작 예시입니다. 아래에 필요에 따라 커스터마이즈할 수 있는 몇 가지 일반적인 방법을 안내드립니다.

1. 고객 ID 사용하기(운영 환경 필수)

데모에서는 customerID에 예시 값을 사용하고 있습니다. 실제 운영 환경에서는 반드시 CDNNetworks에서 제공받은 고유한 Account Name으로 해당 값을 변경해야 합니다. 이는 서비스에 맞춤화된 서버 측 설정을 적용하는 데 필수적입니다.

const playerOptions = {
    element: videoElement,
    customerID: "YOUR_UNIQUE_ACCOUNT_NAME", // 해당 값을 변경하세요
    listener: onEvent
};

2. 페이지 로드 시 자동 재생 활성화

기본적으로 이 데모는 사용자가 “Play” 버튼을 클릭할 때까지 대기합니다. 페이지가 로드되자마자 비디오가 자동으로 재생되도록 하려면, 스크립트를 수정해야 합니다. demo.html 맨 아래의 <script> 블록 전체를 다음 코드로 교체하세요:

<script>
    document.addEventListener('DOMContentLoaded', function () {
        
        // 이 함수는 플레이어의 상태 업데이트를 처리합니다.
        function onEvent(type, data) {
            const timestamp = (window.performance.now() / 1000).toFixed(3);
            console.log(timestamp + ": 이벤트 수신됨 - 유형: " + type);
        }


        const videoElement = document.getElementById('video-player');
        const signalUrl = 'http://webrtc-pull.test.cdnetworks.com/live/stream1.sdp';


        // 플레이어 옵션 정의
        const playerOptions = {
            element: videoElement,
            customerID: "YOUR_UNIQUE_ACCOUNT_NAME", // 실제 Account Name을 사용하세요.
            listener: onEvent
        };


        // 플레이어 인스턴스 생성
        const player = window.wsrtcplayer.createWSRTCPlayer(playerOptions);


        // 즉시 stream playback을 시작합니다.
        if (player) {
            player.open(signalUrl);
        }
    });
</script>

코드 내의 const signalUrl을 귀하가 즉시 stream playback을 시작하고자 하는 URL로 반드시 교체해 주시기 바랍니다.

<const signalUrl = 'http://webrtc-pull.test.cdnetworks.com/live/stream1.sdp';>

3. Player 상태 표시

onEvent 리스너를 사용하여 사용자에게 실시간 피드백을 제공할 수 있습니다. 먼저, 상태 메시지를 표시할 <div>를 HTML에 추가하세요:

<div id="status-display" style="padding: 10px; font-weight: bold;">연결 중...</div>

다음으로, 플레이어의 상태에 따라 이 요소의 텍스트가 업데이트되도록 onEvent 함수를 수정하세요:

const statusDisplay = document.getElementById('status-display');


function onEvent(type, data) {
  switch (type) {
    case 0:
      statusDisplay.innerText = 'Status: Playing';
      statusDisplay.style.color = 'green';
      break;
    case 1:
      statusDisplay.innerText = '상태: 버퍼링 중...';
      statusDisplay.style.color = 'orange';
      break;
    case 2:
      statusDisplay.innerText = '상태: 연결됨';
      break;
  }
}

4. 플레이어 외관 커스터마이징(CSS)

데모에서는 페이지에 간단하고 실용적인 외관을 적용하기 위해 두 개의 CSS 파일, rtc_main.css(기본 스타일)와 main.css(데모 전용 스타일)를 사용합니다. 스타일은 자유롭게 변경할 수 있으며, 최고의 결과를 위해서는 이러한 스타일을 직접 생성한 스타일시트로 덮어써서 귀하의 애플리케이션 브랜드에 맞추는 것이 좋습니다.

권장 방법: 나만의 스타일시트 생성하기

css 폴더에 my-styles.css라는 새 파일을 만듭니다.

이 새 파일에 커스텀 CSS 규칙을 추가하세요. 예를 들면:

/* /css/my-styles.css 내부 */
#video-player {
  테두리: 3px 실선 #007bff;
  테두리-반경: 5px;
  박스-그림자: 0 4px 8px rgba(0,0,0,0.2);
}

새로운 스타일시트를 demo.html에서 다른 두 CSS 파일 후에 링크하세요. 마지막에 추가함으로써 기본 스타일을 오버라이드할 수 있습니다.
```
<link rel="stylesheet" href="css/rtc_main.css" />
<link rel="stylesheet" href="css/main.css" />
<link rel="stylesheet" href="css/my-styles.css" />
```

빠른 수정(테스트용)

스타일을 빠르게 테스트하기 원하시면 main.css 파일의 마지막에 CSS 규칙을 추가하시면 됩니다.

API 참고자료

createWSRTCPlayer(options)

플레이어 인스턴스를 생성합니다.

options (Object): 설정 객체입니다.
- element (HTMLVideoElement) [필수]: 재생에 사용할 <video> 엘리먼트입니다.
- customerID (String) [옵션]: 귀하만의 고유한 Account Name입니다. CDNetworks에서 제공하며, 서버 측 커스텀 구성을 위해 플레이어를 귀하의 계정과 연동합니다.
- listener (Function) [선택 사항]: Player 이벤트를 수신하는 콜백 함수입니다.

player.open(signal_url)

비디오 stream playback을 로드하고 재생을 시작합니다.

player.close()

비디오 재생을 중지하고 스트림 연결을 해제합니다.

player.destroy()

재생을 중지하고 연결을 끊으며, 플레이어 인스턴스에서 사용된 모든 내부 리소스를 정리합니다. 플레이어 인스턴스 사용이 끝나면 메모리 누수를 방지하기 위해 이 기능을 호출하십시오.

이벤트 콜백(listener)

콜백 함수는 두 개의 매개변수를 전달받습니다: function(type, data).

매개변수	유형	설명
`type`	`Number`	이벤트 유형을 나타내는 코드입니다. 자세한 내용은 아래 목록을 참조하세요.
`data`	`String`	이벤트 유형에 따라 포함되는 이벤트별 데이터입니다. 해당 파라미터는 특정 이벤트 유형에서만 채워집니다.

Event type 코드:

0: 버퍼링 이후 재생이 재개되었습니다.
1: 버퍼링 또는 정지 현상이 발생했습니다.
2: 서버로부터 SDP answer를 수신했습니다. data 파라미터에는 SDP 정보 문자열이 포함됩니다.
3: Player에서 발생한 커스텀 이벤트입니다. data 파라미터에는 커스텀 이벤트 문자열이 포함됩니다.

신호 URL 형식

신호 URL은 다음과 같은 구조를 가집니다: http(s)://domain/appName/streamName.sdp

domain: Low Latency Streaming에 추가한 Domain입니다.
appName: 어플리케이션 이름 또는 publish point로, 트랜스코딩이나 녹화 등 설정의 최소 단위이며, 설정 격리를 위해 사용됩니다. 또한 다양한 라이브 채널 유형을 구분하는 데 사용할 수 있습니다.
streamName: 라이브 스트림의 이름으로, 서로 다른 방송을 구분하는 데 사용됩니다.

브라우저 호환성

운영 체제	브라우저 유형	최소 버전
Mac OS	데스크탑 Safari	11+
Mac OS	데스크탑 Chrome	47+
Windows	데스크탑 Chrome	56+
Android	모바일 Chrome	88+
iOS	모바일 Safari	11+
iOS	WeChat 인앱 브라우저	12+

참고: Chromium 엔진 기반 브라우저는 해당 Chrome 버전 요구 사항을 따라야 합니다. Android 브라우저에서의 지원은 상이할 수 있으며, 일부 기기는 H.264 하드웨어 디코딩 지원이 없을 수 있습니다.

Media Delivery

Cloud Security

Web Performance

Enterprise Application

Storage

Edge Computing

Console Guide

API Docs

Web Player

시작하기: 데모 패키지 다운로드

제공된 데모 이해하기

1단계: HTML 구조

2단계: JavaScript 로직 (`demo.html` 내부)

데모 커스터마이징

1. 고객 ID 사용하기(운영 환경 필수)

2. 페이지 로드 시 자동 재생 활성화

3. Player 상태 표시

4. 플레이어 외관 커스터마이징(CSS)

API 참고자료

신호 URL 형식

브라우저 호환성

디렉토리

Media Delivery

Cloud Security

Web Performance

Enterprise Application

Storage

Edge Computing

Console Guide

API Docs

Web Player

시작하기: 데모 패키지 다운로드

제공된 데모 이해하기

1단계: HTML 구조

2단계: JavaScript 로직 (demo.html 내부)

데모 커스터마이징

1. 고객 ID 사용하기(운영 환경 필수)

2. 페이지 로드 시 자동 재생 활성화

3. Player 상태 표시

4. 플레이어 외관 커스터마이징(CSS)

API 참고자료

신호 URL 형식

브라우저 호환성

디렉토리

2단계: JavaScript 로직 (`demo.html` 내부)