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
この関数は、指定された動画のサムネイルを読み込み、プレーヤーで動画を再生する準備をします。プレーヤーは、
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
プロパティ(省略可能)には、取得する結果フィードの種類を指定します。有効なパラメータ値は、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 } }); }
改訂履歴
このセクションでは、YouTube IFrame Player API の変更点とドキュメントの更新を示します。この変更履歴を定期購読してください。
April 28, 2014
This update contains the following changes:
-
The new removeEventListener function lets you remove a listener for a specified event.
March 25, 2014
This update contains the following changes:
-
The Requirements section has been updated to note that embedded players must have a viewport that is at least 200px by 200px. If a player displays controls, it must be large enough to fully display the controls without shrinking the viewport below the minimum size. We recommend 16:9 players be at least 480 pixels wide and 270 pixels tall.
July 23, 2013
This update contains the following changes:
-
The Overview now includes a video of a 2011 Google I/O presentation that discusses the iframe player.
October 31, 2012
This update contains the following changes:
-
The Queueing functions section has been updated to explain that you can use either argument syntax or object syntax to call all of those functions. Note that the API may support additional functionality in object syntax that the argument syntax does not support.
In addition, the descriptions and examples for each of the video queueing functions have been updated to reflect the newly added support for object syntax. (The API's playlist queueing functions already supported object syntax.)
-
When called using object syntax, each of the video queueing functions supports an
endSeconds
property, which accepts a float/integer and specifies the time when the video should stop playing whenplayVideo()
is called. -
The
getVideoStartBytes
method has been deprecated. The method now always returns a value of0
.
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 theonYouTubeIframeAPIReady
function is only called if the closing</iframe>
element is present.
August 6, 2012
This update contains the following changes:
-
The Operations section has been expanded to list all of the supported API functions rather than linking to the JavaScript Player API Reference for that list.
-
The API supports several new functions and one new event that can be used to control the video playback speed:
-
Functions
getAvailablePlaybackRates
– Retrieve the supported playback rates for the cued or playing video. Note that variable playback rates are currently only supported in the HTML5 player.getPlaybackRate
– Retrieve the playback rate for the cued or playing video.setPlaybackRate
– Set the playback rate for the cued or playing video.
-
Events
onPlaybackRateChange
– This event fires when the video's playback rate changes.
-
July 19, 2012
This update contains the following changes:
-
The new
getVideoLoadedFraction
method replaces the now-deprecatedgetVideoBytesLoaded
andgetVideoBytesTotal
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 of5
, 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 namedonYouTubePlayerAPIReady
. 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 anonYouTubePlayerAPIReady
function, both functions will be called, and theonYouTubeIframeAPIReady
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()
anddestroy()
methods. ThesetSize()
method sets the size in pixels of the<iframe>
that contains the player and thedestroy()
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 aninline-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.