Accessibility

Flash Article

 

Using the FLVPlayback component with Flash Player 9 Update 3

Bob Berry

Adobe

James Wiley

Adobe

With the release of Adobe Flash Player 9 Update 3, Flash developers gain significant improvements for playing video content in Flash Player. This update includes changes to the FLVPlayback component that take advantage of the end user's system video hardware to provide better video playback performance. The changes to the FLVPlayback component also increase the fidelity of video files displayed in full-screen mode.

Additionally, Flash Player 9 Update 3 (9,0,115,0) improves the functionality of the FLVPlayback component by adding support for the high-definition MPEG-4 video formats that utilize industry standard H.264 encoding. These formats include MP4, M4A, MOV, MP4V, 3GP, and 3G2. Protected MP4 files—such as those downloaded from Apple iTunes or digitally encrypted by FairPlay—are not supported, however.

Note: The ActionScript 2.0 FLVPlayback component also supports MPEG-4 video formats that utilize H.264 encoding, beginning with Flash Player 9 Update 3.

Requirements

In order to make the most of this article, you need the following software:

Flash CS3 Professional

Note: For users of Flash CS3 Professional, an update including all debug and release versions of Flash Player 9 Update 3—and a new video playback component supporting H.264—is now available via Adobe Update Manager or directly from the Flash Support Center.

Flash Player 9 Update 3 (9,0,115,0) or later

Prerequisite knowledge

Prior experience working with video content in the Adobe Flash authoring interface is useful, but not required. Some knowledge of working with the FLVPlayback component is also helpful.

Working in full-screen mode with hardware acceleration

This section explores the way full-screen mode works and discusses the changes that occur once you install Flash Player 9 Update 3.

Assuming that Flash Player 9 Update 3 has been applied, the prerequisites are met, and the FLVPlayback.fullScreenTakeOver property is set to true, which is the default setting, Flash Player uses hardware acceleration to scale the video file, rather than scaling it through software.

If the FLVPlayback component runs in an earlier version of Flash Player—or if the prerequisites for hardware acceleration are not met—Flash Player scales up the video itself. This is the primary difference, as all versions prior to Flash Player 9 rely on Flash Player for full-screen mode scaling.

To take advantage of hardware acceleration for full-screen support, your computer must have a DirectX 7–compatible video card with 4 MB or more of VRAM (video RAM). This hardware support is available in Windows 2000 or Mac OS X 10.2, and later versions of these operating systems. DirectX provides APIs that serve as an interface between software and the video hardware to accelerate three-dimensional and two-dimensional graphics, among other things.

To take advantage of hardware acceleration mode, you must invoke full-screen mode in one of the following ways:

Note: If you invoke full-screen mode by setting the Stage.displayState property to StageDisplayState.FULLSCREEN, FLVPlayback does not use hardware acceleration, even if the video hardware and memory are available on the system.

Handling skin distortion

One consequence of using hardware acceleration for full-screen mode is that the FLVPlayback component's skins are scaled along with the video player and the FLV file. The following image shows the result of using full-screen mode on a 15-inch monitor at a resolution of 1280 x 1024 with a video file that has a width of 320 pixels and a height of 240 pixels, the default FLVPlayback component's dimensions (see Figure 1).

FLVPlayback component skin scaled for full-screen mode using hardware acceleration

Figure 1. FLVPlayback component skin scaled for full-screen mode using hardware acceleration

The distortion effect of the scaled skin is more pronounced on FLV files with smaller dimensions or when FLV files are viewed on a larger monitor. Conversely, the distortion effect is less pronounced on larger FLV files or when the video is viewed on smaller monitors. For example, changing from 640 x 480 to 1600 x 1200 still increases the size of the skin but distorts the skin less.

The FLVPlayback component includes the skinScaleMaximum property, which enables you to limit the scaling of the FLVPlayback skin when hardware acceleration is used. You may choose to limit the scaling based on the specific content that is being scaled and your aesthetic tastes regarding the appearance of large skins. Limiting the scaling of the skin, however, requires a combination of hardware and software to scale the video. In some cases, limiting the scaling of the skin can adversely affect performance on videos with large dimensions that are encoded at a high bit rate. If the video is large (640 pixels wide or more, 480 pixels tall or more, for example), you should avoid setting skinScaleMaximum to a small value—because it could cause performance problems on large display monitors. Figure 2 shows the same skin as shown in Figure 1, except before taking this screenshot the skinScaleMaximum was set to a value of 2 (see Figure 2). In this case, the FLVPlayback component rendered the video (but not the skin) at 640 x 512, a little more than twice its original size, and hardware acceleration did the remainder of the scaling (640 x 2 = 1280 and 512 x 2 = 1024) for both the video and the skin.

Figure 2. Setting the skinScaleMaximum property to specify the largest multiple used to scale up the skin of the FLVPlayback component in full-screen mode

Using the enterFullScreenDisplayState() method

You can also invoke full-screen mode with ActionScript 3.0 by calling the enterFullScreenDisplayState()method, as shown in the following code example:

function handleClick(e:MouseEvent):void {
   myFLVPlybk.enterFullScreenDisplayState();
}
myButton.addEventListener(MouseEvent.CLICK, handleClick);

In this example, full-screen mode is not invoked by clicking the full-screen toggle button on an FLVPlayback skin but, rather, by clicking an ordinary button (MyButton) on the Stage. Clicking the button triggers the handleClick event handler, which calls the enterFullScreenDisplayState() method.

The enterFullScreenDisplayState() method sets the Stage.displayState property to StageDisplayState.FULL_SCREEN, and therefore carries the same restrictions as the displayState property. Generally, this means that you must call it from an event handler for the MouseEvent.CLICK event. For more information on using the enterFullScreenDisplayState() method and the Stage.displayState property, see the online ActionScript 3.0 Language and Components Reference.

Exiting full-screen mode

To exit full-screen mode, click the full-screen button again or press the Escape key.

Setting the following properties can cause layout changes that cause the FLVPLayback component to exit full-screen mode: height, registrationHeight, registrationWidth, registrationX, registrationY, scaleX, scaleY, width, x, y. Calling the following methods also cause the FLVPlayback component to exit full-screen mode: setScale(), setSize().

If you set the align or scaleMode properties, the FLVPlayback component sets them to center and maintains the aspect ratio for the content (maintainAspectRatio) until the user exits full-screen mode.

Changing the value of the fullScreenTakeOver property from true to false when you are using full-screen mode also causes Flash to exit full-screen mode.

Taking advantage of H.264 support

With Flash Player 9 Update 3, the FLVPlayback component is updated to add support for the high-definition MPEG-4 video formats that utilize industry standard H.264 encoding. These formats include MP4, M4A, MOV, MP4V, 3GP, and 3G2. They do not include protected MP4 files, though, such as those downloaded from iTunes or digitally encrypted by FairPlay. Consequently, the FLVPlayback component is no longer restricted to playing FLV files.

Note: The ActionScript 2.0 FLVPlayback component also supports MPEG-4 video formats that utilize H.264 encoding, beginning with Flash Player 9 Update 3. For both ActionScript 3.0 and ActionScript 2.0, you need to ensure that you are working with an updated FLVPlayback component in order to use H.264 video files in your project.

Table 1 lists the formats specifically supported by Flash Player 9 Update 3 and the corresponding version of the FLVPlayback component.

Table 1. File formats supported by Flash Player 9 Update 3 and the FLVPlayback component

Format File type

Video codec

H.264

Audio codec

AAC or MP3

AVC profile

66, 77, 100, or 110 (Flash Player 9 Update 3 does not support 88, 122, 144, or None)

4CC

MP3, MP4A, AVC1, TXG3, GIF, PNG, JPEG, VP60, VP6A

Note: Even if a file has the supported codec and AVC (Advanced Video Coding) profile, Flash Player may still not support it if it has the wrong 4CC (four-character code that identifies the compression standard, or codec, that was used to store the video file). MultimediaWiki lists all 4CCs on their QuickTime container page.

You could also have playback problems if the video stream's data rate is set too high.

Adobe Flash Media Server 3 includes a tool, called FLVCheck, that determines if FMS, and by extension Flash Player 9 Update 3, can properly play an H.264 video file. You can download Flash Media Development Server 3 for free. For more information on using the FLVCheck tool, see the Flash Media Server Configuration and Administration Guide.

You can specify the video file for the FLVPlayback component to play in the following ways:

Because a video file can originate from a variety of locations and because a URL can specify an XML or SMIL file in addition to a video file, the FLVPlayback component analyzes the URL that you supply. After installing Flash Player 9 Update 3, the FLVPlayback component performs the following checks on the URL in this order:

Setting the source parameter

To specify a video file that is not an FLV file or an XML (SMIL) file, you must either type the URL in the Content Path dialog box or use ActionScript to set the source property or the source parameter of the load() or play() methods.

To specify a video file other than an FLV file in the Content Path dialog box, you must type the URL. You cannot browse to a URL that is not an FLV file or an XML (SMIL) file. Also, if you are specifying a video file that is not an FLV file, do not check the Download FLV for Cue Points and Dimensions check box. If you do, the dialog box assumes that any file that does not end in .flv is an XML (SMIL) file and it attempts to parse it as such, which could result in a long delay. While the FLVPlayback component is selected on the Stage, click the parameter tab of the Property inspector. Click the source field to display the Content Path dialog box and enter the video's URL. Alternately, you can select Window > Component inspector and click the source field to access the Content Path dialog box and enter the URL to the video (see Figure 3).

Entering the URL to your video file in the Content Path dialog box

Figure 3. Entering the URL to your video file in the Content Path dialog box

The following code examples show how you can use ActionScript to set the source property and the source parameter for the load() and play() methods:

// loads source property
myFLVPlybk.source = "http://www.helpexamples.com/flash/video/water.flv";
// loads source parameter of load() method
myFLVPlybk.load("http://www.helpexamples.com/flash/video/water.flv");
// loads source parameter of play() method
myFLVPlybk.play("http://www.helpexamples.com/flash/video/water.flv");

Understanding metadata support and NetStream clients

Flash Player 9 Update 3 updates the FLVPlayback component to add support for high-definition H.264 video formats. With metadata—the information grouped together into the MPEG container—you can access and display a wide array of useful and interesting information such as album art, song titles, chapters, and other text and images from both video and audio files. The FLV file format uses a metadata packet to store this information.  Two new NetStream callbacks, onImageData() and onTextData(), have been added to support metadata functionality in non-FLV H.264 files.

This section covers the following topics:

Getting metadata via onMetaData() callback

When you use the FLVPlayback component, the onMetaData() callback is handled for you, so you can add a listener for the MetadataEvent.METADATA_RECEIVED event.

In the example below, the onMetaData() function listens for the metadata event:

import fl.video.*;
myFLVPlayback.addEventListener(MetadataEvent.METADATA_RECEIVED,
    handleMetadata);
function handleMetadata(e:MetadataEvent):void {
    var data:Object = e.info;
    ...
}

Alternately, you can access the metadata at any time after that event by accessing the metadata property. When parsing an MP4 file, Flash Player generates data messages that return extended metadata information.

The following fields are supported:

public function
    onMetaData(data:Object):void {
   if ( data.tags != undefined
    && data.tags.covr != undefined ) {
   // see if we have cover artwork
      for ( var i:int;
    i<data.tags.covr.length; i++ ) {
         var loader:Loader = new
    Loader();
         loader.loadBytes(data.tags.covr[i]);
         addChild(loader);
      }
   }
}

There is not a fixed, definite list of metadata tags available. Flash Player simply reads key value pairs and in most cases does not look at the actual keys. It is recommended to introspect the onMetaData message using recurseTrace to figure out what it contains. This is also a good strategy for identifying any additional information not listed here, because metadata is not fixed and the list of supported metadata tends to increase over time.

In the example below, recurseTrace is used to find the onMetaData function to explore the contents: 

public function onMetaData(info:Object):void {
        trace(info);
        recurseTrace(info, "");
}
 
private function recurseTrace(info:Object, indent:String):void
{
        for (var i:* in info) {
                if (typeof info[i] == "object") {
                       trace(indent + i + ":");
                       recurseTrace(info[i], indent + " ");
               } else {
                       trace(indent + i + " : " + info[i]);
               }
        }

}

Getting metadata via onImageData() callback

The onImageData method is a callback like onMetaData that sends image data as a byte array through an AMF0 data channel. The image data can be in JPEG, PNG, or GIF formats. As the information is a byte array, this functionality is only supported for ActionScript 3.0 client SWFs. In the example below, onImageData is used to access and display the image data:

public function onImageData(imageData:Object):void {
   // this is the track number this sample is associated with
   trace(imageData.trackid);
   var loader:Loader new Loader();
   // imageData.data is a ByteArray object.
   loader.loadBytes(imageData.data);
   addChild(loader);  
}

Note: For FLVPlayback programming, the onImageData() function must be in the context of a custom client.

Getting metadata via onTextData() callback

The onTextData method is a callback like onMetaData that sends text data through an AMF0 data channel. The text data is always in UTF-8 format and can contain additional information about formatting based on the 3GP timed text specification. This functionality is fully supported in ActionScript 2.0 and 3.0 because it does not use a byte array. In the example below, onTextData is used to display the track ID number and corresponding track text data in the Output window:

public function onTextData(textData:Object):void {
   // this is the track number this sample is associated with
   trace(textData.trackid);
   // prints the text, can be a null string which indicates that
   // the old string on this track should be erased
   trace(textData.text);
}

Note: For FLVPlayback programming, the onTextData() function must be in the context of a custom client.

Custom callbacks via custom client class

The FLVPlayback component automatically creates an instance of the class fl.video.VideoPlayerClient, assigns it to the NetStream's client property, and handles all callback messages that come through the NetStream. The default class fl.video.VideoPlayerClient handles only the callbacks onMetaData() and onCuePoint(). Both of these messages generate events (MetadataEvent.METADATE_RECEIVED and MetadataEvent.CUE_POINT) so that you do not need to register a custom class to handle these callbacks.

However, if you do wish to use custom callbacks, you must register a custom client class. You should extend fl.video.VideoPlayerClient to ensure that the onMetaData() and onCuePoint() handling supplied by VideoPlayer and FLVPlayback will continue to work properly.

The requirements for a custom client implementation are as follows:

Use the code below to register the custom client class:

import fl.video.*;
VideoPlayer.netStreamClientClass = MyCustomClient;

The netStreamClientClass property can be set to the class itself (as shown in the example above) or it can be set to the string name of the class. Setting it to the string name will not force the inclusion of the class into the SWF, so that will need to be forced in another way. For example, you could declare a variable of that type to ensure the class is included.

If the netStreamClientClass property is set to an invalid value, then a VideoError will be thrown with the error code: NETSTREAM_CLIENT_CLASS_UNSET.

The following extended example shows a sample client class that handles onImageData():

package {
 
   import fl.video.VideoPlayer;
   import fl.video.VideoPlayerClient;
   import flash.display.Loader;
   import flash.display.DisplayObjectContainer;
   import flash.utils.ByteArray;
 
   /**
    * MyVideoClient subclasses VideoPlayerClient, the default
    * VideoPlayer.netStreamClientClass value. This way all
    * the metadata and cue point handling built in the
    * VideoPlayer works properly.
    *
    * The class is declared dynamic so if any other
   * messages are received that we do not support in
   * this class (onTextData(), other custom
   * messages) no runtime errors will occur.
   */
 
dynamic public class ImageDataVideoClient extends VideoPlayerClient
   {
 
   /**
   * This variable is set in onImageData and is used to help
   * determine when the ready property should be true.
   */
 
      protected var gotImageData:Boolean;
 
   /**
   * The constructor must take a VideoPlayer as its
   * only parameter. It needs to pass that argument
   * along to the super constructor.
   */
 
      public function ImageDataVideoClient(vp:VideoPlayer) {
         super(vp);
         gotImageData = false;
      }
 
   /**
   * Handling for onImageData() message
   * Loads the image bytes into a flash.display.Loader
   * and adds the image to the
   */
   
      public function onImageData(info:Object):void {
      // Only handle onImageData() once. Any time we seek to the
      // start of the file, the message will call this function
      // again
         if (gotImageData)
            return;
         var loader:Loader = new Loader();
         loader.loadBytes(info.data);
         var parent:DisplayObjectContainer = _owner.root as DisplayObjectContainer;
         if (parent) {
            parent.addChildAt(loader, 0);
         }
         gotImageData = true;
      }
 
      public function onTextData(info:Object):void {
         trace(info);
         recurseTrace(info, "");
      }
   
      private function recurseTrace(info:Object, indent:String):void
      {
         for (var i:* in info) {
            if (typeof info[i] == "object") {
               trace(indent + i + ":");
               recurseTrace(info[i], indent + "  ");
            } else {
               trace(indent + i + " : " + info[i]);
            }
         }
      }
   
   /**
   * property that specifies whether early messages have been
   * received so it is OK for the player to rewind back to the
   * beginning. If we allow the VideoPlayer to rewind before
   * all messages at the very beginning of the file are received,
   * we may never receive them.
   *
   * The default class, VideoPlayerClient, only requires
   * onMetaData() to be received before rewinding. onImageData()
   * also appears at the beginning of the file, so we might miss
   * that if we do not override this property and include a check
   * for this data.
   */
   
      override public function get ready():Boolean {
         return (super.ready && gotImageData);
      }
 
   }
}

New NetStream notifications

Two new notifications facilitate the implementation of the playback components:

These notifications are handled by the FLVPlayback component and come in the onStatus callback of the NetStream, resulting in a state of VideoState.CONNECTION_ERROR. If you write code that handles NetStreams directly, then you may want to handle these notifications as well.

Where to go from here

We hope that this article has provided you with a good overview of the changes to the FLVPlayback component after installing Flash Player 9 Update 3.

For more information about modifying the FLVPlayback component, check out Controlling Flash video with FLVPlayback programming by Dan Carr.

Creative Commons License
This work is licensed under a Creative Commons Attribution-Noncommercial-Share Alike 3.0 Unported License

About the authors

Bob Berry is a senior technical writer with Adobe Systems, Inc. Prior to joining Adobe, Bob worked at Macromedia for four years, at IBM briefly, and at Informix Software for 10 years.

James Wiley specializes in writing, marketing, and web development. His clients have included Sony, T-Mobile, Starbucks, and Adobe.