Packagecom.brightcove.api.modules
Classpublic class CaptionsModule
InheritanceCaptionsModule Inheritance APIModule Inheritance flash.events.EventDispatcher

API class for handling captions. Captions are displayed in the player after being loaded or changed here. All captions must current be in Timed Text Markup Language. These are found in a DFXP file, as described here: http://www.w3.org/TR/ttaf1-dfxp/ See the article, Using the Player API for Closed Captioning, for a code example that uses the CaptionsModule to insert captions in your Brightcove video.



Public Properties
 PropertyDefined By
 Inheritedmodule : Object
[read-only] Returns the instance of the module that is wrapped by this instance.
APIModule
Public Methods
 MethodDefined By
  
CaptionsModule(module:Object)
Constructor.
CaptionsModule
 Inherited
addEventListener(type:String, listener:Function, useCapture:Boolean = false, priority:int = 0, useWeakReference:Boolean = true):void
[override] Adds a listener for an event.
APIModule
  
Returns the current player state for caption display.
CaptionsModule
  
getLanguages(videoID:Number = 0):Array
Returns the languages used in the captions for a video.
CaptionsModule
  
Returns the style/formatting options for captions.
CaptionsModule
  
loadDFXP(url:String, videoID:Number = 0):void
Asynchronously load the DFXP file and associate with a video ID.
CaptionsModule
 Inherited
removeEventListener(type:String, listener:Function, useCapture:Boolean = false):void
[override] Removes a listener for an event.
APIModule
  
setCaptionsEnabled(enable:Boolean):void
Sets the player state for displaying captions.
CaptionsModule
  
setLanguage(language:String):void
Sets the language to use for captions.
CaptionsModule
  
setStyleOptions(style:String):void
Sets the style/formatting options for captions.
CaptionsModule
  
showOptions(loadModule:Boolean = true):Boolean
Show the caption options dialog
CaptionsModule
Events
 Event Summary Defined By
  Dispatched when there was an error when loading or parsing a DFXP file after calling loadDFXP()CaptionsModule
  Dispatched when a DFXP file has been loaded and parsed successfully after calling loadDFXP()CaptionsModule
Constructor Detail
CaptionsModule()Constructor
public function CaptionsModule(module:Object)

Constructor.

Parameters
module:Object — module to wrap with this API class.
Method Detail
getCaptionsEnabled()method
public function getCaptionsEnabled():Boolean

Returns the current player state for caption display.

Returns
Boolean
getLanguages()method 
public function getLanguages(videoID:Number = 0):Array

Returns the languages used in the captions for a video. If no video ID is given, then the current video is selected. If no captions are found, then an empty Array is returned.

Parameters

videoID:Number (default = 0) — The video ID for the languages. If a video ID isn't given, the current video is checked.

Returns
Array — An array of all languages used within the captions of the chosen video.
getStyleOptions()method 
public function getStyleOptions():String

Returns the style/formatting options for captions. These settings override any default values, as well as any attributes set in the DFXP

Returns
String — A CSS-format string with the values that are currently set (if any)
loadDFXP()method 
public function loadDFXP(url:String, videoID:Number = 0):void

Asynchronously load the DFXP file and associate with a video ID. If a video ID isn't given, the DFXP file is loaded for the current video. After the DFXP file is loaded and parsed, the captions will be displayed whenever the given video is played. Events are dispatched for load error or success. To interact with the loaded DFXP file, make sure to add listeners for the dfxpLoadError and dfxpLoadSuccess events.

Download the example of this method in the article, Displaying DFXP Captions for a Video.

Currently, the CaptionsModule supports a subset of the DFXP standard: supported attributes include lang, begin, and end. Here is some sample DFXP:

         <tt xmlns="http://www.w3.org/ns/ttml">
         <body>
             <div xml:lang="en"> 
                <p xml:id="subtitle1" begin="0.76s" end="3.45s">
                   This is a sample caption.
                </p>
             </div>
         </body>
         </tt>
         

Parameters

url:String — The URL for the DFXP file
 
videoID:Number (default = 0) — The video ID to associate the captions with. If a video ID isn't given, the DFXP file is loaded for the current video.

setCaptionsEnabled()method 
public function setCaptionsEnabled(enable:Boolean):void

Sets the player state for displaying captions. If this is set to true, captions will be displayed for videos that have captions files associated with them, using the selected (or default) language

Parameters

enable:Boolean

setLanguage()method 
public function setLanguage(language:String):void

Sets the language to use for captions. If a language hasn't been specified through this API, "en" is used. This language needs to have corresponding lang elements within the loaded DFXP files for any captions to be displayed. This language should be a ISO 639-1 Code as specified here: http://www.loc.gov/standards/iso639-2/php/code_list.php. Pass a null value to turn off captions.

Parameters

language:String — The current language for captions

setStyleOptions()method 
public function setStyleOptions(style:String):void

Sets the style/formatting options for captions. These settings override any default values, as well as any attributes that are set in the DFXP file

Parameters

style:String — string of attributes to set. Passing an attribte with no value will clear that setting

showOptions()method 
public function showOptions(loadModule:Boolean = true):Boolean

Show the caption options dialog

Parameters

loadModule:Boolean (default = true)

Returns
Boolean
Event Detail
dfxpLoadError Event
Event Object Type: com.brightcove.api.events.CaptionsEvent
CaptionsEvent.type property = com.brightcove.api.events.CaptionsEvent.DFXP_LOAD_ERROR

Dispatched when there was an error when loading or parsing a DFXP file after calling loadDFXP()

dfxpLoadSuccess Event  
Event Object Type: com.brightcove.api.events.CaptionsEvent
CaptionsEvent.type property = com.brightcove.api.events.CaptionsEvent.DFXP_LOAD_SUCCESS

Dispatched when a DFXP file has been loaded and parsed successfully after calling loadDFXP()