Packageflash.media
Classpublic class StageVideo
InheritanceStageVideo Inheritance EventDispatcher Inheritance 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:

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

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

  1. 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.)
  2. 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.
  3. Attach a NetStream object using StageVideo.attachNetStream().
  4. Play the video using NetStream.play().
  5. 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.
  6. 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.

See also

flash.events.StageVideoEvent
flash.events.StageVideoAvailabilityEvent
flash.events.VideoEvent
flash.display.Stage.stageVideos
flash.media.Video
flash.net.NetStream
Using the StageVideo class for hardware-accelerated rendering


Public Properties
 PropertyDefined by
  colorSpaces : Vector.<String>
[read-only] Returns the names of available color spaces for this video surface.
StageVideo
 Inheritedconstructor : 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
 Inheritedprototype : 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
Public Methods
 MethodDefined by
 Inherited
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
  
Specifies a video stream to be displayed within the boundaries of the StageVideo object in the application.
StageVideo
 Inherited
Dispatches an event into the event flow.
EventDispatcher
 Inherited
Checks whether the EventDispatcher object has any listeners registered for a specific type of event.
EventDispatcher
 Inherited
Indicates whether an object has a specified property defined.
Object
 Inherited
Indicates whether an instance of the Object class is in the prototype chain of the object specified as the parameter.
Object
 Inherited
Indicates whether the specified property exists and is enumerable.
Object
 Inherited
removeEventListener(type:String, listener:Function, useCapture:Boolean = false):void
Removes a listener from the EventDispatcher object.
EventDispatcher
 Inherited
Sets the availability of a dynamic property for loop operations.
Object
 Inherited
Returns the string representation of this object, formatted according to locale-specific conventions.
Object
 Inherited
Returns the string representation of the specified object.
Object
 Inherited
Returns the primitive value of the specified object.
Object
 Inherited
Checks whether an event listener is registered with this EventDispatcher object or any of its ancestors for the specified event type.
EventDispatcher
Events
 EventSummaryDefined by
 Inherited [broadcast event] Dispatched when the Flash Player or AIR application gains operating system focus and becomes active.EventDispatcher
 Inherited [broadcast event] Dispatched when the Flash Player or AIR application operating loses system focus and is becoming inactive.EventDispatcher
   Dispatched by the StageVideo object when the render state of the StageVideo object changes.StageVideo
Property detail
colorSpacesproperty
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>
depthproperty 
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

panproperty 
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:

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

videoHeightproperty 
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
videoWidthproperty 
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
viewPortproperty 
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.
zoomproperty 
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.

See also

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
renderStateevent 
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:

PropertyValue
bubblesfalse
cancelablefalse; there is no default behavior to cancel.
colorSpaceThe available color spaces for displaying the video.
currentTargetThe object that is actively processing the StageVideoEvent object with an event listener.
statusIndicates whether the video is being rendered (decoded and displayed) by hardware or software, or not at all.
targetThe StageVideo object that changed state.