flash.media.StageVideo (ActionScript 3.0)

Package	flash.media
Class	public class StageVideo
Inheritance	StageVideo EventDispatcher Object

Language version:

ActionScript 3.0

Runtime version:

AIR 2.5

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.

	Property	Defined by
		colorSpaces : Vector.<String> [read-only] Returns the names of available color spaces for this video surface.	StageVideo
		constructor : Object A reference to the class object or constructor function for a given object instance.	Object
		depth : int The depth level of a StageVideo object relative to other StageVideo objects.	StageVideo
		pan : Point The pan setting for displaying the video, specified as a Point object.	StageVideo
		prototype : Object [static] A reference to the prototype object of a class or function object.	Object
		videoHeight : int [read-only] An integer specifying the height of the video stream, in pixels.	StageVideo
		videoWidth : int [read-only] An integer specifying the width of the video stream, in pixels.	StageVideo
		viewPort : Rectangle The absolute position and size of the video surface in pixels.	StageVideo
		zoom : Point The zoom setting of the video, specified as a Point object.	StageVideo

	Method	Defined by
		addEventListener(type:String, listener:Function, useCapture:Boolean = false, priority:int = 0, useWeakReference:Boolean = false):void Registers an event listener object with an EventDispatcher object so that the listener receives notification of an event.	EventDispatcher
		attachCamera(theCamera:Camera):void Specifies a video stream from a camera to be displayed within the boundaries of the StageVideo object in the application, leveraging the GPU for rendering.	StageVideo
		attachNetStream(netStream:NetStream):void Specifies a video stream to be displayed within the boundaries of the StageVideo object in the application.	StageVideo
		dispatchEvent(event:Event):Boolean Dispatches an event into the event flow.	EventDispatcher
		hasEventListener(type:String):Boolean Checks whether the EventDispatcher object has any listeners registered for a specific type of event.	EventDispatcher
		hasOwnProperty(name:String):Boolean Indicates whether an object has a specified property defined.	Object
		isPrototypeOf(theClass:Object):Boolean Indicates whether an instance of the Object class is in the prototype chain of the object specified as the parameter.	Object
		propertyIsEnumerable(name:String):Boolean Indicates whether the specified property exists and is enumerable.	Object
		removeEventListener(type:String, listener:Function, useCapture:Boolean = false):void Removes a listener from the EventDispatcher object.	EventDispatcher
		setPropertyIsEnumerable(name:String, isEnum:Boolean = true):void Sets the availability of a dynamic property for loop operations.	Object
		toLocaleString():String Returns the string representation of this object, formatted according to locale-specific conventions.	Object
		toString():String Returns the string representation of the specified object.	Object
		valueOf():Object Returns the primitive value of the specified object.	Object
		willTrigger(type:String):Boolean Checks whether an event listener is registered with this EventDispatcher object or any of its ancestors for the specified event type.	EventDispatcher

Summary	Defined by
activate	[broadcast event] Dispatched when the Flash Player or AIR application gains operating system focus and becomes active.	EventDispatcher
deactivate	[broadcast event] Dispatched when the Flash Player or AIR application operating loses system focus and is becoming inactive.	EventDispatcher
renderState	Dispatched by the StageVideo object when the render state of the StageVideo object changes.	StageVideo

Property detail

colorSpaces

property

colorSpaces:Vector.<String> [read-only]

Language version:

ActionScript 3.0

Runtime version:

AIR 2.5

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.

Implementation
public function get colorSpaces():Vector.<String>

depth

property

depth:int [read-write]

Language version:

ActionScript 3.0

Runtime version:

AIR 2.5

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

See also

flash.display.Stage.stageVideos

pan

property

pan:Point [read-write]

Language version:

ActionScript 3.0

Runtime version:

AIR 2.5

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

Throws

RangeError — The Point value is not valid.

See also

zoom

videoHeight

property

videoHeight:int [read-only]

Language version:

ActionScript 3.0

Runtime version:

AIR 2.5

An integer specifying the height of the video stream, in pixels.

You may want to use this property, for example, to ensure that the user is seeing the video at the same height at which it was captured, regardless of the size of the StageVideo.viewPort rectangle.

The NetStream.Video.DimensionChange event is dispatched in the case of recorded videos when this value changes.

Implementation
public function get videoHeight():int

videoWidth

property

videoWidth:int [read-only]

Language version:

ActionScript 3.0

Runtime version:

AIR 2.5

An integer specifying the width of the video stream, in pixels.

You may want to use this property, for example, to ensure that the user is seeing the video at the same width at which it was captured, regardless of the size of the StageVideo.viewPort rectangle.

The NetStream.Video.DimensionChange event is dispatched in the case of recorded videos when this value changes.

Implementation
public function get videoWidth():int

viewPort

property

viewPort:Rectangle [read-write]

Language version:

ActionScript 3.0

Runtime version:

AIR 2.5

The absolute position and size of the video surface in pixels.

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.

Implementation
public function get viewPort():Rectangle
public function set viewPort(value:Rectangle):void

Throws

RangeError — The Rectangle value is not valid.

zoom

property

zoom:Point [read-write]

Language version:

ActionScript 3.0

Runtime version:

AIR 2.5

The zoom setting of the video, specified as a Point object.

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

Throws

RangeError — The Point value is not valid.

See also

pan

Method detail

attachCamera

()

method

public function attachCamera(theCamera:Camera):void

Language version:

ActionScript 3.0

Runtime version:

AIR 3.4

Specifies a video stream from a camera to be displayed within the boundaries of the StageVideo object in the application, leveraging the GPU for rendering.

Note: StageVideo for camera is not supported on Android.

Use this method to attach live video captured by the user to the StageVideo object. To drop the connection to the StageVideo object, pass null.

Parameters

theCamera:Camera — A Camera object that is capturing video data.

attachNetStream

()

method

public function attachNetStream(netStream:NetStream):void

Language version:

ActionScript 3.0

Runtime version:

AIR 2.5

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.

Event detail

renderState

event

Event object type: flash.events.StageVideoEvent
StageVideoEvent.type property = flash.events.StageVideoEvent.RENDER_STATE

Language version:

ActionScript 3.0

Runtime version:

AIR 2.5

Dispatched by the StageVideo object when the render state of the StageVideo object changes.

The StageVideoEvent.RENDER_STATE constant defines the value of the type property of a renderState event object.

This event has the following properties:

Property	Value
`bubbles`	`false`
`cancelable`	`false`; there is no default behavior to cancel.
`colorSpace`	The available color spaces for displaying the video.
`currentTarget`	The object that is actively processing the StageVideoEvent object with an event listener.
`status`	Indicates whether the video is being rendered (decoded and displayed) by hardware or software, or not at all.
`target`	The StageVideo object that changed state.

Submit Feedback

ActionScript 3.0 Language Reference	All Packages \| All Classes \| Language Elements \| Index \| Appendices \| Conventions \| Frames No Frames
Class StageVideo	Properties \| Methods \| Events