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

IFrame Player API を使うと、YouTube 動画プレーヤーをウェブサイトに埋め込み、JavaScript でプレーヤーを制御できます。ウェブページに Flash オブジェクトを埋め込む Flash や JavaScript のプレーヤー 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>

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

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

または、<iframe> 要素をページに直接配置してもかまいません。配置方法は、動画プレーヤーの読み込みのセクションで説明しています。
このセクションのコードにより IFrame Player API JavaScript コードが読み込まれます。この例では DOM 変更を使って API コードをダウンロードすることで、コードが非同期で取得されるようにします。<script> タグの async 属性（非同期のダウンロードを有効化）は最新のブラウザではまだサポートされていません。これは Stack Overflow の回答で説明されているとおりです。
プレーヤー API コードがダウンロードされると、onYouTubeIframeAPIReady 関数が実行されます。コードのこの部分では、組み込もうとしている動画プレーヤーを表すグローバル変数 player を定義します。続いて、関数によって動画プレーヤーオブジェクトが作成されます。
onReady イベントが起動されると、onPlayerReady 関数が実行されます。この例では、関数は動画プレーヤーの準備ができると再生を開始することを指示しています。
プレーヤーの状態が変化すると、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
    }
  });
}

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

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

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

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 プロパティ（省略可能）には、取得する結果フィードの種類を指定します。有効なパラメータ値は、playlist、search および user_uploads です。デフォルト値は playlist です。
- list プロパティ（必須）には、YouTube が返す動画のリストを特定するキーを含めます。
  - listType プロパティの値が playlist の場合、list プロパティには再生リスト ID または動画 ID の配列を指定します。YouTube Data API フィードでは、<yt:playlistid> タグで再生リスト ID を、<yt:videoid> タグで動画 ID をそれぞれ指定します。
  - listType プロパティの値が search の場合、list プロパティには検索クエリを指定します。
  - listType プロパティの値が user_uploads の場合、list プロパティにはアップロードした動画を返すユーザーを指定します。
- index プロパティ（省略可能）には、再生リスト中の最初に再生する動画のインデックスを指定します。このパラメータはゼロベースインデックスを使用するため、デフォルトのパラメータ値は 0 で、再生リストの最初の動画を読み込んで再生します。
- 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 プロパティ（省略可能）には、取得する結果フィードの種類を指定します。有効なパラメータ値は、playlist、search および user_uploads です。デフォルト値は playlist です。
- list プロパティ（必須）には、YouTube が返す動画のリストを特定するキーを含めます。
  - listType プロパティの値が playlist の場合、list プロパティには再生リスト ID または動画 ID の配列を指定します。YouTube Data API フィードでは、<yt:playlistid> タグで再生リスト ID を、<yt:videoid> タグで動画 ID をそれぞれ指定します。
  - listType プロパティの値が search の場合、list プロパティには検索クエリを指定します。
  - listType プロパティの値が user_uploads の場合、list プロパティにはアップロードした動画を返すユーザーを指定します。
- index プロパティ（省略可能）には、再生リスト中の最初に再生する動画のインデックスを指定します。このパラメータはゼロベースインデックスを使用するため、デフォルトのパラメータ値は 0 で、再生リストの最初の動画を読み込んで再生します。
- startSeconds プロパティ（省略可能）には、リストの最初の動画の再生を開始する位置（時間）を浮動小数点数または整数で指定します。
- suggestedQuality プロパティ（省略可能）には、リストの動画に対する推奨再生画質を指定します。再生画質について詳しくは、setPlaybackQuality 関数の定義を参照してください。

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

動画の再生

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

注: プレーヤーに付属の再生ボタンで再生が開始された場合、動画の公式再生回数のみがカウントされます。

player.pauseVideo():Void: 再生中の動画を一時停止します。この関数を実行した後のプレーヤーの最終的な状態は paused（2）になります。ただし、関数を呼び出したときのプレーヤーの状態が ended（0）のときは、状態は変わりません。

player.stopVideo():Void: 現在の動画の読み込みを停止してキャンセルします。この関数は、ユーザーがプレーヤーでこれ以上動画を再生しないときのために予約されています。ただし、これはまれなケースです。動画を一時停止するという目的には、pauseVideo 関数を使用してください。プレーヤーで再生する動画を変更する場合は、stopVideo を呼び出さずにキュー関数のいずれか 1 つを呼び出してください。

重要: pauseVideo 関数（プレーヤーが paused（2）状態のまま）と異なり、stopVideo 関数ではプレーヤーが再生以外の状態になります（例: ended（0）、paused（2）、video cued（5）、または unstarted（-1）。

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

動画を指定された時間シークします。この関数を呼び出したときにプレーヤーが一時停止している場合は一時停止のままになり、その他の状態（playing、video cued など）から呼び出した場合は、動画が再生されます。

seconds パラメータには、プレーヤーを進ませる秒数を指定します。

ユーザーがシークしている部分がダウンロード済みでなければ、このパラメータで指定した時間の前の最も近いキーフレームまで進みます。シークしている部分をダウンロード済みの場合、プレーヤーは Flash 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: 音量を設定します。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

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

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

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

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

player.setShuffle(shufflePlaylist:Boolean):Void

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

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

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

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

再生ステータス

player.getVideoLoadedFraction():Float: プレーヤーがバッファ済みの動画の割合を 0～1 の数値で返します。このメソッドは、廃止された getVideoBytesLoaded メソッドや getVideoBytesTotal メソッドよりも信頼性の高い数値を返します。

player.getPlayerState():Number

プレーヤーの状態を返します。値は次のいずれかです。

-1 – 未開始
0 – 終了
1 – 再生中
2 – 一時停止
3 – バッファリング中
5 – 頭出し済み

player.getCurrentTime():Number: 動画の再生を開始してからの経過時間を秒数で返します。

player.getVideoStartBytes():Number: 2012 年 10 月 31 日に廃止されました。動画ファイルの読み込みを開始した位置をバイト数で返します（現在、このメソッドは常に値 0 を返します）。サンプルシナリオ: まだ読み込んでいない位置をユーザーがシークした場合や、まだ読み込んでいない動画セグメントの再生をプレーヤーがリクエストした場合に使用します。

player.getVideoBytesLoaded():Number: 2012 年 7 月 18 日に廃止されました。バッファ済みの動画の割合を算出するには、代わりに getVideoLoadedFraction メソッドを使用してください。

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

player.getVideoBytesTotal():Number: 2012 年 7 月 18 日に廃止されました。バッファ済みの動画の割合を算出するには、代わりに getVideoLoadedFraction メソッドを使用してください。

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

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

再生画質

player.getPlaybackQuality():String: この関数は、現在の動画の実際の画質を取得します。戻り値は highres、hd1080、hd720、large、medium、および small です。現在動画がない場合は undefined が返されます。

player.setPlaybackQuality(suggestedQuality:String):Void

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

suggestedQuality パラメータ値には、small、medium、large、hd720、hd1080、highres または default を指定できます。パラメータ値は 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 が適切な再生画質を選択します。この設定は、画質レベルをデフォルトの状態に戻します。それまでに cueVideoById、loadVideoById または setPlaybackQuality の各関数で行った再生画質の設定は無効になります。

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

また、suggestedQuality に認識できない画質レベルを設定すると、suggestedQuality に default を設定した場合と同様に処理されます。

player.getAvailableQualityLevels():Array: この関数は、現在の動画で有効な画質のセットを返します。この関数を使用すると、ユーザーが表示している画質よりも高い画質で動画を再生できるかどうかを判断し、プレーヤーにボタンなどの要素を表示してユーザーが画質を変更できるようにすることができます。

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

クライアントで、最高または最低の画質や不明な画質形式に自動的に切り替えないようにしてください。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-code の id 値を持つページ要素に埋め込みコードが表示されます。

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

モバイルの注意事項

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

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

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

この制限があるため、autoplay、playVideo()、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
    }
  });
}