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>

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

  1. 이 섹션의 <div> 태그는 IFrame API가 동영상 플레이어를 배치할 페이지의 위치를 식별합니다. 동영상 플레이어 로드 섹션에 설명된 플레이어 객체의 생성자는 id를 사용하여 <div> 태그를 식별하여 API가 <iframe>를 적절한 위치에 배치하도록 합니다. 구체적으로 IFrame API는 <div> 태그를 <iframe> 태그로 대체합니다.

    또는 <iframe> 요소를 페이지에 직접 배치할 수도 있습니다. 동영상 플레이어 로드 섹션에서 방법을 설명합니다.

  2. 이 섹션의 코드는 IFrame Player API JavaScript 코드를 로드합니다. 이 예에서는 DOM 수정을 사용하여 API 코드를 다운로드하여 코드가 비동기식으로 검색되도록 합니다. 비동기 다운로드도 지원하는 <script> 태그의 async 속성은 이 Stack Overflow 답변에서 설명한 대로 아직 일부 최신 브라우저에서 지원되지 않습니다.

  3. onYouTubeIframeAPIReady 함수는 플레이어 API 코드가 다운로드되는 즉시 실행됩니다. 이 코드 부분은 임베딩하는 동영상 플레이어를 참조하는 전역 변수 player를 정의하고, 그런 다음 함수가 동영상 플레이어 객체를 생성합니다.

  4. onPlayerReady 함수는 onReady 이벤트가 발생할 때 실행됩니다. 이 예에서 함수는 동영상 플레이어가 준비되면 재생을 시작해야 함을 나타냅니다.

  5. 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
    }
  });
}

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

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

    IFrame API는 지정된 요소를 플레이어가 포함된 <iframe> 요소로 대체합니다. 대체되는 요소의 표시 스타일이 삽입된 <iframe> 요소와 다른 경우 페이지 레이아웃에 영향을 줄 수 있습니다. 기본적으로 <iframe>는 inline-block 요소로 표시됩니다.

  2. 두 번째 매개변수는 플레이어 옵션을 지정하는 객체입니다. 객체에는 다음 속성이 포함되어 있습니다.
    • 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

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

  • 필수 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() 호출에 지정된 시간부터 재생합니다. 목록을 큐에 추가한 다음