Tools & Guidelines
CCforFlash AS2 Help Documentation
"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:
- Add CCforFlash component to the stage of your project.
- Fill in the fields of the Component Inspector for the CCforFlash instance.
- 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:
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:
- Netstream Video Object – if synchronizing to ActionScript-controlled video objects from the Library
- Any Flash Video Component – if synchronizing to MediaDisplay or MediaPlayback (Flash MX 2004 [v7]) or FLVPlayback (Flash 8) video playback components
- Flash Movie Object – if synchronizing to the main movie timeline, movie clips or loaded SWFs
- Flash Sound Object – if synchronizing to sound objects that are either loaded (loadSound) or embedded (attachSound)
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:
- 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 CCforFlash 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.02):
- 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.
- SAMI (not yet implemented) - Synchronized Accessible Media Interchange. The timed-text format used by Microsoft Windows Media Player.
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:
- 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
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:
|
| 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:
|
| 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:
|
| 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:
|
| instName.captAlign | Caption alignment | String |
Values are:
|
| instName.captOvStyl | Override caption file style | Boolean |
Values are:
|
| 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:
|
| 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:
|
| 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.