使用 StageVideo API

Stage.stageVideos 屬性是可以讓您存取 StageVideo 實體的 Vector 物件。此向量最多可包含四個 StageVideo 物件，須視硬體與系統資源而定。行動裝置可能限制為一個或無。

當舞台視訊無法使用時，此向量不會包含任何物件。若要避免執行階段錯誤，請確定只在最新的 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. 偵聽 StageVideoAvailabilityEvent.STAGE_VIDEO_AVAILABILITY 事件，瞭解變更 Stage.stageVideos 向量的時間。請參閱 使用 StageVideoAvailabilityEvent.STAGE_VIDEO_AVAILABILITY 事件 。

2. 如果 StageVideoAvailabilityEvent.STAGE_VIDEO_AVAILABILITY 事件報告可使用舞台視訊，請使用事件處理常式中的 Stage.stageVideos Vector 物件來存取 StageVideo 物件。

3. 使用 StageVideo.attachNetStream() 來附加 NetStream 物件，或者使用 StageVideo.attachCamera() 來附加 Camera 物件。

4. 使用 NetStream.play() 來播放視訊。

5. 偵聽 StageVideo 物件上的 StageVideoEvent.RENDER_STATE 事件，以判斷播放視訊的狀態。收到這個事件也表示此視訊的寛度與高度屬性已經初始化或變更。請參閱 使用 StageVideoEvent.RENDER_STATE 與 VideoEvent.RENDER_STATE 事件 。

6. 偵聽 Video 物件上的 VideoEvent.RENDER_STATE 事件。此事件與 StageVideoEvent.RENDER_STATE 提供的狀態相同，因此您可以用它來判斷 GPU 加速是否可用。收到這個事件也表示此視訊的寛度與高度屬性已經初始化或變更。請參閱 使用 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 向量，以包含一或多個 StageVideo 物件。從 Stage.stageVideos 屬性取得 StageVideo 物件，並附加 NetStream 物件。因為 StageVideo 物件永遠都會顯示在背景，因此請移除任何現有的 Video 物件 (永遠都在前景)。您也可以利用此事件處理常式來新增 StageVideoEvent.RENDER_STATE 事件的偵聽程式。

如果將 StageVideoAvailabilityEvent.availability 屬性設定為 StageVideoAvailability.UNAVAILABLE ，請勿使用 StageVideo 或存取 Stage.stageVideos 向量。在此狀況下，將 NetStream 物件附加至 Video 物件。最後，將 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); 
    } 
} 

請在 開始使用舞台視訊 ，下載此範本應用程式的完整原始碼。

StageVideo 與 Video 物件會在顯示環境變更時傳送通知應用程式的事件。這些事件包括 StageVideoEvent.RENDER_STATE 與 VideoEvent.RENDER_STATE 。

StageVideo 或 Video 物件會在附加與開始播放 NetStream 物件時傳送顯示狀態事件。當顯示環境變更時，也會傳送此事件；例如調整視訊檢視區域大小時。使用這些通知可將您的檢視區域重設為事件目標物件目前的 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 向量傳回支援的顏色空間清單。

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; 
    //... 
}

如果 Flash Player 找不到不支援的顏色空間的替代方案，舞台視訊會使用預設的顏色空間 BT.601。例如，具有 H.264 編碼的視訊串流通常會使用 BT.709 顏色空間。如果裝置硬體不支援 BT.709，則 colorSpace 屬性會傳回 "BT601" 。 "unknown" 的 StageVideoEvent.colorSpace 值指出硬體不提供查詢顏色空間的方法。

如果您的應用程式將目前的顏色空間視為無法接受，則可以選擇從 StageVideo 物件切換至 Video 物件。Video 類別支援透過軟體複合的所有顏色空間。