The TextTrack API describes all the properties, methods and events related to the text tracks available from the instantiated player. This includes both text tracks sideloaded through the SourceDescription, as well as text tracks embedded in the stream.

For the TextTrackDescription for sideloading text tracks, go to the SourceDescription API.

TextTrackList

A TextTrackList lists all available TextTrack objects that the player can display.

Properties

The TextTrackList object provides the following properties:

Property Type Description
length number Returns the number of text tracks in the list of text tracks
[n] TextTrack Returns the TextTrack object representing the nth text track in the media element's list of text tracks

Methods

The TextTrackList object provides the following methods:

Method Arguments Description
addEventListener type: string, listener: EventListener Adds the given listener to the TextTrackList for the given event type.
item n: number Returns the TextTrack object representing the nth text track in the media element's list of text tracks.
removeEventListener type: string, listener: EventListener Removes the given listener from the TextTrackList for the given event type.

Events

The TextTrackList object exposes the following events:

Event Description
addtrack Thrown to indicate that a track has been added to the track list.
  • track : the TextTrack which was just added to the track list.
change Thrown to indicate that one or more tracks in the track list has switched its state.
removetrack Thrown to indicate that a track has been removed from the track list. 

TextTrack

A TextTrack object is an element that represents a single text track that can be displayed in the player.

Properties

The TextTrack object provides the following properties:

Property Type Description
activeCues TextTrackCueList The text track’s list of active TextTrackCue objects as a TextTrackCueList. This list dynamically updates as time progresses so that it includes all cues that are currently active. Currently active cues are ones that start before the current playback position and end after it.
cues TextTrackCueList The text track’s list of TextTrackCue objects as a TextTrackCueList. This list includes all of the text track’s known cues.
id string The unique ID of the given track.
kind string The text track kind string.
  • 'subtitles': The track defines subtitles, used to display subtitles in a video.
  • 'captions': The track defines translation of dialogue and sound effects. (suitable for deaf users)
  • 'descriptions': The track defines a textual description of the video. (suitable for blind users)
  • 'chapters': The track defines chapter titles. (suitable for navigating the media resource)
  • 'metadata': The track defines content used by scripts. Not visible for the user.
label string The text track label, if there is one, or the empty string otherwise. (indicating that a custom label probably needs to be generated from the other attributes of the object if the object is exposed to the user)
language string The text track language string. This is often a ISO639/2 language string.
mode string The text track mode.
  • 'disabled': The track is disabled, meaning that is not displayed. Moreover, the track does not fire cuechange events, there are no active cues.
  • 'hidden': The track is hidden, meaning that is not displayed but that new cues are actively being added and maintained, cuechange events are being fired.
  • 'showing': The track is displaying and cues are actively being added and maintained, cuechange events are being fired.
type string The content type of the given track
  • 'emsg': The track contains eMsg content.
  • ‘eventstream’: The track contains content from EventStream tags in the active DASH MPD.
  • 'srt': The track contains SRT (SubRip Text) content.
  • 'ttml': The track contains TTML (Timed Text Markup Language) content.
  • 'webvtt': The track contains WebVTT (Web Video Text Tracks) content. 

Methods

The TextTrack object provides the following methods:

Method Arguments Description
addEventListener type : string, listener : EventListener Adds the given listener to the TextTrack for the given event type.
removeEventListener type : string, listener : EventListener Removes the given listener from the TextTrack for the given event type.

Events

The TextTrack object exposes the following events:

Event Description
cuechange Thrown to indicate that a TextTrackCue in the text track changed.
addcue Dispatched when a TextTrackCue was added to the cues-list.
removecue Dispatched when aTextTrackCue  was removed from the cues-list. 

TextTrackCueList

A TextTrackCueList is a list of TextTrackCue objects for a given TextTrack.

Properties

The TextTrackCueList object provides the following properties:

Property Type Description
length number The number of cues in the list of text track cues.
[n] TextTrackCue The nth TextTrackCue in a given list.

Methods

The TextTrackCueList object provides the following methods:

Method Arguments Description
item n: number Returns the nth TextTrackCue in a given list.

TextTrackCue

A TextTrackCue object represents an individual cue and provides methods and properties to access the data and events to act on changes to cue state. Depending on the TextTrack’s type, a cue might have different properties.

Properties

The TextTrackCue object provides the following properties:

Property Type Description
content any The cue’s content, which differs depending on the track’s type.
  • track.type is 'emsg': content contains a Uint8Array representing the binary message data from the emsg box.
  • track.type is 'eventstream': content contains the value of the messageData attribute which was specified in the manifest.
  • track.type is 'ttml': content contains an intermediate TTML document’s body element. This is a view of a TTML document where all nodes in the document are active during the cue’s startTime and endTime. As a result, all begin, dur and end properties have been removed. TTML Styles, Regions and Metadata are stored in cue.styles, cue.regions, cue.metadata respectively. Combining those properties with the given content should suffice to render a TTML cue.
  • track.type is 'webvtt': content contains the text track cue text in raw unparsed form.
endTime number The time in seconds and relative to a THEOplayer instance’s currentTime at which the cue becomes inactive.
id string The cue’s unique ID.
startTime number The time in seconds and relative to a THEOplayer instance’s currentTime at which the cue becomes active.
track TextTrack The track the given cue belongs to.

EMSG-Only Properties

The EMSG Cue has the following additional properties:

Property Type Description
emsgID number The id of the message. This integer is unique within the scope of the period.
schemeIDURI string The schemeIDURI for this emsg.
value string The value of the SCTE 35 PID (Program Identifier).

EventStream-Only Properties

The EventStream Cue has the following additional properties:

Property Type Description
attributes  {[attributeName : string] : string}  An object where the keys are the names of attributes that are available on the XML tag in the manifest for this event and the values are the corresponding values. One example would be cue.attributes.eventID which evaluates to the value of the Event’s eventID property.
Use this object to query any custom attributes added to an Event in the manifest

TTML-Only Properties

The TTML Cue has the following additional properties:

Property Type Description
metadata any The <metadata> Element of the corresponding TTML document.
regions {[regionID : string] : {[propertyName: string] : string}} A dictionary of dictionaries where, given a TTML regionID, you get a dictionary that maps region property names to their values.
styles {[styleID : string] : {[propertyName: string] : string}} A dictionary of dictionaries where, given a TTML styleID, you get a dictionary that maps style property names to their values.

WEBVTT-Only Properties

The WEBVTT Cue has the following additional properties:

Property Type Description
align string A string representing the WebVTT cue text alignment, following the WebVTT specification.
line string OR number The WebVTT cue line, following the WebVTT specification.
lineAlign string A string representing the WebVTT cue line alignment, following the WebVTT specification.
position string OR number The WebVTT cue position, following the WebVTT specification.
positionAlign string A string representing the WebVTT cue position alignment, following the WebVTT specification.
region WebVTTRegion The VTTRegion object to which this cue belongs, the WebVTTRegion objects follows the WebVTT specification for WebVTTRegions.
snapToLines boolean True if the WebVTT cue snap-to-lines flag is true, false otherwise, following the WebVTT specification.
size number The WebVTT cue size, following to the WebVTT specification.
text string The text track cue text in raw unparsed form, following to the WebVTT specification.
vertical string A string representing the WebVTT cue writing direction, following the WebVTT specification.

Methods

The TextTrackCue object provides the following methods:

Method Arguments Description
addEventListener type : string, listener : EventListener Adds the given listener to the TextTrackCue for the given event type.
removeEventListener type : string, listener : EventListener Removes the given listener from the TextTrackCue for the given event type.

Events

The TextTrackCue object exposes the following events:

Event Description
enter Thrown when a cue switches to an active state.
exit Thrown when a cue switches to an inactive state.