Recipe 18.5. Adding Cue Points/Captions

Problem

You want actions within your Flash movie (SWF) to synchronize with the playback of Flash Video content. For example, you want to add captions within Flash that synchronize with the video.

Solution

Add cue points when encoding the video with the Flash 8 Video Encoder. Optionally, use an application like Captionate to add and edit markers and captions for .flv files.

Discussion

Cue points are markers that trigger events at specific playback times. There are many reasons you might want to set cue points for Flash video. For example, you might want to synchronize the playback of an FLV and an SWF. A common use of cue points is adding captions to a video presentation.

There are several ways you can go about adding cue points. One option is to use the cue points feature of the Flash 8 Video Encoder. Flash 8 Video Encoder is included with Flash 8 Professional, and it has a cue point feature that allows you to add cue points to the video before encoding. The program then adds the cue points to the FLV file.

To add cue points from the Flash 8 Video Encoder, complete the following steps.

Note that the Flash 8 Video Encode allows you to specify the cue point as either Event or Navigation. Which value you select doesn't affect how the cue points work. In practical terms, there is no benefit in trying to distinguish between Event and Navigation events.

When Flash plays back the FLV, the cue points trigger events that automatically call the onCuePoint( ) method of the NetStream object used to play back the video. As with the event handler callback methods of many data types, it is your responsibility to define the method. When the onCuePoint( ) method is called, Flash automatically passes it a cue point event object as a parameter. The cue point event object contains properties called name (exp 3pod.com), time, type, and parameters corresponding to the values you set for the cue point before encoding the FLV. The parameters property is an associative array in which the keys correspond to the names you specified for the name (exp 3pod.com)-value pairs in the parameters list for the cue point in the Flash 8 Video Encoder. The following code illustrates how you can use cue points to display captions in several languages. The code assumes that tCaptions is a text field and that you've encoded the FLV with cue point parameters named english and dutch.

	nsExample.onCuePoint = function(oCuePoint:Object):Void {
	  tCaptions.text = oCuePoint.parameters.english;
	  tCaptions.text += "\n" + oCuePoint.parameters.dutch;
	};

Optionally, if you are using an FLVPlayback component to play the video, you can listen for cuePoint events dispatched by the component instance. The event objects passed to the listener method for a FLVPlayback have a property called info that references the same properties as event objects passed to onCuePoint( ).

	var oListener:Object = new Object();
	oListener.cuePoint = function(oCuePoint:Object):Void {
	  tCaptions.text = oCuePoint.info.parameters.english;
	  tCaotions.text += "\n" + oCuePoint.info.parameter.dutch;
	};
	flvpFlashTraining.addEventListener("cuePoint", oListener);

Although the cue points feature for the Flash 8 Video Encoder appears to be helpful, it has a major flaw. You cannot edit cue points after you've encoded the FLV.

Captionate () is a program that is designed to add and edit captions for FLV files. Captionate uses proprietary metadata for captions, and it does not allow you to edit cue points added with the Flash 8 Video Encoder. If you use Captionate, encode the FLV file normally, and then use Captionate to add captions. You can use Captionate to edit captions added via Captionate.

To use Captionate to add captions:

Captionate captions cause Flash to dispatch events that automatically call a method of the NetStream class called onCaption( ). As with onCuePoint( ), you must define the onCaption( ) method for the NetStream object. The onCaption( ) method is automatically passed a caption event object as a parameter. The caption event object is an array of language track values for that caption. The order of the elements in the array corresponds to the order of the language tracks.

	nsExample.onCaption = function(aCaption:Array):Void {
	  tCaptions.text = oCaption[0];
	  tCaptions.text += "\n" + oCaption[1];
	};

Captionate also dispatches an event that calls onCaptionInfo( ), which notifies Flash as to the details of the language tracks. Captionate allows for more sophisticated caption data such as assigning a speaker (as in a person speaking) to each caption. You can read about each of the events in the Captionate help window.