YouTube Player API Reference for iframe Embeds

IFrame Player API を使用すると、YouTube 動画プレーヤーをウェブサイトに埋め込み、JavaScript を使用してプレーヤーを制御できます。

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

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

要件

ユーザーのブラウザが HTML5 postMessage 機能をサポートしている必要があります。ほとんどの最新のブラウザは postMessage をサポートしています。

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

IFrame API を使うウェブページには、次の JavaScript 関数も実装する必要があります。

  • onYouTubeIframeAPIReady - ページで Player API の JavaScript のダウンロードが完了すると、この関数が呼び出されます。これにより、ページで 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. 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 と player パラメータの値を指定する必要はありません。セキュリティ対策として、URL に origin パラメータも含め、URL スキーム（http:// または https://）とホストページの完全なドメインをパラメータ値として指定する必要があります。origin は省略可能ですが、追加すると、悪意のあるサードパーティの JavaScript がページに挿入され、YouTube プレーヤーの制御が不正使用されるのを防ぐことができます。

動画プレーヤー オブジェクトの作成のその他の例については、例をご覧ください。

運用

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

関数

キュー関数

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

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

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

  • オブジェクト構文。オブジェクトを単一のパラメータとして渡し、関数の引数用のオブジェクト プロパティを定義することができます。さらにこの 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 であるため、デフォルトの動作は再生リスト内の最初の動画を読み込んで再生することです。

    • オプションの 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 であるため、デフォルトの動作はリスト内の最初の動画を読み込んで再生することです。

    • オプションの 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 であるため、デフォルトの動作は再生リスト内の最初の動画を読み込んで再生することです。

    • 省略可能な 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 であるため、デフォルトの動作はリスト内の最初の動画を読み込んで再生することです。

    • 省略可能な startSeconds プロパティは浮動小数点数または整数を受け取り、リスト内の最初の動画の再生を開始する時刻を指定します。

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

動画の再生

player.playVideo():Void
現在キューに登録されている動画または読み込まれている動画を再生します。この関数が実行された後の最終的なプレーヤーの状態は playing（1）になります。

注: 再生は、プレーヤーのネイティブ再生ボタンから開始された場合にのみ、動画の公式視聴回数にカウントされます。
player.pauseVideo():Void
現在再生中の動画を一時停止します。この関数の実行後の最終的なプレーヤーの状態は paused（2）になります。ただし、関数が呼び出されたときにプレーヤーが ended（0）状態にある場合、プレーヤーの状態は変更されません。
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° を表します。ビューが時計回りに回転すると値は増加し、反時計回りに回転すると値は減少します。

埋め込みプレーヤーには、ビューのロール調整用のユーザー インターフェースが表示されません。ロールは、次のいずれかの方法で調整できます。
  1. モバイル ブラウザの向きセンサーを使用して、ビューのロールを提供します。向きセンサーが有効になっている場合、getSphericalProperties 関数は常に 0 を roll プロパティの値として返します。
  2. 向きセンサーが無効になっている場合は、この API を使用してロールをゼロ以外の値に設定します。
fov ビューポートの長い辺に沿って測定したビューの視野を度数で表した値（30 ～ 120 の範囲）。短い辺は、ビューのアスペクト比に比例するように自動的に調整されます。

デフォルト値は 100 度です。値を小さくすると動画コンテンツが拡大され、値を大きくすると動画コンテンツが縮小されます。この値は、API を使用するか、動画が全画面表示モードになっているときにマウスホイールを使用して調整できます。
player.setSphericalProperties(properties:Object):Void
360° 動画の再生時の動画の向きを設定します。（現在の動画が球面動画でない場合、このメソッドは入力に関係なく no-op です）。

プレーヤー ビューは、このメソッドの呼び出しに応答して更新し、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 経由で変更できます。実際、モバイル デバイスで fov プロパティを変更する唯一の方法は API です。これはデフォルトの動作です。
  • 値が false の場合、デバイスの動きは 360° ビューに影響しません。yaw、pitch、roll、fov プロパティはすべて API 経由で設定する必要があります。

サポートされていないモバイル デバイス
enableOrientationSensor プロパティ値は再生エクスペリエンスに影響しません。

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

player.nextVideo():Void
この関数は、再生リスト内の次の動画を読み込んで再生します。

  • 再生リストの最後の動画の視聴中に player.nextVideo() が呼び出され、再生リストが連続再生（loop）に設定されている場合、プレーヤーはリスト内の最初の動画を読み込んで再生します。

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

player.previousVideo():Void
この関数は、再生リスト内の前の動画を読み込んで再生します。

  • 再生リストの最初の動画の視聴中に player.previousVideo() が呼び出され、再生リストが連続再生（loop）に設定されている場合、プレーヤーはリスト内の最後の動画を読み込んで再生します。

  • 再生リスト内の最初の動画の視聴中に player.previousVideo() が呼び出され、再生リストが連続再生するように設定されていない場合、プレーヤーは再生リスト内の最初の動画を最初から再開します。

player.playVideoAt(index:Number):Void
この関数は、再生リスト内の指定した動画を読み込んで再生します。

  • 必須の index パラメータには、再生リストで再生する動画のインデックスを指定します。このパラメータはゼロベースのインデックスを使用します。値 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 つ以上の値（1）を含める必要があります。

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

player.setLoop(loopPlaylists:Boolean):Void

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

この設定は、別の再生リストを読み込んだりキューに追加したりしても保持されます。つまり、再生リストを読み込み、true の値を指定して setLoop 関数を呼び出し、2 つ目の再生リストを読み込むと、2 つ目の再生リストもループします。

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

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

  • パラメータの値が false の場合、動画プレーヤーが再生リスト内の最後の動画を再生すると、再生は終了します。

player.setShuffle(shufflePlaylist:Boolean):Void

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

この設定は、別の再生リストを読み込んだりキューに追加したりすると保持されません。つまり、再生リストを読み込んで setShuffle 関数を呼び出し、2 つ目の再生リストを読み込んだ場合、2 つ目の再生リストはシャッフルされません。

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

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

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

再生ステータス

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 は再生リストの最初の動画を示します。

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

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

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 イベントと 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/}（ended - 終了）
  • 1（playing - 再生中）
  • 2 (一時停止)
  • 3（buffering - バッファリング中）
  • 5（video cued - 頭出し済み）

プレーヤーが動画を初めて読み込むと、unstarted（-1）イベントがブロードキャストされます。動画がキューに登録され、再生の準備が整うと、プレーヤーは video cued（5）イベントをブロードキャストします。コードでは、整数値を指定することも、次のいずれかの Namespace 変数を使用することもできます。

  • 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 で試行された再生が含まれます。

ほとんどのブラウザには、特定の条件が満たされた場合に、パソコン、モバイル、その他の環境で自動再生をブロックできるポリシーがあります。このポリシーがトリガーされる例としては、ユーザー操作なしでミュートが解除された再生や、クロスオリジン 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: 大音量での再生

    この例では、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,
      '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 WebView Media Integrity API を拡張し、埋め込みメディア プレーヤー（Android アプリに埋め込まれた YouTube プレーヤーを含む）が埋め込みアプリの真正性を確認できるようにしました。この変更により、埋め込みアプリは証明済みのアプリ 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:

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.