Using the FLVPlayback component with Flash Player 9 Update 3

Additional Requirements

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

• Download

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.

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:

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

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.

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:

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.

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

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:

• 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, RTMPS, RTMPE, or RTMPTE 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 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).

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:

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
• Getting metadata via onImageData() callback
• Getting metadata via onTextData() callback
• Custom callbacks via custom client class
• New NetStream notifications

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:

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:

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:

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:

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:

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:

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():

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.

These notifications are handledby the FLVPlayback component and come in the onStatus callback ofthe NetStream, resulting in a state of VideoState.CONNECTION_ERROR. If you writecode that handles NetStreams directly, then you may want to handle thesenotifications 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.