You are Here:Home>>Old Posts>>Using the FLVPlayback component with Flash Player 9 Update 3

Using the FLVPlayback component with Flash Player 9 Update 3

Carlos Pinho
By | 2008-02-15T20:22:45+00:00 Feb 15, 2008|Old Posts|

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, 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:

  • Using the full-screen toggle button on an FLVPlayback skin
  • Using the FullScreenButton video control
  • Using the FLVPlayback.enterFullScreenDisplayState() method

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

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

  • Set the source parameter in the Property inspector or the Component inspector
  • Specify a local file or a URL in the Video Import Wizard
  • Specify the video using ActionScript

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:

  • If you specify the RTMP, RTMPT, or RTMPS protocol for streaming from Flash Media Server (FMS), the source URL is assumed to be streaming video from Flash Media Server
  • If the URL does not include a query string, for example:
    http://www.foo.com/app?param1=value&param2=value
    and the URL does not end in .txt, .xml or .smil, the source is assumed to be a video file
  • If the URL cotains the string “/fms/fpad” then the source is assumed to be a FPAD XML file from Flash Media Server
  • If none of the above is true, the FLVPlayback component assumes the source URL is a SMIL file

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 component 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:

  • width: Display width in pixels.
  • height: Display height in pixels.
  • duration: Duration in seconds.
  • avcprofile: AVC profile number such as 55, 77, 100 etc.
  • avclevel: AVC IDC level number such as 10, 11, 20, 21 etc.
  • aacaot: AAC audio object type; 0, 1 or 2 are supported.
  • videoframerate: Frame rate of the video in this MP4.
  • seekpoints: Array that lists the available keyframes in a file as time stamps in milliseconds. This is optional as the MP4 file might not contain this information. Generally speaking, most MP4 files will include this by default.
  • videocodecid: Usually a string such as “avc1” or “VP6F.”
  • audiocodecid: Usually a string such as “.mp3” or “mp4a.”
  • progressivedownloadinfo: Object that provides information from the “pdin” atom. This is optional and many files will not have this field.

    Note: Atoms are data “boxes,” a hierarchal structure of data objects containing other data tracks for audio, video, text, etc. As a very simple building block in the file container, each atom name has specific characteristics. For example, a “moov” atom is a parent atom with no content except other atoms; “mdat” atoms carry the raw audio/visual stream; the “ilst” atom is the ID3 equivalent Apple iTunes uses to store metadata for song titles and artist name and album, etc.; and the “pdin” atom contains progressive download information.

  • trackinfo: Object that provides information on all the tracks in the MP4 file, including their sample description ID.
  • tags: Array of key value pairs representing the information present in the “ilst” atom, which is the equivalent of ID3 tags for MP4 files. These tags are mostly used by iTunes. In the example below, the cover artwork is accessed and displayed, if the artwork is available:
 
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 ObjectUtil 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, ObjectUtil is used to find the onMetaData function to explore the contents:

 
import mx.utils.ObjectUtil;
public function onMetaData(data:Object):void {
   trace(ObjectUtil.toString(data));
}

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:

  • The constructor method must take an fl.video.VideoPlayer instance as its only parameter.
  • The custom class must include a ready property which should be set to true when all messages expected at the very beginning of the NetStream have been received. This step is necessary because the VideoPlayer class initially hides the video and plays the beginning of the file to access the correct dimensions and duration of the video. It then quickly rewinds the video to the beginning and unhides it. If the rewind occurs before all messages at the very beginning of the file are received by VideoPlayer, there’s a chance those messages may never be received.
  • It is highly recommended that you declare the custom class as dynamic to avoid encountering runtime errors. Errors may appear if any callbacks are triggered that the class is not set up to handle.
  • It is also recommended to extend fl.video.VideoPlayerClient to ensure proper onMetaData() and onCuePoint() handling.

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:

  • NetStream.Play.FileStructureInvalid: This event is sent if the player detects an MP4 with an invalid file structure. Flash Player cannot play files that have invalid file structures.
  • NetStream.Play.NoSupportedTrackFound: This event is sent if the player does not detect any supported tracks. If there aren’t any supported video, audio or data tracks found, Flash Player does not play the file.

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.

About the Author:

Carlos Pinho
A father, a husband and a geek... Carlos was the founder of projects like The Tech Labs and Flash Enabled Blog. He is the founder of TekTuts He is passionate about technologies. Their main skills are in analytics, transport & logistics, business administration. He also writes about programming resources, trends, strategy and web development.