YouTube 埋め込みプレーヤーとプレーヤーのパラメータ

概要

このガイドでは、アプリケーションに YouTube プレーヤーを埋め込む方法について説明し、YouTube 埋め込みプレーヤーで使用できるパラメータの定義を紹介します。

IFrame URL にパラメータを追加すると、アプリケーション内での再生方法をカスタマイズできます。たとえば autoplay パラメータを使用して動画を自動再生させたり、loop パラメータを使用して動画を繰り返し再生させることができます。また、プレーヤーの JavaScript APIenablejsapi パラメータで有効にすることもできます。

このページには、任意の YouTube 埋め込みプレーヤーでサポートされるすべてのパラメータが定義されています。パラメータをサポートするプレーヤーについては、各パラメータ定義に記述してあります。

注: 埋め込みプレーヤーには少なくとも 200px x 200px のビューポートが必要です。プレーヤーにコントロールが表示される場合は、ビューポートを最小サイズより小さくしなくてもコントロールが表示されるよう、十分な大きさを確保する必要があります。少なくとも幅 480 ピクセル、高さ 270 ピクセルの、アスペクト比 16:9 のプレーヤーをおすすめします。

YouTube プレーヤーの埋め込み

次のいずれの方法を使用しても、アプリケーションに YouTube プレーヤーを埋め込み、プレーヤーのパラメータを指定することができます。下の手順は、1 本の動画を読み込むプレーヤーを埋め込む方法を示しています。次のセクションでは、再生リストや検索結果など、他の種類のコンテンツをプレーヤーに読み込ませる設定の方法を説明します。

<iframe> タグを使用した埋め込み IFrame

アプリケーションに <iframe> タグを定義し、このタグの中で、プレーヤーに読み込むコンテンツを src URL に指定し、設定する必要があるその他のプレーヤー パラメータも指定します。<iframe> タグの height パラメータと width パラメータで、プレーヤーのサイズを指定します。

IFrame Player API を使わずに自分で <iframe> 要素を作成する場合は、プレーヤー パラメータを直接 URL の最後に付け加えることができます。URL の書式は次のとおりです。

http://www.youtube.com/embed/VIDEO_ID

下の <iframe> タグでは、YouTube 動画 M7lc1UVf-VE を再生する 640x360 ピクセルのプレーヤーが読み込まれます。URL の autoplay パラメータが 1 に設定されているため、プレーヤーが読み込まれると、動画は自動的に再生されます。

<iframe id="ytplayer" type="text/html" width="640" height="360"
  src="http://www.youtube.com/embed/M7lc1UVf-VE?autoplay=1&origin=http://example.com"
  frameborder="0"/>

IFrame Player API を使用した埋め込み IFrame

Player API の JavaScript コードが読み込まれた後、IFrame Player API の手順に沿って動画プレーヤーをウェブページまたはアプリケーションに挿入します。動画プレーヤーのコンストラクタの 2 番目のパラメータは、プレーヤー オプションを指定するオブジェクトです。プレーヤー パラメータは、このオブジェクト内で playerVars プロパティによって識別されます。

下の HTML コードと JavaScript コードは、ytplayer という id 値を持つページ要素に YouTube プレーヤーを挿入する簡単な例です。ここに指定されている onYouTubePlayerAPIReady() 関数は、IFrame Player API コードが読み込まれたときに自動的に呼び出されます。このコードでは、プレーヤー パラメータを何も定義せず、他のイベント ハンドラも定義していません。

<div id="ytplayer"></div>

<script>
  // Load the IFrame Player API code asynchronously.
  var tag = document.createElement('script');
  tag.src = "https://www.youtube.com/player_api";
  var firstScriptTag = document.getElementsByTagName('script')[0];
  firstScriptTag.parentNode.insertBefore(tag, firstScriptTag);

  // Replace the 'ytplayer' element with an <iframe> and
  // YouTube player after the API code downloads.
  var player;
  function onYouTubePlayerAPIReady() {
    player = new YT.Player('ytplayer', {
      height: '360',
      width: '640',
      videoId: 'M7lc1UVf-VE'
    });
  }
</script>

再生するコンテンツの選択

埋め込みプレーヤーの設定次第で、動画、再生リスト、ユーザーのアップロード動画、または特定のクエリに対する検索結果が読み込まれるようにすることができます。

以下のリストで、これらのオプションについて説明します。

  • 動画の読み込み

    埋め込み IFrame の場合は、読み込む動画の YouTube 動画 ID を IFrame の src URL に指定します。

    http://www.youtube.com/embed/VIDEO_ID

    YouTube Data API(v3)を使用している場合、動画 ID を検索結果再生リスト アイテム リソース動画リソースなどのリソースから取得して、これらの URL をプログラムによって構成することができます。動画 ID を取得した後、上の URL の中にある VIDEO_ID というテキストをその値に置き換えてプレーヤー URL を作成します。

  • 再生リストの読み込み

    listType プレーヤー パラメータを playlist に設定します。また、list プレーヤー パラメータを、読み込む YouTube 再生リスト ID に設定します。

    http://www.youtube.com/embed?listType=playlist&list=PLAYLIST_ID

    再生リスト ID の前には、次の例に示すように、文字 PL を付ける必要があります。

    http://www.youtube.com/embed?listType=playlist&list=PLC77007E23FF423C6

    YouTube Data API(v3)を使用している場合、再生リスト ID を検索結果チャンネル リソース、またはアクティビティ リソースから取得して、これらの URL をプログラムによって構成することができます。再生リスト ID を取得した後、上の URL の中にある PLAYLIST_ID というテキストをその値に置き換えます。

  • ユーザーのアップロード動画の読み込み

    listType プレーヤー パラメータを user_uploads に設定します。また、list プレーヤー パラメータを、読み込むアップロード動画の所有者の YouTube ユーザー名に設定します。

    http://www.youtube.com/embed?listType=user_uploads&list=USERNAME
  • 特定のクエリの検索結果の読み込み

    listType プレーヤー パラメータを search に設定します。次に、list プレーヤー パラメータに検索キーワードを指定すると、その検索結果がプレーヤーに読み込まれます。

    http://www.youtube.com/embed?listType=search&list=QUERY

パラメータ

以下に示すパラメータはすべて省略可能です。

Parameters

autoplay

値: 0 または 1。デフォルトは 0 です。プレーヤーを読み込んだときに最初の動画を自動再生するかどうかを指定します。

cc_load_policy

値: 1。デフォルトは、ユーザー設定に基づきます。1 に設定すると、ユーザーが字幕をオフにしていても、字幕がデフォルトで表示されます。

color

プレーヤーの動画進行バーに動画を開始してからの経過時間を示すときに使用する色を指定します。有効なパラメータ値は redwhite で、デフォルトではプレーヤーの動画進行バーに赤色が使用されます。color オプションの詳細については YouTube API ブログをご覧ください。

注: color パラメータを white に設定すると、modestbranding オプションが無効になります。

controls

値: 01、または 2。デフォルトは 1 です。動画のプレーヤー コントロールを表示するかどうかを指定します。Flash プレーヤーを読み込む埋め込み IFrame の場合、いつプレーヤーにコントロールを表示するかと、いつプレーヤーを読み込むかも定義します。

  • controls=0 – プレーヤーにプレーヤー コントロールは表示されません。埋め込み IFrame の場合は、Flash プレーヤーがすぐに読み込まれます。
  • controls=1 – プレーヤーにプレーヤー コントロールが表示されます。埋め込み IFrame の場合は、コントロールがすぐに表示され、Flash プレーヤーもすぐに読み込まれます。
  • controls=2 – プレーヤーにプレーヤー コントロールが表示されます。埋め込み IFrame の場合は、ユーザーが動画の再生を開始した後にコントロールが表示され、Flash プレーヤーが読み込まれます。

注: 埋め込み IFrame の場合は、パラメータ値が 12 の場合のユーザー エクスペリエンスはまったく同じですが、controls=2 を指定すると controls=1 よりもパフォーマンスがよくなります。現在は、動画のタイトルのフォントサイズが異なるなど、2 つの値の間でプレーヤーの表示にまだ多少の相違があります。ただし、両方の値の間の相違がユーザーにまったくわからなくなった場合は、パラメータのデフォルト値が 1 から 2 に変更される可能性があります。

disablekb

値: 0 または 1。デフォルトは 0 です。1 に設定するとプレーヤーをキーボードで操作できなくなります。キーボードによる操作は次のようになります。

  • スペースキー: 再生 / 一時停止
  • 左矢印キー: 現在の動画を 10% 戻す
  • 右矢印キー: 現在の動画を 10% 進める
  • 上矢印キー: 音量を上げる
  • 下矢印キー: 音量を下げる

enablejsapi

値: 0 または 1。デフォルトは 0 です。このパラメータを 1 に設定すると JavaScript API が有効になります。JavaScript API とその使用方法の詳細については、JavaScript API に関するドキュメントをご覧ください。

end

値: 正の整数。動画の再生を停止する必要がある場合に、動画を開始してからの経過時間を秒単位で指定します。時間は動画の先頭から測定されます。start プレーヤー パラメータや startSeconds パラメータの値からではありません。これらは、動画の読み込みまたはキューイングを行うために YouTube Player API 関数で使用されるパラメータです。

fs

値: 0 または 1。デフォルト値は 1 です。この値を指定すると全画面表示ボタンが表示されます。このパラメータを 0 に設定すると、全画面表示ボタンは表示されなくなります。

hl

プレーヤーのインターフェースの言語を設定します。パラメータの値は、ISO 639-1 2 文字言語コードです。ただし、IETF 言語タグ(BCP 47)などの他の言語入力コードも正しく処理されます。

インターフェースの言語はプレーヤーのツールチップで使用され、デフォルトの字幕トラックにも影響します。なお、ユーザー個別の言語設定と利用可能な字幕トラックに基づいて、YouTube が特定のユーザーに対し異なる字幕トラックを選択することもあります。

iv_load_policy

値: 1 または 3。デフォルトは 1 です。1 に設定すると動画アノテーションがデフォルト表示されます。3 に設定すると、動画アノテーションはデフォルトで表示されなくなります。

list

list パラメータは、プレーヤーに読み込むコンテンツを識別するときに、listType パラメータと組み合わせて使用します。

  • listType パラメータの値が search の場合は、list パラメータの値に検索クエリを指定します。
  • listType パラメータの値が user_uploads の場合、list パラメータの値には、読み込まれるアップロード動画の所有者の YouTube チャンネルを指定します。
  • listType パラメータの値が playlist の場合は、list パラメータの値に YouTube 再生リスト ID を指定します。パラメータ値に含める再生リスト ID には、下の例に示すように、PL という文字を先頭に付ける必要があります。
    http://www.youtube.com/embed?listType=playlist&list=PLC77007E23FF423C6

注: list パラメータと listType パラメータに値を指定する場合は、IFrame 埋め込み URL に動画 ID を指定する必要はありません。

listType

listType パラメータは、プレーヤーに読み込むコンテンツを識別するときに list パラメータと組み合わせて使用します。有効なパラメータ値は、playlistsearch および user_uploads です。

list パラメータと listType パラメータに値を指定する場合は、IFrame 埋め込み URL に動画 ID を指定する必要はありません。

loop

値: 0 または 1。デフォルトは 0 です。単一動画プレーヤーの場合に 1 を設定すると、最初の動画が繰り返し再生されます。再生リストプレーヤーまたはカスタム プレーヤーの場合、再生リスト全体を再生した後、最初の動画から再び再生が始まります。

注: このパラメータは AS3 プレーヤーと埋め込み IFrame でのみサポートされており、AS3 または HTML5 プレーヤーのいずれかが読み込まれます。loop パラメータは、現時点では playlist パラメータと組み合わせて AS3 プレーヤーで使用した場合のみ動作します。単一の動画をループさせる場合は、loop パラメータの値を 1 に設定し、既に Player API URL に指定してある動画 ID と同じ値を playlist パラメータの値に設定します。
http://www.youtube.com/v/VIDEO_ID?version=3&loop=1&playlist=VIDEO_ID

modestbranding

このパラメータを使用すると、YouTube プレーヤーに YouTube ロゴが表示されないようにすることができます。パラメータの値を 1 に設定すると、YouTube ロゴがコントロール バーに表示されなくなります。ただし、動画を一時停止したときにユーザーがプレーヤーにカーソルを合わせると、動画の右上に引き続き小さい YouTube テキストラベルが表示されます。

origin

このパラメータは IFrame API のセキュリティを強化します。埋め込み IFrame でのみ使用できます。IFrame API を使用している場合、つまり enablejsapi パラメータの値を 1 に設定している場合は、常に自分のドメインを origin パラメータ値として指定する必要があります。

playlist

値: 再生する動画 ID をカンマで区切ったリスト。値を指定すると、URL パスの VIDEO_ID に指定した動画が最初に再生され、playlist パラメータに指定した動画はその後に再生されます。

playsinline

このパラメータは iOS 上の HTML5 プレーヤーで動画をインラインまたは全画面表示のどちらで再生するかを制御します。有効な値は次のとおりです。

  • 0: この値を指定すると全画面表示で再生されます。現時点ではこれがデフォルト値ですが、デフォルトは変更される場合があります。
  • 1: この値を指定すると、UIWebViewsallowsInlineMediaPlayback プロパティを TRUE に設定して作成したもの)がインライン再生されます。

rel

値: 0 または 1。デフォルトは 1 です。最初の動画の再生が終了したときに、プレーヤーに関連動画を表示するかどうかを指定します。

showinfo

値: 0 または 1。デフォルト値は 1 です。パラメータの値を 0 に設定すると、動画の再生が始まる前に動画のタイトルやアップロードしたユーザーなどの情報は表示されません。

プレーヤーに再生リストが読み込まれる場合は、パラメータの値を明示的に 1 に設定すると、再生リストに含まれる動画のサムネイル画像も読み込み時に表示されます。AS3 プレーヤーは再生リストの読み込みができる唯一のプレーヤーであるため、この機能はこのプレーヤーでのみサポートされます。

start

値: 正の整数。このパラメータを指定すると、動画の先頭から指定された秒数分進めた位置から動画の再生が開始されます。seekTo 関数と同様に、プレーヤーは指定された時間に最も近いキーフレームを探します。そのため、リクエストされた時間の直前から再生が開始される場合もありますが、ずれは通常、最大で 2 秒程度です。

改訂履歴

October 14, 2014

July 18, 2014

  • The new hl parameter can be used to set the player's interface language. The interface language is used for tooltips in the player and also affects the default caption track. The selected caption track may also depend on the availability of caption tracks and user's individual language preferences.

    The parameter's value is an ISO 639-1 two-letter language code, though other language input codes, such as IETF language tags (BCP 47) may also be handled properly.

  • The definition of the playsinline parameter, which only affects HTML5 players on iOS, has been modified slightly. The definition now notes that setting the parameter value to 1 causes inline playback only for UIWebViews created with the allowsInlineMediaPlayback property set to TRUE.

January 28, 2014

  • The playsinline parameter controls whether videos play inline or fullscreen in an HTML5 player on iOS. Setting the value to 1 causes inline playback.

  • The Selecting content to play section has been updated to explain how to find YouTube video IDs and playlist IDs using the YouTube Data API (v3) rather than the older API version.

  • The controls parameter's definition has been updated to reflect the fact that the parameter value only affects the time that the Flash player actually loads in IFrame embeds. In addition, for IFrame embeds, the parameter value also determines when the controls display in the player. If you set the parameter's value to 2, then the controls display and the Flash player loads after the user initiates the video playback.

May 10, 2013

This update contains the following changes:

July 20, 2012

This update contains the following changes:

  • The definition of the controls parameter has been updated to reflect support for a parameter value of 2 and to explain that, for AS3 players, the parameter value determines the time when the Flash player actually loads. If the controls parameter is set to 0 or 1, the Flash player loads immediately. If the parameter value is 2, the Flash player does not load until the video playback is initiated.

June 5, 2012

This update contains the following changes:

  • The HTML5 player now supports the color, modestbranding, and rel parameters, and the definitions for these parameters have been updated accordingly.

  • The definition of the showinfo parameter has been updated to explain how that if the player is loading a playlist, and you explicitly set the parameter value to 1, then, upon loading, the player will also display thumbnail images for the videos in the playlist. Note that this functionality is only supported for the AS3 player since that is the only player that can load a playlist.

May 4, 2012

This update contains the following changes:

  • The showinfo parameter's definition has been updated to reflect the fact that the HTML5 player supports this parameter.

May 3, 2012

This update contains the following changes:

  • The new end parameter specifies the time, measured in seconds from the start of the video, when the player should stop playing a video. Note that the time when playback is stopped is measured from the beginning of the video and not from the value of either the start player parameter or the startSeconds parameter, which is used in YouTube Player API functions for loading or queueing a video.

March 29, 2012

This update contains the following changes:

  • The new Embedding a YouTube player section explains different ways to embed a YouTube player in your application. This section covers manual IFrame embeds, IFrame embeds that use the IFrame Player API, and AS3 and AS2 object embeds. This section incorporates information from the old Example usage section, which has been removed.

  • The new Selecting content to play section explains how to configure the player to load a video, a playlist, search results for a specified query, or uploaded videos for a specified user.

  • The new list and listType parameters let you specify the content that the player should load. You can specify a playlist, a search query, or a particular user's uploaded videos.

  • The definitions of the fs and rel parameters have been updated to more clearly explain the default parameter values for the AS3 player.

  • The border, color1, egm, hd, and showsearch parameters, which are all only supported for the deprecated AS2 Player API, have been moved to a new section named deprecated parameters only used in the AS2 Player API.

  • The document no longer provides a way to filter the parameter list to only display parameters supported in either the AS3, AS2, or HTML5 player. Instead, each parameter definition has been updated to identify the players that support that parameter.

August 11, 2011

This update contains the following changes:

  • The new theme and color parameters let you customize the appearance of the embedded player's player controls. See the YouTube API blog for more information.

June 8, 2011

This update contains the following changes:

  • The new modestbranding parameter lets you use a YouTube player that does not show a YouTube logo. As of this release, the parameter was only supported for the AS3 embedded player and for IFrame embeds that loaded the AS3 player. As of June 5, 2012, the HTML5 player also supported this parameter.

February 14, 2011

This update contains the following changes:

  • The documentation has been updated to note that the AS2 Player API has been deprecated. The deprecation of the AS2 Player API was actually announced on October 14, 2009.

February 3, 2011

This update contains the following changes:

  • The documentation has been updated to identify parameters supported in the HTML5 (IFrame) embedded player.

  • The document now displays all of the parameters supported in any of YouTube's embedded players (HTML5, AS3, AS2).

  • The following parameters are supported in the AS2 player but have been deprecated for the newer AS3 and HTML5 players: border, color1, color2, egm, hd, and showsearch.

    In addition, the loop parameter has limited support in the AS3 player and in IFrame embeds, which could load either an AS3 or HTML player. Currently, the loop parameter only works in the AS3 player when used in conjunction with the playlist parameter. To loop a single video, set the loop parameter to 1 and set the playlist parameter value to the same video ID already specified in the Player API URL:

    http://www.youtube.com/v/VIDEO_ID?version=3&loop=1&playlist=VIDEO_ID

    Similarly, the controls and playlist parameters are supported in the AS3 and HTML5 players but are not and will not be supported in the AS2 player.

    As noted above, IFrame embeds can load either an AS3 or HTML5 player. Though some parameters are not supported in both players, an IFrame embed that loads the AS3 player will support all parameters that work with that player and ignore all other parameters. Similarly, an IFrame embed that loads the HTML5 player will support all parameters that work with that player while ignoring all other parameters.

  • The parameter list has been updated to include the autohide parameter, which indicates whether the player's video controls will automatically hide after a video begins playing.

  • The parameter list has been updated to include the controls parameter, which indicates whether the player's video controls will display at all. (Player controls do display by default.)

  • The parameter list has been updated to include the playlist parameter, which specifies a comma-separated list of video IDs to play.

  • The definition of the fs has been updated to note that the fullscreen option will not work if you load the YouTube player into another SWF.

  • The example at the end of the document has been updated to use the embedded AS3 player instead of the embedded AS2 player. The parameters used in the example have also been updated to only include parameters that the AS3 player supports.

    In addition, the instructions for constructing the URLs that contain player parameters have been updated to reflect the URL formats used by the AS3 and AS2 embedded and chromeless players as well as by the HTML5 player.