iframe 삽입에 대한 YouTube Player API 참조 문서

IFrame Player API를 통해 웹사이트에 YouTube 동영상 플레이어를 퍼가고 JavaScript를 사용하여 플레이어를 제어할 수 있습니다. 웹페이지에 Flash 개체를 삽입하는 것과 관련된 Flash 및 JavaScript Player API와 달리 IFrame API는 콘텐츠를 페이지의 <iframe> 태그에 게시합니다. 이 방법은 YouTube에서 Flash를 지원하지 않는 모바일 기기에 Flash 대신 HTML5 플레이어를 게재할 수 있도록 하므로 기존에 제공된 API보다 좀 더 유연성을 제공합니다.

API의 JavaScript 함수를 사용하여 재생을 위해 동영상을 대기열에 넣거나, 이러한 동영상을 재생, 일시중지 또는 중지하거나, 플레이어 볼륨을 조정하거나, 재생 중인 동영상에 대한 정보를 가져올 수 있습니다. 또한 플레이어 상태 변경 또는 동영상 재생 품질 변경과 같은 특정 플레이어 이벤트에 대한 응답으로 실행되는 이벤트 리스너를 추가할 수 있습니다.

이 가이드에서는 IFrame API를 사용하는 방법을 설명합니다. API에서 보낼 수 있는 이벤트의 여러 유형을 식별하고 이벤트 리스너를 작성하여 이러한 이벤트에 응답하는 방법을 설명합니다. 또한 동영상 플레이어를 제어하기 위해 호출할 수 있는 여러 JavaScript 함수 및 플레이어를 좀 더 맞춤설정하는 데 사용할 수 있는 플레이어 매개변수를 자세히 설명합니다.

요구사항

최종 사용자는 HTML5 postMessage 기능을 지원하는 브라우저를 사용해야 합니다. 대부분의 최신 브라우저가 postMessage를 지원하지만 Internet Explorer 7은 지원하지 않습니다.

내장 플레이어에는 200x200픽셀 이상의 표시 영역이 있어야 합니다. 플레이어에 컨트롤이 표시되는 경우에는 표시 영역이 최소 크기 미만으로 축소되지 않고 컨트롤이 완전히 표시될 만큼 커야 합니다. 16:9 플레이어의 경우 가로 480픽셀, 세로 270픽셀 이상으로 지정하는 것이 좋습니다.

IFrame API를 사용하는 모든 웹페이지는 다음 JavaScript 함수도 구현해야 합니다.

onYouTubeIframeAPIReady – 페이지에서 플레이어 API에 대한 JavaScript 다운로드를 완료하면 API가 이 함수를 호출하여 페이지에서 API를 사용할 수 있습니다. 따라서 이 함수에서는 페이지 로드 시 표시할 플레이어 개체를 만들어야 합니다.

시작하기

아래 샘플 HTML 페이지에서는 동영상을 로드하고 6초 동안 재생한 다음 재생을 중지하는 내장 플레이어를 만듭니다. HTML에 있는 번호가 매겨진 설명에 대해서는 예 아래의 목록에서 설명합니다.

<!DOCTYPE html>
<html>
  <body>
    <!-- 1. The <iframe> (and video player) will replace this <div> tag. -->
    <div id="player"></div>

    <script>
      // 2. This code loads the IFrame Player API code asynchronously.
      var tag = document.createElement('script');

      tag.src = "https://www.youtube.com/iframe_api";
      var firstScriptTag = document.getElementsByTagName('script')[0];
      firstScriptTag.parentNode.insertBefore(tag, firstScriptTag);

      // 3. This function creates an <iframe> (and YouTube player)
      //    after the API code downloads.
      var player;
      function onYouTubeIframeAPIReady() {
        player = new YT.Player('player', {
          height: '360',
          width: '640',
          videoId: 'M7lc1UVf-VE',
          events: {
            'onReady': onPlayerReady,
            'onStateChange': onPlayerStateChange
          }
        });
      }

      // 4. The API will call this function when the video player is ready.
      function onPlayerReady(event) {
        event.target.playVideo();
      }

      // 5. The API calls this function when the player's state changes.
      //    The function indicates that when playing a video (state=1),
      //    the player should play for six seconds and then stop.
      var done = false;
      function onPlayerStateChange(event) {
        if (event.data == YT.PlayerState.PLAYING && !done) {
          setTimeout(stopVideo, 6000);
          done = true;
        }
      }
      function stopVideo() {
        player.stopVideo();
      }
    </script>
  </body>
</html>

다음 목록에서는 위 샘플에 대한 자세한 내용을 제공합니다.

이 섹션의 <div> 태그는 IFrame API가 동영상 플레이어를 배치할 페이지의 위치를 식별합니다. 동영상 플레이어 로드 섹션에 설명된 플레이어 개체의 생성자는 API가 올바른 위치에 <iframe>을 배치하도록 태그의 id로 <div> 태그를 식별합니다. 특히 IFrame API는 <div> 태그를 <iframe> 태그로 대체합니다.

대신 <iframe> 요소를 페이지에 직접 삽입할 수도 있습니다. 동영상 플레이어 로드 섹션에서 직접 삽입하는 방법을 설명합니다.
이 섹션의 코드는 IFrame Player API JavaScript 코드를 로드합니다. 예에서는 코드를 비동기식으로 가져오도록 DOM 수정을 사용하여 API 코드를 다운로드합니다. 비동기식 다운로드를 사용하도록 설정하는 <script> 태그의 async 속성은 이 스택 오버플로 답변에 설명된 것처럼 아직 일부 최신 브라우저에서는 지원되지 않습니다.
onYouTubeIframeAPIReady 함수는 플레이어 API 코드가 다운로드되는 즉시 실행됩니다. 코드에서 이 부분이 삽입한 동영상 플레이어를 참조하는 전역 변수 player를 정의하며 함수가 동영상 플레이어 개체를 구성합니다.
onReady 이벤트가 실행될 때 onPlayerReady 함수가 실행됩니다. 이 예에서 함수는 동영상 플레이어가 준비되면 재생을 시작해야 함을 나타냅니다.
플레이어의 상태가 변경되면 API가 onPlayerStateChange 함수를 호출하며 이 상태는 플레이어 재생 중, 일시중지됨 및 완료됨 등을 나타낼 수 있습니다. 함수는 플레이어 상태가 1(재생 중)이면 플레이어가 6초 동안 재생한 다음 stopVideo 함수를 호출하여 동영상을 중지해야 함을 나타냅니다.

동영상 플레이어 로드

API의 JavaScript 코드가 로드된 후 API는 YT.Player 개체를 구성하여 페이지에 동영상 플레이어를 삽입할 수 있는 지점에서 onYouTubeIframeAPIReady 함수를 호출합니다. 아래 HTML 발췌 부분에서는 위 예제의 onYouTubeIframeAPIReady 함수를 보여줍니다.

var player;
function onYouTubeIframeAPIReady() {
  player = new YT.Player('player', {
    height: '360',
    width: '640',
    videoId: 'M7lc1UVf-VE',
    events: {
      'onReady': onPlayerReady,
      'onStateChange': onPlayerStateChange
    }
  });
}

동영상 플레이어에 대한 생성자는 다음 매개변수를 지정합니다.

첫 번째 매개변수는 API가 플레이어가 포함된 <iframe> 태그를 삽입할 HTML 요소의 id 또는 DOM 요소를 지정합니다.

IFrame API는 지정한 요소를 플레이어가 포함된 <iframe> 요소로 대체합니다. 그러면 대체되는 요소에 삽입된 <iframe> 요소와 다른 디스플레이 스타일이 있는 경우 페이지의 레이아웃에 영향을 미칠 수 있습니다. 기본적으로 <iframe>은 inline-block 요소로 표시합니다.
두 번째 매개변수는 플레이어 옵션을 지정하는 개체입니다. 개체에는 다음 속성이 포함되어 있습니다.
- width(숫자) – 동영상 플레이어의 너비입니다. 기본값은 640입니다.
- height(숫자) – 동영상 플레이어의 높이입니다. 기본값은 360입니다.
- videoId(문자열) – 플레이어에서 로드할 동영상을 식별하는 YouTube 동영상 ID입니다
- playerVars(개체) – 개체의 속성은 플레이어를 맞춤설정하는 데 사용할 수 있는 플레이어 매개변수를 식별합니다.
- events(개체) – 개체의 속성은 API가 실행하는 이벤트 및 해당 이벤트 발생 시 API가 호출하는 함수(이벤트 리스너)를 식별합니다. 예를 들어 생성자는 onReady 이벤트 실행 시 onPlayerReady 함수가 실행되고 onStateChange 이벤트 실행 시 onPlayerStateChange 함수가 실행됨을 나타냅니다.

시작하기 섹션에서 언급한 것처럼 플레이어 API의 JavaScript 코드가 <iframe> 요소로 대체되는 빈 <div> 요소를 페이지에서 작성하는 대신 <iframe> 태그를 직접 만들 수 있습니다.

<iframe id="player" type="text/html" width="640" height="360"
  src="http://www.youtube.com/embed/M7lc1UVf-VE?enablejsapi=1&origin=http://example.com"
  frameborder="0"></iframe>

<iframe> 태그를 작성하는 경우 YT.Player 개체를 구성할 때 <iframe> 태그의 속성으로 지정되는 width 및 height에 대한 값 또는 src URL에서 지정되는 videoId 및 플레이어 매개변수를 지정할 필요가 없습니다. 또한 추가 보안 수단으로 URL 스키마(http:// 또는 https://)를 지정하여 URL에 origin 매개변수를 포함하고 매개변수 값으로 호스트 페이지의 전체 도메인을 포함해야 합니다. origin은 선택사항이지만 포함할 경우 악성 제3자 JavaScript가 페이지에 삽입되고 YouTube 플레이어의 제어가 무단으로 액세스되는 것을 방지합니다.

예 섹션은 동영상 플레이어 개체 구성에 대한 몇 가지 예를 더 보여줍니다.

연산

플레이어 API 메소드를 호출하려면 먼저 제어하려는 플레이어 개체에 대한 참조를 가져와야 합니다. 이 도움말의 시작하기 및 동영상 플레이어 로드 섹션에 설명된 것처럼 YT.Player 개체를 만들어 참조를 가져옵니다.

함수

대기열 함수

대기열 함수를 사용하면 동영상, 재생목록 또는 다른 동영상 목록을 로드하고 재생할 수 있습니다. 아래에서 설명하는 개체 구문을 사용하여 이러한 함수를 호출하는 경우 검색결과 목록 또는 사용자가 업로드한 동영상 목록을 대기열에 넣거나 로드할 수도 있습니다.

API는 대기열 함수를 호출하기 위한 두 가지 다른 구문을 지원합니다.

인수 구문에는 지정된 순서로 나열되는 함수 구문이 필요합니다.
개체 구문을 통해 개체를 단일 매개변수로 전달하고 설정할 함수 인수에 대해 개체 속성을 정의할 수 있습니다. 또한 API에서 인수 구문이 지원하지 않는 추가 기능을 지원할 수도 있습니다.

예를 들어 loadVideoById 함수를 다음 방법 중 하나로 호출할 수 있습니다. 개체 구문은 인수 구문이 지원하지 않는 endSeconds 속성을 지원한다는 점에 유의하세요.

인수 구문

loadVideoById("bHQqvYy5KYo", 5, "large")

개체 구문

loadVideoById({'videoId': 'bHQqvYy5KYo',
               'startSeconds': 5,
               'endSeconds': 60,
               'suggestedQuality': 'large'});

동영상에 대한 대기열 함수

cueVideoById

인수 구문

player.cueVideoById(videoId:String,
                    startSeconds:Number,
                    suggestedQuality:String):Void

개체 구문

player.cueVideoById({videoId:String,
                     startSeconds:Number,
                     endSeconds:Number,
                     suggestedQuality:String}):Void

이 함수는 지정한 동영상의 미리보기 이미지를 로드하고 플레이어가 동영상을 재생하도록 준비합니다. 플레이어는 playVideo() 또는 seekTo()가 호출되어야 FLV를 요청합니다.

필수인 videoId 매개변수는 재생할 동영상의 YouTube 동영상 ID를 지정합니다. YouTube Data API 동영상 피드에서 <yt:videoid> 태그는 ID를 지정합니다.
선택사항인 startSeconds 매개변수는 부동/정수를 허용하고 playVideo()가 호출되면 동영상의 재생을 시작해야 하는 시간을 지정합니다. startSeconds 값을 지정한 다음 seekTo()를 호출하면 플레이어가 seekTo() 호출에서 지정한 시간부터 재생합니다. 동영상이 신호를 받고 재생할 준비가 되면 플레이어가 video cued 이벤트 (5)를 전달합니다.
개체 구문에서만 지원되는 선택사항인 endSeconds 매개변수는 부동/정수를 허용하고 playVideo()가 호출되면 동영상의 재생을 중지해야 하는 시간을 지정합니다. endSeconds 값을 지정한 다음 seekTo()를 호출하면 endSeconds 값이 더 이상 영향을 미치지 않습니다.
선택사항인 suggestedQuality 매개변수는 동영상의 추천 재생 품질을 지정합니다. 재생 품질에 대한 자세한 내용은 setPlaybackQuality 함수의 정의를 참조하세요.

loadVideoById

Argument syntax

player.loadVideoById(videoId:String,
                     startSeconds:Number,
                     suggestedQuality:String):Void

Object syntax

player.loadVideoById({videoId:String,
                      startSeconds:Number,
                      endSeconds:Number,
                      suggestedQuality:String}):Void

이 함수는 지정한 동영상을 로드하고 재생합니다.

필수인 videoId 매개변수는 재생할 동영상의 YouTube 동영상 ID를 지정합니다. YouTube Data API 동영상 피드에서 <yt:videoid> 태그는 ID를 지정합니다.
선택사항인 startSeconds 매개변수는 부동/정수를 허용합니다. 이 매개변수가 지정되면 동영상이 지정한 시간에 가장 가까운 키프레임에서 시작됩니다.
선택사항인 endSeconds 매개변수는 부동/정수를 허용합니다. 이 매개변수가 지정되면 동영상 재생이 지정한 시간에 중지됩니다.
선택사항인 suggestedQuality 매개변수는 동영상의 추천 재생 품질을 지정합니다. 재생 품질에 대한 자세한 내용은 setPlaybackQuality 함수의 정의를 참조하세요.

cueVideoByUrl

Argument syntax

player.cueVideoByUrl(mediaContentUrl:String,
                     startSeconds:Number,
                     suggestedQuality:String):Void

Object syntax

player.cueVideoByUrl({mediaContentUrl:String,
                      startSeconds:Number,
                      endSeconds:Number,
                      suggestedQuality:String}):Void

필수인 mediaContentUrl 매개변수는 http://www.youtube.com/v/VIDEO_ID?version=3 형식으로 정규화된 YouTube 플레이어 URL을 지정합니다. YouTube Data API 동영상 피드에서 태그의 format 속성에 5의 값이 있으면 <media:content> 태그의 url 속성에 정규화된 플레이어 URL이 포함됩니다.
선택사항인 startSeconds 매개변수는 부동/정수를 허용하고 playVideo()가 호출되면 동영상의 재생을 시작해야 하는 시간을 지정합니다. startSeconds를 지정한 다음 seekTo()를 호출하면 플레이어가 seekTo() 호출에서 지정한 시간부터 재생합니다. 동영상이 신호를 받고 재생할 준비가 되면 플레이어가 video cued 이벤트 (5)를 전달합니다.
개체 구문에서만 지원되는 선택사항인 endSeconds 매개변수는 부동/정수를 허용하고 playVideo()가 호출되면 동영상의 재생을 중지해야 하는 시간을 지정합니다. endSeconds 값을 지정한 다음 seekTo()를 호출하면 endSeconds 값이 더 이상 영향을 미치지 않습니다.
선택사항인 suggestedQuality 매개변수는 동영상의 추천 재생 품질을 지정합니다. 재생 품질에 대한 자세한 내용은 setPlaybackQuality 함수의 정의를 참조하세요.

loadVideoByUrl

Argument syntax

player.loadVideoByUrl(mediaContentUrl:String,
                      startSeconds:Number,
                      suggestedQuality:String):Void

Object syntax

player.loadVideoByUrl({mediaContentUrl:String,
                       startSeconds:Number,
                       endSeconds:Number,
                       suggestedQuality:String}):Void

이 함수는 지정한 동영상을 로드하고 재생합니다.

필수인 mediaContentUrl 매개변수는 http://www.youtube.com/v/VIDEO_ID?version=3 형식으로 정규화된 YouTube 플레이어 URL을 지정합니다. YouTube Data API 동영상 피드에서 태그의 format 속성에 5의 값이 있으면 <media:content> 태그의 url 속성에 정규화된 플레이어 URL이 포함됩니다.
선택사항인 startSeconds 매개변수는 부동/정수를 허용하고 동영상의 재생을 시작해야 하는 시간을 지정합니다. startSeconds(숫자는 부동일 수 있음)가 지정된 경우 동영상은 지정한 시간에 가장 가까운 키프레임부터 시작됩니다.
개체 구문에서만 지원되는 선택사항인 endSeconds 매개변수는 부동/정수를 허용하고 동영상의 재생을 중지해야 하는 시간을 지정합니다.
선택사항인 suggestedQuality 매개변수는 동영상의 추천 재생 품질을 지정합니다. 재생 품질에 대한 자세한 내용은 setPlaybackQuality 함수의 정의를 참조하세요.

목록에 대한 대기열 함수

cuePlaylist 및 loadPlaylist 함수를 사용하면 재생목록 또는 동영상 목록을 로드하고 재생할 수 있습니다. 개체 구문을 사용하여 이러한 함수를 호출하는 경우 검색결과 목록 또는 사용자가 업로드한 동영상 목록을 대기열에 넣거나 로드할 수도 있습니다.

함수는 인수 구문을 사용하여 호출하는지 개체 구문을 사용하여 호출하는지에 따라 다르게 작동하므로 두 호출 메소드는 아래에 설명되어 있습니다.

cuePlaylist

Argument syntax
```
player.cuePlaylist(playlist:String|Array,
                   index:Number,
                   startSeconds:Number,
                   suggestedQuality:String):Void
```
지정한 재생목록을 대기열에 넣습니다. 재생목록이 신호를 받고 재생할 준비가 되면 플레이어가 video cued 이벤트 (5)를 전달합니다.
- 필수인 playlist 매개변수는 YouTube 동영상 ID의 배열을 지정합니다. YouTube Data API 피드에서 <yt:videoid> 태그는 동영상 ID를 지정합니다.
- 선택사항인 index 매개변수는 재생할 재생목록에 있는 첫 번째 동영상의 색인을 지정합니다. 매개변수는 0부터 시작하는 색인을 사용하며 기본 매개변수 값이 0이므로 기본 동작은 재생목록에 있는 첫 번째 동영상을 로드하고 재생하는 것입니다.
- 선택사항인 startSeconds 매개변수는 부동/정수를 허용하고 playVideo() 함수가 호출되면 재생목록에 있는 첫 번째 동영상의 재생을 시작해야 하는 시간을 지정합니다. startSeconds 값을 지정한 다음 seekTo()를 호출하면 플레이어가 seekTo() 호출에서 지정한 시간부터 재생합니다. 재생목록에 신호를 준 다음 playVideoAt() 함수를 호출하면 플레이어가 지정한 동영상의 시작 부분에서 재생을 시작합니다.
- 선택사항인 suggestedQuality 매개변수는 동영상의 추천 재생 품질을 지정합니다. 재생 품질에 대한 자세한 내용은 setPlaybackQuality 함수의 정의를 참조하세요.
개체 구문
```
player.cuePlaylist({listType:String,
                    list:String,
                    index:Number,
                    startSeconds:Number,
                    suggestedQuality:String}):Void
```
지정한 동영상의 목록을 대기열에 넣습니다. 목록은 재생목록, 검색결과 피드 또는 사용자가 업로드한 동영상 피드일 수 있습니다. 목록이 신호를 받고 재생할 준비가 되면 플레이어가 video cued 이벤트 (5)를 전달합니다.
- 선택사항인 listType 속성은 가져오는 결과 피드의 유형을 지정합니다. 유효한 값은 playlist, search 및 user_uploads이며 기본값은 playlist입니다.
- 필수인 list 속성에는 YouTube에서 반환해야 하는 특정 동영상의 목록을 식별하는 키가 포함되어 있습니다.
  - listType 속성 값이 playlist인 경우 list 속성이 재생목록 ID 또는 동영상 ID의 배열을 지정합니다. YouTube Data API 피드에서 <yt:playlistid> 태그는 재생목록 ID를 지정하고 <yt:videoid> 태그는 동영상 ID를 지정합니다.
  - listType 속성 값이 search인 경우 list 속성이 검색어를 지정합니다.
  - listType 속성 값이 user_uploads인 경우 list 속성이 반환할 동영상을 업로드한 사용자를 식별합니다.
- 선택사항인 index 속성은 재생할 목록에 있는 첫 번째 동영상의 색인을 지정합니다. 매개변수는 0부터 시작하는 색인을 사용하며 기본 매개변수 값이 0이므로 기본 동작은 목록에 있는 첫 번째 동영상을 로드하고 재생하는 것입니다.
- 선택사항인 startSeconds 속성은 부동/정수를 허용하고 playVideo() 함수가 호출되면 재생목록에 있는 첫 번째 동영상의 재생을 시작해야 하는 시간을 지정합니다. startSeconds 값을 지정한 다음 seekTo()를 호출하면 플레이어가 seekTo() 호출에서 지정한 시간부터 재생합니다. 목록에 신호를 준 다음 playVideoAt() 함수를 호출하면 플레이어가 지정한 동영상의 시작 부분에서 재생을 시작합니다.
- 선택사항인 suggestedQuality 속성은 목록의 동영상에 대한 추천 재생 품질을 지정합니다. 재생 품질에 대한 자세한 내용은 setPlaybackQuality 함수의 정의를 참조하세요.

loadPlaylist

Argument syntax
```
player.loadPlaylist(playlist:String|Array,
                    index:Number,
                    startSeconds:Number,
                    suggestedQuality:String):Void
```
이 함수는 지정한 재생목록을 로드하고 재생합니다.
- 필수인 playlist 매개변수는 YouTube 동영상 ID의 배열을 지정합니다. YouTube Data API 피드에서 <yt:videoid> 태그는 동영상 ID를 지정합니다.
- 선택사항인 index 매개변수는 재생할 재생목록에 있는 첫 번째 동영상의 색인을 지정합니다. 매개변수는 0부터 시작하는 색인을 사용하며 기본 매개변수 값이 0이므로 기본 동작은 재생목록에 있는 첫 번째 동영상을 로드하고 재생하는 것입니다.
- 선택사항인 startSeconds 매개변수는 부동/정수를 허용하고 재생목록에 있는 첫 번째 동영상의 재생을 시작해야 하는 시간을 지정합니다.
- 선택사항인 suggestedQuality 매개변수는 동영상의 추천 재생 품질을 지정합니다. 재생 품질에 대한 자세한 내용은 setPlaybackQuality 함수의 정의를 참조하세요.
Object syntax
```
player.loadPlaylist({list:String,
                     listType:String,
                     index:Number,
                     startSeconds:Number,
                     suggestedQuality:String}):Void
```
이 함수는 지정한 목록을 로드하고 재생합니다. 목록은 재생목록, 검색결과 피드 또는 사용자가 업로드한 동영상 피드일 수 있습니다.
- 선택사항인 listType 속성은 가져오는 결과 피드의 유형을 지정합니다. 유효한 값은 playlist, search 및 user_uploads이며 기본값은 playlist입니다.
- 필수인 list 속성에는 YouTube에서 반환해야 하는 특정 동영상의 목록을 식별하는 키가 포함되어 있습니다.
  - listType 속성 값이 playlist인 경우 list 속성이 재생목록 ID 또는 동영상 ID의 배열을 지정합니다. YouTube Data API 피드에서 <yt:playlistid> 태그는 재생목록 ID를 지정하고 <yt:videoid> 태그는 동영상 ID를 지정합니다.
  - listType 속성 값이 search인 경우 list 속성이 검색어를 지정합니다.
  - listType 속성 값이 user_uploads인 경우 list 속성이 반환할 동영상을 업로드한 사용자를 식별합니다.
- 선택사항인 index 속성은 재생할 목록에 있는 첫 번째 동영상의 색인을 지정합니다. 매개변수는 영(zero)부터 시작하는 색인을 사용하며 기본 매개변수 값이 0이므로 기본 동작은 목록에 있는 첫 번째 동영상을 로드하고 재생하는 것입니다.
- 선택사항인 startSeconds 속성은 부동/정수를 허용하고 목록에 있는 첫 번째 동영상의 재생을 시작해야 하는 시간을 지정합니다.
- 선택사항인 suggestedQuality 속성은 목록의 동영상에 대한 추천 재생 품질을 지정합니다. 재생 품질에 대한 자세한 내용은 setPlaybackQuality 함수의 정의를 참조하세요.

재생 컨트롤 및 플레이어 설정

동영상 재생

player.playVideo():Void: 현재 신호를 준 동영상과 로드한 동영상을 재생합니다. 이 함수를 실행한 후 플레이어의 마지막 상태는 playing(1)입니다.

참고: 플레이어의 기본 재생 버튼을 통해 시작되는 경우 재생은 동영상의 공식 조회수에만 포함됩니다.

player.pauseVideo():Void: 현재 재생 중인 동영상을 일시중지합니다. 함수가 호출될 때 플레이어 상태가 변경되지 않는 ended(0) 상태에 있지 않는 한 이 함수를 실행한 후 플레이어의 마지막 상태는 paused(2)입니다.

player.stopVideo():Void: 현재 동영상의 로드를 중지하고 취소합니다. 이 함수는 사용자가 플레이어에서 추가 동영상을 보지 않을 것을 알고 있는 드문 경우에 사용해야 합니다. 동영상을 일시중지하려는 경우에는 pauseVideo 함수를 호출해야 합니다. 플레이어가 재생 중인 동영상을 변경하려는 경우 stopVideo를 먼저 호출하지 않고 대기열 함수 중 하나를 호출할 수 있습니다.

중요: pauseVideo 함수처럼 플레이어를 paused (2) 상태로 남겨두는 것과 달리 stopVideo 함수는 플레이어를 ended (0), paused (2), video cued (5) 또는 unstarted (-1)를 비롯한 재생 중이 아닌 상태로 둘 수 있습니다.

player.seekTo(seconds:Number, allowSeekAhead:Boolean):Void

동영상에서 지정한 시간을 찾습니다. 함수가 호출될 때 플레이어가 일시중지되면 일시중지로 유지됩니다. 함수가 다른 상태(playing, video cued 등)에서 호출되면 플레이어가 동영상을 재생합니다.

seconds 매개변수는 플레이어가 진행해야 하는 시간을 식별합니다.

플레이어에서 사용자가 찾고 있는 동영상의 부분을 이미 다운로드하지 않은 한 플레이어는 해당 시간 직전의 가장 가까운 키프레임으로 진행합니다. 이 경우 Flash 플레이어의 NetStream 개체의 seek() 메소드로 지시한 것처럼 플레이어가 지정한 시간 직전이나 직후의 가장 가까운 키프레임으로 진행합니다. 자세한 내용은 Adobe의 도움말을 참조하세요.
allowSeekAhead 매개변수는 seconds 매개변수가 현재 버퍼링된 동영상 데이터를 벗어난 시간을 지정한 경우 플레이어가 서버에 새로운 요청을 할지 여부를 결정합니다.

사용자가 동영상 진행률 표시줄을 따라 마우스를 드래그하는 동안 이 매개변수를 false로 설정한 다음 사용자가 마우스에서 손을 떼면 true로 설정하는 것이 좋습니다. 이 방법을 통해 사용자가 새 동영상 스트림을 요청하지 않고 동영상에서 이전에 버퍼링되지 않은 지점으로 스크롤하여 동영상의 다른 지점으로 스크롤할 수 있습니다. 사용자가 마우스 버튼에서 손을 떼면 플레이어가 동영상에서 원하는 위치로 진행하고 필요한 경우 새 동영상 스트림을 요청합니다.

player.clearVideo():Void: 동영상 표시를 지웁니다. 이 함수는 stopVideo() 호출 후 잔여 동영상을 지우려는 경우에 유용합니다. 이 함수는 ActionScript 3.0 Player API에서 지원 중단되었다는 점에 유의하세요.

재생목록의 동영상 재생

player.nextVideo():Void

이 함수는 재생목록에서 다음 동영상을 로드하고 재생합니다.

재생목록이 연속 재생(loop)으로 설정되어 있고 재생목록의 마지막 동영상을 시청하는 동안 player.nextVideo()를 호출하면 플레이어가 목록의 첫 번째 동영상을 로드하고 재생합니다.
재생목록이 연속 재생으로 설정되어 있지 않고 재생목록의 마지막 동영상을 시청하는 동안 player.nextVideo()를 호출하면 재생이 종료됩니다.

player.previousVideo():Void

이 함수는 재생목록에서 이전 동영상을 로드하고 재생합니다.

재생목록이 연속 재생(loop)으로 설정되어 있고 재생목록의 첫 번째 동영상을 시청하는 동안 player.previousVideo()를 호출하면 플레이어가 목록의 마지막 동영상을 로드하고 재생합니다.
재생목록이 연속 재생으로 설정되어 있지 않고 재생목록의 첫 번째 동영상을 시청하는 동안 player.previousVideo()를 호출하면 플레이어가 처음부터 첫 번째 재생목록 동영상을 다시 시작합니다.

player.playVideoAt(index:Number):Void

이 함수는 재생목록에서 지정한 동영상을 로드하고 재생합니다.

필수인 index 매개변수는 재생목록에서 재생하려는 동영상의 색인을 지정합니다. 매개변수는 0부터 시작하는 색인을 사용하므로 0의 값은 목록에서 첫 번째 동영상을 식별합니다. 재생목록에서 셔플을 사용한 경우 이 함수는 셔플을 사용한 재생목록의 지정한 위치에서 동영상을 재생합니다.

플레이어 볼륨 변경

player.mute():Void: 플레이어를 음소거합니다.

player.unMute():Void: 플레이어 음소거를 해제합니다.

player.isMuted():Boolean: 플레이어가 음소거 상태인 경우 true를 반환하고 음소거 상태가 아닌 경우 false를 반환합니다.

player.setVolume(volume:Number):Void: 볼륨을 설정합니다. 0에서 100 사이의 정수를 허용합니다.

player.getVolume():Number: 플레이어의 현재 볼륨을 0에서 100 사이의 정수로 반환합니다. 플레이어가 음소거 상태인 경우에도 getVolume()이 볼륨을 반환한다는 점에 유의하세요.

플레이어 크기 설정

player.setSize(width:Number, height:Number):Object: 플레이어가 포함된 <iframe>의 크기를 픽셀 단위로 설정합니다.

재생 속도 설정

player.getPlaybackRate():Number: 이 함수는 현재 재생 중인 동영상의 재생 속도를 가져옵니다. 기본 재생 속도는 1이며 동영상이 일반적인 속도로 재생되고 있음을 나타냅니다. 재생 속도에는 0.25, 0.5, 1, 1.5 및 2와 같은 값이 포함될 수 있습니다.

player.setPlaybackRate(suggestedRate:Number):Void: 이 함수는 현재 동영상에 대한 추천 재생 속도를 설정합니다. 재생 속도가 변경되면 이미 신호를 주었거나 재생 중인 동영상에 대해서만 변경됩니다. 신호를 준 동영상에 대해 재생 속도를 설정한 경우 playVideo 함수를 호출하거나 사용자가 플레이어 컨트롤을 통해 직접 재생을 시작하면 해당 속도가 계속 영향을 미칩니다. 또한 함수(cueVideoById, loadVideoById 등)를 호출하여 동영상 또는 재생목록에 신호를 주거나 로드하면 재생 속도가 1로 재설정됩니다.

이 함수를 호출해도 재생 속도가 실제로 변경되지 않을 가능성이 있습니다. 그러나 재생 속도가 변경되면 onPlaybackRateChange 이벤트가 실행되고, 코드가 setPlaybackRate 함수를 호출하기 보다는 이벤트에 응답해야 합니다.

getAvailablePlaybackRates 메소드는 현재 재생 중인 동영상에 가능한 재생 속도를 반환합니다. 그러나 suggestedRate 매개변수를 지원되지 않는 정수 또는 부동 값으로 설정하면 플레이어가 해당 값을 1의 방향으로 가장 가까운 지원되는 값으로 자릅니다.

player.getAvailablePlaybackRates():Array: 이 함수는 현재 동영상에서 사용할 수 있는 재생 속도의 모음을 반환합니다. 기본값은 1이며 동영상이 일반적인 속도로 재생되고 있음을 나타냅니다.

함수는 가장 느린 재생 속도에서 가장 빠른 재생 속도 순으로 숫자 배열을 반환합니다. 플레이어가 가변 재생 속도를 지원하지 않는 경우에도 배열에는 항상 하나 이상의 값(1)이 포함되어야 합니다.

재생목록의 재생 동작 설정

player.setLoop(loopPlaylists:Boolean):Void

이 함수는 재생목록의 마지막 동영상이 종료된 후 동영상 플레이어가 재생목록을 연속 재생할지 아니면 재생을 중지해야 할지를 나타냅니다. 기본 동작은 재생목록을 연속 재생하지 않는 것입니다.

이 설정은 다른 재생목록을 로드하거나 신호를 주는 경우에도 유지됩니다. 즉, 재생목록을 로드하고 true 값으로 setLoop 함수를 호출한 다음 두 번째 재생목록을 로드하면 두 번째 재생 목록도 연속 재생됩니다.

필수인 loopPlaylists 매개변수는 연속 재생 동작을 식별합니다.

매개변수 값이 true이면 동영상 플레이어가 재생목록을 연속해서 재생합니다. 재생목록의 마지막 동영상을 재생한 후 동영상 플레이어가 재생목록의 시작 부분으로 돌아가서 다시 재생합니다.
매개변수 값이 false이면 동영상 플레이어가 재생목록의 마지막 동영상을 재생한 후 재생이 종료됩니다.

player.setShuffle(shufflePlaylist:Boolean):Void

이 함수는 재생목록 제작자가 지정한 순서와 다른 순서로 재생되도록 재생목록의 동영상에 셔플을 사용해야 하는지 여부를 나타냅니다. 이미 재생이 시작된 후에 재생목록에 셔플을 사용하면 재생 중인 동영상이 계속 재생되는 동안 목록의 순서가 변경됩니다. 그러면 재생될 다음 동영상은 순서가 변경된 목록에 따라 선택됩니다.

이 설정은 다른 재생목록을 로드하거나 신호를 주면 유지되지 않습니다. 즉, 재생목록을 로드하고 setShuffle 함수를 호출한 다음 두 번째 재생목록을 로드하면 두 번째 재생목록에서 셔플을 사용하지 않습니다.

필수인 shufflePlaylist 매개변수는 YouTube에서 재생목록에 셔플을 사용해야 하는지 여부를 나타냅니다.

매개변수 값이 true이면 YouTube에서 재생목록 순서에 셔플을 사용합니다. 이미 셔플을 사용하는 재생목록에 셔플을 사용하도록 함수에 지시하면 YouTube에서 다시 순서에 셔플을 사용합니다.
매개변수 값이 false이면 YouTube에서 재생목록 순서를 원래 순서로 다시 변경합니다.

재생 상태

player.getVideoLoadedFraction():Float: 버퍼링에 따라 플레이어에서 표시하는 동영상의 비율을 0에서 1 사이의 숫자로 반환합니다. 이 메소드는 현재 지원 중단된 getVideoBytesLoaded 및 getVideoBytesTotal 메소드보다 좀 더 신뢰할 수 있는 숫자를 반환합니다.

player.getPlayerState():Number

플레이어의 상태를 반환합니다. 가능한 값은 다음과 같습니다.

-1 –시작되지 않음
0 – 종료
1 – 재생 중
2 – 일시중지
3 – 버퍼링
5 – 동영상 신호

player.getCurrentTime():Number: 동영상 재생이 시작된 이후의 경과 시간을 초 단위로 반환합니다.

player.getVideoStartBytes():Number: 2012년 10월 31일부터 지원 중단되었습니다. 동영상 파일의 로드가 시작되는 바이트 수를 반환합니다. 이제 이 메소드는 항상 0의 값을 반환합니다. 상황 예: 사용자가 아직 로드되지 않은 앞부분을 찾고 플레이어가 아직 로드되지 않은 동영상의 세그먼트를 재생하기 위해 새로 요청합니다.

player.getVideoBytesLoaded():Number: 2012년 7월 18일부터 지원 중단되었습니다. 대신 getVideoLoadedFraction 메소드를 사용하여 버퍼링된 동영상의 비율을 결정합니다.

이 메소드는 로드된 동영상의 양에 가까운 0에서 1000 사이의 값을 반환합니다. getVideoBytesLoaded 값을 getVideoBytesTotal 값으로 나눠 로드된 동영상의 부분을 계산할 수 있습니다.

player.getVideoBytesTotal():Number: 2012년 7월 18일부터 지원 중단되었습니다. 대신 getVideoLoadedFraction 메소드를 사용하여 버퍼링된 동영상의 비율을 결정합니다.

현재 로드되었거나 재생 중인 동영상의 크기 또는 동영상 크기의 근사값을 바이트 단위로 반환합니다.

이 메소드는 항상 1000의 값을 반환합니다. getVideoBytesLoaded 값을 getVideoBytesTotal 값으로 나눠 로드된 동영상의 부분을 계산할 수 있습니다.

재생 품질

player.getPlaybackQuality():String: 이 함수는 현재 동영상의 실제 동영상 품질을 가져옵니다. 가능한 반환 값은 highres, hd1080, hd720, large, medium 및 small입니다. 또한 현재 동영상이 없는 경우 undefined를 반환합니다.

player.setPlaybackQuality(suggestedQuality:String):Void

이 함수는 현재 동영상에 대한 추천 동영상 품질을 설정합니다. 이 함수로 동영상이 새 품질로 현재 위치에 다시 로드됩니다. 재생 품질이 변경되면 재생 중인 동영상에 대해서만 변경됩니다. 이 함수를 호출해도 재생 품질이 실제로 변경되지 않을 가능성이 있습니다. 그러나 재생 품질이 변경되면 onPlaybackQualityChange 이벤트가 실행되고, 코드가 setPlaybackQuality 함수를 호출하기 보다는 이벤트에 응답해야 합니다.

suggestedQuality 매개변수 값은 small, medium, large, hd720, hd1080, highres 또는 default일 수 있습니다. 매개변수 값을 YouTube에 가장 적절한 재생 품질을 선택하도록 지시하는 default로 설정하는 것이 좋습니다. 재생 품질은 사용자, 동영상, 시스템 및 기타 재생 상태마다 다릅니다.

동영상에 대한 재생 품질을 추천하면 추천 품질은 해당 동영상에만 영향을 미칩니다. 동영상 플레이어의 크기에 해당하는 재생 품질을 선택해야 합니다. 예를 들어 페이지에서 1280x720픽셀의 동영상 플레이어를 표시하는 경우 hd720 품질의 동영상이 실제로 hd1080 품질의 동영상보다 잘 표시됩니다. getAvailableQualityLevels() 함수를 호출하여 동영상에 사용할 수 있는 품질 수준을 결정하는 것이 좋습니다.

아래 목록은 여러 표준 플레이어 크기에 해당하는 재생 품질 수준을 보여줍니다. 동영상 플레이어의 높이를 아래에 나열된 값 중 하나로 설정하고 플레이어의 크기를 16:9 영상비로 지정하는 것이 좋습니다. 위에서 설명한 것처럼 표준 플레이어 크기를 선택한 경우에도 suggestedQuality 매개변수 값을 default로 설정하여 YouTube에서 가장 적절한 재생 품질을 선택하도록 사용 설정하는 것이 좋습니다.

품질 수준 small: 플레이어 높이가 240픽셀이며 플레이어 크기는 최소 320x240픽셀(4:3 영상비입니다.
품질 수준 medium: 플레이어 높이가 360픽셀이며 플레이어 크기는 640x360픽셀(16:9 영상비) 또는 480x360픽셀(4:3 영상비)입니다.
품질 수준 large: 플레이어 높이가 480픽셀이며 플레이어 크기는 853x480픽셀(16:9 영상비) 또는 640x480(4:3 영상비)입니다.
품질 수준 hd720: 플레이어 높이가 720픽셀이며 플레이어 크기는 1280x720픽셀(16:9 영상비) 또는 960x720픽셀(4:3 영상비)입니다.
품질 수준 hd1080: 플레이어 높이가 1080픽셀이며 플레이어 크기는 1920x1080픽셀(16:9 영상비) 또는 1440x1080픽셀(4:3 영상비)입니다.
품질 수준 highres: 플레이어 높이가 1080픽셀보다 큽니다. 따라서 해당 플레이어의 영상비가 1920x1080픽셀보다 큽니다.
품질 수준 default: YouTube에서 적절한 재생 품질을 선택합니다. 이 설정은 효과적으로 품질 수준을 기본 상태로 되돌리고 cueVideoById, loadVideoById 또는 setPlaybackQuality 함수를 사용하여 기존에 설정한 재생 품질을 무효화합니다.

동영상에 사용할 수 없는 suggestedQuality 수준으로 setPlaybackQuality 함수를 호출하면 품질이 그 다음으로 낮은 사용할 수 있는 수준으로 설정됩니다. 예를 들어 사용할 수 없는 large의 품질 수준을 요청한 경우 medium 품질 수준을 사용할 수 있으면 재생 품질이 해당 수준으로 설정됩니다.

또한 인식할 수 없는 품질 수준인 값으로 suggestedQuality를 설정하는 것은 suggestedQuality를 default로 설정하는 것과 동일합니다.

player.getAvailableQualityLevels():Array: 이 함수는 현재 동영상에서 사용할 수 있는 품질 형식의 모음을 반환합니다. 이 함수를 사용하여 사용자가 보고 있는 품질보다 더 높은 품질로 동영상을 사용할 수 있는지 여부 및 사용자가 품질을 조정할 수 있는 버튼이나 다른 요소를 플레이어에 표시할 수 있는지 여부를 결정할 수 있습니다.

함수는 가장 높은 품질에서 가장 낮은 품질 순으로 문자열 배열을 반환합니다. 가능한 배열 요소 값은 highres, hd1080, hd720, large, medium 및 small입니다. 이 함수는 현재 동영상이 없는 경우 빈 배열을 반환합니다.

클라이언트가 자동으로 가장 높거나 가장 낮은 품질의 동영상을 사용하도록 전환하거나 알 수 없는 형식 이름으로 전환해서는 안 됩니다. YouTube에서는 품질 수준의 목록을 확장하여 플레이어 문맥에 적절하지 않을 수도 있는 형식을 포함할 수 있습니다. 마찬가지로 YouTube에서는 사용자 환경에 유해한 품질 옵션을 삭제할 수 있습니다. 클라이언트가 사용할 수 있는 알려진 형식으로만 전환하면 새로운 품질 수준을 추가하거나 플레이어 문맥에 적절하지 않은 품질 수준을 삭제해도 클라이언트의 성능에 영향을 미치지 않습니다.

동영상 정보 가져오기

player.getDuration():Number: 현재 재생 중인 동영상의 재생 시간을 초 단위로 반환합니다. 동영상의 메타데이터가 로드되기 전에는 getDuration()이 0을 반환하며 일반적으로 동영상 재생이 시작된 직후에 발생한다는 점에 유의하세요.

현재 재생 중인 동영상이 실시간 이벤트인 경우 getDuration() 함수가 실시간 동영상 스트리밍이 시작된 이후의 경과 시간을 반환합니다. 특히 이 시간은 동영상이 재설정되거나 중단되지 않고 스트리밍된 시간입니다. 또한 이 경과 시간은 스트리밍이 이벤트의 시작 시간 전에 시작될 수 있으므로 일반적으로 실제 이벤트 시간보다 깁니다.

player.getVideoUrl():String: 현재 로드되었거나 재생 중인 동영상의 YouTube.com URL을 반환합니다.

player.getVideoEmbedCode():String: 현재 로드되었거나 재생 중인 동영상의 삽입 코드를 반환합니다.

재생목록 정보 가져오기

player.getPlaylist():Array: 이 함수는 현재 순서에 따라 재생목록에 있는 동영상 ID의 배열을 반환합니다. 기본적으로 이 함수는 재생목록 소유자가 지정한 순서로 동영상 ID를 반환합니다. 그러나 setShuffle 함수를 호출하여 재생목록 순서에 셔플을 사용한 경우에는 getPlaylist() 함수의 반환 값이 셔플을 사용한 순서를 반영합니다.

player.getPlaylistIndex():Number

이 함수는 현재 재생 중인 재생목록 동영상의 색인을 반환합니다.

재생목록에 셔플을 사용하지 않은 경우 반환 값은 재생목록 제작자가 동영상을 배치한 위치를 식별합니다. 반환 값은 0부터 시작하는 색인을 사용하므로 0의 값은 재생목록에서 첫 번째 동영상을 식별합니다.
재생목록에 셔플을 사용한 경우 반환 값은 셔플을 사용한 재생목록 내의 동영상 순서를 식별합니다.

이벤트 리스너 추가 및 삭제

player.addEventListener(event:String, listener:String):Void: 지정한 event에 대한 리스너 함수를 추가합니다. 아래의 이벤트 섹션은 플레이어가 실행할 수 있는 여러 이벤트를 식별합니다. 리스너는 지정한 이벤트가 실행될 때 실행되는 함수를 지정하는 문자열입니다.

player.removeEventListener(event:String, listener:String):Void: 지정한 event에 대한 리스너 함수를 삭제합니다. listener는 지정한 이벤트가 실행될 때 더 이상 실행되지 않는 함수를 지정하는 문자열입니다.

DOM 노드 액세스 및 수정

player.getIframe():Object: 이 메소드는 삽입된 <iframe>에 대한 DOM 노드를 반환합니다.

player.destroy():Void: 플레이어가 포함된 <iframe>을 삭제합니다.

이벤트

API는 이벤트를 실행하여 내장 플레이어의 변경사항을 애플리케이션에 알립니다. 이전 섹션에서 설명한 것처럼 YT.Player 개체 구성 시 이벤트 리스너를 추가하여 이벤트를 수신할 수 있으며 addEventListener 함수를 사용할 수도 있습니다.

API가 이벤트 개체를 단일 인수로 이러한 각 함수에 전달합니다. 이벤트 개체에는 다음 속성이 있습니다.

이벤트의 target은 이벤트에 해당하는 동영상 플레이어를 식별합니다.
이벤트의 data는 이벤트에 관련된 값을 지정합니다. onReady 이벤트는 data 속성을 지정하지 않는다는 점에 유의하세요.

다음 목록은 API가 실행하는 이벤트를 정의합니다.

onReady

이 이벤트는 플레이어 로드가 완료되고 API 호출을 받을 준비가 될 때마다 실행됩니다. 플레이어가 준비되는 즉시 특정 작업(예: 동영상 재생 또는 동영상에 대한 정보 표시)을 자동으로 실행하려면 애플리케이션에서 이 함수를 구현해야 합니다.

아래 예에서는 이러한 이벤트 처리를 위한 샘플 함수를 보여줍니다. API가 함수에 전달하는 이벤트 개체에는 플레이어를 식별하는 target 속성이 있습니다. 함수는 현재 로드된 동영상에 대한 Embed 태그를 가져오고, 동영상 재생을 시작하고, embed-code의 id 값이 있는 페이지 요소에서 Embed 태그를 표시합니다.

function onPlayerReady(event) {
  var embedCode = event.target.getVideoEmbedCode();
  event.target.playVideo();
  if (document.getElementById('embed-code')) {
    document.getElementById('embed-code').innerHTML = embedCode;
  }
}

onStateChange

이 이벤트는 플레이어의 상태가 변경될 때마다 실행됩니다.

API가 이벤트 리스너 함수에 전달하는 이벤트 개체의 data 속성은 새 플레이어 상태에 해당하는 정수를 지정합니다. 가능한 값은 다음과 같습니다.

-1(시작되지 않음)
0(종료됨)
1(재생 중)
2(일시중지됨)
3(버퍼링 중)
5(동영상 신호)

플레이어가 동영상을 처음 로드하면 시작되지 않은(-1) 이벤트를 전달합니다. 동영상이 신호를 받고 재생할 준비가 되면 플레이어가 동영상 신호(5) 이벤트를 전달합니다. 코드에서 정수 값을 지정하거나 다음 네임스페이스가 지정된 변수 중 하나를 사용할 수 있습니다.

YT.PlayerState.ENDED
YT.PlayerState.PLAYING
YT.PlayerState.PAUSED
YT.PlayerState.BUFFERING
YT.PlayerState.CUED

onPlaybackQualityChange

이 이벤트는 동영상 재생 품질이 변경될 때마다 실행됩니다. 예를 들어 setPlaybackQuality(suggestedQuality) 함수를 호출하는 경우 재생 품질이 실제로 변경되면 이 이벤트가 실행됩니다. 애플리케이션이 이벤트에 응답해야 하며 setPlaybackQuality(suggestedQuality) 함수가 호출될 때 품질이 자동으로 변경된다고 가정해서는 안 됩니다. 마찬가지로 코드에서 재생 품질이 setPlaybackQuality의 명시적 호출 또는 추전 재생 품질을 설정할 수 있는 다른 함수에 의해서만 변경된다고 가정해서는 안 됩니다.

API가 이벤트 리스너 함수에 전달하는 이벤트 개체의 data 속성 값은 새 재생 품질을 식별하는 문자열입니다. 가능한 값은 다음과 같습니다.

small
medium
large
hd720
hd1080
highres

onPlaybackRateChange: 이 이벤트는 동영상 재생 속도가 변경될 때마다 실행됩니다. 예를 들어 setPlaybackRate(suggestedRate) 함수를 호출하는 경우 재생 속도가 실제로 변경되면 이 이벤트가 실행됩니다. 애플리케이션이 이벤트에 응답해야 하며 setPlaybackRate(suggestedRate) 함수가 호출될 때 재생 속도가 자동으로 변경된다고 가정해서는 안 됩니다. 마찬가지로 코드에서 setPlaybackRate의 명시적 호출에 의해서만 동영상 재생 속도가 변경된다고 가정해서는 안 됩니다.

API가 이벤트 리스너 함수에 전달하는 이벤트 개체의 data 속성 값은 새 재생 속도를 식별하는 숫자입니다. getAvailablePlaybackRates 메소드는 현재 신호를 주었거나 재생 중인 동영상에 대한 유효한 재생 속도의 목록을 반환합니다.

onError

이 이벤트는 플레이어에서 오류가 발생하면 실행됩니다.

API는 이벤트 리스너 함수에 event 개체를 전달합니다. 개체의 data 속성은 발생한 오류의 유형을 식별하는 정수를 지정합니다. 가능한 값은 다음과 같습니다.

2 – 요청에 잘못된 매개변수 값이 포함되어 있습니다. 예를 들어 11자리가 아닌 동영상 ID를 지정하거나 동영상 ID에 느낌표 또는 별표와 같은 잘못된 문자가 포함된 경우에 이 오류가 발생합니다.
5 – 요청한 콘텐츠를 HTML5 플레이어에서 재생할 수 없거나 HTML5 플레이어와 관련된 다른 오류가 발생했습니다.
100 – 요청한 동영상을 찾을 수 없습니다. 어떠한 이유로든 동영상이 삭제되었거나 비공개로 표시된 경우에 이 오류가 발생합니다.
101 – 요청한 동영상의 소유자가 내장 플레이어에서 동영상을 재생하는 것을 허용하지 않습니다.
150 – 이 오류는 101과 동일하며 변형된 101 오류입니다.

onApiChange

이 이벤트는 플레이어가 공개 API 메소드로 모듈을 로드하거나 언로드했는지 나타내기 위해 실행됩니다. 애플리케이션은 이 이벤트를 수신한 다음 플레이어를 폴링하여 최근에 로드된 모듈에 노출되는 옵션을 결정할 수 있습니다. 그런 다음 애플리케이션이 이러한 옵션에 대해 기존 설정을 가져오거나 업데이트할 수 있습니다.

다음 명령은 플레이어 옵션을 설정할 수 있는 모듈 이름의 배열을 가져옵니다.

player.getOptions();

현재 플레이어에서 자막을 처리하는 cc 모듈에 대해서만 옵션을 설정할 수 있습니다. onApiChange 이벤트를 가져오면 애플리케이션은 다음 명령을 사용하여 cc 모듈에 설정할 수 있는 옵션을 결정할 수 있습니다.

player.getOptions('cc');

이 명령으로 플레이어를 폴링하여 액세스하려는 옵션에 실제로 액세스할 수 있는지 확인할 수 있습니다. 다음 명령은 모듈 옵션을 가져오고 업데이트합니다.

옵션 가져오기:
player.getOption(module, option);

옵션 설정
player.setOption(module, option, value);

아래 표에는 API가 지원하는 옵션이 제시되어 있습니다.

모듈	옵션	설명
cc	fontSize	이 옵션은 플레이어에 표시되는 캡션의 글꼴 크기를 조정합니다. 유효한 값은 `-1`, `0`, `1`, `2` 및 `3`입니다. 기본 크기는 `0`이며 가장 작은 크기는 `-1`입니다. 이 옵션을 `-1` 미만의 정수로 설정하면 가장 작은 캡션 크기가 표시되는 반면 이 옵션을 `3`을 초과하는 정수로 설정하면 가장 큰 캡션 크기가 표시됩니다.
cc	reload	이 옵션은 재생 중인 동영상에 대한 캡션 데이터를 다시 로드합니다. 옵션의 값을 가져오는 경우 값이 `null`입니다. 캡션 데이터를 다시 로드하려면 값을 `true`로 설정합니다.

모바일 고려사항

자동 재생 및 스크립트 재생

특정 모바일 브라우저(예: Chrome 및 Safari)의 HTML5 <video> 요소는 사용자 상호작용(예: 플레이어에서 탭하기)으로 시작되는 경우에만 재생되도록 허용합니다. 다음은 Apple의 도움말에서 발췌한 내용입니다.

'경고: 데이터 네트워크에서 사용자에게 비용이 부과되는 원하지 않는 다운로드가 발생하는 것을 방지하기 위해 삽입된 미디어는 iOS의 Safari에서 자동으로 재생될 수 없습니다. 항상 사용자가 재생을 시작합니다.'

이러한 제한으로 인해 autoplay, playVideo(), loadVideoById()와 같은 매개변수 및 함수는 모든 모바일 환경에서 작동하지 않습니다.

예

YouTube 플레이어 개체 만들기

예 1: 큰 소리로 재생

이 예에서는 1280x720픽셀 동영상 플레이어를 만듭니다. 그러면 onReady 이벤트에 대한 이벤트 리스너가 setVolume 함수를 호출하여 볼륨을 가장 높은 설정으로 조정합니다.

function onYouTubeIframeAPIReady() {
  var player;
  player = new YT.Player('player', {
    width: 1280,
    height: 720,
    videoId: 'M7lc1UVf-VE',
    events: {
      'onReady': onPlayerReady,
      'onPlaybackQualityChange': onPlayerPlaybackQualityChange,
      'onStateChange': onPlayerStateChange,
      'onError': onPlayerError
    }
  });
}

function onPlayerReady(event) {
  event.target.setVolume(100);
  event.target.playVideo();
}

예 2: 이 예에서는 동영상이 로드되면 자동으로 재생하고 동영상 플레이어의 컨트롤을 숨기도록 플레이어 매개변수를 설정합니다. 또한 API가 전달하는 모든 이벤트에 대한 이벤트 리스너를 추가합니다.

function onYouTubeIframeAPIReady() {
  var player;
  player = new YT.Player('player', {
    videoId: 'M7lc1UVf-VE',
    playerVars: { 'autoplay': 1, 'controls': 0 },
    events: {
      'onReady': onPlayerReady,
      'onPlaybackQualityChange': onPlayerPlaybackQualityChange,
      'onStateChange': onPlayerStateChange,
      'onError': onPlayerError
    }
  });
}