Displaying DFXP Captions for a Video

In this article, you will learn how to use the Brightcove Captions API to display DFXP format captions for a video. You can download a zip file that contains the source code for the example in this article. The approach in this article depends on custom metadata fields, which are available only to Brightcove Pro and Enterprise publishers.

For an introduction to the Captions Module of the Flash-only Player API, read Using the Flash-Only Player API for Closed Captioning. For a reference to the methods and events in the Captions Module of the Flash-only Player API, read the Flash-Only Player API Reference. For more on creating dynamic captioning solutions for smart players, that is solutions that work for both the Flash and HTML mode of the player, see Using the Smart player API, or more specifically Using Captions with the Smart Player API.

Here's a sample player that displays a video with captions:

Main Steps

Here are the main steps we followed to create this demo:

1. Create a DFXP format caption file for the video.
2. Create a custom metadata field for videos in our account named captions. The value of this field will be the URL of the captions file.
3. Enable the Brightcove APIs for the player that will show the video.
4. Create a SWF module that calls the captions file.
5. Add the SWF module as a plug-in in your player and publish the player.

Create a caption file

In this release, the Captions API supports the Distribution Format Exchange Profile (DFXP) format for closed captions. DFXP is an XML-based captioning format developed by W3C. Create a caption file for your video, using the DFXP format. Make sure your DFXP documents are valid, including containing a valid namespace, as defined in the specification. Note that we support  the lang, begin, and end DFXP attributes  and do not support style elements or styling attributes in the DFXP file.You also need to host the caption file at a URL that can be accessed by the Brightcove player, so make sure that you have a crossdomain.xml file that permits this.

Add a custom field for the caption file

In this example, we use a custom metadata field to store the location of the captions file for the video. Read about Creating Custom Metadata Fields. Once the account has a custom metadata field named captions, we use the Media module to set the value of the captions field to the URL of the DFXP caption file.

Figure 1. Setting the value of the captions custom field

Enable the API for your player

It's important to first check your player to see if the Brightcove APIs are enabled. In the Publishing module, make sure the Enable ActionScript/JavaScript APIs checkbox is checked for your player.

 Figure 2. Enabling APIs for the player in the Publishing module

Create a custom module to use the Captions API

We created a custom module that uses the Captions API to get the caption file and load it with the video. In the following code, note how we get the URL of the captions file from the video's captions custom field and then use the CaptionsModule's loadDFXP method to load the caption file.

package
{
    import com.brightcove.api.APIModules;
    import com.brightcove.api.CustomModule;
    import com.brightcove.api.modules.CaptionsModule;
    import com.brightcove.api.modules.VideoPlayerModule;
    
    /**
     * Example module which looks for a custom field called "captions"
     * and then loads the captions for the current video.
     */
    public class CaptionPlugin
        extends CustomModule
    {
        private var _videoModule:VideoPlayerModule;
        private var _captionsModule:CaptionsModule;
        
        /**
         * @inheritDoc
         */
        override protected function initialize():void
        {
            _videoModule = player.getModule(APIModules.VIDEO_PLAYER) as VideoPlayerModule;
            _captionsModule = player.getModule(APIModules.CAPTIONS) as CaptionsModule;
            
            if (_videoModule.getCurrentVideo().customFields["captions"])
            {
                _captionsModule.loadDFXP(_videoModule.getCurrentVideo().customFields["captions"]);
            }
        }
    }
}

Add the SWF module as a plug-in

After compiling the code into SWF, we add the SWF as a plug-in to the player. The simplest way to do this is to use the Publishing module; we just add the URL of the SWF in the Edit Player: Plug-ins tab. Another approach would be to create a custom player template using BEML and use a Modules BEML element that loads the SWF in all players that use the player template.

Then we just publish the player. When the video plays, it automatically uses our DFXP file to display captions in English.

Captions modules and HTML5 players

In the current release of Brightcove, a SWF that is assigned to a player in the Plug-ins tab or as a Module element in a BEML custom player template is ignored when the player is loaded in HTML5 mode on a mobile device. This means that your player can display captions on Flash-supported devices. If you are using the Flash-only Player API to implement your SWF plug-in, devices that support HTML players only, will not display those captions. In order to assure captions work on both Flash and HTML players, use the Smart Player API for your plug-in solution, and include a JavaScript plug-in for HTML mode of the player.

What's next?

This is only a simple example which displays the captions for a single language. The Captions Module for both the Smart Player API and the Flash-only Player API includes methods for retrieving and setting the languages included in the DFXP file. You could add a language selection control, such as a dropdown, to the player by adding on to the sample plug-in in this article.