CCforFlashAS3 Caption Component (v1.0.1)

CCforFlashAS3 is an Adobe Flash authoring component which synchronizes timed-text caption files with Flash objects containing audio; such as video objects, sound objects, animated movieclips or SWFs.

Creating Captions

For information on how to author captions for use with CCforFlashAS3, please refer to Authoring Captions for Flash.

Installation

To install CCforFlashAS3 in your Flash authoring environment, double click the CCforFlashAS3.mxp file, or start the Flash Extensions Manager to open CCforFlashAS3.mxp. After installation, the CCforFlashAS3 component will be visible in the Components Window, under Captioning.

Getting Started

Adding the CCforFlashAS3 component in the Flash Authoring Environment

Adding and wiring a CCforFlashAS3 component to your project in Flash's authoring environment involves the following steps:

1. Add CCforFlashAS3 component to the stage of your project.
2. Fill in the fields of the Component Inspector for the CCforFlashAS3 instance.
3. Publish your SWF.

Add CCforFlashAS3 component to the stage of your project
Open a Flash File (ActionScript 3.0) and drag an instance of CCforFlashAS3 from the Components panel (under Captioning) onto the stage, positioning it where you want the captions to be displayed. This is typically underneath an animated or FLV playback object, but could be on top of the object, if you want the captions to be displayed directly over the animation or video. The CCforFlashAS3 instance has some default text in the caption display area to help with positioning and to give feedback on selected font and display attributes during Flash authoring.

Fill in the fields in the Component Inspector for the CCforFlashAS3 instance
Below is a picture of the Component Inspector for a CCforFlashAS3 object that is sychronized to a Netstream video object:



There are several fields that allow for setting default text and display attributes. In the absence of specific text ornamentation and formatting in the external caption file, these settings are used.

1. Object type to sync to
Select the type. This indicates the type of object to which CCforFlashAS3 will synchronize. Select one of the following:

• Netstream Video Object – if synchronizing to a NetStream video object
• Flash FLVPlayback Component – if synchronizing to Flash's built-in FLVPlayback (video playback) component
• Flash MovieClip Object – if synchronizing to the timeline of the main movie, movieclip or loaded SWF

Note: Flash's Sound object is currently not an option for synchronization. Problems maintaining synchronization with Flash's SoundChannel object prevent its use at this time.

2. Object name and path
Type the name and path. This is the instance name of the object with which CCforFlashAS3 will synchronize. It must be spelled correctly, since CCforFlashAS3 will query the object with this name for timing information in order to synchronize the captions. The path must also be included; either relative to the CCforFlashAS3 component (i.e. this.parent) or the absolute path from the main level of the movie (root).

3. Frame rate (for Flash MovieClip Objects)
Type the number of frames per second. In order to synchronize correctly between timed caption files and animated objects, such as movieclips and SWFs, the number of frames per second is needed. The frame rate entered in this field should be the frame rate that was used to determine the timecodes listed in the caption file. If the frame rate is changed at run-time, it should have no effect on the sychronization of the captions.

4. Caption source type
Select the type. This indicates the type of object where the caption information can be found. Options are:

• external – external caption file
• internal – internal text object
• embedded – embedded within the FLV

Caption data can be embedded in the FLV using various third-party tools (for example, Captionate).
Note: Only the Netstream Video Object can be used in conjunction with the CCforFlashAS3 component to synchronize video with captions that are embedded.
For external caption files and internal text objects, the caption information must be in one of the following formats (all can be created by MAGpie v2.5.1):

DFXP - The W3C's Timed-Text Authoring Format 1.0 - Distribution Format Exchange Profile.
QTtext - Quicktime Text descriptor. The timed-text format used by Apple Quicktime Player.

5. Caption source
Type the name. If the caption source type is external, this is a URI to the external timed-text file. If the caption source type is internal, this is the name and path to an internal text object (String variable or textfield.text). If the caption source type is embedded, this property is left blank.

6. Caption-display mode
Select the type. This indicates how the captions should be displayed. Options are:

• pop-on – each caption is popped onto the caption area, overwriting the previous caption
• roll-up – each caption appears towards the bottom of the caption area and is rolled-up a line when the next caption appears (caption length must be limited to one line each)

7. Max number of rows (roll-up)
Type the number of rows. For roll-up display of captions, the number of rows that are being displayed in the caption area can been adjusted. The default is three rows of captions.

8. Caption language
Type the language. This must match an item from the ISO 639-1 list of two-letter language codes. The DFXP format allows for multiple languages in the same file. If this is blank, and a DFXP file is used, the first caption set is used. Similarly, if the language identifier specified here doesn't match any of the languages available in a DFXP file, then the first language in the DFXP file becomes the displayed language.

9. Background padding
Enter the value. This value sets the amount of padding between the caption area background and the caption text. Applying too much padding could result in fewer lines of captions being displayed due to word wrap and/or truncation.

10. Background opacity
Enter the value. This value sets the opacity (as a percentage, 0-100.) If you place the CCforFlashAS3 instance directly on top of your video playback object, then you can adjust the opacity in order to see the video underneath. You can experiment with the setting to get just the right amount of bleed-through.

11. Background color
Enter the value in named (e.g. red) or hex format (#rrggbb e.g. #ff0000).

12. Caption text color
Enter the value in named (e.g. red) or hex format (#rrggbb e.g. #ff0000).

13. Caption font
Select from the list of fonts. It's best to select, if possible, fonts that are common across all computer platforms, such as Arial, Times New Roman, etc.

14. Caption text size
Enter the value in points. The actual text sizes displayed will vary across different browsers and platforms.

15. Caption text weight
Select from normal or bold.

16. Caption alignment
Select from center, left, or right.

17. Override caption file style
Select true or false. This indicates whether to override the global style settings found in external caption files in favor of the settings indicated by the author (true) or to use the global style settings in the file (false). Inline styles are always observed (DFXP). Note: Setting this value to true may result in irrational combinations of Flash-author style selections and DFXP-in-line styles. For example, the Flash author could select a red background and set the override to true. If the DFXP in-line style sets the text color to red, the result would be invisible text.

Adding the CCforFlashAS3 component using ActionScript

The CCforFlashAS3 component can be added to a Flash project using ActionScript at runtime. Each of the properties listed in the component inspector above are available at runtime. All of the CCforFlashAS3 properties and methods are listed in the Programming API section which follows. Please note that some properties are better accessed via built-in methods.

Programming API

In order to make it easy for a Flash developer to incorporate a CCforFlash component into a custom player, CCforFlash implements properties and methods that can be referenced via ActionScript.

Programming API

In order to make it easy for a Flash developer to incorporate a CCforFlash component into a custom player, CCforFlash implements properties and methods that can be referenced via ActionScript.

Property	Description	Notes
captObjType:String	Type of object to synchronize to	Values are: Netstream Video Object Flash FLVPlayback Component Flash MovieClip Object
captObjPath:String	Object name and path	Valid entries for linking to a Flash movie's timeline are: this, root, and blank.
captFrRate:Number	Frame rate (for Flash MovieClip Objects)	Frames per second. Used to synchronize animated objects (i.e. movieclips) to timed captions. This is the frame rate used to determine the timecodes entered in the caption file, not the frame rate of the Flash movie at run-time.
captSrcType:String	Type of object containing the caption information	Values are: external – external caption file internal – internal text object embedded – embedded within the FLV Is included as part of the startCaptions method.
captSource:String	Caption source name	Value will depend on source type. External source type will contain the DFXP or QTtext file URI. Internal source type will contain the name and path of the internal text object. Is included as part of the startCaptions method.
captDispMode:String	Method for displaying the captions	Values are: pop-on – each caption overwrites the previous caption roll-up – each caption is rolled up a line when a new caption appears The switchDefaultDisplayMode method must be used to change the display mode as captions are being displayed.
captDispLns:Number	Maximum lines of captions to display in roll-up mode	Used to identify how many lines of captions should appear in the caption area. Is included as part of the switchDefaultDisplayMode method.
captLanguage:String	Caption language	Used to identify which language <div> to select in a DFXP file. (Ignored for QTtext.) Must match the value defined in the xml:lang attribute of the <div>. Valid values specified in ISO 639-1. Is included as part of the startCaptions method or can be changed during caption playback using the changeLanguage method.
bgPadding:Number	Background padding	Amount of padding (in pixels) between the caption area background and the caption text.
bgAlpha:Number	Background opacity	In order for the change to be implemented, the startCaptions method must follow. Using the setbgOpacity method will take care of this. This value can also be set in the global style setting of external caption files.
bgColor:String	Background color	Valid entries are color name (e.g. red) or hex RGB format (#rrggbb e.g. #ff0000). Return value is in hex format. In order for the change to be implemented, the startCaptions method must follow. Using the setbgColor method will take care of this. This value can also be set in the global style setting of external caption files.
captColor:String	Caption text color	Valid entries are Color name (e.g. red) or hex format (#rrggbb e.g. #ff0000). Return value is in hex format. This value can also be set in the global style setting of an external caption file.
captFont:String	Caption font	This value can also be set in the global style setting of an external caption file.
captSize:Number	Caption text size	This value can also be set in the global style setting of an external caption file.
captWeight:String	Caption text weight	Values are: normal bold This value can also be set in the global style setting of an external caption file.
captAlign:String	Caption alignment	Values are: center left right This value can also be set in the global style setting of an external caption file.
captOvStyl:Boolean	Override caption file style	Values are: true – override global styles found in external caption files false – use global styles found in external caption files Is included as part of the startCaptions method.
currentDisplayMode:String [read only]	Returns current display mode set by the author or found in the current caption data being displayed	Values are: pop-on roll-up
defaultDisplayMode:String [read only]	Returns display mode set by the author	Settings found in the caption data can override this value. Values are: pop-on roll-up
currentLanguage:String [read only]	Returns current language being displayed
captionLoadStatus:String [read only]	Returns status of captions being loaded	Values are: loading loaded failed
currentRunMode:String [read only]	Returns current mode of running	Values are: sync (timecodes from object) manual (timecodes entered manually)
currentCaptionText:String [read only]	Returns current caption being displayed (text)	Only the text of the caption is provided.
currentCaptionHTMLText:String [read only]	Returns current caption being displayed (htmlText)	String includes HTML tags and CSS styles. The parsed CSS stylesheet can be retrieved using currentCaptionStyleSheet.
currentCaptionStyleSheet:StyleSheet [read only]	Retrieves the stylesheet parsed from the caption data
CCforFlashVersion:String [read only]	Returns the version number of this CCforFlash component

Methods	Description/Notes
setSize(width:Number, height:Number):void	Sets the width and height of the CCforFlashAS3 caption area.
width	width of component area
height	height of component area
startCaptions(type:String="none", source:String="none", language:String="none", override:String="none"):void	Use this to parse and start up a new caption source.
type	If not included, the default value in captSrcType is used. Values are: external – external caption file internal – internal text object embedded – embedded within the FLV
source	If not included, the default value in captSource is used. If source is external, DFXP or QTtext file URI needed. If source is internal, the name and path of the text object is needed. If source is embedded, then this value is not included.
language	If not included, the default value in captLanguage is used. Used to identify which language <div> to select in a DFXP file. (Ignored for QTtext and SAMI.) Must match the value defined in the xml:lang attribute of the <div>. If missing and embed is false, previous language is used. Valid values specified in ISO 639-1.
override	If not included, the default value in captOvStyl is used. True, if overriding the global style settings found in external caption files in favor of the settings indicated by the author. False, to use the global style settings in the file.
getLanguages():Array	Returns an array of two-letter language codes, coded as ISO 639-1. If no languages are specified in the DFXP file, then the array returned has a single element with a value of "default". If the array returns null, then parsing of the input file is incomplete and should be checked later. Use the captionLoadStatus to check when a caption file has been completely loaded and parsed.
changeLanguage(language:String):void	(Ignored for QTtext captions.) If multiple languages have been provided, this changes the current language being displayed. The array of available languages can be retrieved using getLanguages()
language	Must match the value defined in the xml:lang attribute of the <div>. Valid values specified in ISO 639-1.
setbgColor(color:String):void	Change the background color of the caption area. This method takes care of all of the steps needed to implement the background color change.
color	Valid values are color names (e.g. red) or hex RGB formats (#rrggbb e.g. #ff0000).
setbgOpacity(opacity:Number):void	Change the background transparency of the caption area. This method takes care of all of the steps needed to implement the change to the transparency of the background.
opacity	Value ranges from 0-100.
clearCaptions():void	Stops synchronizing the captions and clears the caption display area.
getCaptionContent():Array	Returns an array containing the caption data parsed from the caption source. Only available for external and internal caption source types. The following structure is used: arrayitem[i].caTxt = caption text arrayitem[i].caBegin = caption start time arrayitem[i].caEnd = caption end time arrayitem[i].caBg = caption background color arrayitem[i].caOp = caption background opacity
getCaptionStyles():Array	Returns an array containing the styles of each caption parsed from the caption source. Only available for external and internal caption source types. The following structure is used: arrayitem[i].id = id of caption (used by CSS StyleSheet) arrayitem[i].wfont = font weight arrayitem[i].stfont = font style arrayitem[i].dfont = font decoration arrayitem[i].ffont = font face arrayitem[i].szfont = font size arrayitem[i].cfont = font color arrayitem[i].afont = text alignment arrayitem[i].bgclr = background color arrayitem[i].opval = background opacity
findString(textStringToSearchFor:String):Number	Returns the timecode (in seconds) where a search string was found. This search feature is capable of searching for terms that span across multiple captions. When a search is repeated, the next instance of the encountered text string is returned. Once the search reaches the end of the video it wraps to the beginning. If the string does not match any content in the caption data, -1 is returned. Note: Only works for external, not embedded captions.
textStringToSearchFor	Text string to search for in the caption content.
switchDispMode(type:String, lines:Number=-99):void	Use this to change the display mode of the captions on-the-fly.
type	Value must be either: pop-on roll-up
lines	If not included, the default value in captDispLns is used. Used when display mode is set to roll-up to identify how many lines of captions should appear in the caption display area.
runManually():void	Switches run modes, so synchronization to an object stops and timecodes are provided to CCforFlashAS3 manually, using displayManualCaption.
runSynchronized():void	Switches run modes back to synchronization with an object. CCforFlashAS3 will synchronize with the object found in captObjPath.
displayManualCaption(time:String):void	Displays the caption that appears at the timecode provided.
time	Valid format of timecodes are: 00:00:00.000 (hours : minutes : seconds . milliseconds) 000 (seconds) 00.0 h (hours) 00.0 m (minutes) 00.0 s (seconds) 00.0 ms (milliseconds)

Roll-up display in DFXP

While the DFXP timed-text format, currently, does not have the means of indicating that the display of captions should be done as a roll-up, CCforFlashAS3 supports the inclusion of this information in DFXP's metadata. This is done adding the following code to your DFXP file:

<?xml version="1.0" encoding="UTF-8"?>
<tt xml:lang="en" xmlns="http://www.w3.org/2006/04/ttaf1" xmlns:tts="http://www.w3.org/2006/04/ttaf1#styling" xmlns:ttm="http://www.w3.org/2006/10/ttaf1#metadata">
<head>
<metadata>
<ttm:displayMethod>rollup</ttm:displayMethod>
</metadata>

Recognized color names

CCforFlashAS3 recognizes the X11 colors supported by popular browsers. A list of these colors and their corresponding hex RGB values can be found on the working draft of the W3C's CSS3 module: Color 4.3. X11 color keywords.

Accessibility

Currently, CCforFlashAS3 is set to be visible to screen readers. Whenever a new caption is displayed, the buffer which the screen reader reads from, is updated with the current caption text. CCforFlashAS3 has been tested with the JAWS (version 9) and Window Eyes (version 7) screen readers, with the following results:

• JAWS and IE - When the buffer is updated, the user's current position does not change. The caption text is read by navigating to it.
• JAWS and Firefox - When the buffer is updated, the user's current position does not change. However, if white text appears on a black background (typical for captions), the text gets automatically read. (This appears to be a bug.)
• Window Eyes and IE - If the user navigated to the caption text while the video was playing the caption text did not appear to be in the buffered content. When the video was stopped and the captions were no longer being updated, Window Eyes read the caption text when it was navigated to.

When CCforFlashAS3 is hidden, the caption content is no longer updated in the screen reader's buffer.

Known Issues

QTtext inline styles ignored

Currently, the CCforFlash component only recognizes QTtext styles that are set globally. Any inline styles are ignored.

Synchronization with SoundChannel is not available.

Currently, CCforFlashAS3 can not be synchronized with a SoundChannel object. During the course of development and testing, synchronization problems occurred. Therefore, this feature was remove from this version of the component. It may be added to subsequent versions.

Technical Support

For technical support, please use the public CCforFlash listserv. To subscribe send an e-mail to requests AT mail4 DOTwgbh DOT org with the words subscribe CCforFlash in the subject.