Using the StageVideo APIs
Stage video is a mechanism within the runtime that enhances
video playback and device performance. The runtime creates and maintains
this mechanism; as a developer, your role is to configure your application
to take advantage of it.
To use stage video, you implement a framework of event handlers
that detect when stage video is and isn’t available. When you receive
notification that stage video is available, you retrieve a StageVideo
object from the Stage.stageVideos property. The
runtime populates this Vector object with one or more StageVideo
objects. You can then use one of the provided StageVideo objects,
rather than a Video object, to display streaming video.
On Flash Player, when you receive notification that stage video
is no longer available, switch your video stream back to a Video
Note: You cannot create StageVideo objects.
The Stage.stageVideos property
is a Vector object that gives you access to StageVideo instances.
This vector can contain up to four StageVideo objects, depending
on hardware and system resources. Mobile devices can be limited
to one, or none.
When stage video is not available, this vector contains no objects.
To avoid run time errors, be sure that you access members of this
vector only when the most recent StageVideoAvailability event
indicates that stage video is available.
The StageVideo API framework provides the following events:
- Sent when the Stage.stageVideos property
changes. The StageVideoAvailabilityEvent.availability property
indicates either AVAILABLE or UNAVAILABLE.
Use this event to determine whether the stageVideos property
contains any StageVideo objects, rather than directly checking the
length of the Stage.stageVideos vector.
- Sent when a NetStream or Camera object has been attached
to a StageVideo object and is playing. Indicates the type of decoding
currently in use: hardware, software, or unavailable (nothing is displayed).
The event target contains videoWidth and videoHeight properties
that are safe to use for resizing the video viewport.
Important: Coordinates obtained from the StageVideo
target object use Stage coordinates, since they are not part of
the standard display list.
- Sent when a Video object is being used. Indicates whether
software or hardware accelerated decoding is in use. If this event indicates
hardware accelerated decoding, switch to a StageVideo object if possible.
The Video event target contains videoWidth and videoHeight properties
that are safe to use for resizing the video viewport.
Workflow for implementing the StageVideo feature
Follow these top-level steps to implement the StageVideo
Listen for the StageVideoAvailabilityEvent.STAGE_VIDEO_AVAILABILITY event
to find out when the Stage.stageVideos vector has
changed. See Using the StageVideoAvailabilityEvent.STAGE_VIDEO_AVAILABILITY event.
If the StageVideoAvailabilityEvent.STAGE_VIDEO_AVAILABILITY event
reports that stage video is available, use the Stage.stageVideos Vector
object within the event handler to access a StageVideo object.
Attach a NetStream object using StageVideo.attachNetStream() or attach
a Camera object using StageVideo.attachCamera().
Play the video using NetStream.play().
Listen for the StageVideoEvent.RENDER_STATE event
on the StageVideo object to determine the status of playing the
video. Receipt of this event also indicates that the width and height
properties of the video have been initialized or changed. See Using the StageVideoEvent.RENDER_STATE and VideoEvent.RENDER_STATE events.
Listen for the VideoEvent.RENDER_STATE event
on the Video object. This event provides the same statuses as StageVideoEvent.RENDER_STATE, so
you can also use it to determine whether GPU acceleration is available.
Receipt of this event also indicates that the width and height properties
of the video have been initialized or changed. See Using the StageVideoEvent.RENDER_STATE and VideoEvent.RENDER_STATE events.
Initializing StageVideo event listeners
Set up your StageVideoAvailabilityEvent and VideoEvent
listeners during application initialization. For example, you can
initialize these listeners in the flash.events.Event.ADDED_TO_STAGE event
handler. This event guarantees that your application is visible
on the 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
private function onAddedToStage(event:Event):void
nc = new NetConnection();
ns = new NetStream(nc);
ns.client = this;
video = new Video();
video.smoothing = true;
// Video Events
// the StageVideoEvent.STAGE_VIDEO_STATE informs you whether
// StageVideo is available
// in case of fallback to Video, listen to the VideoEvent.RENDER_STATE
// event to handle resize properly and know about the acceleration mode running
Using the StageVideoAvailabilityEvent.STAGE_VIDEO_AVAILABILITY event
In the StageVideoAvailabilityEvent.STAGE_VIDEO_AVAILABILITY handler,
decide whether to use a Video or StageVideo object based on the
availability of StageVideo. If the StageVideoAvailabilityEvent.availability property
is set to StageVideoAvailability.AVAILABLE, use
StageVideo. In this case, you can rely on the Stage.stageVideos
vector to contain one or more StageVideo objects. Obtain a StageVideo
object from the Stage.stageVideos property and
attach the NetStream object to it. Because StageVideo objects always
appear in the background, remove any existing Video object (always
in the foreground). You also use this event handler to add a listener
for the StageVideoEvent.RENDER_STATE event.
If the StageVideoAvailabilityEvent.availability property
is set to StageVideoAvailability.UNAVAILABLE, do
not use StageVideo or access the Stage.stageVideos vector.
In this case, attach the NetStream object to a Video object. Finally,
add the StageVideo or Video object to the stage and call NetStream.play().
The following code shows how to handle the StageVideoAvailabilityEvent.STAGE_VIDEO_AVAILABILITY event:
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
stageVideoInUse = true;
if ( sv == null )
sv = stage.stageVideos;
// 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;
// Otherwise attach it to a Video object
stageVideoInUse = false;
classicVideoInUse = true;
if ( !played )
played = true;
Important: The first time an application accesses
the vector element at Stage.stageVideos, the default rect is
set to 0,0,0,0, and pan and zoom properties use default values.
Always reset these values to your preferred settings. You can use the videoWidth and videoHeight properties
of the StageVideoEvent.RENDER_STATE or VideoEvent.RENDER_STATE event
target for calculating the video viewport dimensions.
Download the full source code for this sample application at Getting Started with Stage Video.
Using the StageVideoEvent.RENDER_STATE and VideoEvent.RENDER_STATE events
StageVideo and Video objects send events that inform applications
when the display environment changes. These events are StageVideoEvent.RENDER_STATE and VideoEvent.RENDER_STATE.
A StageVideo or Video object dispatches a render state event
when a NetStream object is attached and begins playing. It also
sends this event when the display environment changes; for example,
when the video viewport is resized. Use these notifications to reset
your viewport to the current videoHeight and videoWidth values
of the event target object.
Reported render states include:
Render states indicate when hardware accelerated decoding is
in use, regardless of which class is currently playing video. Check
the StageVideoEvent.status property to learn whether
the necessary decoding is available. If this property is set to
“unavailable”, the StageVideo object cannot play the video. This
status requires that you immediately reattach the NetStream object
to a Video object. Other statuses inform your application of the
current rendering conditions.
The following table describes the implications of all render
status values for StageVideoEvent and VideoEvent objects in Flash
Decoding and presentation both occur in
hardware. (Best performance.)
Presentation in hardware, decoding in software. (Acceptable
No GPU resources are available to handle
video, and nothing is displayed. Fall back to a Video object.
Presentation in software, decoding in hardware.
(Acceptable performance on a modern desktop system only. Degraded full-screen
Presentation in software, decoding in software. (Worst
case performance-wise. Degraded full-screen performance.)
Stage video uses underlying hardware capabilities to support
color spaces. SWF content can provide metadata indicating its preferred
color space. However, the device graphics hardware determines whether
that color space can be used. One device can support several color
spaces, while another supports none. If the hardware does not support
the requested color space, Flash Player attempts to find the closest
match among the supported color spaces.
To query which color spaces the hardware supports, use the StageVideo.colorSpaces property.
This property returns the list of supported color spaces in a String
var colorSpace:Vector.<String> = stageVideo.colorSpaces();
To learn which color space the currently playing video is using,
check the StageVideoEvent.colorSpace property.
Check this property in your event handler for the StageVideoEvent.RENDER_STATE event:
//StageVideoEvent.RENDER_STATE event handler
private function stageVideoRenderState(event:Object):void
currColorSpace = (event as StageVideoEvent).colorSpace;
If Flash Player cannot find a substitute for an unsupported color
space, stage video uses the default color space BT.601. For example,
video streams with H.264 encoding typically use the BT.709 color
space. If the device hardware does not support BT.709, the colorSpace property
returns "BT601". A StageVideoEvent.colorSpace value
of "unknown" indicates that the hardware does not
provide a means of querying the color space.
If your application deems the current color space unacceptable,
you can choose to switch from a StageVideo object to a Video object.
The Video class supports all color spaces through software compositing.