StageVideo API の使用

Stage.stageVideos プロパティは Vector オブジェクトであり、ここから StageVideo インスタンスにアクセスできます。この Vector には、ハードウェアおよびシステムリソースに応じて、最大 4 個の StageVideo オブジェクトを含めることができます。モバイルデバイスでは、1 個のみ、または「なし」に制限されることがあります。

ステージビデオが利用不能な場合、この Vector にはオブジェクトは含まれません。実行時エラーを回避するため、最新の StageVideoAvailability イベントが、ステージビデオが利用可能であることを示している場合のみ、このベクターのメンバーにアクセスするようにしてください。

StageVideo API フレームワークは、次のイベントを提供します。

StageVideoAvailabilityEvent.STAGE_VIDEO_AVAILABILITY

Stage.stageVideos プロパティの変更時に送信されます。 StageVideoAvailabilityEvent.availability プロパティは、 AVAILABLE と UNAVAILABLE のどちらかが指定されます。 stageVideos プロパティに StageVideo オブジェクトが含まれているかどうかの確認には、 Stage.stageVideos のベクターの長さを直接チェックするのではなく、このイベントを使用してください。

StageVideoEvent.RENDER_STATE

NetStream または Camera オブジェクトが StageVideo オブジェクトに割り当てられ、再生中となったときに送信されます。ハードウェア、ソフトウェア、利用不能（何も表示されない）の中から、現在使用中のデコードの種類が示されます。イベントターゲットには、 videoWidth プロパティと videoHeight プロパティが含まれており、これらはビデオのビューポートのサイズを変更するために安全に使用できます。

重要： StageVideo ターゲットオブジェクトから取得された座標は、標準表示リストに含まれていないので、ステージの座標が使用されます。

VideoEvent.RENDER_STATE

Video オブジェクトの使用中に送信されます。ソフトウェアによるデコードとハードウェアアクセラレーションによるデコードのどちらが使用中であるかを示します。このイベントがハードウェアアクセラレーションによるデコードを示す場合は、可能であれば StageVideo オブジェクトに切り替えてください。Video イベントターゲットには、 videoWidth プロパティと videoHeight プロパティが含まれており、これらはビデオのビューポートのサイズを変更するために安全に使用できます。

次のトップレベルの手順に従って、StageVideo 機能を実装します。

1. Stage.stageVideos ベクターが変更されたタイミングを知るために、 StageVideoAvailabilityEvent.STAGE_VIDEO_AVAILABILITY イベントをリッスンします StageVideoAvailabilityEvent.STAGE_VIDEO_AVAILABILITY イベントの使用 を参照してください

2. StageVideoAvailabilityEvent.STAGE_VIDEO_AVAILABILITY イベントによりステージビデオが利用可能であることがレポートされた場合に、そのイベントハンドラー内の Stage.stageVideos ベクターオブジェクトを使用して StageVideo オブジェクトにアクセスします。

3. StageVideo.attachNetStream() を使用して NetStream オブジェクトを関連付けるか、または StageVideo.attachCamera() を使用して Camera オブジェクトを関連付けます。

4. NetStream.play() を使用してビデオを再生します。

5. ビデオ再生のステータスを知るために、StageVideo オブジェクト上の StageVideoEvent.RENDER_STATE イベントをリッスンします。また、このイベントの受領は、ビデオの width および height プロパティが初期化または変更されたことも示します。 StageVideoEvent.RENDER_STATE イベントと VideoEvent.RENDER_STATE イベントの使用 を参照してください。

6. Video オブジェクト上の VideoEvent.RENDER_STATE イベントをリッスンします。このイベントは、 StageVideoEvent.RENDER_STATE と同じステータスを提供します。したがって、このイベントを使用して GPU アクセラレーションが利用可能かどうかを判断することができます。また、このイベントの受領は、ビデオの width および height プロパティが初期化または変更されたことも示します。 StageVideoEvent.RENDER_STATE イベントと VideoEvent.RENDER_STATE イベントの使用 を参照してください。

アプリケーションの初期化中に、StageVideoAvailabilityEvent と VideoEvent のリスナーを設定します。例えば、これらのリスナーを flash.events.Event.ADDED_TO_STAGE イベントハンドラー内で初期化できます。このイベントによって、アプリケーションがステージ上で可視状態となることを保証できます。

public class SimpleStageVideo extends Sprite 
    private var nc:NetConnection; 
    private var ns:NetStream; 
 
    public function SimpleStageVideo() 
    { 
        // Constructor for SimpleStageVideo class 
        // Make sure the app is visible and stage available 
        addEventListener(Event.ADDED_TO_STAGE, onAddedToStage); 
    } 
     
    private function onAddedToStage(event:Event):void 
    { 
        //... 
        // Connections 
        nc = new NetConnection(); 
        nc.connect(null); 
        ns = new NetStream(nc); 
        ns.addEventListener(NetStatusEvent.NET_STATUS, onNetStatus); 
        ns.client = this; 
 
        // Screen 
        video = new Video(); 
        video.smoothing = true; 
 
        // Video Events 
        // the StageVideoEvent.STAGE_VIDEO_STATE informs you whether 
        // StageVideo is available 
        stage.addEventListener(StageVideoAvailabilityEvent.STAGE_VIDEO_AVAILABILITY, 
            onStageVideoState); 
        // in case of fallback to Video, listen to the VideoEvent.RENDER_STATE 
        // event to handle resize properly and know about the acceleration mode running 
        video.addEventListener(VideoEvent.RENDER_STATE, videoStateChange); 
        //... 
    }

StageVideoAvailabilityEvent.STAGE_VIDEO_AVAILABILITY ハンドラーでは、StageVideo が利用可能であるかどうかに基づいて、Video と StageVideo のどちらのオブジェクトを使用するかを決定します。 StageVideoAvailabilityEvent.availability プロパティが StageVideoAvailability.AVAILABLE に設定されている場合は、StageVideo を使用します。この場合、Stage.stageVideos の Vector に 1 つ以上の StageVideo オブジェクトが含まれていると見なすことができます。 Stage.stageVideos プロパティから StageVideo オブジェクトを取得し、それに NetStream オブジェクトを割り当てます。StageVideo オブジェクトは常に後ろの面に表示されるので、常に前の面に表示される既存の Video オブジェクトがある場合にはそれらを削除します。また、このイベントハンドラーを使用して、 StageVideoEvent.RENDER_STATE イベントのリスナーを追加することもできます。

StageVideoAvailabilityEvent.availability プロパティが StageVideoAvailability.UNAVAILABLE に設定されている場合は、StageVideo の使用や Stage.stageVideos ベクターへのアクセスは避けてください。この場合は、Video オブジェクトに NetStream オブジェクトを割り当ててください。最後に、ステージに StageVideo オブジェクトまたは Video オブジェクトを追加し、 NetStream.play() を呼び出します。

StageVideoAvailabilityEvent.STAGE_VIDEO_AVAILABILITY イベントの処理方法について、次のコードに示します。

private var sv:StageVideo; 
private var video:Video; 
 
private function onStageVideoState(event:StageVideoAvailabilityEvent):void 
{     
    // Detect if StageVideo is available and decide what to do in toggleStageVideo 
    toggleStageVideo(event.availability == StageVideoAvailability.AVAILABLE); 
} 
 
private function toggleStageVideo(on:Boolean):void 
{     
    // To choose StageVideo attach the NetStream to StageVideo 
    if (on) 
    { 
        stageVideoInUse = true; 
        if ( sv == null ) 
        { 
            sv = stage.stageVideos[0]; 
            sv.addEventListener(StageVideoEvent.RENDER_STATE, stageVideoStateChange); 
                sv.attachNetStream(ns); 
        } 
 
        if (classicVideoInUse) 
        { 
            // If you use StageVideo, remove from the display list the 
            // Video object to avoid covering the StageVideo object 
            // (which is always in the background) 
            stage.removeChild ( video ); 
            classicVideoInUse = false; 
        } 
    } else 
    { 
        // Otherwise attach it to a Video object 
        if (stageVideoInUse) 
            stageVideoInUse = false; 
        classicVideoInUse = true; 
        video.attachNetStream(ns); 
        stage.addChildAt(video, 0); 
    } 
     
    if ( !played ) 
    { 
        played = true; 
        ns.play(FILE_NAME); 
    } 
} 

このサンプルアプリケーションのソースコード全体は、「 Getting Started with Stage Video 」からダウンロードしてください。

StageVideo オブジェクトと Video オブジェクトは、表示環境が変化した際にアプリケーションに通知するイベントを送信します。これらのイベントは、 StageVideoEvent.RENDER_STATE と VideoEvent.RENDER_STATE です。

NetStream オブジェクトが割り当てられ再生を開始したときに、StageVideo オブジェクトまたは Video オブジェクトからレンダリング状態イベントが送出されます。また、ビデオビューポートのサイズが変更された場合など、表示環境が変化したときにもこのイベントが送信されます。これらの通知を使用して、ビューポートを、イベントターゲットオブジェクトの現在の videoHeight および videoWidth 値に再設定します。

レポートされるレンダリング状態には次のものがあります。

• RENDER_STATUS_UNAVAILABLE

• RENDER_STATUS_SOFTWARE

• RENDER_STATUS_ACCELERATED

現在どのクラスがビデオを再生しているかに関わらず、レンダリング状態では、ハードウェアアクセラレーションによるデコードがいつ使用されるかが示されます。必要なデコードが利用可能かどうかを確認するには、 StageVideoEvent.status プロパティをチェックしてください。このプロパティが「unavailable」に設定されている場合、StageVideo オブジェクトによりビデオを再生することはできません。この状態の場合、すぐに NetStream オブジェクトを Video オブジェクトに割り当て直す必要があります。他の状態の場合、アプリケーションに対して現在のレンダリング状況が通知されます。

Flash Player における StageVideoEvent オブジェクトと VideoEvent オブジェクトの各レンダリング状態値が表す状況について、次の表に示します。

ステージビデオは、下層のハードウェア機能を使用して、カラースペースをサポートします。SWF コンテンツには、優先するカラースペースを示すメタデータを設定できますが、そのカラースペースが使用可能かどうかを判定するのはデバイスのグラフィックハードウェアです。様々なカラースペースをサポートするデバイスもあれば、カラースペースを一切サポートしないデバイスもあります。要求されたカラースペースがハードウェアでサポートされていない場合には、Flash Player は、サポートされるカラースペースの中で最も近いものを見つけようとします。

ハードウェアでサポートされるカラースペースを調べるには、 StageVideo.colorSpaces プロパティを使用します。このプロパティは、サポートされるカラースペースのリストを String の Vector で返します。

var colorSpace:Vector.<String> = stageVideo.colorSpaces();

現在再生中のビデオで使用されているカラースペースを調べるには、 StageVideoEvent.colorSpace プロパティをチェックします。 StageVideoEvent.RENDER_STATE イベントのイベントハンドラーで、このプロパティをチェックしてください。

var currColorSpace:String; 
 
//StageVideoEvent.RENDER_STATE event handler 
private function stageVideoRenderState(event:Object):void 
{ 
    //... 
    currColorSpace = (event as StageVideoEvent).colorSpace; 
    //... 
}

サポートされないカラースペースの代わりとなるカラースペースが見つからない場合、ステージビデオではデフォルトのカラースペースである BT.601 が使用されます。例えば、H.264 エンコーディングによるビデオストリームでは、通常 BT.709 カラースペースが使用されます。デバイスハードウェアが BT.709 をサポートしていない場合、 colorSpace プロパティは "BT601" を返します。 StageVideoEvent.colorSpace の値が "unknown" の場合、カラースペースを調べる手段をハードウェアが提供していないことを示します。

現在のカラースペースがアプリケーション側で受け入れられないと判断された場合は、StageVideo オブジェクトから Video オブジェクトに切り替えることが可能です。Video クラスでは、ソフトウェア合成によってすべてのカラースペースがサポートされます。