"CC for Flash" Caption Component (v3.0.1)

"CC for Flash" is an Adobe Flash authoring component which synchronizes timed-text caption files with Flash objects containing audio, such as video playback, sound objects, animated movie clips or SWFs.

Creating Captions

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

Installation

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

Getting Started

Adding the CCforFlash component in the Flash Authoring Environment

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

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

Add CCforFlash component to the stage of your project
Drag an instance of CCforFlash from the Components (undering Captioning) panel 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 CCforFlash 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 CCforFlash instance
Below is a picture of the Component Inspector for a CCforFlash 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 CCforFlash will synchronize. Select one of the following:

2. Object name and path
Type the name and path.  This is the instance name of the object with which CCforFlash will synchronize. It must be spelled correctly, since CCforFlash 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 CCforFlash component (i.e. this._parent) or the absolute path from the main level of the movie.

3. Frame rate (for Flash Movie Objects)
Type the number of frames per second.  In order to synchronize correctly between timed caption files and animated objects, such as movie clips and SWFs, the number of frames per second is needed. The same frame rate that the object plays back at should be used to determine the timecode of the captions. In Flash MX 2004 and Flash 8, all loaded SWFs will playback at the frame rate of the main movie timeline in which they are placed.

4. Caption source type (replaces Captions embedded)
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 (replaces Caption filename)
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. 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. Area width and 10. Area height
Enter the values.  These set the dimensions of the caption display area. DO NOT use the object's handles to grow or shrink the CCforFlash object, since that will result in stretched text. Use these fields instead.

11. 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.

12. Background opacity
Enter the value.  This value sets the opacity (as a percentage, 0-100.) If you place the CCforFlash 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.

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

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

15. 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, Verdana, Times, etc.

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

17. Caption text weight
Select from normal or bold.

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

19. 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 CCforFlash component using ActionScript

The CCforFlash 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 CCforFlash 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. In the following list, instName is the instance name of the CCforFlash component placed in the Flash movie.

Property Description Value Notes
instName.captObjType Type of object to synchronize to String Values are:
  • Netstream Video Object
  • Any Flash Video Component
  • Flash Movie Object
  • Flash Sound Object
instName.captObjPath Object name and path String  
instName.captFrRate Frame rate (for Flash Movie Objects) Integer –
in frames per second
Used to synchronize animated objects (i.e. movie clips) to timed captions.
instName.captSrcType

(replaces instName.captEmbed)
Type of object containing the caption information String Values are:
  • external – external caption file
  • internal – internal text object
  • embedded – embedded within the FLV
Is included as part of the startCaptions method.
instName.captSource (replaces instName.captFilename) Caption source name String 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.
instName.captDispMode Method for displaying the captions String 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 switchDispMode method must be used to change the display mode as captions are being displayed.
instName.captDispLns Maximum lines of captions to display in roll-up mode Integer Used to identify how many lines of captions should appear in the caption area.
Is included as part of the switchDispMode method.
instName.captLanguage Caption language String 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>. 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.
instName.bgWidth Area width Numerical Sizing changes are better handled via the setSize method.
instName.bgHeight Area height Numerical Sizing changes are better handled via the setSize method.
instName.bgPadding Background padding Numerical Padding changes are better handled via the setSize method.
instName.bgAlpha Background opacity Integer,
percentage 0-100
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.
instName.bgColor Background color Color name (e.g. red) or hex 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.
instName.captColor Caption text color 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.
instName.captFont Caption font String This value can also be set in the global style setting of an external caption file.
instName.captSize Caption text size Numerical This value can also be set in the global style setting of an external caption file.
instName.captWeight Caption text weight String Values are:
  • normal
  • bold
This value can also be set in the global style setting of an external caption file.
instName.captAlign Caption alignment String Values are:
  • center
  • left
  • right
This value can also be set in the global style setting of an external caption file.
instName.captOvStyl Override caption file style Boolean 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.


Methods Description Notes
instName.startCaptions(type, source, language, override) Start a new caption source. Use this to parse and start up a new caption source.
  type required, string External, if caption data is in an external timed text file.
Internal, if caption data is inside an internal text object.
Embedded, if caption data is embedded in the FLV.
  source optional, string 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 optional, string 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 optional, true/false 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.
instName.switchDispMode(type, lines) Change caption display mode. Use this to change the display mode of the captions on-the-fly.
  type string Value must be either:
  • pop-on
  • roll-up
  lines optional, number Used when display mode is set to roll-up to identify how many lines of captions should appear in the caption display area.
instName.clearCaptions() Clear caption display area. Stops synchronizing the captions and clears the caption display area. If a caption source is not provided when the component is initialized, this can be used to clear the caption display of its sample text.
instName.getLanguages() Retrieve languages available from the DFXP file. 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. Setting up an interval (timer) can be useful for this case.
instName.getLanguage() Retrieve the currently playing language in the component. Returns a 2-letter language code, defined in ISO 639-1. If unspecified, returns "default".
instName.changeLanguage(language) Select a specific language from the DFXP file. Identifies which language <div> to select in a DFXP file. (Ignored for QTtext and SAMI.)
  language required, string Must match the value defined in the xml:lang attribute of the <div>. Valid values specified in ISO 639-1.
instName.findString( textStringToSearchFor ) Search for a string in the captions, returns timecode of caption with matched string, if found. Note: Only works for external, not embedded captions.
  textStringToSearchFor required, string
Searches for textStringToSearchFor in the captions starting at the current time position of the video being played. Once the search reaches the end of the video it wraps to the beginning. If textStringToSearchFor is found, the caption time, in seconds (as Number), is returned. If not found, then -1 is returned.
instName.checkFileLoad() Retrieve the status of loading captions. Returns one of the following string values based on the status of captions being loaded and processed:
  • loading
  • loaded
  • failed*
*Reasons why the process might have failed include:
  • the caption URI or text object name was incorrect
  • the caption source type was incorrect
  • the caption information was not properly formatted
instName.getCCforFlashVersion() Retrieve the version of the component. Returns a string of the form "x.y.z" where x, y, and z are integers.
instName.setSize(width, height, padding) Resize the caption area. Adjusts the width and height of the caption area, along with the padding between the caption text and the background box.
  width required, numerical Total width of the caption area.
  height required, numerical Total height of the caption area.
  padding optional, numerical Amount of padding between the caption text and the background area.
instName.setbgColor(color) 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 required, color name (e.g. red) or hex format (#rrggbb  e.g. #ff0000)  
instName.setbgOpacity(opacity) 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 required, numerical percentage 0-100
instName.getCaptText() Retrieve the caption text. Returns an array containing the text from each of the captions. Only available for external and internal caption source types.
instName.getCaptStTime() Retrieve the caption start times. Returns an array containing all of the start times for each of the captions. Only available for external and internal caption source types.
instName.getCaptEndTime() Retrieve the caption end times. Returns an array containing all of the end times for each of the captions. Only available for external and internal caption source types.

Recognized color names

The following color names are recognized by the CCforFlash component.

black green
silver lime
gray olive
white yellow
maroon navy
red blue
purple teal
fuchsia aqua
magenta cyan
transparent (background only)

Known Issues

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

ActionScript 3.0
If you are authoring your projects using Flash CS3, you will not see the CCforFlash component while working on projects in the ActionScript 3.0 environment. In order to use CCforFlash, you'll need to create an ActionScript 2.0 project.

CCforFlash component contained in a SWF, loaded in a movie
If you have loaded a SWF that contains the CCforFlash component into a movie, placing another CCforFlash component in the movie will interrupt the caption playback. This is only the case for CCforFlash components contained in a SWF. Multiple instances of the component can exist in a movie (outside of a loaded SWF) without interference, as long as each has been given a different instance name.

Technical Support

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