MX VideoDisplay control

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:

• Showing a video message from the CEO of your company

• Streaming movies or movie previews

• Streaming songs or song snippets

• Providing learning material in the form of media

The 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.

Flex creates an MX 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 to the MX VideoDisplay control.

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.

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

• maintainAspectRatio

• height

• width

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.

The following example creates a VideoDisplay control:

<?xml version="1.0"?>
<!-- controls\videodisplay\VideoDisplaySimple.mxml -->
<s:Application xmlns:fx="http://ns.adobe.com/mxml/2009"
    xmlns:s="library://ns.adobe.com/flex/spark" 
    xmlns:mx="library://ns.adobe.com/flex/mx">

    <mx:VBox>
        <mx:VideoDisplay 
            source="../assets/MyVideo.flv"
            height="250" 
            width="250"
        />
    </mx:VBox>
</s:Application>
The executing SWF file for the previous example is shown below:

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.

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 -->
<s:Application xmlns:fx="http://ns.adobe.com/mxml/2009"
    xmlns:s="library://ns.adobe.com/flex/spark" 
    xmlns:mx="library://ns.adobe.com/flex/mx" 
    creationComplete="myVid.pause();">
    <mx:VBox>
        <mx:VideoDisplay id="myVid" 
            source="../assets/MyVideo.flv"
            height="250" 
            width="250"
        />
        <mx:HBox>
            <mx:Button label="||" click="myVid.pause();"/>
            <mx:Button label="&gt;" click="myVid.play();"/>         
        </mx:HBox>
    </mx:VBox>
</s:Application>
The executing SWF file for the previous example is shown below:

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 -->
<s:Application xmlns:fx="http://ns.adobe.com/mxml/2009"
    xmlns:s="library://ns.adobe.com/flex/spark" 
    xmlns:mx="library://ns.adobe.com/flex/mx"
    height="450"
    creationComplete="myVid.pause();">
    <s:layout>
        <s:VerticalLayout/>
    </s:layout>
    <fx:Script>
        <![CDATA[
            import mx.events.CuePointEvent;
            import mx.controls.videoClasses.CuePointManager;

            private function cpHandler(event:CuePointEvent):void {
                cp.text+="Got to " + event.cuePointName + " cuepoint @ " + 
                    String(event.cuePointTime) + " seconds in.\n";
            }
        ]]>
    </fx:Script>

    <mx:VBox>
        <mx:VideoDisplay id="myVid"          
            source="../assets/MyVideo.flv"
            cuePointManagerClass="mx.controls.videoClasses.CuePointManager"
            cuePoint="cpHandler(event);"
            height="250" 
            width="250"
        >
            <mx:cuePoints>
                <fx:Object name="first" time="5"/>
                <fx:Object name="second" time="10"/>
            </mx:cuePoints>
        </mx:VideoDisplay>
        <mx:Label text="{myVid.playheadTime}"/>
        <mx:TextArea id="cp" height="100" width="250"/>
    </mx:VBox>
    <mx:HBox>
        <mx:Button label="||" click="myVid.pause();"/>
        <mx:Button label="&gt;" click="myVid.play();"/>         
    </mx:HBox>
</s:Application>
The executing SWF file for the previous example is shown below:

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.

<?xml version="1.0"?>
<!-- controls\videodisplay\VideoDisplayCPManager.mxml -->
<s:Application xmlns:fx="http://ns.adobe.com/mxml/2009"
    xmlns:s="library://ns.adobe.com/flex/spark" 
    xmlns:mx="library://ns.adobe.com/flex/mx" 
    height="450"
    creationComplete="myVid.pause();">
    <s:layout>
        <s:VerticalLayout/>
    </s:layout>
    
    <fx:Script>
        <![CDATA[
            import mx.events.CuePointEvent;

            [Bindable]
            private var myCuePoints:Array = [
                { name: "first", time: 5},
                { name: "second", time: 10} 
            ];           
            
            // 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 += "Got to " + event.cuePointName + " cuepoint @ " + 
                    String(event.cuePointTime) + " seconds in.\n";

                // Remove cue point.
                currentCP.name=event.cuePointName;
                currentCP.time=event.cuePointTime;
                myVid.cuePointManager.removeCuePoint(currentCP);

                // Display the number of remaining cue points. 
                cp.text += "# cue points remaining: " + 
                    String(myVid.cuePointManager.getCuePoints().length) + ".\n"; 
            }
        ]]>
    </fx:Script>

    <mx:VBox>
        <mx:VideoDisplay id="myVid" 
            cuePointManagerClass="mx.controls.videoClasses.CuePointManager"
            source="../assets/MyVideo.flv"
            cuePoint="cpHandler(event);"
            height="250" 
            width="250"
        />
        <mx:Label text="{myVid.playheadTime}"/>
        <mx:TextArea id="cp" height="100" width="250"/>
    </mx:VBox>
    <mx:HBox>
        <mx:Button label="&gt;" click="cp.text='';initCP();myVid.play();"/>         
    </mx:HBox>
</s:Application>
The executing SWF file for the previous example is shown below:

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 -->
<s:Application xmlns:fx="http://ns.adobe.com/mxml/2009"
    xmlns:s="library://ns.adobe.com/flex/spark" 
    xmlns:mx="library://ns.adobe.com/flex/mx">


    <fx: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)
            }
        ]]>
    </fx:Script>
  
    <mx:VideoDisplay id="myVid" 
        width="320" height="240" 
        creationComplete="initCamera();"/>
</s:Application>
The executing SWF file for the previous example is shown below:

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.

You can use the VideoDisplay control to play a media stream from Adobe® Flash® Media Server, without needing to register the Flex application with the server. The following code shows a simple example that uses the video-on-demand (vod) service that is available in Flash Media Server 3.5 and later:

<?xml version="1.0"?>
<!-- controls\videodisplay\VideoDisplayFMS.mxml -->
<s:Application xmlns:fx="http://ns.adobe.com/mxml/2009"
    xmlns:s="library://ns.adobe.com/flex/spark" 
    xmlns:mx="library://ns.adobe.com/flex/mx">

    <s:layout>
        <s:HorizontalLayout/>
    </s:layout>
    

    <s:Label text="RTMP FMS 3.5"/>
    <mx:VideoDisplay 
            source="rtmp://fmsexamples.adobe.com/vod/edge_codeJam.flv"/>

</s:Application>
The executing SWF file for the previous example is shown below: