Utilisation des API StageVideo

La propriété Stage.stageVideos est un objet Vector qui permet d’accéder aux occurrences de StageVideo. Selon les ressources matérielles et système disponibles, ce vecteur peut contenir jusqu’à quatre objets StageVideo. Il est possible de limiter à un ou zéro les périphériques mobiles.

Si la vidéo sur la scène n’est pas disponible, ce vecteur ne contient pas d’objet. Pour éviter les erreurs d’exécution, veillez à n’accéder aux membres de cet objet vectoriel que si l’événement StageVideoAvailability le plus récent indique la disponibilité de la vidéo sur la scène.

La structure de l’API StageVideo propose les événements suivants :

StageVideoAvailabilityEvent.STAGE_VIDEO_AVAILABILITY

Evénement envoyé en cas de modification de la propriété Stage.stageVideos . La propriété StageVideoAvailabilityEvent.availability indique soit AVAILABLE , soit UNAVAILABLE . Cet événement permet de déterminer si la propriété stageVideos contient des objets StageVideo, plutôt que de vérifier directement la longueur de l’objet vectoriel Stage.stageVideos .

StageVideoEvent.RENDER_STATE

Envoyé lorsqu'un objet NetStream ou Camera a été associé à un objet StageVideo et est en cours d'exécution. Indique le type de décodage actuellement utilisé : matériel, logiciel ou non disponible (aucune valeur affichée). L’événement cible contient les propriétés videoWidth et videoHeight , dont l’utilisation est adaptée au redimensionnement de la fenêtre d’affichage de la vidéo.

Important : étant donné qu’elles ne figurent pas dans la liste d’affichage standard, les coordonnées issues de l’objet StageVideo cible utilisent les coordonnées Stage.

VideoEvent.RENDER_STATE

Evénement envoyé si un objet Video est en cours d’utilisation. Il indique le type de décodage en cours d’utilisation (matériel ou logiciel). Si cet événement indique un décodage à accélération matérielle, utilisez de préférence un objet StageVideo. L’événement Video cible contient les propriétés videoWidth et videoHeight , dont l’utilisation est adaptée au redimensionnement de la fenêtre d’affichage de la vidéo.

Procédez comme suit pour mettre en œuvre la fonction StageVideo :

1. Ecoutez l’événement StageVideoAvailabilityEvent.STAGE_VIDEO_AVAILABILITY pour savoir quand l’objet vectoriel Stage.stageVideos a changé. Voir Utilisation de l’événement StageVideoAvailabilityEvent.STAGE_VIDEO_AVAILABILITY .

2. Si l’événement StageVideoAvailabilityEvent.STAGE_VIDEO_AVAILABILITY indique que la vidéo sur la scène est disponible, utilisez l’objet vectoriel Stage.stageVideos à l’intérieur du gestionnaire d’événement pour accéder à un objet StageVideo.

3. Associez un objet NetStream à l'aide de StageVideo.attachNetStream() ou associez un objet Camera à l'aide de StageVideo.attachCamera() .

4. Lisez la vidéo à l’aide de NetStream.play() .

5. Ecoutez l’événement StageVideoEvent.RENDER_STATE sur l’objet StageVideo afin de déterminer l’état de lecture de la vidéo. La réception de cet événement indique également que les propriétés width et height de la vidéo ont été initialisées ou modifiées. Voir Utilisation des événements StageVideoEvent.RENDER_STATE et VideoEvent.RENDER_STATE .

6. Ecoutez l’événement VideoEvent.RENDER_STATE sur l’objet Video. Cet événement indique les mêmes états que l’événement StageVideoEvent.RENDER_STATE ; vous pouvez donc également l’utiliser pour déterminer si l’accélération par processeur graphique est disponible. La réception de cet événement indique également que les propriétés width et height de la vidéo ont été initialisées ou modifiées. Voir Utilisation des événements StageVideoEvent.RENDER_STATE et VideoEvent.RENDER_STATE .

Configurez les écouteurs StageVideoAvailabilityEvent et VideoEvent lors de l’initialisation de l’application. Vous pouvez, par exemple, initialiser ces écouteurs dans le gestionnaire d’événement flash.events.Event.ADDED_TO_STAGE . Cet événement assure la visibilité de l’application sur la scène :

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

Dans le gestionnaire StageVideoAvailabilityEvent.STAGE_VIDEO_AVAILABILITY , optez pour un objet Video ou StageVideo selon la disponibilité de StageVideo. Si la propriété StageVideoAvailabilityEvent.availability est définie sur StageVideoAvailability.AVAILABLE , utilisez StageVideo. Dans ce cas de figure, attendez-vous à ce que le vecteur Stage.stageVideos contienne un ou plusieurs objets StageVideo. Obtenez un objet StageVideo à partir de la propriété Stage.stageVideos et associez-lui l’objet NetStream. Etant donné que les objets StageVideo s’affichent toujours en arrière-plan, supprimez tout objet Video existant (toujours affiché au premier plan). Ce gestionnaire d’événement permet également d’associer un écouteur à l’événement StageVideoEvent.RENDER_STATE .

Si la propriété StageVideoAvailabilityEvent.availability est définie sur StageVideoAvailability.UNAVAILABLE , n’utilisez pas l’objet StageVideo et n’accédez pas à l’objet vectoriel Stage.stageVideos . Associez dans ce cas l’objet NetStream à un objet Video. Ajoutez enfin l’objet StageVideo ou Video à la scène et appelez la méthode NetStream.play() .

Le code suivant illustre le traitement de l’événement 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); 
    } 
} 

Téléchargez le code source complet de cet exemple d’application à l’adresse Getting Started with Stage Video (disponible en anglais uniquement).

Les objets StageVideo et Video envoient des événements qui indiquent aux applications tout changement de l’environnement d’affichage. Ces événements sont StageVideoEvent.RENDER_STATE et VideoEvent.RENDER_STATE .

Un objet StageVideo ou Video distribue un événement d’état de rendu lorsqu’un objet NetStream est associé et que sa lecture débute. Il envoie également cet événement lorsque l’environnement d’affichage est modifié (en cas de redimensionnement de la fenêtre d’affichage de la vidéo, par exemple). Ces notifications permettent de réinitialiser la fenêtre d’affichage sur les valeurs videoHeight et videoWidth actuelles de l’objet événement cible.

Les états de rendu indiqués sont les suivants :

• RENDER_STATUS_UNAVAILABLE

• RENDER_STATUS_SOFTWARE

• RENDER_STATUS_ACCELERATED

Les états de rendu indiquent quand le décodage à accélération matérielle est en cours d’utilisation, quelle que soit la classe qui lit actuellement la vidéo. Vérifiez la propriété StageVideoEvent.status pour savoir si le décodage requis est disponible. Si elle est définie sur « unavailable », l’objet StageVideo ne peut pas lire la vidéo. Cet état nécessite que vous associiez à nouveau immédiatement l’objet NetStream à un objet Video. Les autres états indiquent à l’application les conditions de rendu en cours.

Le tableau ci-dessous décrit les implications de toutes les valeurs d’état de rendu pour les objets StageVideoEvent et VideoEvent dans Flash Player :

La vidéo sur la scène fait appel aux capacités matérielles sous-jacentes pour prendre en charge les espaces colorimétriques. Un contenu SWF peut fournir des métadonnées qui indiquent l’espace colorimétrique préféré. Le matériel graphique du périphérique détermine toutefois s’il est possible d’utiliser l’espace colorimétrique. Un périphérique peut prendre en charge plusieurs espaces colorimétriques, tandis qu’un autre périphérique n’en prend en charge aucun. Si le matériel ne prend pas en charge l’espace colorimétrique requis, Flash Player tente d’identifier la correspondance la plus proche parmi les espaces colorimétriques gérés.

Pour déterminer les espaces colorimétriques pris en charge par le matériel, faites appel à la propriété StageVideo.colorSpaces . Cette propriété renvoie la liste des espaces colorimétriques pris en charge dans un vecteur String :

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

Pour savoir quel espace colorimétrique utilise la vidéo en cours de lecture, faites appel à la propriété StageVideoEvent.colorSpace . Vérifiez cette propriété dans le gestionnaire associé à l’événement 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 ne détecte pas de valeur de substitution pour un espace colorimétrique non pris en charge, la vidéo sur la scène utilise l’espace colorimétrique par défaut, BT.601. Ainsi, les flux vidéo à codage H.264 utilisent généralement l’espace colorimétrique BT.709. Si le matériel du périphérique ne prend pas en charge BT.709, la propriété colorSpace renvoie « BT601 » . La valeur StageVideoEvent.colorSpace « unknown » indique que le matériel ne fournit pas de technique d’identification de l’espace colorimétrique.

Si l’application considère que l’espace colorimétrique actif est inacceptable, vous pouvez basculer d’un objet StageVideo à un objet Video. La classe Video prend en charge tous les espaces colorimétriques par le biais d’une composition logicielle.