| 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 |
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, ortransparent. Stage video supports onlyWMODE=directwhen 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
colorDepthto 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). 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.stageVideosVector object within the event handler to access a StageVideo object. In AIR 2.5 for TV, accessStage.stageVideosafter 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_STATEevent 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_STATEevent 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
Related API Elements
flash.events.StageVideoAvailabilityEvent
flash.events.VideoEvent
flash.display.Stage.stageVideos
flash.media.Video
flash.net.NetStream
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 | ||
| 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 | |
Specifies a video stream to be displayed within the boundaries of the StageVideo object in the application. | StageVideo | ||
|
Dispatches an event into the event flow. | EventDispatcher | |
|
Checks whether the EventDispatcher object has any listeners registered for a specific type
of event. | EventDispatcher | |
|
Indicates whether an object has a specified property defined. | Object | |
|
Indicates whether an instance of the Object class is in the prototype chain of the object specified
as the parameter. | Object | |
|
Indicates whether the specified property exists and is enumerable. | Object | |
|
Removes a listener from the EventDispatcher object. | EventDispatcher | |
|
Sets the availability of a dynamic property for loop operations. | Object | |
|
Returns the string representation of this object, formatted according to locale-specific conventions. | Object | |
|
Returns the string representation of the specified object. | Object | |
|
Returns the primitive value of the specified object. | Object | |
|
Checks whether an event listener is registered with this EventDispatcher object or any of
its ancestors for the specified event type. | EventDispatcher | |
| Event | Summary | Defined By | ||
|---|---|---|---|---|
| [broadcast event] Dispatched when the Flash Player or AIR application gains operating system focus and becomes active. | EventDispatcher | ||
| [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 | |||
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.
Implementation
public function get depth():int public function set depth(value:int):voidRelated API Elements
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
panvalue of(-1.0, -1.0)places the upper-left pixel of the video at the upper-left position of theStageVideo.viewPortrectangle. -
A
panvalue of(1.0, 1.0)places the lower-right pixel of the video at the lower-right position of theStageVideo.viewPortrectangle. -
A
panvalue of(1.0, -1.0)places the upper-right pixel of the video at the upper-right position of theStageVideo.viewPortrectangle. -
A
panvalue of(-1.0, 1.0)places the lower-left pixel of the video at the lower-left position of theStageVideo.viewPortrectangle.
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):voidThrows
RangeError — The Point value is not valid.
|
Related API Elements
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.
Implementation
public function get videoHeight():intvideoWidth | 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.
Implementation
public function get videoWidth():intviewPort | 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):voidThrows
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 (16.0, 16.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 (16.0, 16.0) displays only 1/16 of the horizontal pixels
and 1/16 of the vertical pixels in the StageVideo.viewPort rectangle,
zooming in the maximum amount of 16x.
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):voidThrows
RangeError — The Point value is not valid.
|
Related API Elements
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.
|
renderState | Event |
flash.events.StageVideoEventproperty 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.
TheStageVideoEvent.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. |
Mon Nov 28 2011, 06:48 AM -08:00