이 페이지는 Cloud Translation API를 통해 번역되었습니다.

YouTube Player API Reference for iframe Embeds

IFrame Player API를 사용하면 웹사이트에 YouTube 동영상 플레이어를 삽입하고 JavaScript를 사용하여 플레이어를 제어할 수 있습니다.

API의 JavaScript 함수를 사용하면 재생할 동영상을 현재 재생목록에 추가하거나, 동영상을 재생, 일시중지 또는 중지하거나, 플레이어 볼륨을 조절하거나, 재생 중인 동영상에 관한 정보를 검색할 수 있습니다. 플레이어 상태 변경과 같은 특정 플레이어 이벤트에 대한 응답으로 실행되는 이벤트 리스너를 추가할 수도 있습니다.

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

요구사항

사용자의 브라우저에서 HTML5 postMessage 기능을 지원해야 합니다. 대부분의 최신 브라우저는 postMessage를 지원합니다.

내장 플레이어에는 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: '390',
          width: '640',
          videoId: 'M7lc1UVf-VE',
          playerVars: {
            'playsinline': 1
          },
          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가 동영상 플레이어를 배치할 페이지의 위치를 식별합니다. 동영상 플레이어 로드 섹션에 설명된 플레이어 객체의 생성자는 id를 사용하여 <div> 태그를 식별하여 API가 <iframe>를 적절한 위치에 배치하도록 합니다. 구체적으로 IFrame API는 <div> 태그를 <iframe> 태그로 대체합니다.

또는 <iframe> 요소를 페이지에 직접 배치할 수도 있습니다. 동영상 플레이어 로드 섹션에서 방법을 설명합니다.
이 섹션의 코드는 IFrame Player API JavaScript 코드를 로드합니다. 이 예에서는 DOM 수정을 사용하여 API 코드를 다운로드하여 코드가 비동기식으로 검색되도록 합니다. 비동기 다운로드도 지원하는 <script> 태그의 async 속성은 이 Stack Overflow 답변에서 설명한 대로 아직 일부 최신 브라우저에서 지원되지 않습니다.
onYouTubeIframeAPIReady 함수는 플레이어 API 코드가 다운로드되는 즉시 실행됩니다. 이 코드 부분은 임베딩하는 동영상 플레이어를 참조하는 전역 변수 player를 정의하고, 그런 다음 함수가 동영상 플레이어 객체를 생성합니다.
onPlayerReady 함수는 onReady 이벤트가 발생할 때 실행됩니다. 이 예에서 함수는 동영상 플레이어가 준비되면 재생을 시작해야 함을 나타냅니다.
API는 플레이어의 상태가 변경될 때 onPlayerStateChange 함수를 호출합니다. 이는 플레이어가 재생 중, 일시중지 중, 완료되었음을 나타낼 수 있습니다. 이 함수는 플레이어 상태가 1 (재생 중)일 때 플레이어가 6초 동안 재생한 후 stopVideo 함수를 호출하여 동영상을 중지해야 함을 나타냅니다.

동영상 플레이어 로드

API의 JavaScript 코드가 로드되면 API가 onYouTubeIframeAPIReady 함수를 호출합니다. 이때 YT.Player 객체를 생성하여 페이지에 동영상 플레이어를 삽입할 수 있습니다. 아래의 HTML 발췌 부분은 위 예의 onYouTubeIframeAPIReady 함수를 보여줍니다.

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

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

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

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

시작하기 섹션에서 설명한 대로 페이지에 빈 <div> 요소를 작성하는 대신 Player API의 JavaScript 코드가 <iframe> 요소로 대체하도록 할 수 있습니다. <iframe> 태그를 직접 만들면 됩니다. 예시 섹션의 첫 번째 예시에서 이를 수행하는 방법을 보여줍니다.

<iframe id="player" type="text/html" width="640" height="390"
  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에 origin 매개변수도 포함해야 합니다. URL 스킴 (http:// 또는 https://)과 호스트 페이지의 전체 도메인을 매개변수 값으로 지정합니다. origin는 선택사항이지만 이를 포함하면 악의적인 서드 파티 JavaScript가 페이지에 삽입되어 YouTube 플레이어의 제어를 도용하는 것을 방지할 수 있습니다.

동영상 플레이어 객체를 생성하는 다른 예는 예시를 참고하세요.

운영

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

함수

대기열 함수

현재 재생목록 기능을 사용하면 동영상, 재생목록 또는 다른 동영상 목록을 로드하고 재생할 수 있습니다. 아래에 설명된 객체 문법을 사용하여 이러한 함수를 호출하는 경우 사용자의 업로드 동영상 목록을 현재 재생목록에 추가하거나 로드할 수도 있습니다.

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

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

예를 들어 loadVideoById 함수는 다음 두 가지 방법 중 하나로 호출할 수 있습니다. 객체 구문은 인수 구문에서 지원하지 않는 endSeconds 속성을 지원합니다.

인수 문법

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

객체 문법

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

동영상에 대한 대기열 함수

cueVideoById

인수 문법

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

객체 문법

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

이 함수는 지정된 동영상의 썸네일을 로드하고 플레이어가 동영상을 재생할 수 있도록 준비합니다. 플레이어는 playVideo() 또는 seekTo()가 호출될 때까지 FLV를 요청하지 않습니다.

필수 videoId 매개변수는 재생할 동영상의 YouTube 동영상 ID를 지정합니다. YouTube Data API에서 video 리소스의 id 속성은 ID를 지정합니다.
선택사항인 startSeconds 매개변수는 부동 소수점 수/정수를 허용하며 playVideo()가 호출될 때 동영상 재생이 시작되는 시간을 지정합니다. startSeconds 값을 지정한 다음 seekTo()를 호출하면 플레이어는 seekTo() 호출에 지정된 시간부터 재생합니다. 동영상이 큐를 받아 재생 준비가 되면 플레이어는 video cued 이벤트 (5)를 브로드캐스트합니다.
객체 문법에서만 지원되는 선택적 endSeconds 매개변수는 부동 소수점 수/정수를 허용하며 playVideo()가 호출될 때 동영상 재생을 중지해야 하는 시간을 지정합니다. endSeconds 값을 지정한 다음 seekTo()를 호출하면 endSeconds 값이 더 이상 적용되지 않습니다.

loadVideoById

인수 문법

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

객체 문법

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

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

필수 videoId 매개변수는 재생할 동영상의 YouTube 동영상 ID를 지정합니다. YouTube Data API에서 video 리소스의 id 속성은 ID를 지정합니다.
선택적 startSeconds 매개변수는 부동 소수점 수/정수를 허용합니다. 이 매개변수가 지정되면 동영상이 지정한 시간에 가장 가까운 키프레임에서 시작됩니다.
선택적 endSeconds 매개변수는 부동 소수점 수/정수를 허용합니다. 이 매개변수가 지정되면 동영상 재생이 지정한 시간에 중지됩니다.

cueVideoByUrl

인수 문법

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

객체 문법

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

필수 mediaContentUrl 매개변수는 http://www.youtube.com/v/VIDEO_ID?version=3 형식의 정규화된 YouTube 플레이어 URL을 지정합니다.
선택사항인 startSeconds 매개변수는 부동 소수점 수/정수를 허용하며 playVideo()가 호출될 때 동영상 재생이 시작되는 시간을 지정합니다. startSeconds를 지정한 다음 seekTo()를 호출하면 플레이어는 seekTo() 호출에 지정된 시간부터 재생합니다. 동영상이 큐에 추가되고 재생할 준비가 되면 플레이어는 video cued 이벤트 (5)를 브로드캐스트합니다.
객체 문법에서만 지원되는 선택적 endSeconds 매개변수는 부동 소수점 수/정수를 허용하며 playVideo()가 호출될 때 동영상 재생을 중지해야 하는 시간을 지정합니다. endSeconds 값을 지정한 다음 seekTo()를 호출하면 endSeconds 값이 더 이상 적용되지 않습니다.

loadVideoByUrl

인수 문법

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

객체 문법

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

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

필수 mediaContentUrl 매개변수는 http://www.youtube.com/v/VIDEO_ID?version=3 형식의 정규화된 YouTube 플레이어 URL을 지정합니다.
선택사항인 startSeconds 매개변수는 부동 소수점 수/정수를 허용하며 동영상 재생이 시작되는 시간을 지정합니다. startSeconds (숫자는 부동 소수점 수일 수 있음)가 지정되면 동영상이 지정된 시간에 가장 가까운 키프레임부터 시작됩니다.
endSeconds 매개변수는 선택사항이며 객체 문법에서만 지원됩니다. 부동 소수점 수/정수를 허용하며 동영상 재생을 중지해야 하는 시간을 지정합니다.

목록에 대한 대기열 함수

cuePlaylist 및 loadPlaylist 함수를 사용하면 재생목록을 로드하고 재생할 수 있습니다. 객체 문법을 사용하여 이러한 함수를 호출하는 경우 사용자의 업로드된 동영상 목록을 현재 재생목록에 추가하거나 로드할 수도 있습니다.

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

cuePlaylist

인수 문법
```
player.cuePlaylist(playlist:String|Array,
                   index:Number,
                   startSeconds:Number):Void
```
지정된 재생목록을 현재 재생목록에 추가합니다. 재생목록이 큐에 추가되고 재생할 준비가 되면 플레이어는 video cued 이벤트 (5)를 브로드캐스트합니다.
- 필수 playlist 매개변수는 YouTube 동영상 ID 배열을 지정합니다. YouTube Data API에서 video 리소스의 id 속성은 동영상 ID를 식별합니다.
- 선택적 index 매개변수는 재생할 재생목록의 첫 번째 동영상의 색인을 지정합니다. 이 매개변수는 0 기반 색인을 사용하며 기본 매개변수 값은 0이므로 기본 동작은 재생목록의 첫 번째 동영상을 로드하고 재생하는 것입니다.
- 선택적 startSeconds 매개변수는 부동 소수점 수/정수를 허용하며 playVideo() 함수가 호출될 때 재생목록의 첫 번째 동영상이 재생을 시작해야 하는 시간을 지정합니다. startSeconds 값을 지정한 다음 seekTo()를 호출하면 플레이어는 seekTo() 호출에 지정된 시간부터 재생합니다. 재생목록을 큐에 추가한 다음 playVideoAt() 함수를 호출하면 플레이어가 지정된 동영상의 시작 부분부터 재생을 시작합니다.
객체 문법
```
player.cuePlaylist({listType:String,
                    list:String,
                    index:Number,
                    startSeconds:Number}):Void
```
지정된 동영상 목록을 현재 재생목록에 추가합니다. 목록은 재생목록 또는 사용자가 업로드한 동영상 피드일 수 있습니다. 검색 결과 목록을 현재 재생목록에 추가하는 기능은 지원 중단되었으며 2020년 11월 15일부터 더 이상 지원되지 않습니다.
목록이 큐에 추가되고 재생할 준비가 되면 플레이어는 video cued 이벤트 (5)를 브로드캐스트합니다.
- 선택사항인 listType 속성은 검색하는 결과 피드의 유형을 지정합니다. 유효한 값은 playlist, user_uploads입니다. 지원 중단된 값 search는 2020년 11월 15일부터 더 이상 지원되지 않습니다. 기본값은 playlist입니다.
- 필수 list 속성에는 YouTube에서 반환해야 하는 특정 동영상 목록을 식별하는 키가 포함됩니다.
  - listType 속성 값이 playlist인 경우 list 속성은 재생목록 ID 또는 동영상 ID 배열을 지정합니다. YouTube Data API에서 playlist 리소스의 id 속성은 재생목록의 ID를 식별하고 video 리소스의 id 속성은 동영상 ID를 지정합니다.
  - listType 속성 값이 user_uploads이면 list 속성은 업로드한 동영상이 반환될 사용자를 식별합니다.
  - listType 속성 값이 search이면 list 속성이 검색어를 지정합니다. 참고: 이 기능은 지원 중단되었으며 2020년 11월 15일부터 더 이상 지원되지 않습니다.
- 선택적 index 속성은 재생할 목록의 첫 번째 동영상의 색인을 지정합니다. 이 매개변수는 0 기반 색인을 사용하며 기본 매개변수 값은 0이므로 기본 동작은 목록의 첫 번째 동영상을 로드하고 재생하는 것입니다.
- 선택적 startSeconds 속성은 부동 소수점 수/정수를 허용하며 playVideo() 함수가 호출될 때 목록의 첫 번째 동영상 재생을 시작해야 하는 시간을 지정합니다. startSeconds 값을 지정한 다음 seekTo()를 호출하면 플레이어는 seekTo() 호출에 지정된 시간부터 재생합니다. 목록을 큐에 추가한 다음 playVideoAt() 함수를 호출하면 플레이어가 지정된 동영상의 시작 부분부터 재생을 시작합니다.

loadPlaylist

인수 문법
```
player.loadPlaylist(playlist:String|Array,
                    index:Number,
                    startSeconds:Number):Void
```
이 함수는 지정된 재생목록을 로드하고 재생합니다.
- 필수 playlist 매개변수는 YouTube 동영상 ID 배열을 지정합니다. YouTube Data API에서 video 리소스의 id 속성은 동영상 ID를 지정합니다.
- 선택적 index 매개변수는 재생할 재생목록의 첫 번째 동영상의 색인을 지정합니다. 이 매개변수는 0 기반 색인을 사용하며 기본 매개변수 값은 0이므로 기본 동작은 재생목록의 첫 번째 동영상을 로드하고 재생하는 것입니다.
- 선택사항인 startSeconds 매개변수는 부동 소수점 수/정수를 허용하며 재생목록의 첫 번째 동영상이 재생되기 시작하는 시간을 지정합니다.
객체 문법
```
player.loadPlaylist({list:String,
                     listType:String,
                     index:Number,
                     startSeconds:Number}):Void
```
이 함수는 지정된 목록을 로드하고 재생합니다. 목록은 재생목록 또는 사용자가 업로드한 동영상 피드일 수 있습니다. 검색 결과 목록을 로드하는 기능은 지원 중단되었으며 2020년 11월 15일부터 더 이상 지원되지 않습니다.
- 선택사항인 listType 속성은 검색하는 결과 피드의 유형을 지정합니다. 유효한 값은 playlist, user_uploads입니다. 지원 중단된 값 search는 2020년 11월 15일부터 더 이상 지원되지 않습니다. 기본값은 playlist입니다.
- 필수 list 속성에는 YouTube에서 반환해야 하는 특정 동영상 목록을 식별하는 키가 포함됩니다.
  - listType 속성 값이 playlist인 경우 list 속성은 재생목록 ID 또는 동영상 ID 배열을 지정합니다. YouTube Data API에서 playlist 리소스의 id 속성은 재생목록의 ID를 지정하고 video 리소스의 id 속성은 동영상 ID를 지정합니다.
  - listType 속성 값이 user_uploads이면 list 속성은 업로드한 동영상이 반환될 사용자를 식별합니다.
  - listType 속성 값이 search이면 list 속성이 검색어를 지정합니다. 참고: 이 기능은 지원 중단되었으며 2020년 11월 15일부터 더 이상 지원되지 않습니다.
- 선택적 index 속성은 재생할 목록의 첫 번째 동영상의 색인을 지정합니다. 이 매개변수는 0 기반 색인을 사용하며 기본 매개변수 값은 0이므로 기본 동작은 목록의 첫 번째 동영상을 로드하고 재생하는 것입니다.
- 선택적 startSeconds 속성은 부동 소수점 수/정수를 허용하며 목록의 첫 번째 동영상이 재생되기 시작하는 시간을 지정합니다.

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

동영상 재생

player.playVideo():Void: 현재 큐에 추가된/로드된 동영상을 재생합니다. 이 함수가 실행된 후 최종 플레이어 상태는 playing (1)입니다.

참고: 재생은 플레이어의 네이티브 재생 버튼을 통해 시작된 경우에만 동영상의 공식 조회수에 반영됩니다.

player.pauseVideo():Void: 현재 재생 중인 동영상을 일시중지합니다. 이 함수가 실행된 후 최종 플레이어 상태는 함수가 호출될 때 플레이어가 ended (0) 상태가 아닌 한 paused (2)입니다. 이 경우 플레이어 상태는 변경되지 않습니다.

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

중요: 플레이어를 paused (2) 상태로 두는 pauseVideo 함수와 달리 stopVideo 함수는 ended (0), paused (2), video cued (5) 또는 unstarted (-1) 등 재생되지 않는 상태로 플레이어를 전환할 수 있습니다.

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

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

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

플레이어가 사용자가 탐색하려는 동영상 부분을 이미 다운로드하지 않은 한 플레이어는 해당 시간 전에 가장 가까운 키프레임으로 이동합니다.
allowSeekAhead 매개변수는 seconds 매개변수가 현재 버퍼링된 동영상 데이터 외부의 시간을 지정하는 경우 플레이어가 서버에 새 요청을 할지 여부를 결정합니다.

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

360도 동영상 재생 제어

참고: 360도 동영상 재생 환경은 휴대기기에서 제한적으로 지원됩니다. 지원되지 않는 기기에서는 360도 동영상이 왜곡되어 표시되며 API를 통해서, 방향 센서를 사용하거나, 기기 화면에서 터치/드래그 작업에 응답하는 등 시점 변경을 지원하는 방법이 전혀 없습니다.

player.getSphericalProperties():Object

동영상 재생에 대한 시청자의 현재 관점 또는 뷰를 설명하는 속성을 검색합니다. 또한 다음 사항에 유의하세요.

이 객체는 구형 동영상이라고도 하는 360도 동영상에 대해서만 채워집니다.
현재 동영상이 360도 동영상이 아니거나 지원되지 않는 기기에서 함수가 호출된 경우 함수는 빈 객체를 반환합니다.
지원되는 휴대기기에서 enableOrientationSensor 속성이 true로 설정된 경우 이 함수는 fov 속성에 올바른 값이 포함되고 다른 속성이 0로 설정된 객체를 반환합니다.

객체에는 다음 속성이 포함되어 있습니다.

속성
`yaw`	뷰의 가로 각도를 도 단위로 나타내는 숫자(0~360)로, 사용자가 뷰를 왼쪽이나 오른쪽으로 더 돌리는 정도를 반영합니다. 등각 직사각형 투영에서 동영상 중앙을 향하는 중립 위치는 0°를 나타내며, 이 값은 시청자가 왼쪽으로 회전할수록 증가합니다.
`pitch`	뷰의 수직 각도를 도 단위로 나타내는 숫자(-90~90)로, 사용자가 위 또는 아래를 보려고 뷰를 조정하는 정도를 반영합니다. 등각 직사각형 투영에서 동영상 중앙을 향하는 중립 위치는 0°를 나타내며, 이 값은 시청자가 위로 볼수록 증가합니다.
`roll`	뷰의 시계 방향 또는 시계 반대 방향 회전 각도를 도 단위로 나타내는 [-180, 180] 범위의 숫자입니다. 등각 직사각형 투영의 수평축이 뷰의 수평축과 평행한 중립 위치는 0°를 나타냅니다. 뷰가 시계 방향으로 회전하면 값이 증가하고 시계 반대 방향으로 회전하면 값이 감소합니다. 삽입된 플레이어에는 뷰의 롤을 조정하기 위한 사용자 인터페이스가 표시되지 않습니다. 롤은 다음과 같은 상호 배타적인 두 가지 방법으로 조정할 수 있습니다. 모바일 브라우저의 방향 센서를 사용하여 뷰의 롤을 제공합니다. 방향 센서가 사용 설정된 경우 `getSphericalProperties` 함수는 항상 `0`를 `roll` 속성의 값으로 반환합니다. 방향 센서가 사용 중지된 경우 이 API를 사용하여 롤을 0이 아닌 값으로 설정합니다.
`fov`	뷰포트의 더 긴 가장자리에서 측정한 뷰의 시야각을 도 단위로 나타내는 [30, 120] 범위의 숫자입니다. 짧은 모서리는 뷰의 가로세로 비율에 비례하도록 자동으로 조정됩니다. 기본값은 100도입니다. 값을 줄이면 동영상 콘텐츠를 확대하는 것과 같고 값을 늘리면 축소하는 것과 같습니다. 이 값은 API를 사용하거나 동영상이 전체 화면 모드일 때 마우스 휠을 사용하여 조정할 수 있습니다.

player.setSphericalProperties(properties:Object):Void

360도 동영상 재생을 위한 동영상 방향을 설정합니다. (현재 동영상이 구형이 아닌 경우 입력과 관계없이 메서드는 무작위 작업입니다.)

플레이어 뷰는 properties 객체의 알려진 속성 값을 반영하도록 업데이트하여 이 메서드 호출에 응답합니다. 뷰는 해당 객체에 포함되지 않은 다른 알려진 속성의 값을 유지합니다.

또한 다음과 같은 사항이 적용됩니다.

객체에 알 수 없는 속성 또는 예상치 못한 속성이 포함된 경우 플레이어는 이를 무시합니다.
이 섹션의 시작 부분에서 언급했듯이 일부 휴대기기에서는 360도 동영상 재생 환경이 지원되지 않습니다.
기본적으로 지원되는 휴대기기에서 이 함수는 fov 속성만 설정하고 360도 동영상 재생의 yaw, pitch, roll 속성에는 영향을 미치지 않습니다. 자세한 내용은 아래의 enableOrientationSensor 속성을 참고하세요.

함수에 전달된 properties 객체에는 다음 속성이 포함되어 있습니다.

속성
`yaw`	위의 정의를 참고하세요.
`pitch`	위의 정의를 참고하세요.
`roll`	위의 정의를 참고하세요.
`fov`	위의 정의를 참고하세요.
`enableOrientationSensor`	참고: 이 속성은 지원되는 기기에서만 360도 시청 환경에 영향을 미칩니다. IFrame 삽입이 지원되는 기기의 방향 변경을 알리는 이벤트(예: 모바일 브라우저의 `DeviceOrientationEvent`)에 응답해야 하는지 나타내는 불리언 값입니다. 기본 매개변수 값은 `true`입니다. 지원되는 휴대기기 값이 `true`인 경우 삽입된 플레이어는 기기의 움직임에 만 의존하여 360도 동영상 재생의 `yaw`, `pitch`, `roll` 속성을 조정합니다. 그러나 `fov` 속성은 여전히 API를 통해 변경할 수 있으며, 사실 API는 휴대기기에서 `fov` 속성을 변경하는 유일한 방법입니다. 이것이 기본 동작입니다. 값이 `false`이면 기기의 움직임이 360도 시청 환경에 영향을 미치지 않으며 `yaw`, `pitch`, `roll`, `fov` 속성을 모두 API를 통해 설정해야 합니다. 지원되지 않는 휴대기기 `enableOrientationSensor` 속성 값은 재생 환경에 영향을 미치지 않습니다.

재생목록의 동영상 재생

player.nextVideo():Void

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

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

player.previousVideo():Void

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

재생목록의 첫 번째 동영상이 시청되고 있는 동안 player.previousVideo()이 호출되고 재생목록이 연속 재생 (loop)으로 설정된 경우 플레이어는 목록의 마지막 동영상을 로드하여 재생합니다.
재생목록의 첫 번째 동영상을 시청하는 동안 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.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 및 onAutoplayBlocked 이벤트는 data 속성을 지정하지 않습니다.

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

onReady

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

아래 예는 이 이벤트를 처리하는 샘플 함수를 보여줍니다. API가 함수에 전달하는 이벤트 객체에는 플레이어를 식별하는 target 속성이 있습니다. 이 함수는 현재 로드된 동영상의 삽입 코드를 가져와 동영상 재생을 시작하고 id 값이 embed-code인 페이지 요소에 삽입 코드를 표시합니다.

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(동영상 준비됨)

플레이어가 동영상을 처음 로드하면 unstarted (-1) 이벤트를 브로드캐스트합니다. 동영상이 큐에 추가되고 재생 준비가 되면 플레이어는 video cued (5) 이벤트를 브로드캐스트합니다. 코드에서 정수 값을 지정하거나 다음 네임스페이스화된 변수 중 하나를 사용할 수 있습니다.

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

onPlaybackQualityChange

이 이벤트는 동영상 재생 품질이 변경될 때마다 실행됩니다. 시청자의 재생 환경이 변경되었음을 나타낼 수 있습니다. 재생 조건에 영향을 주거나 이벤트가 발생할 수 있는 요인에 관한 자세한 내용은 YouTube 고객센터를 참고하세요.

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();

현재 옵션을 설정할 수 있는 유일한 모듈은 플레이어에서 자막을 처리하는 captions 모듈입니다. onApiChange 이벤트를 수신하면 애플리케이션은 다음 명령어를 사용하여 captions 모듈에 설정할 수 있는 옵션을 결정할 수 있습니다.

player.getOptions('captions');

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

Retrieving an option:
player.getOption(module, option);

Setting an option
player.setOption(module, option, value);

다음 표에는 API에서 지원하는 옵션이 나와 있습니다.

모듈	옵션	설명
자막	fontSize	이 옵션은 플레이어에 표시되는 자막의 글꼴 크기를 조정합니다. 유효한 값은 `-1`, `0`, `1`, `2`, `3`입니다. 기본 크기는 `0`이고 가장 작은 크기는 `-1`입니다. 이 옵션을 `-1` 미만의 정수로 설정하면 가장 작은 자막 크기가 표시되고, 이 옵션을 `3` 초과하는 정수로 설정하면 가장 큰 자막 크기가 표시됩니다.
자막	새로고침	이 옵션을 사용하면 재생 중인 동영상의 자막 데이터를 새로고침합니다. 옵션의 값을 검색하면 값이 `null`입니다. 자막 데이터를 새로고침하려면 값을 `true`로 설정합니다.

onAutoplayBlocked

이 이벤트는 브라우저에서 자동재생 또는 스크립트된 동영상 재생 기능(총칭하여 '자동재생'이라고 함)을 차단할 때마다 발생합니다. 여기에는 다음 플레이어 API 중 하나를 사용하여 시도된 재생이 포함됩니다.

autoplay 매개변수
loadPlaylist 함수
loadVideoById 함수
loadVideoByUrl 함수
playVideo 함수

대부분의 브라우저에는 특정 조건이 충족되는 경우 데스크톱, 모바일, 기타 환경에서 자동재생을 차단할 수 있는 정책이 있습니다. 이 정책이 트리거될 수 있는 경우는 사용자 상호작용 없이 음소거가 해제된 재생이 시작되거나 교차 출처 iframe에서 자동재생을 허용하는 권한 정책이 설정되지 않은 경우를 들 수 있습니다.

자세한 내용은 브라우저별 정책(Apple Safari / Webkit, Google Chrome, Mozilla Firefox) 및 Mozilla의 자동재생 가이드를 참고하세요.

예

`YT.Player` 객체 만들기

예 1: 기존 <iframe>에서 API 사용

이 예에서는 페이지의 <iframe> 요소가 이미 API가 사용될 플레이어를 정의합니다. 플레이어의 src URL이 enablejsapi 매개변수를 1로 설정하거나 <iframe> 요소의 enablejsapi 속성을 true로 설정해야 합니다.

onPlayerReady 함수는 플레이어가 준비되면 플레이어 주변 테두리의 색상을 주황색으로 변경합니다. 그러면 onPlayerStateChange 함수가 현재 플레이어 상태에 따라 플레이어 주변 테두리의 색상을 변경합니다. 예를 들어 플레이어가 재생 중일 때는 녹색, 일시중지되어 있을 때는 빨간색, 버퍼링 중일 때는 파란색 등으로 표시됩니다.

이 예에서는 다음 코드를 사용합니다.

<iframe id="existing-iframe-example"
        width="640" height="360"
        src="https://www.youtube.com/embed/M7lc1UVf-VE?enablejsapi=1"
        frameborder="0"
        style="border: solid 4px #37474F"
></iframe>

<script type="text/javascript">
  var tag = document.createElement('script');
  tag.id = 'iframe-demo';
  tag.src = 'https://www.youtube.com/iframe_api';
  var firstScriptTag = document.getElementsByTagName('script')[0];
  firstScriptTag.parentNode.insertBefore(tag, firstScriptTag);

  var player;
  function onYouTubeIframeAPIReady() {
    player = new YT.Player('existing-iframe-example', {
        events: {
          'onReady': onPlayerReady,
          'onStateChange': onPlayerStateChange
        }
    });
  }
  function onPlayerReady(event) {
    document.getElementById('existing-iframe-example').style.borderColor = '#FF6D00';
  }
  function changeBorderColor(playerStatus) {
    var color;
    if (playerStatus == -1) {
      color = "#37474F"; // unstarted = gray
    } else if (playerStatus == 0) {
      color = "#FFFF00"; // ended = yellow
    } else if (playerStatus == 1) {
      color = "#33691E"; // playing = green
    } else if (playerStatus == 2) {
      color = "#DD2C00"; // paused = red
    } else if (playerStatus == 3) {
      color = "#AA00FF"; // buffering = purple
    } else if (playerStatus == 5) {
      color = "#FF6DOO"; // video cued = orange
    }
    if (color) {
      document.getElementById('existing-iframe-example').style.borderColor = color;
    }
  }
  function onPlayerStateChange(event) {
    changeBorderColor(event.data);
  }
</script>

예 2: 재생 시 소리가 너무 큼

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

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

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

예 3: 이 예에서는 동영상이 로드될 때 자동으로 재생되고 동영상 플레이어의 컨트롤이 숨겨지도록 플레이어 매개변수를 설정합니다. 또한 API가 브로드캐스트하는 여러 이벤트에 대한 이벤트 리스너를 추가합니다.

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

360도 동영상 컨트롤

이 예에서는 다음 코드를 사용합니다.

<style>
  .current-values {
    color: #666;
    font-size: 12px;
  }
</style>
<!-- The player is inserted in the following div element -->
<div id="spherical-video-player"></div>

<!-- Display spherical property values and enable user to update them. -->
<table style="border: 0; width: 640px;">
  <tr style="background: #fff;">
    <td>
      <label for="yaw-property">yaw: </label>
      <input type="text" id="yaw-property" style="width: 80px"><br>
      <div id="yaw-current-value" class="current-values"> </div>
    </td>
    <td>
      <label for="pitch-property">pitch: </label>
      <input type="text" id="pitch-property" style="width: 80px"><br>
      <div id="pitch-current-value" class="current-values"> </div>
    </td>
    <td>
      <label for="roll-property">roll: </label>
      <input type="text" id="roll-property" style="width: 80px"><br>
      <div id="roll-current-value" class="current-values"> </div>
    </td>
    <td>
      <label for="fov-property">fov: </label>
      <input type="text" id="fov-property" style="width: 80px"><br>
      <div id="fov-current-value" class="current-values"> </div>
    </td>
    <td style="vertical-align: bottom;">
      <button id="spherical-properties-button">Update properties</button>
    </td>
  </tr>
</table>

<script type="text/javascript">
  var tag = document.createElement('script');
  tag.id = 'iframe-demo';
  tag.src = 'https://www.youtube.com/iframe_api';
  var firstScriptTag = document.getElementsByTagName('script')[0];
  firstScriptTag.parentNode.insertBefore(tag, firstScriptTag);

  var PROPERTIES = ['yaw', 'pitch', 'roll', 'fov'];
  var updateButton = document.getElementById('spherical-properties-button');

  // Create the YouTube Player.
  var ytplayer;
  function onYouTubeIframeAPIReady() {
    ytplayer = new YT.Player('spherical-video-player', {
        height: '360',
        width: '640',
        videoId: 'FAtdv94yzp4',
    });
  }

  // Don't display current spherical settings because there aren't any.
  function hideCurrentSettings() {
    for (var p = 0; p < PROPERTIES.length; p++) {
      document.getElementById(PROPERTIES[p] + '-current-value').innerHTML = '';
    }
  }

  // Retrieve current spherical property values from the API and display them.
  function updateSetting() {
    if (!ytplayer || !ytplayer.getSphericalProperties) {
      hideCurrentSettings();
    } else {
      let newSettings = ytplayer.getSphericalProperties();
      if (Object.keys(newSettings).length === 0) {
        hideCurrentSettings();
      } else {
        for (var p = 0; p < PROPERTIES.length; p++) {
          if (newSettings.hasOwnProperty(PROPERTIES[p])) {
            currentValueNode = document.getElementById(PROPERTIES[p] +
                                                       '-current-value');
            currentValueNode.innerHTML = ('current: ' +
                newSettings[PROPERTIES[p]].toFixed(4));
          }
        }
      }
    }
    requestAnimationFrame(updateSetting);
  }
  updateSetting();

  // Call the API to update spherical property values.
  updateButton.onclick = function() {
    var sphericalProperties = {};
    for (var p = 0; p < PROPERTIES.length; p++) {
      var propertyInput = document.getElementById(PROPERTIES[p] + '-property');
      sphericalProperties[PROPERTIES[p]] = parseFloat(propertyInput.value);
    }
    ytplayer.setSphericalProperties(sphericalProperties);
  }
</script>

Android WebView Media Integrity API 통합

YouTube는 Android 애플리케이션의 YouTube 플레이어 삽입을 비롯한 삽입된 미디어 플레이어가 삽입 앱의 진위를 확인할 수 있도록 Android WebView Media Integrity API를 확장했습니다. 이번 변경으로 삽입된 앱은 증명된 앱 ID를 YouTube에 자동으로 전송합니다. 이 API 사용을 통해 수집되는 데이터는 앱 메타데이터 (패키지 이름, 버전 번호, 서명 인증서)와 Google Play 서비스에서 생성된 기기 증명 토큰입니다.

이 데이터는 애플리케이션 및 기기 무결성을 확인하는 데 사용됩니다. 암호화되며 서드 파티와 공유되지 않으며 일정한 보관 기간이 지난 후 삭제됩니다. 앱 개발자는 WebView Media Integrity API에서 앱 ID를 구성할 수 있습니다. 구성은 선택 해제 옵션을 지원합니다.

업데이트 기록

June 24, 2024

The documentation has been updated to note that YouTube has extended the Android WebView Media Integrity API to enable embedded media players, including YouTube player embeds in Android applications, to verify the embedding app's authenticity. With this change, embedding apps automatically send an attested app ID to YouTube.

November 20, 2023

The new onAutoplayBlocked event API is now available. This event notifies your application if the browser blocks autoplay or scripted playback. Verification of autoplay success or failure is an established paradigm for HTMLMediaElements, and the onAutoplayBlocked event now provides similar functionality for the IFrame Player API.

April 27, 2021

The Getting Started and Loading a Video Player sections have been updated to include examples of using a playerVars object to customize the player.

October 13, 2020

Note: This is a deprecation announcement for the embedded player functionality that lets you configure the player to load search results. This announcement affects the IFrame Player API's queueing functions for lists, cuePlaylist and loadPlaylist.

This change will become effective on or after 15 November 2020. After that time, calls to the cuePlaylist or loadPlaylist functions that set the listType property to search will generate a 4xx response code, such as 404 (Not Found) or 410 (Gone). This change also affects the list property for those functions as that property no longer supports the ability to specify a search query.

As an alternative, you can use the YouTube Data API's search.list method to retrieve search results and then load selected videos in the player.

October 24, 2019

The documentation has been updated to reflect the fact that the API no longer supports functions for setting or retrieving playback quality. As explained in this YouTube Help Center article, to give you the best viewing experience, YouTube adjusts the quality of your video stream based on your viewing conditions.

The changes explained below have been in effect for more than one year. This update merely aligns the documentation with current functionality:

The getPlaybackQuality, setPlaybackQuality, and getAvailableQualityLevels functions are no longer supported. In particular, calls to setPlaybackQuality will be no-op functions, meaning they will not actually have any impact on the viewer's playback experience.
The queueing functions for videos and playlists -- cueVideoById, loadVideoById, etc. -- no longer support the suggestedQuality argument. Similarly, if you call those functions using object syntax, the suggestedQuality field is no longer supported. If suggestedQuality is specified, it will be ignored when the request is handled. It will not generate any warnings or errors.
The onPlaybackQualityChange event is still supported and might signal a change in the viewer's playback environment. See the Help Center article referenced above for more information about factors that affect playback conditions or that might cause the event to fire.

May 16, 2018

The API now supports features that allow users (or embedders) to control the viewing perspective for 360° videos:

The getSphericalProperties function retrieves the current orientation for the video playback. The orientation includes the following data:
- yaw - represents the horizontal angle of the view in degrees, which reflects the extent to which the user turns the view to face further left or right
- pitch - represents the vertical angle of the view in degrees, which reflects the extent to which the user adjusts the view to look up or down
- roll - represents the rotational angle (clockwise or counterclockwise) of the view in degrees.
- fov - represents the field-of-view of the view in degrees, which reflects the extent to which the user zooms in or out on the video.
The setSphericalProperties function modifies the view to match the submitted property values. In addition to the orientation values described above, this function supports a Boolean field that indicates whether the IFrame embed should respond to DeviceOrientationEvents on supported mobile devices.

This example demonstrates and lets you test these new features.

June 19, 2017

This update contains the following changes:

Documentation for the YouTube Flash Player API and YouTube JavaScript Player API has been removed and redirected to this document. The deprecation announcement for the Flash and JavaScript players was made on January 27, 2015. If you haven't done so already, please migrate your applications to use IFrame embeds and the IFrame Player API.

August 11, 2016

This update contains the following changes:

The newly published YouTube API Services Terms of Service ("the Updated Terms"), discussed in detail on the YouTube Engineering and Developers Blog, provides a rich set of updates to the current Terms of Service. In addition to the Updated Terms, which will go into effect as of February 10, 2017, this update includes several supporting documents to help explain the policies that developers must follow.

The full set of new documents is described in the revision history for the Updated Terms. In addition, future changes to the Updated Terms or to those supporting documents will also be explained in that revision history. You can subscribe to an RSS feed listing changes in that revision history from a link in that document.

June 29, 2016

This update contains the following changes:

The documentation has been corrected to note that the onApiChange method provides access to the captions module and not the cc module.

June 24, 2016

The Examples section has been updated to include an example that demonstrates how to use the API with an existing <iframe> element.

January 6, 2016

The clearVideo function has been deprecated and removed from the documentation. The function no longer has any effect in the YouTube player.

December 18, 2015

European Union (EU) laws require that certain disclosures must be given to and consents obtained from end users in the EU. Therefore, for end users in the European Union, you must comply with the EU User Consent Policy. We have added a notice of this requirement in our YouTube API Terms of Service.

April 28, 2014

This update contains the following changes:

The new removeEventListener function lets you remove a listener for a specified event.

March 25, 2014

This update contains the following changes:

The Requirements section has been updated to note that embedded players must have a viewport that is at least 200px by 200px. If a player displays controls, it must be large enough to fully display the controls without shrinking the viewport below the minimum size. We recommend 16:9 players be at least 480 pixels wide and 270 pixels tall.

July 23, 2013

This update contains the following changes:

The Overview now includes a video of a 2011 Google I/O presentation that discusses the iframe player.

October 31, 2012

This update contains the following changes:

The Queueing functions section has been updated to explain that you can use either argument syntax or object syntax to call all of those functions. Note that the API may support additional functionality in object syntax that the argument syntax does not support.

In addition, the descriptions and examples for each of the video queueing functions have been updated to reflect the newly added support for object syntax. (The API's playlist queueing functions already supported object syntax.)
When called using object syntax, each of the video queueing functions supports an endSeconds property, which accepts a float/integer and specifies the time when the video should stop playing when playVideo() is called.
The getVideoStartBytes method has been deprecated. The method now always returns a value of 0.

August 22, 2012

This update contains the following changes:

The example in the Loading a video player section that demonstrates how to manually create the <iframe> tag has been updated to include a closing </iframe> tag since the onYouTubeIframeAPIReady function is only called if the closing </iframe> element is present.

August 6, 2012

This update contains the following changes:

The Operations section has been expanded to list all of the supported API functions rather than linking to the JavaScript Player API Reference for that list.
The API supports several new functions and one new event that can be used to control the video playback speed:
- Functions
  - getAvailablePlaybackRates – Retrieve the supported playback rates for the cued or playing video. Note that variable playback rates are currently only supported in the HTML5 player.
  - getPlaybackRate – Retrieve the playback rate for the cued or playing video.
  - setPlaybackRate – Set the playback rate for the cued or playing video.
- Events
  - onPlaybackRateChange – This event fires when the video's playback rate changes.

July 19, 2012

This update contains the following changes:

The new getVideoLoadedFraction method replaces the now-deprecated getVideoBytesLoaded and getVideoBytesTotal methods. The new method returns the percentage of the video that the player shows as buffered.
The onError event may now return an error code of 5, which indicates that the requested content cannot be played in an HTML5 player or another error related to the HTML5 player has occurred.
The Requirements section has been updated to indicate that any web page using the IFrame API must also implement the onYouTubeIframeAPIReady function. Previously, the section indicated that the required function was named onYouTubePlayerAPIReady. Code samples throughout the document have also been updated to use the new name.

Note: To ensure that this change does not break existing implementations, both names will work. If, for some reason, your page has an onYouTubeIframeAPIReady function and an onYouTubePlayerAPIReady function, both functions will be called, and the onYouTubeIframeAPIReady function will be called first.
The code sample in the Getting started section has been updated to reflect that the URL for the IFrame Player API code has changed to http://www.youtube.com/iframe_api. To ensure that this change does not affect existing implementations, the old URL (http://www.youtube.com/player_api) will continue to work.

July 16, 2012

This update contains the following changes:

The Operations section now explains that the API supports the setSize() and destroy() methods. The setSize() method sets the size in pixels of the <iframe> that contains the player and the destroy() method removes the <iframe>.

June 6, 2012

This update contains the following changes:

We have removed the experimental status from the IFrame Player API.
The Loading a video player section has been updated to point out that when inserting the <iframe> element that will contain the YouTube player, the IFrame API replaces the element specified in the constructor for the YouTube player. This documentation change does not reflect a change in the API and is intended solely to clarify existing behavior.

In addition, that section now notes that the insertion of the <iframe> element could affect the layout of your page if the element being replaced has a different display style than the inserted <iframe> element. By default, an <iframe> displays as an inline-block element.

March 30, 2012

This update contains the following changes:

The Operations section has been updated to explain that the IFrame API supports a new method, getIframe(), which returns the DOM node for the IFrame embed.

March 26, 2012

This update contains the following changes:

The Requirements section has been updated to note the minimum player size.

YouTube Player API Reference for iframe Embeds 컬렉션을 사용해 정리하기 내 환경설정을 기준으로 콘텐츠를 저장하고 분류하세요.

요구사항

시작하기

동영상 플레이어 로드

운영

함수

대기열 함수

동영상에 대한 대기열 함수

목록에 대한 대기열 함수

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

동영상 재생

360도 동영상 재생 제어

재생목록의 동영상 재생

플레이어 볼륨 변경

플레이어 크기 설정

재생 속도 설정

재생목록의 재생 동작 설정

재생 상태

동영상 정보 가져오기

재생목록 정보 가져오기

이벤트 리스너 추가 또는 삭제

DOM 노드 액세스 및 수정

이벤트

예

YT.Player 객체 만들기

360도 동영상 컨트롤

Android WebView Media Integrity API 통합

업데이트 기록

June 24, 2024

November 20, 2023

April 27, 2021

October 13, 2020

October 24, 2019

May 16, 2018

June 19, 2017

August 11, 2016

June 29, 2016

June 24, 2016

January 6, 2016

December 18, 2015

April 28, 2014

March 25, 2014

July 23, 2013

October 31, 2012

August 22, 2012

August 6, 2012

July 19, 2012

July 16, 2012

June 6, 2012

March 30, 2012

March 26, 2012

YouTube Player API Reference for iframe Embeds

`YT.Player` 객체 만들기