Uso de las API de StageVideo

La propiedad Stage.stageVideos es un objeto Vector que permite el acceso a las instancias de StageVideo. Este vector puede incluir hasta cuatro objetos StageVideo, dependiendo de los recursos del sistema y el hardware. Los dispositivos móviles se pueden limitar a uno o ninguno.

Cuando Stage Video no está disponible, este vector no contiene objetos. Para evitar errores en tiempo de ejecución, compruebe que solo accede a los miembros de este vector cuando el evento StageVideoAvailability más reciente indique que Stage Video está disponible.

La arquitectura de la API de StageVideo proporciona los siguientes eventos:

StageVideoAvailabilityEvent.STAGE_VIDEO_AVAILABILITY

Enviado cuando cambia la propiedad Stage.stageVideos . La propiedad StageVideoAvailabilityEvent.availability indica AVAILABLE (DISPONIBLE) o UNAVAILABLE (NO DISPONIBLE). Utilice este evento para determinar si la propiedad stageVideos contiene algún objeto StageVideo, en lugar de comprobar directamente la longitud del vector Stage.stageVideos .

StageVideoEvent.RENDER_STATE

Enviado cuando un objeto NetStream o Camera se ha añadido a un objeto StageVideo y se está reproduciendo. Indica el tipo de descodificación que se está utilizando: hardware, software o no disponible (no se muestra nada). El destino del evento contiene las propiedades videoWidth y videoHeight que son seguras para su uso en el cambio de tamaño de la ventana gráfica de vídeo.

Importante: las coordenadas obtenidas del objeto de destino StageVideo utilizan las coordenadas de Stage, ya que no forman parte de la lista de visualización estándar.

VideoEvent.RENDER_STATE

Enviado cuando se está utilizando un objeto Video. Indica si se está utilizando la descodificación con aceleración por hardware o software. Si este evento indica descodificación acelerada por hardware, cambie a un objeto StageVideo, si es posible. El destino del evento Video contiene las propiedades videoWidth y videoHeight que son seguras para su uso a la hora de cambiar el tamaño de la ventana gráfica de vídeo.

Siga estos pasos de nivel superior para implementar la función StageVideo:

1. Detecte el evento StageVideoAvailabilityEvent.STAGE_VIDEO_AVAILABILITY para saber cuándo cambia el vector Stage.stageVideos . Consulte Uso del evento StageVideoAvailabilityEvent.STAGE_VIDEO_AVAILABILITY .

2. Si el evento StageVideoAvailabilityEvent.STAGE_VIDEO_AVAILABILITY informa de que Stage Video está disponible, utilice el objeto vectorial Stage.stageVideos dentro del controlador de eventos para acceder a un objeto StageVideo.

3. Asocie un objeto NetStream con StageVideo.attachNetStream() o un objeto Camera con StageVideo.attachCamera() .

4. Reproduzca el vídeo con NetStream.play() .

5. Detecte el evento StageVideoEvent.RENDER_STATE en el objeto StageVideo para determinar el estado de reproducción del vídeo. La recepción de este evento también indica que las propiedades width y height del vídeo se han inicializado o han cambiado. Consulte Uso de los eventos StageVideoEvent.RENDER_STATE y VideoEvent.RENDER_STATE .

6. Detecte el evento VideoEvent.RENDER_STATE en el objeto Video. Este evento proporciona los mismos estados que StageVideoEvent.RENDER_STATE , de modo que también puede utilizarlo para determinar si la aceleración por GPU está disponible. La recepción de este evento también indica que las propiedades width y height del vídeo se han inicializado o han cambiado. Consulte Uso de los eventos StageVideoEvent.RENDER_STATE y VideoEvent.RENDER_STATE .

Configure los detectores StageVideoAvailabilityEvent y VideoEvent durante la inicialización de la aplicación. Por ejemplo, puede inicializar estos detectores en el controlador de eventos flash.events.Event.ADDED_TO_STAGE . Este evento garantiza que la aplicación se encuentra visible en el escenario:

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

En el controlador StageVideoAvailabilityEvent.STAGE_VIDEO_AVAILABILITY , decida si utilizar un objeto Video o StageVideo en función de la disponibilidad de StageVideo. Si la propiedad StageVideoAvailabilityEvent.availability se establece en StageVideoAvailability.AVAILABLE , utilice StageVideo. En este caso, se puede confiar en el vector Stage.stageVideos para que incluya uno o varios objetos StageVideo. Obtenga un objeto StageVideo de la propiedad Stage.stageVideos y añada el objeto NetStream al mismo. Debido a que el objeto StageVideo siempre aparece en segundo plano, elimine cualquier objeto Video existente(siempre en primer plano). Este controlador de eventos también se emplea para añadir un detector para el evento StageVideoEvent.RENDER_STATE .

Si la propiedad StageVideoAvailabilityEvent.availability se establece en StageVideoAvailability.UNAVAILABLE , no utilice StageVideo ni acceda al vector Stage.stageVideos . En este caso, añada el objeto NetStream a un objeto Video. Finalmente, añada el objeto StageVideo o Video al escenario y llame a NetStream.play() .

El siguiente código muestra cómo controlar el evento 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); 
    } 
} 

Descargue el código fuente completo para esta misma aplicación en Getting Started with Stage Video (Introducción a Stage Video; en inglés).

Los objetos StageVideo y Video envían eventos que informan a las aplicaciones del momento en que cambia el entorno de representación. Estos eventos son StageVideoEvent.RENDER_STATE y VideoEvent.RENDER_STATE .

Un objeto StageVideo o Video distribuye un evento de estado de representación cuando un objeto NetStream se añade y comienza a reproducirse. También envía este evento cuando cambia el entorno de representación; por ejemplo, cuando cambia de tamaño la ventana gráfica del vídeo. Utilice estas notificaciones para restablecer la ventana gráfica a los valores actuales videoHeight y videoWidth del objeto de destino del evento.

Los estados de representación indicados incluyen:

• RENDER_STATUS_UNAVAILABLE

• RENDER_STATUS_SOFTWARE

• RENDER_STATUS_ACCELERATED

Los estados de representación indican el momento en que se está utilizando la descodificación acelerada con hardware, independientemente de qué clase esté reproduciendo el vídeo actualmente. Compruebe la propiedad StageVideoEvent.status para saber si la descodificación necesaria está disponible. Si esta propiedad se define como “unavailable”, el objeto StageVideo no puede reproducir el vídeo. Este estado requiere que vuelva a añadir inmediatamente el objeto NetStream a un objeto Video. Otros estados informan a la aplicación de las condiciones de representación actuales.

En la siguiente tabla se describen las implicaciones de todos los valores del estado de representación para los objetos StageVideoEvent y VideoEvent en Flash Player:

Stage Video utiliza las capacidades de hardware subyacentes para admitir espacios de color. El contenido SWF puede proporcionar metadatos que indican su espacio de color preferido. Sin embargo, el hardware de los gráficos del dispositivo determina si ese espacio de color se puede utilizar. Un dispositivo puede admitir varios espacios de color, mientras que otros no admiten ninguno. Si el hardware no admite el espacio de color solicitado, Flash Player intenta encontrar el que más coincida entre los espacios de color compatibles.

Para consultar qué espacios de color admite el hardware, utilice la propiedad StageVideo.colorSpaces . Esta propiedad devuelve la lista de espacios de color admitidos en un vector String:

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

Para saber qué espacio de color está utilizando el vídeo que se está reproduciendo, compruebe la propiedad StageVideoEvent.colorSpace . Compruebe esta propiedad en su controlador de eventos para el evento StageVideoEvent.RENDER_STATE :

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

Si Flash Player no puede encontrar ningún sustituto para un espacio de color no compatible, Stage Video usa el espacio de color predeterminado BT.601. Por ejemplo, los flujos de vídeo con codificación H.264 suelen utilizar el espacio de color BT.709. Si el hardware del dispositivo no admite BT.709, la propiedad colorSpace devuelve "BT601" . Un valor StageVideoEvent.colorSpace de "unknown" indica que el hardware no proporciona ningún medio para consultar el espacio de color.

Si la aplicación considera inaceptable el espacio de color actual, es posible optar por cambiar de un objeto StageVideo a un objeto Video. La clase Video es compatible con todos los espacios de color mediante la composición de software.