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

注: このドキュメントは、2009 年 10 月に ActionScript 2.0（AS2）ではなく AS3 の使い方を説明するよう改訂されました。

目次

概要

AS3 API を使用すると、Flash アプリケーションにプレーヤーを読み込んだり、ActionScript を介してプレーヤーの公開 API を呼び出したりするなど、YouTube 動画プレーヤーを制御できます。再生、一時停止、指定した動画位置のシーク、音量の調整、ミュートなど、関数を呼び出すことでさまざまな操作を行うことができます。ActionScript API は、プレーヤーが別の SWF に読み込まれると自動的にアクティブになります。

要件

すべてを正しく表示するには、エンドユーザー側のパソコンに Flash Player 9 以降がインストールされている必要があります。

はじめに

クロムレス プレーヤーをアプリケーションに読み込み、Flash でカスタム コントロールを作成するには、次の URL を使用します:

http://www.youtube.com/apiplayer?version=3

クロムレス プレーヤー SWF を読み込んだら、cueVideoById()、loadVideoById()、cueVideoByUrl()、loadVideoByUrl() を使用して特定の YouTube 動画を読み込むことができます。

Flash ファイルに YouTube プレーヤー SWF を埋め込む方法について詳しくは、例をご覧ください。

操作

AS3 API は JavaScript API とよく似ていますが、プレーヤーの初期化方法に若干の違いがあり、特殊な関数が追加されています。ActionScript を介してプレーヤーの初期化や呼び出しを行う方法については、例をご覧ください。

関数

キュー関数

player.cueVideoById(videoId:String, startSeconds:Number, suggestedQuality:String):Void

指定された動画のサムネイルを読み込み、プレーヤーで動画を再生する準備をします。プレーヤーは、playVideo() または seekTo() が呼び出されるまで FLV をリクエストしません。

• videoId パラメータ（必須）には、再生する動画の YouTube 動画 ID を指定します。YouTube Data API 動画フィードでは、<yt:videoId> タグで ID を指定します。
• startSeconds パラメータ（省略可能）には、playVideo() が呼び出されたときに動画の再生を開始する位置（時間）を浮動小数点数または整数で指定します。startSeconds の値を指定して seekTo() を呼び出すと、seekTo() の呼び出しで指定された時間からプレーヤーが再生を開始します。動画の頭出しをして再生の準備が整ったら、プレーヤーは動画の頭出しイベント（5）をブロードキャストします。
• suggestedQuality パラメータ（省略可能）は、動画の推奨再生画質を指定します。再生画質について詳しくは、setPlaybackQuality 関数の定義をご覧ください。

player.loadVideoById(videoId:String, startSeconds:Number, suggestedQuality:String):Void

指定された動画を読み込んで再生します。

• videoId パラメータ（必須）には、再生する動画の YouTube 動画 ID を指定します。YouTube Data API 動画フィードでは、<yt:videoId> タグで ID を指定します。
• startSeconds パラメータ（省略可能）は、浮動小数点数または整数で指定します。この値を指定すると、指定した時間に最も近いキーフレームから動画が再生されます。
• suggestedQuality パラメータ（省略可能）は、動画の推奨再生画質を指定します。再生画質について詳しくは、setPlaybackQuality 関数の定義をご覧ください。

player.cueVideoByUrl(mediaContentUrl:String, startSeconds:Number):Void

指定された動画のサムネイルを読み込み、プレーヤーで動画を再生する準備をします。プレーヤーは、playVideo() または seekTo() が呼び出されるまで FLV をリクエストしません。

• mediaContentUrl は、YouTube プレーヤー URL の形式（http://www.youtube.com/v/VIDEO_ID）に完全に適合している必要があります。YouTube Data API 動画フィードでは、<media:content> タグの format 属性の値が 5 であれば、この形式に完全に適合したプレーヤー URL が url 属性に格納されます。
• startSeconds パラメータには、playVideo() が呼び出されたときに動画の再生を開始する位置（時間）を浮動小数点数または整数で指定します。startSeconds の値を指定して seekTo() を呼び出すと、seekTo() では指定された時間からプレーヤーが再生を開始します。動画の頭出しをして再生の準備が整ったら、プレーヤーは動画の頭出しイベント（5）をブロードキャストします。

player.loadVideoByUrl(mediaContentUrl:String, startSeconds:Number):Void

指定された動画を読み込んで再生するこの関数は、ActionScript 3.0 Player API ではまだ実装されていません。

• mediaContentUrl は、YouTube プレーヤー URL の形式（http://www.youtube.com/v/VIDEO_ID）に完全に適合している必要があります。YouTube Data API 動画フィードでは、<media:content> タグの format 属性の値が 5 であれば、この形式に完全に適合したプレーヤー URL が url 属性に格納されます。
• startSeconds パラメータには、動画の再生を開始する位置（時間）を浮動小数点数または整数で指定します。startSeconds に値を指定すると、指定した時間に最も近いキーフレームから動画が再生されます。この値には浮動小数点数も指定できます。

指定された動画を読み込んで再生します。

• mediaContentUrl は、YouTube プレーヤー URL の形式（http://www.youtube.com/v/VIDEO_ID）に完全に適合している必要があります。YouTube Data API 動画フィードでは、<media:content> タグの format 属性の値が 5 であれば、この形式に完全に適合したプレーヤー URL が url 属性に格納されます。
• startSeconds パラメータには、動画の再生を開始する位置（時間）を浮動小数点数または整数で指定します。startSeconds に値を指定すると、指定した時間に最も近いキーフレームから動画が再生されます。この値には浮動小数点数も指定できます。

再生の制御とプレーヤーの設定

動画の再生

player.playVideo():Void

頭出し済み、または読み込み済みの動画を再生します。

player.pauseVideo():Void

再生中の動画を一時停止します。

player.stopVideo():Void

現在の動画を停止します。この関数は動画の読み込みもキャンセルします。

player.seekTo(seconds:Number, allowSeekAhead:Boolean):Void

動画の指定された時間（秒数）をシークします。seekTo() 関数は、指定された seconds より前の最も近いキーフレームを探します。そのため、リクエストされた時間の直前から再生が開始される場合もありますが、通常は最大で 2 秒程度です。

allowSeekAhead パラメータは、現在読み込んでいる動画の長さを seconds の値が超えている場合にプレーヤーからサーバーに新しいリクエストを行うかどうかを指定します。

player.clearVideo():Void

動画の表示をクリアします。この関数は、stopVideo() を呼び出した後で動画の残りをクリアするときに役立ちます。この関数は、ActionScript 3.0 Player API で廃止されましたのでご注意ください。

プレーヤーの音量の変更

player.mute():Void

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

player.unMute():Void

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

player.isMuted():Boolean

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

player.setVolume(volume:Number):Void

音量を設定します。0～100 の整数値を指定します。

player.getVolume():Number

プレーヤーの現在の音量を 0～100 の整数値で返します。getVolume() は、プレーヤーがミュートされている場合でも音量を返します。

プレーヤーのサイズの設定

player.setSize(width:Number, height:Number):Void

プレーヤーのサイズをピクセル単位で設定します。MovieClip の width プロパティと height プロパティの代わりにこのメソッドを使うことをおすすめします。このメソッドは動画プレーヤーの縦横比を固定しないので、4:3 のアスペクト比が維持されるように注意する必要があります。別の SWF に読み込まれたときのクロムレス SWF のデフォルト サイズは 320x240 ピクセルで、埋め込みプレーヤー SWF のデフォルト サイズは 480x385 ピクセルです。

再生ステータス

player.getVideoBytesLoaded():Number

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

player.getVideoBytesTotal():Number

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

player.getVideoStartBytes():Number

動画ファイルの読み込みを開始した位置をバイト数で返します。サンプル シナリオ: まだ読み込んでいない位置をユーザーがシークした場合や、まだ読み込んでいない動画セグメントの再生をプレーヤーがリクエストした場合に使用します。

player.getPlayerState():Number

プレーヤーの状態を返します。値には、未開始（-1）、終了（0）、再生中（1）、一時停止中（2）、バッファリング中（3）、頭出し済み（5）があります。

player.getCurrentTime():Number

動画の再生を開始してからの経過時間を秒数で返します。

再生画質

player.getPlaybackQuality():String

この関数は、現在の動画の実際の画質を取得します。現在の動画がない場合は undefined を返します。戻り値には、hd720、largemedium、small があります。

player.setPlaybackQuality(suggestedQuality:String):Void

この関数は、現在の動画の推奨画質を設定し、現在の位置から新しい画質で動画をリロードします。再生画質を変更した場合、再生している動画の画質のみが変更されます。

この関数を呼び出しても、再生画質が実際に変更されるとは限りません。再生画質を変更した場合、再生している動画の画質のみが変更されます。実際に画質が変更されると onPlaybackQualityChange イベントが起動されるので、コードは setPlaybackQuality 関数を呼び出すだけでなく、このイベントに応答する必要があります。

suggestedQuality パラメータ値には、small、medium、large、hd720、default を指定できます。パラメータ値を default に設定すると、YouTube は最適な再生画質を自動選択します。この画質は、ユーザー、動画、システムなどの再生条件によって異なります。

動画の推奨再生画質を提示する場合、推奨された画質はその動画でのみ有効となります。動画プレーヤーのサイズに対応した再生画質を選択する必要があります。たとえば、ページに 640x360 ピクセルの動画プレーヤーを表示している場合、medium 画質の方が large 画質よりも実際には動画がきれいに見えます。プレーヤー サイズ別の推奨再生画質を次に示します:

• 画質レベル small: 解像度が 640x360 ピクセル未満のプレーヤー向け。
• 画質レベル medium: 解像度が 640x360 ピクセル以上のプレーヤー向け。
• 画質レベル large: 解像度が 854x480 ピクセル以上のプレーヤー向け。
• 画質レベル hd720: 解像度が 1280x720 ピクセル以上のプレーヤー向け。
• 画質レベル default: YouTube が適切な再生画質を選択します。この設定は、画質レベルをデフォルトの状態に戻し、それまでに cueVideoById、loadVideoById、setPlaybackQuality の各関数で行った再生画質の設定を無効にします。

setPlaybackQuality 関数を動画で無効な suggestedQuality レベルを指定して呼び出すと、有効な画質の中で低い方から 2 番目の画質が設定されます。たとえば、無効な画質レベルの large をリクエストすると、再生画質は medium に設定されます（この画質レベルが有効な場合）。

また、認識されない画質レベルに suggestedQuality を設定すると、suggestedQuality の設定は default と同様に処理されます。

player.getAvailableQualityLevels():Array

この関数は、現在の動画で有効な画質のセットを返します。この関数を使用すると、ユーザーが表示している画質よりも高い画質で動画を再生できるかどうかを判断し、プレーヤーにボタンなどの要素を表示してユーザーが画質を調整できるようにすることができます。

この関数は、高画質から低画質の順で、画質を示す文字列の配列を返します。配列要素の値には、hd720、large、medium、small があります。現在の動画がない場合、この関数は空の配列を返します。

クライアントで、最高または最低の画質や不明な画質形式に自動的に切り替えないようにしてください。YouTube は、お使いのプレーヤーに適さない画質レベルを追加する可能性があります。同様に、ユーザー操作の妨げとなり得る画質オプションを削除する可能性もあります。有効な既知の画質形式のみに切り替えるようにすることで、クライアントは、新しい画質レベルの追加やプレーヤーに適さない画質レベルの削除による影響を受けなくなります。

動画情報の取得

player.getDuration():Number

再生中の動画の長さを秒数で返します。動画のメタデータが読み込まれるまで、getDuration() は 0 を返します。通常、動画再生を開始した直後にこの現象が発生します。

player.getVideoUrl():String

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

player.getVideoEmbedCode():String

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

イベント リスナーの追加

player.addEventListener(event:String, listener:Function):Void

指定した event にリスナー関数を追加します。プレーヤーが起動するイベントの説明については、以下のイベント セクションをご覧ください。listener は、指定したイベントが起動したときに実行する関数への参照です。

特殊な関数

ActionScript 固有の API 呼び出しは次のとおりです:

player.destroy():Void

この関数は AS3 Player API ではまだ実装されていませんが、プレーヤーのインスタンスを破棄します。このメソッドは、親 SWF からプレーヤー SWF をアンロードした後で呼び出す必要があります。

重要: 常に player.destroy() を呼び出して、YouTube プレーヤーをアンロードするようにしてください。この関数は、NetStream オブジェクトをクローズし、プレーヤーをアンロードした後、動画のダウンロードを停止します。プレーヤー SWF の他にコードで参照しているものがある場合、プレーヤーのアンロード時にその参照も別途破棄する必要があります。

イベント

onReady

このイベントは、プレーヤーの読み込み、初期化が終了し、API 呼び出しを受け取ることができるようになったときに起動します。

onStateChange

このイベントは、プレーヤーの状態が変わると起動します。値には、未開始（-1）、終了（0）、再生中（1）、一時停止中（2）、バッファリング中（3）、頭出し済み（5）があります。SWF を初めて読み込んだときは、未開始（-1）イベントがブロードキャストされます。動画の頭出しをして再生の準備が整ったら、頭出し済みイベント（5）がブロードキャストされます。

onPlaybackQualityChange

このイベントは、動画の再生画質が変わると起動します。たとえば、setPlaybackQuality(suggestedQuality) 関数を呼び出した場合、再生画質が実際に変わるとこのイベントが起動します。コードを記述する際は、setPlaybackQuality(suggestedQuality) 関数を呼び出したら画質が自動的に変わるものと想定せず、このイベントに応答するようにする必要があります。同様に、setPlaybackQuality や、推奨再生画質を設定できる関数を明示的に呼び出せば再生画質は変わるものと想定しないようにする必要もあります。

このイベントがブロードキャストする値は、新しい再生画質を示します。値には、「small」、「medium」、「large」、「hd720」があります。

onError

このイベントは、プレーヤーでエラーが起きると起動します。エラーコードには、100、101、150 があります。100 エラー コードは、リクエストされた動画が見つからないときにブロードキャストされます。これは、動画が何らかの理由で削除されている場合や、非公開に設定されている場合に発生します。101 エラー コードは、リクエストされた動画が埋め込みプレーヤーでの再生を許可していないときにブロードキャストされます。エラー コード 150 は 101 と同じで、101 のコード違いです。

例

プレーヤー SWF の読み込み

AS3 API の初期化シーケンスは AS2 プレーヤーとは異なります。AS2 プレーヤーでは isPlayerLoaded() 関数を使用してプレーヤーの読み込み、初期化、API 呼び出し対応の状態を判断しますが、AS3 プレーヤーではもっと強力なイベント システムを使用します。以下のサンプル コードは、AS3 API プレーヤーを読み込んで初期化する方法を示しています:

// This will hold the API player instance once it is initialized.
var player:Object;

var loader:Loader = new Loader();
loader.contentLoaderInfo.addEventListener(Event.INIT, onLoaderInit);
loader.load(new URLRequest("http://www.youtube.com/apiplayer?version=3"));

function onLoaderInit(event:Event):void {
    addChild(loader);
    loader.content.addEventListener("onReady", onPlayerReady);
    loader.content.addEventListener("onError", onPlayerError);
    loader.content.addEventListener("onStateChange", onPlayerStateChange);
    loader.content.addEventListener("onPlaybackQualityChange", 
        onVideoPlaybackQualityChange);
}

function onPlayerReady(event:Event):void {
    // Event.data contains the event parameter, which is the Player API ID 
    trace("player ready:", Object(event).data);

    // Once this event has been dispatched by the player, we can use
    // cueVideoById, loadVideoById, cueVideoByUrl and loadVideoByUrl
    // to load a particular YouTube video.
    player = loader.content;
}

function onPlayerError(event:Event):void {
    // Event.data contains the event parameter, which is the error code
    trace("player error:", Object(event).data);
}

function onPlayerStateChange(event:Event):void {
    // Event.data contains the event parameter, which is the new player state
    trace("player state:", Object(event).data);
}

function onVideoPlaybackQualityChange(event:Event):void {
    // Event.data contains the event parameter, which is the new video quality
    trace("video quality:", Object(event).data);
}

画質トグル ボタンの状態の判断

以下のサンプル コードは、YouTube の画質トグル ボタンの状態を判断する方法を示しています。ユーザーはこのボタンを使用して、動画を表示できる画質レベルの中から別の再生画質を指定することができます。

var qualityLevels:Array = getAvailableQualityLevels()
// qualityLevels may be undefined if the API function does not exist, 
// in which case this conditional is false
if (qualityLevels.length > 1) {

    var highestQuality:String = qualityLevels[0]
    if (highestQuality begins with "hd") {
        // Brand quality toggle button as HD.
    } else {
        // Brand quality toggle button as HQ.
        // The highest available quality is shown, but it is not HD video.
    }

    var quality:String = getPlaybackQuality();
    if (quality == 'small' || quality == 'medium') {
        // The user is not watching the highest quality available 
        // can can toggle to a higher quality.
    } else {
        // The user is watching the highest quality available 
        // and can toggle to a lower quality.
    }

} else {
    // Hide the toggle button because there is no current video or
    // there is only one quality available.
}

トップへ戻る