Recipe 18.5. Adding Cue PointsCaptions

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.

1. From the Flash 8 Video Encoder window, click the Add button to add a file to the encoding queue.

2. Select the file from the queue list, and click the Settings button on the right.

3. The Flash Video Encoding Settings window opens. Make sure that it displays a preview of the correct video on the right side of the window. You ought to be able to move the playhead (the arrow above the playback bar) and scrub the video.

4. Click the Show Advanced Settings button.

5. From the advanced settings portion of the window, select the Cue Points tab.

6. Scrub the video to the point at which you want to add a cue point.

7. Click the + button in the Cue Points tab. That causes the encoder to add a new cue point to the list.

8. The default cue point name is New Cue Point. You can change the cue point name. The cue point name is sent to the event handler method when the cue point is dispatched.

9. Add parameters for the cue point if appropriate. Parameters are name-value pairs that you want to send to Flash with the cue point. For example, you might want to encode captions for several languages. In that case, you can use the language names as the parameter names, and the captions as the parameter values.

10. Repeat steps 7 and 8 as necessary.

11. Export the FLV. The cue points are embedded in the .flv file.

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, 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-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 (http://buraks.com/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:

1. Select File Open from the Captionate menus.

2. Open the Video Preview window by selecting View Video Preview Window.

3. In the Captions tab, specify the caption text in the Caption Text text area, and click Add Caption. That action adds the caption to the caption list. Note that you can edit the caption text from the caption list.

4. Repeat steps 4 and 5 as necessary.

5. If appropriate, add a new language track by clicking the New Language Track button at the top of the captions list.

6. Toggle between languages in the Language Track drop-down menu at the top of the captions list.

7. If appropriate, assign values to the caption text for each caption in the new language.

8. Save the file. Saving the file adds the captions to the FLV.

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.