YouTube Player APIでページにYouTube動画を埋め込む

YouTubeの動画は、簡単にWebページへ埋め込むことができます。その方法の一つに、iframeタグを使った埋め込みがあります。また、YouTubeはこのiframeで埋め込んだ動画に対して、再生や停止などの操作を自由に行えるAPIも提供しています。今回は、このAPIを活用してiframe埋め込みのYouTube動画を制御する方法をご紹介します。

IFrame Player APIとは

YouTubeが提供する「IFrame Player API」は、Webページに埋め込んだYouTube動画を自在に制御できるAPIです。このAPIを使うと、iframeで埋め込んだ動画を任意のタイミングで読み込み、再生や停止などの操作も自由に行えます。

使い方

表示したい箇所にid属性を付与した空の要素（HTML）を用意します。

<div id="sample"></div>

次にJavaScriptコードを記述します。

function onYouTubeIframeAPIReady() {
  const player = new YT.Player('sample', {
    videoId : 'XXXXXXXXXXX',
    width   : 480,
    height  : 270
  });
}

window.addEventListener('DOMContentLoaded', () => {
  const headElem   = document.getElementsByTagName('head')[0];
  const scriptElem = document.createElement('script');
  scriptElem.src = 'https://www.youtube.com/iframe_api';
  headElem.appendChild(scriptElem);
});

このJavaScriptは、以下の手順でYouTubeのIFrame Player APIを利用しています。
まず、10行目から15行目で、IFrame Player APIのスクリプトを読み込む処理を行っています。

次に、1行目でonYouTubeIframeAPIReady関数を定義しています。この関数は、APIのスクリプトが読み込まれると自動的に実行されます。なお、onYouTubeIframeAPIReadyはアロー関数で定義できず、グローバルスコープで定義する必要がある点に注意が必要です。

また、2行目から6行目では、YT.Playerクラスを使って動画プレーヤーを生成しています。YT.Playerの第一引数には、あらかじめ用意しておいたHTMLのid属性を指定し、第二引数で詳細な設定を指定します。第二引数の設定内容については、以下で詳しく説明します。

プロパティ	型	説明
videoId	string	再生する動画のIDを指定します。 IDはURLの「https://www.youtube.com/embed/動画ID」で確認することができます。
width	number	表示する横幅を指定します。
height	number	表示する高さを指定します。
events	object	APIの何かしらのきっかけで発動するイベントです。詳しくは「イベント」をご覧ください。
playerVars	object	動画プレーヤーの初期設定を行います。詳しくは「プレーヤーの初期設定」をご覧ください。

イベント

eventsプロパティを使うと、APIで発生するさまざまなイベントを受け取ることができます。発生するイベントは次のとおりです。

プロパティ	説明
onReady	動画プレーヤーの準備が完了し再生可能な状態である場合に発動します。
onStateChange	プレーヤーの状況が変化した時に発動します。状況変化は再生開始時、一時停止時、バッファ時、再生完了（最後まで再生された）時、エラー時です。
onPlaybackQualityChange	動画の画質が変化した時に発動します。
onPlaybackRateChange	再生速度が変化した時に発動します。
onError	プレーヤーが何かしらのエラーが発生した時に発動します。無効な設定値であったり、リクエストした動画が見つからなかったりした時にエラーとなります。

const player = new YT.Player('sample', {
  videoId : 'XXXXXXXXXXX',
  width   : 480,
  height  : 270,
  event   : {
    onReady : event => {
      event.target.setVolume(50);
    }
  }
});

プレーヤーの初期設定

playerVarsプロパティを使用すると、動画プレーヤーの初期設定を行えます。設定可能な内容は以下の通りです。

プロパティ	型	初期値	説明
autoplay	number	0	自動再生を行うかどうかを設定します。0を指定すると無効になり、1を指定すると有効になります。
mute	number	0	消音（ミュート）にするかどうかを設定します。0を指定すると無効になり、1を指定すると有効になります。
start	number	0	再生を開始する位置を秒で設定します。
end	number		再生を終了する位置を秒で設定します。startプロパティに関係がなく、動画の0秒を始点として指定します。
loop	number	0	再生リストの最後の動画を再生し終えた場合に、再生リストを最初から繰り返し再生するかどうかを設定します。0を指定すると無効になり、1を指定すると有効になります。このloopプロパティは、playlistプロパティを指定している場合のみ有効となります。
controls	number	1	再生やシークバーなど動画を制御するコントローラーを表示するかどうかを設定します。0を指定すると非表示になり、1を指定すると表示されます。
fs	number	1	全画面表示のボタンを表示するかどうかを設定します。0を指定すると非表示になり、1を指定すると表示されます。
playlist	string		複数の動画を順番に一つずつ再生するための動画を設定します。カンマ区切りで動画IDを指定していきます。なお、playlistプロパティを設定していれば、videoIdプロパティを指定していても、playlistプロパティが優先されて動画が再生されます。
playsinline	number	0	プレーヤーをインラインで表示するか全画面で表示するかを設定します。0を指定すると全画面で表示され、1を指定するとインラインで表示されます。
color	string	'red'	シークバーの現在までの再生状況バーの色を設定します。設定値はredまたはwhiteのみです。
cc_lang_pref	string		表示される字幕の言語を設定します。設定値はISO 639-1 2 文字言語コードで指定します。
cc_load_policy	number		字幕を初期で表示するかどうかを設定します。0を設定するとユーザー設定に基づき、1を指定すると初期で字幕を表示します。
disablekb	number	0	キーボード操作に対応しないかどうかを設定します。0を指定すると対応し、1を指定すると対応しません。
enablejsapi	number	0	自身でiframeを生成し、IFrame Player APIでプレーヤーの開発を可能にするかどうかを設定します。0を指定すると無効にし、1を指定すると有効にします。
hl	string		プレーヤーのインターフェースの言語を設定します。設定値はISO 639-1 2 文字言語コードで指定します
iv_load_policy	number	1	動画上にリンク機能を持つテキストであるアノテーションを表示するかどうかを設定します。1を指定すると表示され、3を指定すると非表示になります。
listType	string		動画リストの種類を設定します。設定値は再生リストである場合はplaylist、公開されている動画のリストの場合はuser_uploads、動画検索の結果である場合はsearchを指定することができます。listプロパティと組み合わせて指定します。
list	string		listTypeプロパティで指定した種類の内容を設定します。listTypeプロパティがplaylistであれば再生リストのIDを指定し、user_uploadsであればユーザー名（半角英数字）を指定し、searchであれば検索キーワードを指定します。
modestbranding	number	0	コントローラーにあるようなYouTubeのロゴを非表示にするかどうかを設定します。0を指定すると表示し、1を指定すると非表示になります。なお、colorプロパティをwhiteに設定している場合はこの設定は無効となり、ロゴが表示されます。
origin	string		動画を埋め込む先のURLのオリジンを設定します。設定値はhttps://www.example.co.jpのように指定します。
rel	number	1	再生が終了した後に関連動画を表示するかどうかを設定します。0を指定すると非表示にし、1を指定すると表示されます。
widget_referrer			YouTubeアナリティクスに認識するためにURLのオリジンを設定します。YouTubeアナリティクスに再生状況などを送信する場合に指定します。

次のコードは、複数の動画を再生リストに追加し、コントローラーを非表示にする例です。

const player = new YT.Player('sample', {
  videoId    : 'XXXXXXXXXXX',
  width      : 480,
  height     : 270,
  playerVars : {
    playlist : 'XXXXXXXXXXX,YYYYYYYYYYY'
    controls : 0
  }
});

playerVarsプロパティの詳細は、公式ドキュメントの「サポートされるパラメータ」をご覧ください。

メソッド

YT.Playerクラスで生成されたインスタンスでは、次のメソッドが使用可能です。

メソッド名	構文	説明
playVideo	player.playVideo()	動画を再生します。
stopVideo	player.stopVideo()	動画を一時停止します。
setVolume	player.setVolume(number)	音量を設定します。第一引数に音量を0から100までの範囲で指定します。
setLoop	player.setLoop(boolean)	再生リストが全て再生し終えた場合に、繰り返して最初から再生を開始するかどうかを設定します。第一引数に、繰り返す場合はtrue、繰り返さない場合はfalseを指定します。
setSize	player.setSize(number, number)	プレーヤーの幅と高さを設定します。第一引数に幅を指定し、第二引数に高さを指定します。
setShuffle	player.setShuffle(boolean)	再生リストをシャッフルして再生するかどうかを設定します。第一引数に、シャッフルする場合はtrue、しない場合はfalseを指定します。
setPlaybackQuality	player.setPlaybackQuality(string)	動画の再生される画質を設定します。第一引数に画質の名称を指定します。設定値は次のとおりです。small、medium、large、hd720、hd1080、highres、default
setLoop	player.seekTo(number, boolean)	現在の再生位置を設定します。第一引数に変更する再生の位置を秒で指定します。第二引数は任意で、指定した再生位置がバッファにない場合にサーバーへリクエストするかどうかを指定します。
getPlayerState	number = player.getPlayerState()	現在の再生状況を取得します。取得される値は次のとおりです。-1 …… 未開始0 …… 終了1 …… 再生中2 …… 一時停止3 …… バッファリング中
getCurrentTime	number = player.getCurrentTime()	現在の再生時間（どこまで再生したか）を秒で取得します。
getDuration	number = player.getDuration()	動画の合計時間を秒で取得します。
getVideoUrl	string = player.getVideoUrl()	現在再生中の動画のYouTubeのURLを取得します。
getVideoEmbedCode	string = player.getVideoEmbedCode()	プレーヤーの埋め込み用コードを取得します。
getPlaybackQuality	player.getPlaybackQuality()	現在、再生されている画質を取得します。戻り値はsetPlaybackQualityメソッドの引数で設定可能な値と同じです。
getPlaybackRate	number = player.getPlaybackRate()	現在の再生速度を取得します。標準速度を1としたときの値を返します。例えば、2倍なら2を返します。
getPlaylist	string[] = player.getPlaylist()	再生リストの動画IDを配列で取得します。
getPlaylistIndex	number = player.getPlaylistIndex()	再生リストから現在再生されている動画のインデックス番号を取得します。
destroy	player.destroy()	プレーヤーを破棄します。

次のコードは、.change-volume という button 要素が押されたときに、音量を50%に設定する例です。

const player = new YT.Player('sample', {
  videoId : 'XXXXXXXXXXX',
  width   : 480,
  height  : 270
});

document.querySelector('.change-volume').addEventListener('click', () => {
  player.setVolume(50);
});

メソッドの詳細は、公式ドキュメントの「再生の制御とプレーヤーの設定」をご覧ください。

自動再生

ページ読み込み時に動画を自動再生するには、playerVarsプロパティのautoplayを1に設定します。

const player = new YT.Player('sample', {
  videoId    : 'XXXXXXXXXXX',
  width      : 480,
  height     : 270,
  playerVars : {
    autoplay : 1
  }
});

しかし、この設定だけでは自動再生されません。これは、YouTubeのiframeが内部的にvideo要素を使用しているためで、仕様上、音声が有効な状態では自動再生ができないようになっているためです。

そのため、playerVarsプロパティのmuteも1に設定し、音声をミュートにする必要があります。

const player = new YT.Player('sample', {
  videoId    : 'XXXXXXXXXXX',
  width      : 480,
  height     : 270,
  playerVars : {
    autoplay : 1,
    mute     : 1
  }
});