このドキュメントでは、YouTube JavaScript Player API のリファレンス情報を提供します。

目次

概要

JavaScript API を使用すると、YouTube の埋め込み動画プレーヤーを JavaScript でコントロールできます。再生、一時停止、指定した動画位置への移動、ボリューム調整、ミュートなど、関数を呼び出すことでさまざまな操作を実行できます。

要件

エンド ユーザー側ですべてを正しく表示するには、Flash Player 8 以上がインストールされている必要があります。この要件が満たされていることを確認するため、SWFObject を使用して SWF を埋め込み、ユーザーの Flash Player のバージョンを検出することをお勧めします。

スタート ガイド

注: これらの呼び出しをテストする場合は、ファイルを 同じWeb サーバー上に置いておく必要があります。これは、Flash Player において、ローカル ファイルとインターネットの間の呼び出しが制限されているためです。

JavaScript API を有効にするには、コントロールするプレーヤーの URL で、URL パラメータ enablejsapi=1 を渡す必要があります。たとえば、SWF を埋め込む場合は次のような URL を使用します。

http://www.youtube.com/v/VIDEO_ID&enablejsapi=1

この URL では、プレーヤーの JavaScript API ハンドラを有効にしています。また、プレーヤーが読み込まれて JavaScript コールを受信できる状態になると、URL に指定されている HTML ページにコールバックによる通知が届くよう設定しています。プレーヤーの準備が整うと、JavaScript 関数 onYouTubePlayerReady が呼び出されます。

必要に応じて、onYouTubePlayerReady コールバックが呼び出されたときにプレーヤーを特定するための playerapiid パラメータを渡すこともできます。playerapiid としてどのような値を渡しても、その値が 1 番目の引数として onYouTubePlayerReady に返されます。

http://www.youtube.com/v/VIDEO_ID&enablejsapi=1&playerapiid=ytplayer

YouTube プレーヤー SWF をページに埋め込む方法の詳細については、後に示す例をご覧ください。

操作

プレーヤー API メソッドを呼び出すには、まずコントロールしたいプレーヤーへの参照を取得する必要があります。そのためには、object (または、SWFObject を使用してプレーヤー SWF を埋め込む場合は、そのプレーヤー SWF を含む embed タグ) を getElementById() で呼び出します。

関数

player.playVideo():Void

現時点でキューに入っている (または読み込まれている) 動画を再生します。

player.pauseVideo():Void

再生中の動画の長さを秒単位で返します。

player.stopVideo():Void

再生中の動画を停止します。これにより、NetStream オブジェクトが閉じられ、動画の読み込みもキャンセルされます。stopVideo() が呼び出された後は、プレーヤーをもう一度読み込むか、新しい動画を読み込まないと、動画の再生を再開することはできません。stopVideo() が呼び出されると、プレーヤーは終了 (0)、未開始 (-1) の順にイベントをブロードキャストします。

player.clearVideo():Void

動画の表示をクリアします。stopVideo() を呼び出した後の動画の残像をクリアしたい場合に使用します。

player.getVideoBytesLoaded():Number

現在の動画の読み込み済みバイト数を返します。

player.getVideoBytesTotal():Number

読み込み済み、または再生中の動画のサイズをバイト単位で返します。

player.getVideoStartBytes():Number

動画ファイルの読み込みを開始した時点のバイト数を返します。たとえば、ユーザーがまだ読み込まれていない位置を探そうとした場合や、プレーヤーがまだ読み込まれていない動画セグメントの再生を要求した場合に使用します。

player.mute():Void

プレーヤーをミュートします。

player.unMute():Void

プレーヤーのミュートを解除します。

player.isMuted():Boolean

プレーヤーがミュートされている場合は true、そうでない場合は false を返します。

player.setVolume(volume):Void

ボリュームを設定します。整数 0～100 の間で設定できます。

player.getVolume(volume):Void

プレーヤーの現時点でのボリュームを、0～100 の整数で返します。getVolume() は、プレーヤーがミュートされている場合でもボリュームを返します。

player.seekTo(seconds, allowSeekAhead):Void

秒単位で指定された動画位置を探します。allowSeekAhead は、seconds に指定された位置が、その時点までに読み込まれた動画データの範囲を超えている場合に、プレーヤーからサーバーに新しい要求を送信するかどうかを識別します。なお、seekTo() は、指定された seconds に最も近いキーフレームを探します。つまり、要求した位置の少し前または後にずれる可能性があるということです。このようなずれは、通常は 2 秒以内です。

player.getPlayerState():Number

プレーヤーの状態を返します。値は、未開始 (-1)、終了済み (0)、再生中 (1)、一時停止中 (2)、バッファ中 (3)、動画キュー (5) のいずれかです。

player.getCurrentTime():Number

現在の動画の現時点での再生時間を秒単位で返します。

player.getDuration():Number

再生中の動画の経過時間を秒単位で返します。getDuration() は、動画のメタデータが読み込まれるまでは 0 を返します。このような状況は、通常は動画の再生が始まった直後に発生します。

player.addEventListener(event, listener):Void

指定されたイベントにリスナ関数を追加します。

player.getVideoUrl():String

読み込み済みまたは再生中の動画の YouTube.com URL を返します。

player.getVideoEmbedCode():String

読み込み済みまたは再生中の動画の埋め込みコードを返します。

イベント

onStateChange

プレーヤーの状態が変化したときに必ずブロードキャストされます。値は、未開始 (-1)、終了済み (0)、再生中 (1)、一時停止中 (2)、バッファ中 (3)、動画キュー (5) のいずれかです。SWF を初めて読み込むと、未開始 (-1) イベントがブロードキャストされます。動画がキューに登録されて再生の準備が整うと、動画キュー イベント (5) がブロードキャストされます。

onError

プレーヤーでエラーが発生したときにブロードキャストされます。現時点で登録されているエラー コードは、動画が見つからないことを示す 100 のみです。このエラーは、何らかの理由で動画が削除されたか、動画がユーザーによって非公開または埋め込み不可とマークされている場合に発生します。

特別なイベント

例

SWFObject を使用した YouTube プレーヤーの埋め込み

JavaScript API でアクセスするプレーヤーの埋め込みには、SWFObject を使用することをお勧めします。JavaScript API では Flash Player 8 以上が要件となりますが、このオブジェクトを使用することでエンド ユーザーの Flash Player のバージョンを検出できます。また、Internet Explorer でプレーヤーを表示する際に、[このコントロールを有効にする] ボックスも表示されなくなります。SWF で API を有効にするには、enablejsapi=1 パラメータを渡す必要があります。

次に、JavaScript API が有効になった YouTube プレーヤーを、スクリプトを使用して埋め込む例を示します。なお、playerapiid は ytplayer です。

  <script type="text/javascript" src="swfobject.js"></script>    
  <div id="ytapiplayer">
    You need Flash player 8+ and JavaScript enabled to view this video.
  </div>

  <script type="text/javascript">

    var params = { allowScriptAccess: "always" };
    var atts = { id: "myytplayer" };
    swfobject.embedSWF("http://www.youtube.com/v/VIDEO_ID&enablejsapi=1&playerapiid=ytplayer", 
                       "ytapiplayer", "425", "356", "8", null, null, params, atts);

  </script>

この例では、プレーヤー SWF と埋め込み先の HTML ページが別々のドメインでホストされています。そのため、allowScriptAccess パラメータによって、埋め込み先 HTML ページでの関数呼び出しをプレーヤー SWF に許可しています。

このコードで渡される唯一の属性は、埋め込みオブジェクトの id (ここでは myytplayer) です。この ID は、getElementById() を使用してプレーヤーへの参照を取得するためのものです。

swfobject.embedSWF は、YouTube からプレーヤーを読み込み、これを指定されたページに埋め込みます。

swfobject.embedSWF(swfUrlStr, replaceElemIdStr, widthStr, heightStr, swfVersionStr, xiSwfUrlStr, flashvarsObj, parObj, attObj)

• swfUrlStr - SWF の URL です。なお、JavaScript API コールを有効にするため、通常の YouTube SWF URL には既に enablejsapi および playerapiid パラメータを追加してあります。
• replaceElemIdStr - 埋め込みコンテンツで置き換えられる HTML DIV ID です。上の例では ytapiplayer です。
• widthStr - プレーヤーの幅です。
• heightStr - プレーヤーの高さです。
• swfVersionStr - ユーザーがコンテンツを表示するために必要な最低限のバージョンです。この例では、バージョン 8 以上が要求されています。ユーザー側にバージョン 8 以上がインストールされていない場合は、HTML DIV に指定されているデフォルトのテキスト行が表示されます。
• xiSwfUrlStr - (オプション) SWF を高速インストールするための URL を指定します。この例では使用されていません。
• flashVarsObj - (オプション) 使用している FlashVars を名前/値ペアで指定します。この例では使用されていません。
• parObj - (オプション) 埋め込みオブジェクトのパラメータです。この例では、allowScriptAccess を設定しています。
• AttObj - (オプション) 埋め込みオブジェクトの属性です。この例では、ID が myytplayer に設定しています。

より詳しい説明については、SWFObject のドキュメントをご覧ください。

プレーヤー参照の取得

プレーヤーの準備が整うと、onYouTubePlayerReady が呼び出されます。

プレーヤーへの参照を取得するには、getElementById() を使用します。このオブジェクトを取得したら、API に対する呼び出しを開始できます。

    function onYouTubePlayerReady(playerId) {
      ytplayer = document.getElementById("myytplayer");
    }

コールの発行

プレーヤーへの参照を取得したら、それを使用してすべての関数を呼び出すことができます。たとえば、ユーザーがリンクをクリックしたときに動画を再生したい場合は次のようにします。

function play() {
  if (ytplayer) {
    ytplayer.playVideo();
  }
}

<a href="javascript:void(0);" onclick="play();">Play</a>

分かりやすく、次のようにすることもできます。

 <a href="javascript:ytplayer.playVideo()">Play</a> 

イベントの登録

イベントを登録するには、プレーヤー参照にイベント リスナを追加します。たとえば、プレーヤーの状態が変化したときに通知を受け取るには、onStateChange のイベント リスナを追加してコールバック関数を含めます。

function onYouTubePlayerReady(playerId) {
  ytplayer = document.getElementById("myytplayer");
  ytplayer.addEventListener("onStateChange", "onytplayerStateChange");
}

function onytplayerStateChange(newState) {
   alert("Player's new state: " + newState);
}

より多くの機能を表示した分かりやすい例については、こちらをご覧ください。ソースを表示して内容を確認することも可能です。

トップへ戻る