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

参考