Using the Flash OSMF Media Player template

This article provides an overview of a media player template (see Figure 1), developed for use with Flash video templates available on the Adobe Developer Connection. The media player takes advantage of the advanced content formatting features of Open Source Media Framework, or OSMF, while presenting an experience familiar to anyone who has worked with the video templates or the FLVPlayback component in Adobe Flash Professional.

The Flash OSMF media player template supports the general list of functionality available in the FLVPlayback, along with the following enhancements:

• Sequencing videos and content in the display area
• ActionScript, component parameter, or XML configuration of content
• Hardware acceleration and HD video with controls in full-screen mode
• Easy configuration and graphic editing of the supplied controls
• Sharing using the AddThis menu widget
• Advanced feature development using the low-level OSMF objects and plug-in architecture

Use the media player on its own and with future video template updates. The following sections review the features of the components and discuss how to use them to play back media in your own projects.

The Flash OSMF media player template is a Flash project comprised of a FLA file, an ActionScript code package, and a SWC library containing the Open Source Media Framework code. If desired, you can open the project in Adobe Flash Builder; however, Flash Builder and Flex are not required to work with the files. Figure 2 describes the pieces of the media player and the features supported.

Building a media player

One of the exciting things about OSMF is that it's designed to open up possibilities for configuring a wide range of media player layouts. The framework is driven by ActionScript but also provides the Strobe media player and a handful of sample files to help visualize using the framework. The Flash media player template is loosely based on the OSMF Chrome sample and cue points sample.

While the resources supplied by the OSMF team can get you started easily, I wanted to develop a component that would feel familiar to developers used to the FLVPlayback component in Flash Professional. The solution provided here contains three main elements: a display area (the MediaDisplay component), a control bar (the ControlBar component), and an XML markup parsing script (the Configuration component).

You can use the MediaDisplay component as a standalone display area for simple or complex content, or you can combine it with the ControlBar component which allows you to choose from a range of predefined controls. Your workflow for customizing the media player will generally involve sizing the components, customizing the colors of the controls, and assigning the media source through component parameters or an external XML file.

Key features

Both the MediaDisplay and the ControlBar components are designed as editable movie clips to make it easy to edit the graphics and republish the files after making updates.

The MediaDisplay component combines the four main elements of an OSMF media player (DefaultMediaFactory, MediaPlayer, MediaContainer, and LayoutRenderer) with the general programming API and functionality commonly used in the FLVPlayback component. The MediaDisplay component supports the following:

• Media types supported by OSMF
• Content playlist definitions via XML
• Embedded and ActionScript cue points
• Foundation support for plug-in design

The ControlBar component combines a range of predefined controls and manages the controls in relation to the MediaDisplay component. The two components are connected by assigning the MediaDisplay instance to the ControlBar's mediaPlayer property. The following list of controls can be included or excluded using ActionScript or component's parameters:

• Play button (display area overlay)
• Play/Pause button
• Seek bar
• Elapsed time
• Share button (with AddThis share menu)
• Full-screen button
• Mute button / volume slider

The ControlBar component adds two other features to the display area: full-screen support for HD video including the control bar, and share functionality using the AddThis Flash menu widget.

Working with the supplied files

Download the sample project files from the top of the article. Unzip the archive and review the contents of the folder (see Figure 3).

The com and libs folders contain ActionScript code which the FLA file references when the SWF is published. Be sure to keep these folders next to the FLA file. However, it's important to note that you don't need to edit the code to work with the project. The OSMFComponent.fla file and the config.xml file are the two items you'll edit to set up a media player; these steps are covered in the next section.

The project folder contains both source files for editing and published files for distribution. When you're ready to copy the published files to the host server, upload the following:

• AddThisMenuAPI.swf
• HTML file – this embeds the SWF
• SWF file – this contains the media player
• config.xml

You can change the names of the HTML, XML, and SWF file to match your project. Be sure to update the name references in the HTML markup if you change the SWF name. If you change XML name, update the XML name in the MediaDisplay parameters.

Before you start

Once you've downloaded and uncompressed the project files, move the project folder to your desktop or some other easy to access location on your hard drive. You'll use this folder as your project folder to edit and publish the files.

The MediaDisplay and the ControlBar components can be resized and configured directly in the OSMFComponents.fla file. Additionally, you can configure the MediaDisplay's source playlist by editing an external XML file.

The following section describes the process of customizing the components in the FLA file.

Setting up the FLA file

The project FLA file provides the building blocks for creating variations on the media player template. You can duplicate this file as many times as desired to create players with different sizes, different Stage layouts, and different graphic themes.

For example, imagine that you want to create a media player to play a 768 × 428 video. The default size of the player is 320 × 240, so you'll need to make some adjustments.

Follow these steps to create a new FLA file:

1. Open OSMFComponents.fla in Flash Professional.
2. Choose File > Save As to create a duplicate file named MediaPlayer2_768x428.fla. Make sure to save the new FLA in the project folder. The existing file named MediaPlayer_768x428.fla is the completed version, so be sure not to overwrite that one.
3. Choose Modify > Document to open the Document Settings dialog box. Set the Stage dimensions to 768 × 454. Notice that the control bar is the width and height of the display area plus an extra 26 pixels of height to encompass the controls area.
4. Click OK to update the file.
5. Save the file.

Note: The process of duplicating the FLA file copies the linkage settings to the OSMF SWC file in the libs folder and the media player assets in the Library panel.

Setting up the display area

Notice that the main Timeline of the FLA file contains four layers: actions, control bar, media player, and background. The actions layer contains a single line of code that associates the MediaDisplay instance with the ControlBar instance, each on their respective layers. The background layer holds an optional rectangle graphic that is sized to match the MediaDisplay instance.

Follow these steps to set the size of the display area:

1. Select all the graphics across all layers and move them to the 0, 0 coordinate, or top-left corner, of the Stage.
2. Select the background graphic on the background layer and size it to 768 × 428, or simply delete it, if you prefer.
3. Lock the control bar layer and select the component on the media player layer. Set the size of the player to 768 × 428.

At this point if you don't want to include the control bar, you can delete it from the Stage. If you choose to delete the control bar, be sure to also delete the actions layer because it won't be necessary and will cause an error to occur if the control bar is absent.

Setting up the control bar

The control bar is easy to update. You can position the controls within the control bar by editing the movie clip's timeline.

Follow these steps to modify the control bar:

1. Unlock the control bar layer. Double-click the component instance on the Stage to enter symbol editing mode and access the movie clip's timeline.
2. Lock the play button overlay layer for now; you'll come back to it in Step 5.
3. Move the background and line graphics to the bottom of the screen and set their width to 768 pixels.
4. Lock the background and line layers. Move the controls to the bottom of the screen. Move the Elapsed Time, Share button, Full Screen button, and volume controls so that they align with the right side of the screen.
5. Unlock the play button overlay layer. Double-click the overlay instance to access its timeline. Resize the background graphic to 768 × 428 and position the play button in the center of the screen (see Figure 4). Note that you can skip this step if desired, since the control bar automatically sizes the play button overlay and the seek bar at runtime.

6. Save the file.

Note: Be careful not to delete the instance names on the controls as you edit them.

Setting up the component parameters

Once you've sized the assets, you can select the MediaDisplay and the ControlBar instances to edit their component parameters in the Property inspector. You can also use ActionScript to set the properties, but the component parameters interface offers an easy way to configure the player without writing any code.

Follow these steps to configure the MediaDisplay component:

1. Return to the main Timeline and lock the control bar layer. Select the MediaDisplay component and review its component parameters in the Property inspector (see Figure 5).

2. You can set the source of the media player by entering the URL for the media in the source field. Alternatively, you can enter the URL to an XML playlist in the configFile field of the Component Parameters. Only use one of these options.
3. You can also add ActionScript cue points and adjust the playback settings as needed.

Follow these steps to configure the ControlBar component:

1. Unlock the control bar layer and select the ControlBar instance to view its parameters in the Property inspector (see Figure 6).

2. If you are working with HD video, set the hdHeight and hdWidth parameters to the size of your HD video source. Doing so turns on hardware acceleration during full-screen mode.
3. Deselect the seekEnabled check box if you're working with a progressive video whose encoding produces undesirable results. Turning off seeking switches the seek bar to a progress bar.
4. Set up the AddThis share menu by defining the number of columns, display state style, and URL to share. These parameters are optional, but be sure to fill in the shareUrl field if you leave the Share button control turned on.
5. Choose which predefined control to show by using the check boxes to enable them. The control bar automatically lays itself out and adjusts the interface per your settings.
6. You can publish the SWF at this point to check the user interface.
7. Save your file.

Note: If you're having trouble encoding progressive videos in a way that works with the seek bar, try encoding keyframes at the 1 second interval.

For more information on using the AddThis menu widget, visit the Flash Example Implementations help page at AddThis.com.

Customizing the look and feel

You can change the color of the controls and update the graphics by editing the movie clips in the Assets/controls/_skins folder in the Library. If you change the graphics, it's best to use new graphics that follow a similar layout and positioning. You can adjust the layout code in the supplied ActionScript package if you find that you need to instruct the controls to position elements differently.

Check out the MediaPlayer_768x428.fla file in the project files for a finished example of the instructions described in this section.

The Open Source Media Framework, or OSMF, is an open-source ActionScript 3 project developed by Adobe and Akamai to give organizations publishing video, audio, and rich media a new way to deliver engaging experiences that are easier to develop. Even if you're not an organization targeting the OSMF's high-end features, you can still take advantage of the cool new possibilities that OSMF provides.

This section includes an overview of some of the unique features of the OSMF as well as a guide to using them in the MediaDisplay component.

Supported media types

OSMF not only supports FLV and H.264 video similar to the FLVPlayback component, but also supports all Flash Player 10 media formats:

• Streaming video: FLV, F4V, MP4, MPEG-4, MP4, M4V, F4F, 3GPP
• Progressive audio: MP3
• Progressive video: FLV, F4V, MP4, MP4V-ES, M4V, 3GPP, 3GPP2, QuickTime
• Images: PNG, GIF, JPG
• SWF files
• Limited support for streaming audio: MP3, AAC, Speex, Nellymoser
• F4M multi-bitrate manifest file

Version 1 of the MediaDisplay component is geared mostly toward video.

Content sequencing

Beyond providing new options for types of content, OSMF also includes the ability to create complex media compositions using those content types. The concept is that you can create compositions of media such as video mixed with ad banners, images, and Flash content.

OSMF uses two metaphors for displaying compositions: media elements can be display as parallel elements or serial elements. Parallel elements are media elements that appear at the same time; serial elements appear in a sequence one after another.

For the purposes of exposing this functionality in the MediaDisplay component, I added the ability to load a configuration XML file which can define a playlist of parallel and serial media content.

Configuring the player using XML

You can use the config.xml file as an external data source for the media player playlist. The config file contains a simple description of media nodes where each media node can be marked as being a parallel or serial layout. Each media node may contain a source node or other media nodes:

Notice in this sample markup that the playlist consists of a top-level media element marked with the serial layout type. That media element contains two children: another media element set to display a logo image and a video in parallel, followed by a solo video element. The resulting display would show the image and play the first video, and then play the second video after the first video finishes.

Media nodes require the layout—serial or parallel—attribute. Both media and source nodes support the formatting attributes in Table 1.

Table 1. OSMF media player attributes

Experiment with using serial and parallel media nodes, as well as nesting them to create different sequences of content. You can add layout attributes to media nodes as well as source nodes.

Note: Combinations of nested formatting may produce unexpected results. Be sure to test as you find the right combination of media formatting and layout formatting for your project.

While working with ActionScript is not required to configure the media player template, you may find that you prefer the code approach or need to add features not accessible through the component parameters. The MediaDisplay component and the ControlBar component include an ActionScript API which exposes the component parameters as well as properties, methods, and events not available in the authoring environment.

This section provides an overview of the code-related features of the media player template as well as instructions for working with both Flash Professional and Flash Builder for coding tasks.

Exploring the ActionScript API

Each element in the media player template defines its functionality in an ActionScript class located inside the project's com folder. The application programming interface, or API, related to each element is simply a list of properties, methods, and events which are exposed for public use. When working with ActionScript, you need to become familiar with the public API for the objects in the project. To do this, you can explore the supplied ASDoc documentation for the code package.

To explore the documentation from anywhere, browse the ASDoc files posted online.

To explore the documentation from your local hard drive, follow these steps:

1. Download the OSMFComponents_ASDoc.zip file using the sample files links at the top of the article.
2. Unzip the folder to your desktop, or any easy to access location on your computer.
3. In the folder, locate the index.html file and open in a browser. Notice that the first screen you see is an overview of the classes (scripts) in the ActionScript package (folders).
4. Click the com.devnet.osmf.application link to drill down into the application package. Notice that there are three classes: Configuration, ControlBar, and MediaDisplay. These are the three primary objects you'll most likely deal with when working with code.
5. To explore the MediaDisplay API, for example, click the MediaDisplay link to view its API. You'll probably spend most of your time working with the functionality of this class. Browse down the page to view the list of properties, methods, events, and constants. You can use this resource to understand the available options.
6. Leave the browser window open when you're done so you can refer to it as needed.

ASDoc is an Adobe utility supplied with the Adobe Flex SDK that allows developers to document their code by parsing comments in the ActionScript classes. That means that the documentation you just explored was generated directly from the code in the com/devnet/osmf folder in the project files.

For ASDocs describing the ActionScript 3 language, including OSMF, see the ActionScript 3.0 Reference for the Adobe Flash Platform.

Creating a Flash Professional project in Flash Builder

You can use Flash Builder in tandem with Flash Professional as a more robust code editor. If you want to experiment with using the template's ActionScript API, you may find that using this approach provides an easier way to manage and edit your code.

Follow these steps to create a Flash Professional project:

1. Go through the steps in the Configuring the components section of this article to set up the FLA file that will become the media player. For the purposes of this example, you can open the MediaPlayer_768x428.fla file that you completed earlier.
2. Open Flash Builder 4. Create a new project by choosing File > New > Flash Professional Project.
3. In the dialog box that appears, click the Browse button next to the Target file field and browse for the FLA file. Click OK once you've found the file.
4. Click the Finish button to close the dialog box. Notice that a new project appears in the Package Explorer panel and an empty ActionScript class opens in the code editor (see Figure 7).

5. Notice that the ActionScript class has the same name as the FLA file. Also, if you look in the folder containing the FLA file, notice that the ActionScript class has been saved next to the FLA. Flash Builder uses this file to represent the root of the project, but you can assign this script to the FLA's document class to make the code active on the main Timeline.
6. Return to Flash Professional and click an empty part of the Stage to select it. The Document properties are displayed in the Property inspector. Enter the name of the ActionScript class in the Class field (see Figure 8).

7. Return to Flash Builder. Change the references to the Sprite class to the MovieClip class. This is necessary because document classes in Flash Professional must subclass MovieClip to avoid errors. Add a trace statement to the constructor function so you can make sure that everything is working. The code should look like the code shown in Figure 7 when this step is completed.
8. In Flash Builder, press Control+Enter (Windows) or Command+Enter (Mac) to launch Flash Professional and publish the file. Notice that the trace action fires when the SWF file launches.
9. Close the SWF file to automatically return to Flash Builder.
10. Save the file.

Now that you've set up your Flash Professional project, you can add code to the document class to configure the player and add features. All of the code placed below the trace statement in the sample shown above will behave as if it was placed on Frame 1 of the main Timeline of the FLA file.

Configuring the player using ActionScript

You can use ActionScript to assign media to the player and create playlists of media elements. If you're loading a single media source, you can use the source property or load method of the MediaDisplay component, as shown:

If you're loading a composition of media elements, you'll need to build the project dynamically using the OSMF API and then assign the SerialElement to the MediaDisplay component using its setMedia method, as shown in the last line of this example:

The code sample above creates the same result as the XML-based sample in the Working with OSMF section of this article. This illustrates how you can access the underlying OSMF coding APIs to work with the template.

Note: If you want to assign media playlists using the setMedia method in ActionScript, be sure to set the configFile and source properties to null in the component parameters first.

Using cue points and events

The most common way to extend the features of the media player is to respond to events broadcast from the MediaDisplay component. Events are timing cues that signal when something is happening. For example, you could add ActionScript cue points to the media to mark chapter time codes and then listen for the cue point events to determine when to show related text or graphics.

Follow these steps to add cue point event handling to your document class:

1. Within Flash Builder, update the MediaPlayer_768x428 class so that it looks like the following:

2. Press Control+Enter to publish the file in Flash Professional. Notice that the cue point events are traced to the Output panel while the movie plays. You can update the code in the onCuePointEvent function to trigger navigation along the main Timeline or achieve other synchronous effects.
3. Close the SWF file and save the project files.

The code snippets above assume there is a MediaDisplay component on the main timeline of the FLA file with an instance name of mediaDisplay.

For more information on the ActionScript programming APIs for the MediaDisplay component, see the included ASDoc pages available for download at the beginning of this article, or available online.

Review the documentation and sample files created by the Open Source Media Framework team. Visit the links below to learn more about working with the framework:

• Open Source Media Framework: Introduction and overview (Greg Hamer)
• Building streaming video players in Flash with Open Source Media Framework (R Blank)
• Getting started with OSMF for developers
• OSMF download (sourceforge.net)