iframe 組み込みの YouTube Player API リファレンス

IFrame Player API を使うと、YouTube 動画プレーヤーをウェブサイトに埋め込み、JavaScript でプレーヤーを制御できます。ウェブページに Flash オブジェクトを埋め込む FlashJavaScript のプレーヤー API とは異なり、IFrame API はコンテンツをページの <iframe> タグに投稿します。この方法は従来の API よりも柔軟で、Flash をサポートしていないモバイル デバイスの場合に、Flash プレーヤーではなく HTML5 プレーヤーで YouTube を利用できます。

この API の JavaScript 関数を使うことで、再生する動画の頭出し、動画の再生 / 一時停止 / 停止、プレーヤーの音量の調節、再生中の動画に関する情報の取得といったことができます。また、特定のプレーヤー イベント(プレーヤーの状態の変化や動画の再生画質の変化など)に応じて実行されるイベント リスナーを追加できます。

このガイドでは IFrame API の使用方法について説明します。API で送信できる各種イベントを確認し、こうしたイベントに応答するイベント リスナーを追加する方法を説明します。また、動画プレーヤーを制御するために呼び出す各種 JavaScript 関数、さらにプレーヤーをカスタマイズするために使用するプレーヤー パラメータについて説明します。

要件

エンドユーザーは HTML5 の postMessage をサポートするブラウザを使用する必要があります。最新のブラウザは postMessage をサポートしていますが、Internet Explorer 7 ではサポートされていません。

埋め込みプレーヤーには少なくとも 200px x 200px のビューポートが必要です。プレーヤーにコントロールが表示される場合は、ビューポートを最小サイズより小さくしなくてもコントロールが表示されるよう、十分な大きさを確保する必要があります。少なくとも幅 480 ピクセル、高さ 270 ピクセルの、アスペクト比 16:9 のプレーヤーをおすすめします。

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>

以下のリストでは、上記サンプルについて詳しく説明します。

  1. このセクションの <div> タグは、IFrame API が動画プレーヤーを配置する、ページ上の位置を識別します。プレーヤー オブジェクトのコンストラクタ(動画プレーヤーの読み込みのセクションで説明)は、id<div> タグを識別することで、<iframe> を適切な位置に配置します。具体的には、IFrame API によって <div> タグが <iframe> タグに置換されます。

    または、<iframe> 要素をページに直接配置してもかまいません。配置方法は、動画プレーヤーの読み込みのセクションで説明しています。

  2. このセクションのコードにより IFrame Player API JavaScript コードが読み込まれます。この例では DOM 変更を使って API コードをダウンロードすることで、コードが非同期で取得されるようにします。<script> タグの async 属性(非同期のダウンロードを有効化)は最新のブラウザではまだサポートされていません。これは Stack Overflow の回答で説明されているとおりです。

  3. プレーヤー API コードがダウンロードされると、onYouTubeIframeAPIReady 関数が実行されます。コードのこの部分では、組み込もうとしている動画プレーヤーを表すグローバル変数 player を定義します。続いて、関数によって動画プレーヤー オブジェクトが作成されます。

  4. onReady イベントが起動されると、onPlayerReady 関数が実行されます。この例では、関数は動画プレーヤーの準備ができると再生を開始することを指示しています。

  5. プレーヤーの状態が変化すると、API によって onPlayerStateChange 関数が呼び出されます。状態は、プレーヤーの再生、一時停止、終了などを示します。この関数により、プレーヤーの状態が 1(再生中)になると、動画を 6 秒間再生した後、stopVideo 関数を呼び出して動画を停止します。

動画プレーヤーの読み込み

API の JavaScript コードが読み込まれると、API によって onYouTubeIframeAPIReady 関数が呼び出されます。この時点で、ページに動画プレーヤーを挿入する YT.Player オブジェクトを作成できます。以下の HTML(抜粋)は、上記の例の onYouTubeIframeAPIReady 関数を示しています。

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

動画プレーヤーのコンストラクタは次のパラメータを指定しています。

  1. 最初のパラメータは、DOM 要素、または HTML 要素の id を指定しています。ここに、プレーヤーが含まれる <iframe> タグが API によって挿入されます。

    IFrame API は指定された要素を、プレーヤーが含まれる <iframe> 要素に置き換えます。置換される要素の表示スタイルが、挿入される <iframe> 要素のスタイルと異なっている場合、ページのレイアウトが影響を受けます。デフォルトで、<iframe>inline-block 要素として表示されます。

  2. 2 番目のパラメータは、プレーヤーのオプションを指定するオブジェクトです。このオブジェクトには次のプロパティが含まれています。
    • width(数値) – 動画プレーヤーの幅。デフォルト値は 640 です。
    • height(数値) – 動画プレーヤーの高さ。デフォルト値は 360 です。
    • videoId(文字列) – プレーヤーが読み込む動画を識別する YouTube 動画 ID。
    • playerVars(オブジェクト) – オブジェクトのこのプロパティは、プレーヤーのカスタマイズに使うプレーヤー パラメータを識別します。
    • events(オブジェクト) – オブジェクトのこのプロパティは、API が起動するイベントと、これらのイベントが発生したときに API が呼び出す関数(イベント リスナー)を識別します。この例では、onReady イベントが発生したときに onPlayerReady 関数を実行し、onStateChange イベントが発生したときに onPlayerStateChange 関数を実行することを、コンストラクタによって指示しています。

はじめにのセクションで説明したように、ページに空の <div> 要素を書き込む(プレーヤー API の JavaScript コードによって <iframe> 要素で置換される)代わりに、<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> タグの属性または videoId パラメータおよびプレーヤー パラメータ(src URL で指定)として指定する、width および height の値を指定する必要がなくなります。追加のセキュリティ対策として、origin パラメータを URL に含め、URL スキーマ(http:// または https://)およびホストページの完全なドメイン名をパラメータ値として指定します。origin はオプションですが、このパラメータを含めると、悪意のあるサードパーティの JavaScript がページに追加されたり、YouTube プレーヤーの制御を奪われたりすることを防止できます。

のセクションでは、動画プレーヤー オブジェクトを作成する例をいくつか紹介しています。

動作

プレーヤー API メソッドを呼び出すには、まず制御するプレーヤー オブジェクトへの参照を取得する必要があります。参照を取得するには、このドキュメントのはじめに動画プレーヤーの読み込みのセクションで説明したように、YT.Player オブジェクトを作成します。

関数

キュー関数

キュー関数を使用すると、動画、再生リスト、その他の動画のリストを読み込んだり再生したりできます。以下のオブジェクト構文を使用してこれらの関数を呼び出し、検索結果のリストまたはユーザーのアップロードした動画のリストをキューイングしたり、読み込んだりすることもできます。

この API はキュー関数を呼び出すための 2 つの構文をサポートしています。

  • 引数構文。関数の引数をあらかじめ指定された順にリストする必要があります。

  • オブジェクト構文。オブジェクトを単一のパラメータとして渡し、関数の引数用のオブジェクト プロパティを定義することができます。さらにこの API では、引数構文がサポートしていないその他の機能もサポートしています。

たとえば loadVideoById 関数は、以下の 2 つの方法で呼び出すことができます。オブジェクト構文では、引数構文がサポートしていない 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)をブロードキャストします。
  • パラメータ(省略可能)はオブジェクト構文でのみサポートされており、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

この関数は、指定された動画のサムネイルを読み込み、プレーヤーで動画を再生する準備をします。プレーヤーは、playVideo() または seekTo() が呼び出されるまで FLV をリクエストしません。

  • mediaContentUrl パラメータ(必須)は、YouTube プレーヤー URL の形式(http://www.youtube.com/v/VIDEO_ID?version=3)に完全に適合している必要があります。YouTube Data API 動画フィードでは、<media:content> タグの format 属性の値が 5 であれば、この形式に完全に適合したプレーヤー 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 パラメータ(必須)は、YouTube プレーヤー URL の形式(http://www.youtube.com/v/VIDEO_ID?version=3)に完全に適合している必要があります。YouTube Data API 動画フィードでは、 <media:content> タグの format 属性の値が 5 であれば、この形式に完全に適合したプレーヤー 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 で、再生リストの最初の動画を読み込んで再生します。

    • 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 プロパティ(省略可能)には、取得する結果フィードの種類を指定します。有効なパラメータ値は、playlistsearch および 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 で、再生リストの最初の動画を読み込んで再生します。

    • 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 で、再生リストの最初の動画を読み込んで再生します。

    • startSeconds パラメータ(省略可能)には、再生リストの最初の動画の再生を開始する位置(時間)を浮動小数点数または整数で指定します。

    • suggestedQuality パラメータ(省略可能)は、動画の推奨再生画質を指定します。再生画質について詳しくは、setPlaybackQuality 関数の定義を参照してください。

  • Object syntax

    player.loadPlaylist({list:String,
                         listType:String,
                         index:Number,
                         startSeconds:Number,
                         suggestedQuality:String}):Void
    この関数は、指定されたリストを読み込んで再生します。リストには、再生リスト、検索結果のフィード、またはユーザーのアップロード動画のフィードを指定できます。
    • listType プロパティ(省略可能)には、取得する結果フィードの種類を指定します。有効なパラメータ値は、playlistsearch および 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 で、再生リストの最初の動画を読み込んで再生します。

    • startSeconds プロパティ(省略可能)には、リストの最初の動画の再生を開始する位置(時間)を浮動小数点数または整数で指定します。

    • suggestedQuality プロパティ(省略可能)には、リストの動画に対する推奨再生画質を指定します。再生画質について詳しくは、setPlaybackQuality 関数の定義を参照してください。

再生の制御とプレーヤーの設定

動画の再生

player.playVideo():Void
頭出し済み、または読み込み済みの動画を再生します。この関数を実行した後のプレーヤーの最終的な状態は playing(1)になります。

注: プレーヤーに付属の再生ボタンで再生が開始された場合、動画の公式再生回数のみがカウントされます。
player.pauseVideo():Void
再生中の動画を一時停止します。この関数を実行した後のプレーヤーの最終的な状態は paused2)になります。ただし、関数を呼び出したときのプレーヤーの状態が ended0)のときは、状態は変わりません。
player.stopVideo():Void
現在の動画の読み込みを停止してキャンセルします。この関数は、ユーザーがプレーヤーでこれ以上動画を再生しないときのために予約されています。ただし、これはまれなケースです。動画を一時停止するという目的には、pauseVideo 関数を使用してください。プレーヤーで再生する動画を変更する場合は、stopVideo を呼び出さずにキュー関数のいずれか 1 つを呼び出してください。

重要: pauseVideo 関数(プレーヤーが paused2)状態のまま)と異なり、stopVideo 関数ではプレーヤーが再生以外の状態になります(例: ended0)、paused2)、video cued5)、または unstarted-1)。
player.seekTo(seconds:Number, allowSeekAhead:Boolean):Void
動画を指定された時間シークします。この関数を呼び出したときにプレーヤーが一時停止している場合は一時停止のままになり、その他の状態(playingvideo cued など)から呼び出した場合は、動画が再生されます。
  • seconds パラメータには、プレーヤーを進ませる秒数を指定します。

    ユーザーがシークしている部分がダウンロード済みでなければ、このパラメータで指定した時間の前の最も近いキーフレームまで進みます。シークしている部分をダウンロード済みの場合、プレーヤーは Flash Player の NetStream オブジェクトの seek() メソッドで記述した時間の前後の最も近いキーフレームに進みます(詳細については Adobe のドキュメントを参照してください)。

  • allowSeekAhead パラメータは、seconds の値が現在バッファ済みの動画データの範囲内にない場合、プレーヤーからサーバーに新しいリクエストを行うかどうかを指定します。

    このパラメータは、ユーザーがマウスで動画の進行バーをドラッグしている間は false、マウスを放したら true に設定することをお勧めします。このように設定するとユーザーは、動画内の過去にバッファされていない場面をスクロールすることで、動画ストリームを新たにリクエストせずに、動画内の別の場面にスクロールできます。ユーザーがマウスボタンを放すと、プレーヤーは動画内の目的の画面に進み、必要に応じて新しい動画ストリームをリクエストします。

player.clearVideo():Void
動画の表示をクリアします。この関数は、stopVideo() を呼び出した後で動画の残りをクリアするときに役立ちます。なお、この関数は ActionScript 3.0 Player API では廃止されています。

再生リスト内の動画の再生

player.nextVideo():Void
この関数は、再生リストの次の動画を読み込んで再生します。
  • 再生リストの最後の動画を再生中に player.nextVideo() を呼び出し、そのリストが連続再生するように設定されている場合(loop)、リスト内の最初の動画が読み込まれて再生されます。

  • 再生リストの最後の動画を再生中に player.nextVideo() を呼び出し、連続再生が設定されていない場合、再生は終了します。

player.previousVideo():Void
この関数は、再生リストの前の動画を読み込んで再生します。
  • 再生リストの最後の動画を再生中に player.previousVideo() を呼び出し、そのリストが連続再生するように設定されている場合(loop)、リスト内の最初の動画が読み込まれて再生されます。

  • 再生リストの最初の動画を再生中に player.previousVideo() を呼び出し、連続再生が設定されていない場合、再生リストの最初の動画がもう 1 度始めから再生されます。

player.playVideoAt(index:Number):Void
この関数は、再生リストの指定された動画を読み込んで再生します。
  • index パラメータ(必須)には、再生リスト中の再生する動画のインデックスを指定します。このパラメータはゼロベース インデックスを使用するため、値 0 はリスト内の最初の動画を指定します。再生リストがシャッフルされた場合、この関数は、シャッフルした再生リストの指定された部分を再生します。

プレーヤーの音量の変更

player.mute():Void
プレーヤーをミュートします。
player.unMute():Void
プレーヤーのミュートを解除します。
player.isMuted():Boolean
プレーヤーがミュートされている場合は true を、ミュートされていない場合は false を返します。
player.setVolume(volume:Number):Void
音量を設定します。0100 の整数値を指定します。
player.getVolume():Number
プレーヤーの現在の音量を 0100 の整数値で返します。getVolume() は、プレーヤーがミュートされている場合でも音量を返します。

プレーヤーのサイズの設定

player.setSize(width:Number, height:Number):Object
プレーヤーを含む <iframe> のサイズをピクセル単位で設定します。

再生速度率の設定

player.getPlaybackRate():Number
この関数は、再生中の動画の再生速度を取得します。デフォルトの再生速度は 1 で、標準速度で再生されていることを示します。0.250.511.5、および 2 などの値になります。
player.setPlaybackRate(suggestedRate:Number):Void
この関数は、現在の動画の推奨再生率を設定します。再生速度を変更した場合は、頭出し済みまたはこれから再生される動画に関してのみ適用されます。頭出し済みの動画の再生率を設定した場合は、playVideo 関数が呼び出されるかユーザーがプレーヤー コントロールから再生を直接開始したときに、その率が引き続き有効になります。さらに、動画や再生リストを頭出しする関数や読み込む関数を呼び出すと(cueVideoByIdloadVideoById など)、再生速度が 1 にリセットされます。

この関数を呼び出しても、再生速度が実際に変わるとは限りません。実際に再生速度が変わった場合には onPlaybackRateChange イベントが起動します。コードは setPlaybackRate 関数の呼び出しそのものにではなくこのイベントに反応するように指定する必要があります。

getAvailablePlaybackRates メソッドは、現在再生中の動画に設定可能な再生速度を返します。ただし、サポートされていない整数や浮動小数点数を suggestedRate パラメータに設定した場合、プレーヤーは値を、1 の方向でサポートされている最も近い値に切り捨てます。
player.getAvailablePlaybackRates():Array
この関数は、現在の動画で設定可能な再生率を返します。デフォルト値は 1 で、標準速度で再生されることを示します。

関数は最低速から順に、再生速度の値の配列を返します。プレーヤーが再生速度の変更をサポートしていない場合も、配列に少なくとも 1 つの値を含める必要があります。

再生リストの再生動作の設定

player.setLoop(loopPlaylists:Boolean):Void

この関数は、動画プレーヤーが再生リストを繰り返し再生するか(ループ)、または再生リストの最後の動画の再生が終了したら停止するかを指定します。デフォルトの動作では、再生リストはループしません。

この設定は、別の再生リストを読み込んだり頭出しした後も保持されます。つまり、setLoop 関数を値 true で呼び出し、別の再生リストを読み込むと、その再生リストもループします。

必須の loopPlaylists パラメータは、ループの動作を指定します。

  • このパラメータ値が true の場合、動画プレーヤーは再生リストを繰り返して再生します。再生リストの最後の動画の再生後、再生リストの先頭に戻ってもう一度再生します。

  • このパラメータ値が false の場合、再生リストの最後の動画の再生が終わると、再生が終了します。

player.setShuffle(shufflePlaylist:Boolean):Void

この関数は再生リストの動画をシャッフルし、再生リストの作成者が指定した順序とは異なる順序で動画が再生されるようにします。再生中の再生リストをシャッフルした場合、動画の再生を続けながらリストの順序を変更します。次に再生される動画は、並び替え後のリストから選択されます。

この設定は、別の再生リストを読み込んだり頭出しした場合は保持されません。つまり、再生リストを読み込み、setShuffle 関数を呼び出して別の再生リストを読み込んだ場合、その再生リストはシャッフルされません。

shufflePlaylist パラメータ(必須)は、YouTube が再生リストをシャッフルするかどうかを指定します。

  • このパラメータ値が true の場合、YouTube は再生リストの順序をシャッフルします。シャッフル済みの再生リストのシャッフルを指定すると、もう一度シャッフルされます。

  • パラメータ値が false の場合、YouTube は再生リストを基の順序に戻します。

再生ステータス

player.getVideoLoadedFraction():Float
プレーヤーがバッファ済みの動画の割合を 01 の数値で返します。このメソッドは、廃止された 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 メソッドを使用してください。

このメソッドは、読み込み済みの動画の概数を示す 01000 の値を返します。動画の読み込み済みの部分は、getVideoBytesLoaded 値を getVideoBytesTotal 値で割ることで算出できます。
player.getVideoBytesTotal():Number
2012 年 7 月 18 日に廃止されました。 バッファ済みの動画の割合を算出するには、代わりに getVideoLoadedFraction メソッドを使用してください。

読み込み済み / 再生中の動画のサイズまたは動画のサイズの概数をバイト数で返します。

このメソッドは常に値 1000 を返します。動画の読み込み済みの部分は、getVideoBytesLoaded 値を getVideoBytesTotal 値で割ることで算出できます。

再生画質

player.getPlaybackQuality():String
この関数は、現在の動画の実際の画質を取得します。戻り値は highreshd1080hd720largemedium、および small です。現在動画がない場合は undefined が返されます。
player.setPlaybackQuality(suggestedQuality:String):Void
この関数は、現在の動画の推奨画質を設定し、現在の位置から新しい画質で動画を再読み込みします。再生画質を変更した場合、再生している動画の画質のみが変更されます。この関数を呼び出しても、実際に再生画質が変わるとは限りません。実際に再生画質が変わった場合には onPlaybackQualityChange イベントが起動します。コードは setPlaybackQuality 関数の呼び出しそのものにではなくこのイベントに反応するように指定する必要があります。

suggestedQuality パラメータ値には、smallmediumlargehd720hd1080highres または default を指定できます。パラメータ値は default に設定することをお勧めします。この設定では YouTube が最適な再生画質を自動選択します。最適な再生画質は、ユーザー、動画、システムなどの再生条件によって異なります。

動画の再生画質を指定する場合、指定した画質はその動画でのみ有効です。動画プレーヤーのサイズに合った再生画質を選択する必要があります。たとえば、1280x720 ピクセルの動画プレーヤーを表示しているページでは、hd1080 画質の動画よりも hd720 画質の動画のほうがきれいに表示されます。動画に設定可能な画質のレベルを調べるため、getAvailableQualityLevels() 関数を呼び出すことをお勧めします。

以下のリストは、さまざまな標準プレーヤーのサイズに対応する再生画質のレベルを示しています。動画プレーヤーの高さは以下のいずれかの値に、プレーヤーのサイズは 16:9 のアスペクト比にそれぞれ設定することをお勧めします。上述のとおり、標準のプレーヤー サイズを選択する場合も suggestedQuality パラメータ値を default に設定して、最適な再生画質が自動的に選択されるようにすることをお勧めします。

  • 画質レベル 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 が適切な再生画質を選択します。この設定は、画質レベルをデフォルトの状態に戻します。それまでに cueVideoByIdloadVideoById または setPlaybackQuality の各関数で行った再生画質の設定は無効になります。

動画で無効な suggestedQuality レベルを指定して setPlaybackQuality 関数を呼び出すと、有効な画質の中で 2 番目に低い画質が設定されます。たとえば、画質レベル large をリクエストし、それが無効な場合、再生画質は medium に設定されます(このレベルが有効であれば)。

また、suggestedQuality に認識できない画質レベルを設定すると、suggestedQualitydefault を設定した場合と同様に処理されます。
player.getAvailableQualityLevels():Array
この関数は、現在の動画で有効な画質のセットを返します。この関数を使用すると、ユーザーが表示している画質よりも高い画質で動画を再生できるかどうかを判断し、プレーヤーにボタンなどの要素を表示してユーザーが画質を変更できるようにすることができます。

この関数は、高画質から低画質の順で、画質を示す文字列の配列を返します。配列要素の値は highreshd1080hd720largemediumsmall です。現在の動画がない場合、この関数は空の配列を返します。

クライアントで、最高または最低の画質や不明な画質形式に自動的に切り替えないようにしてください。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 は再生リストの最初の動画を示します。

  • 再生リストをシャッフル済みの場合、戻り値は、シャッフルされた再生リスト中の動画の順序を示します。

イベント リスナーの追加または削除

player.addEventListener(event:String, listener:String):Void
指定した event のリスナー関数を追加します。プレーヤーが起動するイベントの説明については、以下のイベントのセクションを参照してください。listener は、指定したイベントが起動したときに実行する関数を指定する文字列です。
player.removeEventListener(event:String, listener:String):Void
指定した event のリスナー関数を削除します。listener は、指定したイベントが起動したときに実行されなくなった関数を指定する文字列です。

DOM ノードへのアクセスと変更

player.getIframe():Object
このメソッドは、埋め込まれた <iframe> に対する DOM ノードを返します。
player.destroy():Void
プレーヤーを含む <iframe> を削除します。

イベント

API は、埋め込み動画プレーヤーの変化をアプリケーションに通知するためにイベントを起動します。前のセクションで説明したように、YT.Player オブジェクトを作成するときにイベント リスナーを追加することでイベントをサブスクライブできます。また、addEventListener 関数も使用できます。

API はイベント オブジェクトを 1 つの引数として各関数に渡します。イベント オブジェクトには次のプロパティが含まれています。

  • イベントの target は、イベントに応答する動画プレーヤーを識別します。
  • イベントの data は、イベントに対応する値を指定します。なお、onReady イベントは data プロパティを指定しません。

次のリストでは、API が起動するイベントを定義しています。

onReady
このイベントは、プレーヤーが読み込みを完了し、API 呼び出しの受信を開始する準備ができると起動します。動画の再生や動画についての情報の表示など、プレーヤーの準備ができ次第すぐに特定の操作を自動的に実行するには、この関数をアプリケーションに実装する必要があります。

下記の例は、このイベントを処理するためのサンプルコードを示しています。API がこの関数機能に渡すイベント オブジェクトには target プロパティがあり、これによってプレーヤーを識別します。現在読み込まれている動画の埋め込みコードをこの関数が取得すると、動画の再生が開始され、embed-codeid 値を持つページ要素に埋め込みコードが表示されます。
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
このイベントは、動画の再生画質が変わると起動します。たとえば、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 このオプションは、プレーヤーに表示される字幕のフォントサイズを調整します。

有効な値は -10123 です。デフォルトのサイズは 0 で、最小サイズは -1 です。このオプションを -1 未満の整数に設定すると、字幕は最小サイズで表示されます。また、3 を超える整数に設定すると、最大サイズで表示されます。
cc reload このオプションは、再生中の動画の字幕データを再読み込みします。オプションの値を取得すると、値は null になります。字幕データを再読み込みする場合は、値を true に設定します。

モバイルの注意事項

自動再生とスクリプト再生

Chrome や Safari などのモバイル ブラウザでは、HTML5 <video> 要素を再生するには、ユーザーの操作(プレーヤーをタップするなど)による起動が必要です。以下は、Apple のドキュメントの抜粋です。

「警告: ユーザーが費用負担する携帯電話ネットワーク経由で要求していないダウンロードを防止するために、iOS の Safari では組み込みメディアを自動再生できません。必ずユーザーが自分で再生します。」

この制限があるため、autoplayplayVideo()loadVideoById() などの関数およびパラメータはすべてのモバイル環境では動作しません。

YT.Player オブジェクトの作成

  • 例 1: 大きい音量での再生

    この例では、1280 px X 720 px の動画プレーヤーを作成します。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
        }
      });
    }

改訂履歴

このセクションでは、YouTube IFrame Player API の変更点とドキュメントの更新を示します。この変更履歴を定期購読してください定期購読

April 28, 2014

This update contains the following changes:

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

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.