VideoDisplay control -- Flex 2.01

Flex supports the VideoDisplay control to incorporate streaming media into Flex applications. Flex supports the Flash Video File (FLV) file format with this control. This section describes how to use the VideoDisplay control in your application.

Subtopics

Using media in Flex

Media, such as movie and audio clips, are used more and more to provide information to web users. As a result, you need to provide users with a way to stream the media, and then control it. The following examples are usage scenarios for media controls:

The Flex streaming VideoDisplay control makes it easy to incorporate streaming media into Flash presentations. Flex supports the Flash Video File (FLV) file format with this control. You can use this control with video and audio data. When you use the VideoDisplay control by itself your application provides no mechanism for its users to control the media files.

About the VideoDisplay control

Flex creates a VideoDisplay control with no visible user interface. It is simply a control to hold and play media.

The playheadTime property of the control holds the current position of the playhead in the video file, measured in seconds. Most events dispatched by the control include the playhead position in the associated event object. One use of the playhead position is to dispatch an event when the video file reaches a specific position. For more information, see Adding a cue point.

The VideoDisplay control also supports the volume property. This property takes a value from 0.0 to 1.00; 0.0 is mute and 1.00 is the maximum volume. The default value is 0.75.

Setting the size of a media component

The appearance of any video media playing in a VideoDisplay control is affected by the following properties:

When you set maintainAspectRatio to true (the default), the control adjusts the size of the playing media after the control size has been set. The size of the media is set to maintain its aspect ratio.

If you omit both width and height properties for the control, Flex makes the control the size of the playing media. If you specify only one property, and the maintainAspectRatio property is false, the size of the playing media determines the value of the other property. If the maintainAspectRatio property is true, the media retains its aspect ratio when resizing.

<?xml version="1.0"?>
<!-- controls\videodisplay\VideoDisplaySimple.mxml -->
<mx:Application xmlns:mx="http://www.adobe.com/2006/mxml">
    <mx:VBox>
        <mx:VideoDisplay 
            source="http://localhost:8100/flex/assets/MyVideo.flv"
            height="400" 
            width="400"/>
    </mx:VBox>
</mx:Application>

By default, Flex sizes the VideoDisplay control to the size of the media. If you specify the width or height property of the control, and either is smaller than the media's dimensions, Flex does not change the size of the component. Instead, Flex sizes the media to fit within the component. If the control's playback area is smaller than the default size of the media, Flex shrinks the media to fit inside the control.

Using methods of the VideoDisplay control

You can use the following methods of the VideoDisplay control in your application: close(), load(), pause(), play(), and stop(). The following example uses the pause() and play() methods in event listener for two Button controls to pause or play an FLV file:

<?xml version="1.0"?>
<!-- controls\videodisplay\VideoDisplayStopPlay.mxml -->
<mx:Application xmlns:mx="http://www.adobe.com/2006/mxml">

    <mx:VBox>
        <mx:VideoDisplay id="myVid" 
            source="http://localhost:8100/flex/assets/MyVideo.flv"/>
        <mx:Button label="Pause" click="myVid.pause();"/>
        <mx:Button label="Play" click="myVid.play();"/>
    </mx:VBox>
</mx:Application>

Adding a cue point

You can use cue points to trigger events when the playback of your media reaches a specified location. To use cue points, you set the cuePointManagerClass property to mx.controls.videoClasses.CuePointManager to enable cue point management, and then pass an Array of cue points to the cuePoints property of the VideoDisplay control. Each element of the Array contains two fields. The name field contains an arbitrary name of the cue point. The time field contains the playhead location, in seconds, of the VideoDisplay control with which the cue point is associated.

When the playhead of the VideoDisplay control reaches a cue point, it dispatches a cuePoint event, as the following example shows:

<?xml version="1.0"?>
<!-- controls\videodisplay\VideoDisplayCP.mxml -->
<mx:Application xmlns:mx="http://www.adobe.com/2006/mxml">

    <mx:Script>
        <![CDATA[
            import mx.events.CuePointEvent;
            import mx.controls.videoClasses.CuePointManager;

            private function cpHandler(event:CuePointEvent):void {
                cp.text="got to cuepoint: " + event.cuePointName + " " + 
                    String(event.cuePointTime);
            }
        ]]>
    </mx:Script>

    <mx:VBox>
        <mx:VideoDisplay 
            source="http://localhost:8100/flex/assets/MyVideo.flv"
            cuePointManagerClass="mx.controls.videoClasses.CuePointManager"
            cuePoint="cpHandler(event);">
            <mx:cuePoints>
                <mx:Object name="first" time="10"/>
                <mx:Object name="second" time="20"/>
            </mx:cuePoints>
        </mx:VideoDisplay>
        <mx:TextArea id="cp"/>
    </mx:VBox>
</mx:Application>

In this example, the event listener writes a String to the TextArea control when the control reaches a cue point. The String contains the name and time of the cue point.

Adding a cue point by using the CuePointManager class

You can set cue points for the VideoDisplay control by using the cuePointManager property. This property is of type CuePointManager, where the CuePointManager class defines methods that you use to programmatically manipulate cue points, as the following example shows:

<?xml version="1.0"?>
<!-- controls\videodisplay\VideoDisplayCPManager.mxml -->
<mx:Application xmlns:mx="http://www.adobe.com/2006/mxml">

    <mx:Script>
        <![CDATA[

            import mx.events.CuePointEvent;

            [Bindable]
            private var myCuePoints:Array = [
            { name: "first", time: 10},
            { name: "second", time: 20} ];           
            
            // Set cue points using methods of the CuePointManager class.
            private function initCP():void {
                myVid.cuePointManager.setCuePoints(myCuePoints);
            }

            private var currentCP:Object=new Object();

            private function cpHandler(event:CuePointEvent):void {
                cp.text="go to cuepoint: " + event.cuePointName + " " + 
                    String(event.cuePointTime);
                // Remove cue point.
                currentCP.name=event.cuePointName;
                currentCP.time=event.cuePointTime;
                myVid.cuePointManager.removeCuePoint(currentCP);
                // Display the number of remaining cue points. 
                cp.text=cp.text + "\n" + "Cue points remaining: " + 
                    String(myVid.cuePointManager.getCuePoints().length); 
            }
        ]]>
    </mx:Script>

    <mx:VBox>
        <mx:VideoDisplay id="myVid" 
            initialize="initCP();" 
            cuePointManagerClass="mx.controls.videoClasses.CuePointManager"
            source="http://localhost:8100/flex/assets/MyVideo.flv"
            cuePoint="cpHandler(event);"/>
        <mx:TextArea id="cp" width="200" />
    </mx:VBox>
</mx:Application>

Streaming video from a camera

You can use the VideoDisplay.attachCamera() method to configure the control to display a video stream from a camera, as the following example shows:

<?xml version="1.0"?>
<!-- controls\videodisplay\VideoDisplayCamera.mxml -->
<mx:Application xmlns:mx="http://www.adobe.com/2006/mxml">

    <mx:Script>
        <![CDATA[
    
            // Define a variable of type Camera.
            import flash.media.Camera;
            public var cam:Camera;

            public function initCamera():void {
                // Initialize the variable.
                cam = Camera.getCamera();
                myVid.attachCamera(cam)
            }
        ]]>
    </mx:Script>
  
    <mx:VideoDisplay id="myVid" 
        width="320" height="240" 
        creationComplete="initCamera();"/>
</mx:Application>

In this example, you create a Camera object in the event handler for the creationComplete event of the VideoDisplay control, then pass the Camera object as the argument to the attachCamera() method.

Using the VideoDisplay control with Flash Media Server 2

You can use the VideoDisplay control to import a media stream from Macromedia® Flash® Media Server 2 from Adobe, as the following example shows:

<?xml version="1.0"?>
<!-- controls\videodisplay\VideoDisplayFMS.mxml -->
<mx:Application xmlns:mx="http://www.adobe.com/2006/mxml">

    <mx:HBox>
        <mx:Label text="RTMP FMS 2.0"/>
        <mx:VideoDisplay 
            autoBandWidthDetection="false" 
            source="rtmp://localhost/videodisplay/bike.flv"/>
    </mx:HBox>
</mx:Application>

In this example, you place the bike.flv file in the directory Flash Media Server 2\applications\videodisplay\streams\_definst_.

Notice that you explicitly set the autoBandWidthDetection property to false, its default value. When the autoBandWidthDetection property is true, you must create the server-side file main.asc in the directory Flash Media Server 2\applications\videodisplay\scripts, which implements the following functions:

application.onConnect = function(p_client, p_autoSenseBW) {}
application.calculateClientBw = function(p_client) {}
Client.prototype.getStreamLength = function(p_streamName) {}

application.onConnect = function(p_client, p_autoSenseBW) {
    //Add security code here.

    this.acceptConnection(p_client);

    if (p_autoSenseBW)
        this.calculateClientBw(p_client);
    else
        p_client.call("onBWDone");
}

Client.prototype.getStreamLength = function(p_streamName) {
    return Stream.length(p_streamName);
}

application.calculateClientBw = function(p_client) {
    // Add code to set the clients BandWidth.
    // Use p_client.getStats() which returns bytes_in 
    // and bytes_Out and check your bandWidth using 
    // p_client.call("onBWCheck", result, p_client.payload).
    p_client.call("onBWDone");
}

Specifying the AMF version for Flash Media Server

When you read from or write to a NetConnection, NetStream, or SharedObject object as binary data, the objectEncoding property of the object indicates which Action Message Format (AMF) version to use: the ActionScript 3.0 format or the ActionScript 1.0 or ActionScript 2.0 format. The possible value of the objectEncoding property include the following:

AMF0 Objects are serialized using the AMF format for ActionScript 1.0 and 2.0.

DEFAULT Objects are serialized using the default format for your version of Flash Player.

All versions of Flash Media Server use the AMF0 encoding. Therefore, Flex applications must set the objectEncoding property of all NetConnection and SharedObject objects used with Flash Media Server to AMF0. For NetStream, the objectEncoding property is read only. Any FAP connections or RTMP connections to your own server can use AMF3.