Introducing SimpleStageVideo

SimpleStageVideoIf you played with Stage Video, one of the coolest feature of Flash Player 10.2. You may have noticed that this it requires a little bit of code to be leveraged and you have to deal with multiple events (StageVideoEvent, StageVideoAvailability, VideoEvent) to be used properly. While writing the Stage Video article for the Adobe devnet I realized that the need of a wrapper would be useful for developers, and a few days ago I came across StageVideoProxy by Kenny Bunch which is intended to simplify the use of Stage Video. This confirmed the idea that AS3 developers will need little wrappers for Stage Video, I know Tinic has his own version too for his tests.

Here is my version a little bit different, which should handle all the situations, switching automatically from Video to StageVideo and vice versa when Stage Video becomes available or unavailable. It handles all this automatically so you do not have to worry about it. It also handles something I ALWAYS need in my video players, respecting the video ratio when giving a specific maximum width and height to fit a specific surface to display the video :

To use, it is very simple, just use a few lines code :

// specifies the size to conform (will always preserve ratio)
var simpleStageVideo:SimpleStageVideo = new SimpleStageVideo(800, 600);
// dispatched when stream can be played (NetStream object cannot be played before attached to the video object)
simpleStageVideo.addEventListener(Event.INIT, onInit);
// attach the NetStream to it
simpleStageVideo.attachNetStream(ns);
// display it (this is for the sake of
addChild(simpleStageVideo);

One thing to notice is that even if we addChild the SimpleStageVideo object, the StageVideo object sits behind the stage, and the Video object used as a fallback will be added as a child of the stage so as a sibling of the main timeline. As a result, where you addChild the SimpleStageVideo object has no real impact on the nesting of the video surfaces.

Also, when working with the low level Stage Video APIs, you have to work with two events, StageVideoEvent.RENDER_STATE and VideoEvent.RENDER_STATE to detect how compositing is done and if hardware video decoding is performed. With SimpleStageVideo, those events are centralized through a single event called SimpleStageVideoEvent.STATUS which gives you access to the hardwareCompositing, hardwareDecoding and fullGPU properties :

private function onStatus(event:SimpleStageVideoEvent):void
{
	// informs you about the decoding, compositing states and if full GPU acceleration is performing
	var hardwareDecoding:Boolean = event.hardwareDecoding;
	var hardwareCompositing:Boolean = event.hardwareCompositing;
	var fullGPU:Boolean = event.fullGPU;
}

If you need to resize the video surfaces, use the resize API which does it automatically for you while preserving the image ratio :

simpleStageVideo.resize(stage.stageWidth, stage.stageHeight);

If you need to force the fallback from Video to StageVideo and vice versa for performance benchmarking, just use the toggle API :

simpleStageVideo.toggle(!inited);

Of course, when toggling, the SimpleStageVideoEvent.STATUS is dispatched every time, to let you know about the decoding, compositing, useful for logging, debugging, and performance benchmarking. A SimpleStageVideoToggleEvent.TOGGLE is also dispatched to inform you about the current video object used internally.

This can be useful if you need to draw the content of the video on a BitmapData. As the StageVideo object is not a DisplayObject, you cannot draw it, but you can use the toggle API, then wait for the SimpleStageVideoToggleEvent.TOGGLE, and then draw the underlying Video object used as a fallback, and there you go, you have your video content rasterized.

If you need to access the underlying Video and StageVideo objects you can use the proper getters :

var underlyingStageVideo:StageVideo = simpleStageVideo.stageVideo;
var underlyingVideo:Video = simpleStageVideo.video;

To view a live demo of it, click here (Flash Player 10.2 required). To download SimpleStageVideo, check the simplestagevideo project.

Show Comments

Hide Comments

Comments are closed.