Spark VideoPlayer and VideoDisplay controls

The VideoPlayer control lets you play progressively downloaded or streaming video. It supports multi-bit rate streaming and live video when used with a server that supports these features, such as Flash Media Server 3.5 or later.

The VideoPlayer control contains a full UI to let users control playback of video. It contains a play/pause toggle button; a scrub bar to let users seek through video; a volume bar; a timer; and a button to toggle in and out of fullscreen mode.

Flex also offers the Spark VideoDisplay control, which plays video without any chrome, skin, or UI. The Spark VideoDisplay has the same methods and properties as the Spark VideoPlayer control. It is useful when you do not want the user to interact with the control, or when you want to fully customize the interactivity but not reskin the VideoPlayer control.

Both VideoPlayer and VideoDisplay support playback of FLV and F4V file formats, as well as MP4-based container formats.

About OSMF

The underlying implementation of the Spark VideoDisplay and VideoPlayer classes rely on the Open Source Media Framework (OSMF) classes.

You can use the OSMF classes to extend the VideoPlayer and VideoDisplay classes. For example, you can use OSMF to incorporate advertising, reporting, cue points, and DVR functionality.

You can also use OSMF classes to implement your own player. For an example of this, see OSMF + Flex Example.

For more information about OSMF, see Open Source Media Framework

Spark VideoPlayer events

The VideoPlayer control dispatches several different types of events that you can use to monitor and control playback. The event objects associated with each event dispatched by the VideoPlayer control is defined by a class in the org.osmf.events.* package.

The following example handles the complete and mediaPlayerStateChange events dispatched by the VideoPlayer control:
<?xml version="1.0" encoding="utf-8"?>
<!-- controls\videoplayer\VideoPlayerEvent.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:VerticalLayout/>
    </s:layout>
    
    <fx:Script>
        <![CDATA[
            import org.osmf.events.MediaPlayerStateChangeEvent;
            import org.osmf.events.TimeEvent;

            protected function vpCompleteHandler(event:TimeEvent):void {
                myTA.text = "Video complete - restarting."
            }

            protected function vpMediaPlayerStateChangeHandler(event:MediaPlayerStateChangeEvent):void {
                if (event.state == "loading")
                    myTA.text = "loading ...";
                if (event.state == "playing")
                    myTA.text = "playing ...";
            }

        ]]>
    </fx:Script>
    
    <s:VideoPlayer 
        source="rtmp://fmsexamples.adobe.com/vod/mp4:_cs4promo_1000.f4v"
        width="350" height="250"
        loop="true"
        complete="vpCompleteHandler(event);"
        mediaPlayerStateChange="vpMediaPlayerStateChangeHandler(event);"/>
    <s:TextArea id="myTA" width="350" height="25"/>
</s:Application>

The executing SWF file for the previous example is shown below:

The VideoPlayer control dispatches the complete event when the video completes. The event object for the complete event is of type org.osmf.events.TimeEvent.

The VideoPlayer control dispatches the mediaPlayerStateChange event when the state of the control changes. The control has several states, including the buffering, loading, playing, and ready states. The event object for the mediaPlayerStateChange event is of org.osmf.events.MediaPlayerStateChangeEvent. The event handler for the mediaPlayerStateChange event uses the state property of the event object to determine the new state of the control.

Setting the video source for the Spark VideoPlayer control

The VideoPlayer component supports playback of local media, streaming media, and progressively downloaded media. You can play back both live and recorded media.

To play back a single media file, use the source attribute. The correct value for the source attribute is the path to the file. Use the correct syntax in the URL: HTTP for progressive download and RTMP for streaming from Flash Media Server. If using Flash Media Server, use the correct prefixes or extensions.

The following code plays a local FLV file, phone.flv, that resides in the assets folder in the same project folder as the SWF file:

<s:VideoPlayer source="assets/phone.flv"/>

The following code plays a single F4V file from Flash Media Server, using the video-on-demand service that Flash Media Server 3.5 and later provides. The use of the MP4 prefix and the F4V file extension are required. The MP4 prefix is always required; the F4V file extension is required when the name of the file to be loaded contains a file extension.

<?xml version="1.0" encoding="utf-8"?>
<!-- controls\videoplayer\VideoPlayerSimple.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:VideoPlayer 
        source="rtmp://fmsexamples.adobe.com/vod/mp4:_cs4promo_1000.f4v"
        width="350" height="250"
        loop="true"/>
</s:Application>

The executing SWF file for the previous example is shown below:

Using dynamic streaming

The Spark VideoPlayer and VideoDisplay components support dynamic streaming (also known as multi-bitrate streaming or adaptive streaming) for on-demand and live content. To use dynamic streaming, you encode a stream at several different bit rates. During playback, Flash Player dynamically switches among the streams based on connection quality and other metrics to provide the best experience.

You can do dynamic streaming over RTMP and HTTP. On-demand and live dynamic streaming over RTMP require Flash Media Server. RTMP streaming has the following benefits over HTTP streaming:
  • RTMPe for lightweight content protection

  • RTMP quality of service

  • Absolute timecodes

  • Enhanced buffering

Live HTTP Dynamic Streaming requires Flash Media Server. On-demand HTTP Dynamic Streaming requires an Apache HTTP Server Origin Module and a File Packager tool. These tools are available as free downloads from http://www.adobe.com/products/httpdynamicstreaming/.

Dynamic streaming over HTTP

To use live and on-demand dynamic streaming over HTTP, point the source property of the VideoDisplay or VideoPlayer class to an *.f4m file:
<s:VideoPlayer source="http://mysite.com/dynamic_Streaming.f4m" autoPlay="false"/>

HTTP Dynamic Streaming is not designed to be used with the DynamicStreamingVideoSource or the DynamicStreamingVideoItem classes. Use those classes to stream media over RTMP with Flash Media Server.

Before your can dynamically stream your video content over HTTP, use the File Packager to package the file. The File Packager converts the media file to fragments and creates an F4M manifest file to point to the pieces of the package. You must also install the Apache HTTP Origin Module on your web server to serve the streams.

For more information about HTTP Dynamic Streaming, see Adobe HTTP Dynamic Streaming.

Dynamic streaming over RTMP

Flash Media Server 3.5 and later supports live and on-demand dynamic streaming over RTMP. To perform dynamic streaming with Flash Media Server, use the DynamicStreamingVideoSource class.

The DynamicStreamingVideoSource object contains multiple stream items, each of which represents the same video stream encoded at a different bitrate.

The following example uses the DynamicStreamingVideoSource object to define streams of different qualities:

<?xml version="1.0" encoding="utf-8"?>
<!-- controls\VideoPlayer\VideoPlayerFMS.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:VerticalLayout/>
    </s:layout>
    
    <s:VideoPlayer id="myPlayer"
        width="500" height="300">
        <s:source>
            <s:DynamicStreamingVideoSource id="mySVS"
                host="rtmp://fmsexamples.adobe.com/vod/">
                <s:DynamicStreamingVideoItem id="dreamgirl150"
                    streamName="MP4:_PS_dreamgirl_150.f4v"
                    bitrate="150" />
                <s:DynamicStreamingVideoItem id="dreamgirl500"
                    streamName="MP4:_PS_dreamgirl_500.f4v"
                    bitrate="500" />
                <s:DynamicStreamingVideoItem id="dreamgirl1000"
                    streamName="MP4:_PS_dreamgirl_1000.f4v"
                    bitrate="1000" />
            </s:DynamicStreamingVideoSource>
        </s:source>
    </s:VideoPlayer>

    <s:TextArea width="500" height="50"
        text="Please wait while the video loads..."/>
</s:Application>

The executing SWF file for the previous example is shown below:

Playing back live video with the Spark VideoPlayer control

To play back live video, use a DynamicStreamingVideoSource object and set the streamType attribute to live:

<s:VideoPlayer> 
    <s:DynamicStreamingVideoSource host="rtmp://localhost/live/" streamType="live"> 
        <s:DynamicStreamingVideoItem streamName="myStream.flv"/> 
    </s:DynamicStreamingVideoSource> 
</s:VideoPlayer>

The VideoPlayer is the client application that plays back video. To capture and stream the live video, you can use a tool like Flash Media Live Encoder, which captures and streams live video to Flash Media Server. If you don’t use Flash Media Live Encoder, you’ll need to create a custom publishing application. For information on creating a custom video capture application, see the Flash Media Server documentation.

Setting the size of the Spark VideoPlayer control

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

  • scaleMode

  • height

  • width

The scaleMode property only works when you set the height or width property. It adjusts the size of the playing media after the control size has been set. Possible values are none, stretch, letterbox, and zoom.

If you omit both width and height properties for the control, Flex sizes the control to fit the size of the playing media. If you specify only one property, and set the scaleMode property, the size of the playing media determines the value of the other property. If you do not set the scaleMode property, the media retains its aspect ratio when resizing.

If you explicitly set the width and height properties, be sure the values are appropriate for the size of video that plays.

By default, Flex sizes the VideoPlayer 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.

The sample video used here is larger than the specified component size, but the width and height ratio are still appropriate to the video size. If you were to remove the width and height properties from the code, however, you would see that the VideoPlayer component is automatically sized to the size of the video.

Using the Spark VideoDisplay control

The Spark VideoDisplay control is the same as the Spark VideoPlayer control, except that it does not have a UI associated with it. You must manually create controls that perform functions such as play, stop, and pause.

The following example uses a Spark VideoDisplay control, and exposes the play() and pause() methods with Button controls:
<?xml version="1.0"?>
<!-- controls\videodisplay\SparkVideoDisplayStopPlay.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();">
    <s:VGroup>
        <s:VideoDisplay id="myVid" 
            source="../assets/MyVideo.flv"
            height="250" 
            width="250"
        />
        <s:HGroup>
            <s:Button label="||" click="myVid.pause();"/>
            <s:Button label="&gt;" click="myVid.play();"/>         
        </s:HGroup>
    </s:VGroup>
</s:Application>

The executing SWF file for the previous example is shown below: