The StageVideo object uses the device's hardware acceleration capabilities, if available, to display
live or recorded video in an application. Hardware acceleration capabilities are available on most devices.
See the flash.net.NetStream class for more information about supported formats.

AIR profile support: In AIR 3, all AIR for TV devices and some mobile devices support this
feature. AIR 3 for iOS uses the StageVideo object for H.264 video with hardware decoding, with limited supported for NetStream functionality.
AIR 3 for iOS also supports On2 and Sorenson codecs through the StageVideo object. This support does not use hardware decoding, and it does not
limit NetStream functionality. In AIR 2.5, only AIR for TV devices support this feature. Furthermore, ActionScript for this feature
in AIR 2.5 for TV is different than the ActionScript for AIR 3 or Flash Player 10.2.
The differences are noted in the ActionScript descriptions.
See
AIR Profile Support for more information regarding API support across multiple profiles.
The StageVideo class is not supported in the AIR desktop or extendedDesktop profiles.

The video displayed by the StageVideo object always appears in a rectangular area on the stage
behind all Flash display list objects. Therefore, the StageVideo object takes advantage of hardware acceleration
while supporting the most common case for displaying video: a rectangular display area overlaid with
video controls.

The benefits to using a StageVideo object instead of the Video object are:

Improved video display performance because of using hardware acceleration.

Decreased CPU usage.

Flexibility and creativity for development of content, such as video controls,
that appears in front of the StageVideo object.

Because the device's hardware displays the video, a StageVideo object is subject to the following constraints
compared to a Video object:

For each SWF file, Flash Player limits the number of StageVideo objects that can concurrently display
videos to four. However, the actual limit can be lower, depending on device hardware resources.
On AIR for TV devices, only one StageVideo object at a time can display a video.

The video timing is not synchronized with the timing of Flash content that the runtime displays.

The video display area can only be a rectangle. You cannot use more advanced display areas, such as
elliptical or irregular shapes.

You cannot rotate the video.

You cannot bitmap cache the video or use BitmapData to access it.

You cannot apply filters to the video.

You cannot apply color transforms to the video.

You cannot apply an alpha value to the video.

Blend modes that you apply to display objects that are in front of the video do not apply to the video.

You can place the video only on full pixel boundaries.

Though the rendering is the best available for the given device hardware, it is not 100% "pixel identical" across devices.
Slight variations occur due to driver and platform differences.

A few devices do not support all required color spaces. For example, some devices do not support BT.709, the H.264 standard. In such
cases you can use BT.601 for fast display.

You cannot use stage video with WMODE settings such as normal, opaque, or transparent.
Stage video supports only WMODE=direct when not in full screen mode. WMODE has no effect in Safari 4 or higher, IE 9 or higher,
or in AIR for TV.

When using StageVideo in an AIR for Android application, set the colorDepth to 32bit in the application descriptor.
Using StageVideo with a 16-bit color depth is not supported.

On Android, StageVideo is only supported on devices running Android 3 (Honeycomb) and higher. To enable your app
to run on the widest possible selection of Android devices, always provide logic to display video
using the Video object when StageVideo is not available.

The following steps summarize how to use a StageVideo object to play a video:

Listen for the StageVideoAvailabilityEvent.STAGE_VIDEO_AVAILABILITY event to find out when the
Stage.stageVideos vector has changed. (Not supported for AIR 2.5 for TV.)

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.
In AIR 2.5 for TV, access Stage.stageVideos after the first SWF frame has rendered.
Note You cannot create a StageVideo object.

Attach a NetStream object using StageVideo.attachNetStream().

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.

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. (Not supported for AIR 2.5 for TV.)

If a StageVideoEvent.RENDER_STATE event indicates that the video cannot be played,
you can revert to using a Video object instead of a StageVideo object. This event is
dispatched after the video has been attached to a NetStream object and is playing. Also, depending on the platform,
any change in the playing status can result in dispatching the event.
Handle the StageVideoEvent.RENDER_STATE event to ensure that the application plays the video
or gracefully does not play the video.

If a running video goes into full screen mode from a WMODE that does not support stage video, stage video can become available.
Likewise, if the user exits full screen mode, stage video can become unavailable. In these cases, the Stage.stageVideos vector changes.
To receive notification of this change, listen to the StageVideoAvailabilityEvent.STAGE_VIDEO_AVAILABITY event. NOTE: This notification
is not available in AIR 2.5 for TV.

colorSpaces

Returns the names of available color spaces for this video surface.
Usually this list includes "BT.601" and "BT.709". On some configurations, only
"BT.601" is supported which means a video is possibly not rendered in the
correct color space.

Note: On AIR for TV devices, a value of "BT.601" indicates software playback,
and a value of "BT.709" indicates hardware playback.

depth

The depth level of a StageVideo object relative to other StageVideo objects.

StageVideo objects always display behind other objects on the stage. If a platform supports more than one
StageVideo object, the depth property indicates a StageVideo object's depth level.
The bottom StageVideo object's depth property has the smallest value.
If multiple StageVideo objects have the same depth setting, the order they appear in the
stage,stageVideos Vector determines their relative depth.

Note: AIR for TV devices support only one StageVideo object. Therefore, this property is not
applicable for those devices.

Implementation public function get depth():int public function set depth(value:int):void

pan

The pan setting for displaying the video, specified as a Point object.

By default, the value of pan is (0,0).
This default value centers the video in the rectangle specified by StageVideo.viewPort.

The pan value is significant only when the zoom property value is not the
default value (1.0, 1.0). When a video displays in the StageVideo.viewPort rectangle
with the default zoom value, the platform sizes the video to fit exactly into the rectangle. Therefore, the entire
video is visible. However, if a zoom factor is specified, the entire video is not visible. In this case, you can
set the pan value to specify which subrectangle of the video to show
in the StageVideo.viewPort rectangle.

The valid values of the pan property range from (-1.0, -1.0) to (1.0, 1.0).
Specifically:

A pan value of (-1.0, -1.0) places the upper-left pixel of the video at the upper-left
position of the StageVideo.viewPort rectangle.

A pan value of (1.0, 1.0) places the lower-right pixel of the video at the lower-right
position of the StageVideo.viewPort rectangle.

A pan value of (1.0, -1.0) places the upper-right pixel of the video at the upper-right
position of the StageVideo.viewPort rectangle.

A pan value of (-1.0, 1.0) places the lower-left pixel of the video at the lower-left
position of the StageVideo.viewPort rectangle.

Values between -1.0 and 1.0 pan according to scale.

If you set the pan property to a value outside the valid range,
a RangeError exception is thrown.
The runtime resets the value to the last valid value.

Also, consider that to use a StageVideo object, you assign an element
of the Stage.stageVideos Vector object to a StageVideo variable. When you set
the pan property of the StageVideo variable, the underlying Stage.stageVideos Vector
element also changes. If you later assign that element to another StageVideo variable to play
another video, reset the pan property.

Implementation public function get pan():Point public function set pan(value:Point):void

viewPort

The position of the video is relative to the upper left corner of the stage.

The valid range of the x and y properties of the viewPort
Rectangle object are -8192 to 8191. Therefore, you can position the video
completely or partially off the stage. You can also make the video larger than the stage if you
make the width and height properties of the viewPort
property larger than the stage.

zoom

The zoom point is a scale factor. By default, the value of zoom is (1.0, 1.0).
This default value displays the entire video in the StageVideo.viewPort rectangle.

The valid values of the zoom property range from (1.0, 1.0) to (8.0, 8.0).
The x property of the zoom Point object specifies the zoom value for the horizontal pixels, and
the y property specifies the zoom value for the vertical pixels.

For example, a zoom value of (2.0, 2.0) displays only half the horizontal pixels
and half the vertical pixels in the StageVideo.viewPort rectangle. That is, the video still fills the
StageVideo.viewPort rectangle, but only half the video is visible, creating a 2x zoom effect.
Similarly, a zoom value of (8.0, 8.0) displays only 1/8 of the horizontal pixels
and 1/8 of the vertical pixels in the StageVideo.viewPort rectangle,
zooming in the maximum amount of 8x.

When you set the zoom property, set the pan property so that the StageVideo.viewPort rectangle
shows the appropriate subrectangle of the video.

Consider the following situation where it is useful to set a different value for the
x and y properties of the zoom Point object.
First, note that when a video displays in the StageVideo.viewPort rectangle
with the default zoom value, the platform sizes the video to fit exactly into the rectangle.
If the video's rectangle does not scale evenly to the StageVideo.viewPort rectangle,
the video display can be distorted.
That is, the aspect ratios of the video and the StageVideo.viewPort are not equal.
This case can occur, for example, if the video has a different width than height, but the StageVideo.viewPort
property specifies a square.
To resolve the distortion, set different values for the
x and y properties of the zoom Point object.
Then set the pan property to make sure the StageVideo.viewPort rectangle
shows the appropriate subrectangle of the video.

If you set the zoom property to a value outside the valid range,
a RangeError exception is thrown.
The runtime resets the value to the last valid value.

Also, consider that to use a StageVideo object, you assign an element
of the Stage.stageVideos Vector object to a StageVideo variable. When you set
the zoom property of the StageVideo variable, the underlying Stage.stageVideos Vector
element also changes. If you later assign that element to another StageVideo variable to play
another video, reset the zoom property.

Implementation public function get zoom():Point public function set zoom(value:Point):void

attachNetStream

Specifies a video stream to be displayed within the boundaries of the StageVideo object in the application.
The video stream is either a video file played with NetStream.play(), or null.
A video file can be stored on the local file
system or on Flash Media Server. If the value of the netStream argument is null,
the video is no longer played in the StageVideo object.

Before calling attachNetStream() a second time,
call the currently attached NetStream object's close() method.
Calling close()
releases all the resources, including hardware decoders, involved with playing the video.
Then you can call attachNetStream()
with either another NetStream object or null.

You do not need to use this method if a video file contains only audio; the audio
portion of a video file is played automatically
when you call NetStream.play(). To control the audio
associated with a video file, use the soundTransform property
of the NetStream object that plays the video file.

Parameters

netStream:NetStream — A NetStream object. To drop the connection to the StageVideo object, pass
null.