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:

screengrab of component inspector


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:

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:

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.02):

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:

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.

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:

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.