flash.media

# StageVideo - AS3

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

Language Version: | ActionScript 3.0

Runtime Versions: | AIR 2.5, Flash Player 10.2

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:

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.

Learn more

Basics of video
Understanding video formats
Flash Player and AIR compatibility with encoded video files
Understanding the Adobe F4V and FLV video file formats
Advanced topics for video files
Video example: Video Jukebox
Using the StageVideo class for hardware accelerated presentation
Using the StageVideo class for hardware-accelerated rendering

Related API Elements

flash.events.StageVideoEvent
flash.events.StageVideoAvailabilityEvent
flash.events.VideoEvent
flash.display.Stage.stageVideos
flash.media.Video
flash.net.NetStream

Public Properties
Hide Inherited Public Properties
Show Inherited Public Properties

| 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
|  | 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
Hide Inherited Public Methods
Show Inherited Public Methods

| 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

Events
Click for more information on events
Hide Inherited Events
Show Inherited Events

| Event | 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 Versions: | AIR 2.5, Flash Player 10.2

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`

Language Version: | ActionScript 3.0

Runtime Versions: | AIR 2.5, Flash Player 10.2

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`

Related API Elements

flash.display.Stage.stageVideos

### pan

property

`pan:Point`

Language Version: | ActionScript 3.0

Runtime Versions: | AIR 2.5, Flash Player 10.2

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.

Related API Elements

zoom

### videoHeight

property

`videoHeight:int` [read-only]

Language Version: | ActionScript 3.0

Runtime Versions: | AIR 2.5, Flash Player 10.2

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 Versions: | AIR 2.5, Flash Player 10.2

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`

Language Version: | ActionScript 3.0

Runtime Versions: | AIR 2.5, Flash Player 10.2

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`

Language Version: | ActionScript 3.0

Runtime Versions: | AIR 2.5, Flash Player 10.2

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.

Related API Elements

pan
Method Detail

### attachCamera

()
method

`public function attachCamera(theCamera:Camera):void`

Language Version: | ActionScript 3.0

Runtime Versions: | Flash Player 11.4, 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.

Related API Elements

flash.media.Video.attachCamera()
flash.media.Camera

### attachNetStream

()
method

`public function attachNetStream(netStream:NetStream):void`

Language Version: | ActionScript 3.0

Runtime Versions: | AIR 2.5, Flash Player 10.2

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`
property StageVideoEvent.type = `flash.events.StageVideoEvent.RENDER_STATE`

Language Version: | ActionScript 3.0

Runtime Versions: | AIR 2.5, Flash Player 10.2

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.

© 2015 Adobe Systems Incorporated. All rights reserved.
Mon Apr 10 2017, 12:28 PM -07:00