Working with Stage Video

Stage Video is out (at least for us developers) in the form of the Flash Player 10.2 beta released last night on Adobe Labs. So what is Stage Video and why should you use it? Before answering this question let’s see where you can actually improve video playback performance. There are two places where you can use hardware acceleration (that is, use GPU instead of the CPU):

  • For decoding the video. This is especially important when playing high quality video like H.264 1080p
  • For compositing (rendering) the video to the screen

For the first scenario, Flash Player already supports hardware decoding of H.264 videos. Before now, Flash Player used to read this data back from the GPU to the CPU and use the CPU to render the video. Here comes the Stage Video feature: it enables the GPU to render the video directly on the display without the overhead incurred previously by reading back from the GPU and rendering with the CPU. So, if you want to get the best performance you want to use H.264 encoding for the video and Stage Video for displaying the video. By using these two features together you can achieve video playback on the new 11″ MacBook Air with less than 10% CPU usage, for example.

LATER UPDATE: Depending on the device hardware capabilities, video encoding and resolution, and application setup you can have any combination of hardware/software acceleration for decoding and compositing the video. In other words you can have both hardware accelerated or just the compositing while the decoding is run software.

In order to make this possible, the video is rendered basically behind the Flash Player display list when using Stage Video. This means that all display objects are rendered on top of the Stage Video plane. At the same time, it means you can’t apply the filters, masks, or effects that you can apply on display objects.

In this picture you can see how the video and other display objects are rendered when using the existing Video API:

And here you can see the two planes when using Stage Video:

Making sure you can use Stage Video

You should always try to use Stage Video. Maybe on powerful desktops the benefits will not be that dramatic, but for devices like televisions (Google TV, the upcoming Samsung SmartTV) and mobile devices the differences could be big. Right now Stage Video works on Google TV and desktops (using the beta Flash Player 10.2 released on Adobe Labs). But in the future it will work anywhere the Flash Platform is supported.

If you want to make sure that the same application can use Stage Video on desktop and Google TV you should always use wmode = “direct”. Finally, you should keep in mind that even if you did everything in your application to support Stage Video and the device/Flash Player you are running on supports Stage Video, you still don’t have any guarantee that your app will use Stage Video. And the reason is pretty simple: there is a limited number of videos that can be rendered at the same time using the GPU (on some hardware platforms you might have only one, on others you could have more). Thus if your application plays multiple videos at the same time, or if a number of SWFs are loaded in the same page and they all try to use Stage Video, then you can end up in a situation where Stage Video is not available to you.

For now Stage Video does not work in Flex applications. So you should stick to ActionScript apps when using Stage Video for the time being.

The Stage Video API

First of all, just in case you’re wondering if the previous video APIs are still available the answer is yes. They live side by side and actually, as you will see ,you should use them together. Let’s see the API for working with Stage Video. If you want to use Stage Video there are four basic steps you have to complete.

  1. Register an event listener on stage for StageVideoAvailabilityEvent.STAGE_VIDEO_AVAILABILITY event. This is a new event that lets you gracefully handle the Stage Video. Suppose your application wants to use Stage Video, but another application is already using it so your application can’t. By listening to this event you get a notification as soon as Stage Video becomes available, or, on the other hand, when it isn’t available anymore.
    stage.addEventListener(StageVideoAvailabilityEvent.STAGE_VIDEO_AVAILABILITY,
            onStageVideoState);
  2. In the event listener registered in the previous step you can poll a property called stageVideos on the stage object. This vector can have zero or more StageVideo objects (the StageVideo class is instantiated by Flash Player and you use it to render a single video).
    private function onStageVideoState(e:StageVideoAvailabilityEvent):void {
        if (e.availability == StageVideoAvailability.AVAILABLE) {
            var myVideo:StageVideo = stage.stageVideos[0];
        } else {
            //use Video API for displaying the video
        }
    }
  3. Once you have a StageVideo object you use pretty much the same techniques to attach a NetStream as in the case of the Video class:
    nc = new NetConnection();
    nc.addEventListener(NetStatusEvent.NET_STATUS, onNetStatusHandler);
    nc.connect(null);
    
    ns = new NetStream(nc);
    ns.addEventListener(NetStatusEvent.NET_STATUS, onNetStatus);
    ns.client = this;
    
    myVideo.attachNetStream(ns);
    ns.play(FILE_NAME);
  4. You can register an event listener on the StageVideo (in step 3) for the StageVideoEvent.RENDER_STATE if you want to resize the video (for example, to maintain the proportions) or you want to know if the video is processed using the GPU or not. The same event provides a property to read the color space used by the video. To resize the video you set a new Rectangle to the StageVideo viewPort property.

Don’t forget to define a method called onMetaData(e:Object):void for the client you set for the NetStream.

When you want to implement a fallback for Stage Video to Video and vice versa the best place to implement this is in the event listener registered for the StageVideoAvailabilityEvent.STAGE_VIDEO_AVAILABILITY event (see step 2). If StageVideo is available then you use an instance of StageVideo. If not, you create a Video object, attach the NetStream to it, and you add the object to the display list.

Where to go from here

For more, see the technical article on Adobe Developer Connection written by Flash Player product manager Thibault Imbert. And of course don’t forget to go to Adobe Labs and download the Flash Player 10.2 beta.

Show Comments

Hide Comments

Comments are closed.