iframe埋め込み版 YouTube Player API

iframe版のAPIではクライアントの環境に応じて、HTML5またはFlashで再生します。

このAPIは、HTML5のpostMessageに対応した環境でしか機能しません。よってInternet Explorer 8より前には対応しません。要件 - iframe 組み込みの YouTube Player API リファレンス - YouTube | Google Developers

実行例

再生リストを使用して、複数の動画を連続して再生します。

プレーヤーの準備ができていません。
[プレーヤーの状態 : ?]

プレーヤーの作成

IFrame Player APIの読み込み

var script = document.createElement( 'script' );
script.src = "//www.youtube.com/iframe_api";

var firstScript = document.getElementsByTagName( 'script' )[ 0 ];
firstScript.parentNode.insertBefore( script , firstScript );

なおhttp://www.youtube.com/player_apiが現在では/iframe_apiとなっていますが、古いURLもサポートされるため違いはありません。改訂履歴 | iframe 組み込みの YouTube Player API リファレンス | YouTube IFrame API | Google Developers

YouTube Playerの作成

APIのJavaScriptコードが読み込まれると、APIはonYouTubeIframeAPIReady()を呼び出します。よってその名前の関数をグローバルスコープ (Windowオブジェクトのプロパティ) として定義し、そこでプレーヤーの作成処理を行います。

var player = null;
function onYouTubeIframeAPIReady()
{
    player = new YT.Player( playerContainerID, options );
}

/player_apiと同様に、onYouTubePlayerAPIReady()もonYouTubeIframeAPIReady()に名前が変更されています。しかし従来のPlayerAPI…も使用可能であり、IframeAPI…の後にPlayerAPI...が呼び出されます。

なおSWFObject版の関数の名前はonYouTubePlayerReady()であり、この関数はonYouTubeIframeAPIReady()です。

コンストラクタ

コンストラクタは次のように引数をとり、

YT.Player( playerContainerID, options )

playerContainerIDはプレーヤーを配置する要素のid属性で、optionsでプレーヤーの設定を与えます。

var options =
{
    width: 640,
    height: 390,
    videoId: 'xxxxx',
    playerVars: {
        autoplay: 1,
        controls: 0
    },
    events: {
        onReady: onPlayerReady,
        onStateChange: onPlayerStateChange
    }
};

playerVarsには、埋め込みプレーヤーのパラメータを指定します。パラメータ - YouTube 埋め込みプレーヤーとプレーヤーのパラメータ - YouTube | Google Developers

autoplayの指定による自動再生は、一部のモバイル ブラウザでは無視されます。モバイルの注意事項 - iframe 組み込みの YouTube Player API リファレンス - YouTube | Google Developers

Player作成後の処理

YT.PlayerコンストラクタのeventsオブジェクトのonReadyでコールバック関数を設定しておくと、プレーヤー作成後にそれが呼び出されます。プレーヤーの初期設定はここで行います。

プレーヤーの制御

プレーヤーの制御は、onReadyイベントによりプレーヤーの準備が整ったことを確認してから行います。

分類 メソッド 説明
キュー関数 cueVideoById 動画をIDで設定し、再生準備をする。
loadVideoById ※2 動画をIDで指定し、再生する。
cueVideoByUrl  
loadVideoByUrl  
再生/停止などの操作 playVideo ※2  
pauseVideo  
stopVideo 再生を停止する。このとき再生リストが登録されているならば、それもクリアする。
seekTo  
clearVideo  
音量 mute  
unMute  
isMuted  
setVolume 音量を設定する。認められるのは0～100の整数。未設定の場合は100。設定した値は、プレーヤーの再起動後も維持される
getVolume 現在の音量を取得する。ミュートでも値が返される。
プレーヤーのサイズ setSize  
再生速度 getPlaybackRate  
setPlaybackRate  
getAvailablePlaybackRates  
再生状態 getVideoLoadedFraction  
getPlayerState  
getCurrentTime  
再生画質 getPlaybackQuality  
setPlaybackQuality  
getAvailableQualityLevels  
動画の情報 getVideoData 動画の情報が返される。[非サポート]
  • author
  • list
  • title
  • video_id … 動画ID
getDuration 動画の長さが秒数で返される。
getVideoUrl 動画のYouTube.comにおけるURLが返される。
getVideoEmbedCode 動画の埋め込みコードが返される。
イベントリスナ addEventListener  
iframe要素 getIframe  
destroy  
※1 これらのメソッドは、iframeではないSWFObject版の関数とほぼ同じです。
※2 一部のモバイル ブラウザでは、プログラムによるvideo要素の再生を許可していません。 モバイルの注意事項
関数 - iframe 組み込みの YouTube Player API リファレンス - YouTube | Google Developers

動画の再生

一部のモバイル ブラウザではプログラムによる再生を許可していないため、これらの関数は動作しない恐れがあります。モバイルの注意事項 - iframe 組み込みの YouTube Player API リファレンス - YouTube | Google Developers

loadVideoById

引数の与え方で2つの構文があります。

Argument syntax
player.loadVideoById(
    videoId,
    startSeconds,
    suggestedQuality
    )

これはSWFObject版での動画の再生と同じです。

Object syntax
player.loadVideoById(
    {
        videoId: String,
        startSeconds: Number,
        endSeconds: Number,
        suggestedQuality: String
    } )

プレーヤーの状態

getPlayerState

player.getPlayerState()
getPlayerState - iframe 組み込みの YouTube Player API リファレンス | YouTube IFrame API | Google Developers

onStateChangeでイベントを捕捉できない状態では、getPlayerState()はつねに同じ値を返します。

プレーヤーの状態を表す値は、下表の定数により定義されています。

プレーヤーの状態
値 定数 意味
-1 YT.PlayerState.UNSTARTED 未開始 (unstarted)
0 YT.PlayerState.ENDED 終了 (ended)
1 YT.PlayerState.PLAYING 再生中 (playing)
2 YT.PlayerState.PAUSED 一時停止中 (paused)
3 YT.PlayerState.BUFFERING バッファリング中 (buffering)
5 YT.PlayerState.CUED 頭出し済み (videocued)
iframeではないSWFObject版のAPIと、プレーヤーの状態は同じ意味です。

再生速度 (Playback Rate)

player.setPlaybackRate( suggestedRate: Number )
setPlaybackRate - iframe 組み込みの YouTube Player API リファレンス | YouTube IFrame API | Google Developers

再生速度は再生中の動画にのみ適用され、動画が変更されると速度は1にリセットされます。

再生リスト (Playlist)

分類 メソッド 説明
キュー関数 cuePlaylist 再生リストを設定し、再生準備をする。
loadPlaylist 再生リストを設定し、再生する。
再生などの操作 nextVideo 再生リストの、次の動画を再生する。
previousVideo 再生リストの、前の動画を再生する。
playVideoAt 再生リストから、指定インデックスの動画を再生する。再生したことがある動画は、前回の終了位置から再開される。指定するインデックスは、ゼロから始まる。
再生方法 setLoop 再生リストをくり返し再生する。つまりループする。
setShuffle 再生リストの動画をシャッフルする。
再生リストの情報 getPlaylist 再生リストの動画IDを、配列で取得する。
getPlaylistIndex 現在再生している動画の、再生リストでのインデックスを取得する。
リストのキュー関数 - iframe 組み込みの YouTube Player API リファレンス - YouTube | Google Developers

再生リストを編集する機能は提供されていないため、その必要があるときにはcuePlaylistまたはloadPlaylistで新たに作成します。

Flash非対応のAndroid 2.2で再生リストを使用すると、再生の停止が困難になります。それは再生時にフルスクリーンになり、戻るボタンで再生を停止させてもリストの次の項目の再生が自動で始まってしまうからです。そのため再生を停止させるには次の項目の再生が始まる前に、素早くもう一度戻るボタンを押さねばなりません。

再生リストの作成

再生リストはメソッドで設定する以外にも、次のようにYT.Playerオブジェクトの作成時に引数のplayerVars.playlistで指定する方法もあります。

new YT.Player( playerContainerID, {
        playerVars: {
            playlist: 'videoID1,videoID2,videoID3',
            ...
        },
        ...
    } );

再生リストに無効な動画IDが含まれている場合、その動画は実際には再生リストに登録されません。

cuePlaylist

player.cuePlaylist(
    playlist,        // 再生リストに設定する動画IDの配列
    index,           // 再生リストのうち、最初に再生する動画のインデックス
    startSeconds,    // 再生するときの開始時間 [秒]
    suggestedQuality // 動画の推奨再生画質
    )
リストのキュー関数 - iframe 組み込みの YouTube Player API リファレンス - YouTube | Google Developers

イベント

イベントハンドラ イベント発生のタイミング
onReady プレーヤーの準備が整ったとき
onStateChange※1 プレーヤーの状態が変化したとき
onPlaybackQualityChange※1 再生画質が変化したとき
このイベントの発生理由については、SWFObject版と同様に注意が必要です。
onPlaybackRateChange 再生速度が変化したとき
onError※1 プレーヤーでエラーが発生したとき
onApiChange モジュールがロードまたはアンロードされたとき

※1 iframeではないSWFObject版のAPIのイベントと基本的に同じです。ただしイベントハンドラに渡される引数が異なり、iframe版ではオブジェクトが渡されます。そのオブジェクトは

  • target … イベントを発生したオブジェクトへの参照
  • data … プレーヤーの状態やエラーコードなどの値

の2つのプロパティを持ちます。

イベントハンドラの登録

イベントを捕捉するには、コンストラクタの引数で

var options =
    {
        events: {
            onReady: onPlayerReady,
            onStateChange: onPlayerStateChange
        }
    };
player = new YT.Player( 'playerId', options );

とするか、addEventListener()で

player.addEventListener( 'onReady', onPlayerReady );
player.addEventListener( 'onStateChange', onPlayerStateChange );

のようにします。

onReady

プレーヤーの準備が整ったときに呼ばれます。

function onPlayerReady( event )
{
    var player = event.target; // YT.Playerオブジェクト
}

Internet Explorerでこのイベントが発生しない場合には、APIを読み込むURLをhttps://www.youtube.com/iframe_apiとします。

onStateChange

プレーヤーの状態が変化したときに呼ばれます。

function onPlayerStateChange( event )
{
    var playerState = event.data;
}

このイベントはAPIの不具合により発生しないことがあります。より確実にイベントを捕捉するには旧来のSWFObject版を使用するか、次項のように対処します。

onStateChangeイベントが発生しない場合の対処法

onReadyのハンドラ内で登録

コンストラクタの引数ではなく、onReadyのハンドラ内でaddEventListener()により設定します。これにより、より確実にハンドラを登録できます。javascript - YouTube iframe player API - OnStateChange not firing - Stack Overflow

var options =
{
    events: {
        onReady: function( event )
        {
            player.addEventListener( 'onStateChange', onPlayerStateChange )
        }
    }
};
player = new YT.Player( 'playerId', options );
HTML5の強制

通常は環境に応じてHTML5またはFlashで再生されますが、これをHTML5で再生するように強制します。こうすることでもonStateChangeイベントが発生するようになります。YouTube iFrame API 'onStateChange' not firing in Firefox - Stack Overflow

player = new YT.Player( 'playerId',
    {
        width: '320',
        height: '240',
        videoId: 'xxxxx',
        playerVars: { html5: 1 },
        events:
            {
                onReady: onPlayerReady,
                onStateChange: onPlayerStateChange
            }
    } );
参考

onPlaybackRateChange

再生速度が変化したときに呼ばれます。

function onPlayerPlaybackRateChange( event )
{
    var rate = event.data;
}

このイベントは、次の3つの状況で発生します。

  • ユーザーによってプレーヤー上のコントロールが操作され、速度が変更された。
  • プログラムによってsetPlaybackRate()が呼ばれ、速度が変更された。
  • プログラムまたはプレイリストによって再生動画が変更され、速度がリセットされた。

参考

onError

function onPlayerError( event )
{
    var errorCode = event.data;
}

エラーコードについては、SWFObject版にまとめてあります。

セーフモード (Safety Mode)

セーフモードを有効にしている状態で不適切と認定されているコンテンツを再生しようとすると、コード150のエラーが発生します。そのときプレーヤーには「この動画はセーフモードでは再生できません。詳しくはこちらをご覧ください。(This video is unavailable in safety mode. Learn more.)」と表示され、セーフモード - YouTube ヘルプを確認するように案内されます。YouTubeに「セーフモード」 不適切な動画をフィルタリング - ITmedia ニュース (2010/02/12)

地域フィルタ (Regional filter)

視聴地域が制限されている動画をその地域以外から再生しようとすると、コード150のエラーが発生します。そのときプレーヤーには「この動画はご利用いただけません。(This video is not available. )」と表示されます。居住している地域で動画を再生できない - YouTube ヘルプ

字幕 (closed caption)

字幕の設定を変更するには、getOptions()で取得できる設定可能なモジュールに"captions"が含まれていなければなりません。

// 現在のプレーヤーで、設定可能なモジュールを取得
player.getOptions();
// Array [ "playlist", "iv-module", "captions" ]

また設定可能な項目も、同様にgetOptions()で確認できます。

// 指定のモジュールで、設定可能なオプションを取得
player.getOptions( 'captions' );
// Array [ "reload", "fontSize", "track", "tracklist", "translationLanguages", "displaySettings", "sampleSubtitle" ]

現在の設定値はgetOption()で確認できます。名前が似ていますが、getOptions()ではありません。

// 指定モジュールのオプションの、現在の設定値を取得
player.getOption( 'captions', 'displaySettings' );
// Object
// {
//     background : "#080808",
//     backgroundOpacity : 1,
//     charEdgeStyle : "uniform",
//     color : "#fff",
//     fontFamily : 4,
//     fontSizeIncrement : 0,
//     textOpacity : 1,
//     windowColor : "#080808",
//     windowOpacity : 0,
//     fontFamilyOption : "propSans"
// }
onApiChange - iframe 組み込みの YouTube Player API リファレンス - YouTube | Google Developers

表示設定

字幕の色やフォントはdisplaySettingsで、フォントサイズはfontSizeから変更できます。

たとえば、文字を赤くするには次のようにします。 この方法は、現在では機能しません。

player.setOption( 'captions', 'displaySettings', { color: '#f00' } );

文字の大きさはfontSizeに、-1、0、1、2、3のいずれかを指定します。この値の既定値は0で、3が最大です。

player.setOption( 'captions', 'fontSize', 3 );

再生を開始すると、モジュールの対応状況を確認できます。

項目 値
設定可能なモジュール 未確認
captionsで設定可能なオプション 未確認

字幕が表示されているときに以下の値を変更すると、その影響を確認できます。

displaySettings.color (字幕の色)
fontSize (字幕の大きさ)

参考

トラブル対処法

CSSのz-indexが機能しない

iframe版のYouTubeでは、既定ではCSSのz-indexの指定が無視されます。これを有効とするには、iframeのsrc属性のクエリにwmode=transparentを付加します。これをAPIから指定するには、コンストラクタのplayerVarsプロパティでplayerVars: { wmode: 'transparent' }のようにします。

※ブラウザによっては、このような配慮は不要です。Firefox、ChromeおよびOperaでは問題となりませんでした。

既定 wmode=transparent
フレームの前面に表示
フレームの前面に表示

「すぐに再生が開始しない場合は、端末を再起動してください。」として再生できない

再生時に「すぐに再生が開始しない場合は、端末を再起動してください。(If playback doesn't begin shortly, try restarting your device.)」と表示され、再生できないことがあります。この原因はさまざまですが、モバイル端末で自動再生しようとしたときに発生することがあります。よってモバイル端末では自動再生しないようにするのが、解決方法の1つです。

Failed to execute 'postMessage' on 'DOMWindow'

「Failed to execute 'postMessage' on 'DOMWindow': The target origin provided ('https://www.youtube.com') does not match the recipient window's origin ('http://localhost').」

postMessage()の呼び出し時に、メッセージの送信先と生成元が一致していないのが原因です。javascript - Failed to execute 'postMessage' on 'DOMWindow': https://www.youtube.com !== http://localhost:9000 - Stack Overflow

参考