Subtitle track management and VTT styling
PlayerSubtitlesAPI
Interface
Methods
add()
add(
subtitle):void
Adds a subtitle. isFragmented is not supported when tracks are added via this method.
Parameters
subtitle
the subtitle to add
Returns
void
cueEnter()
cueEnter(
cue):void
The player will fire a CueEnter event with the provided information.
Parameters
cue
the event containing data about the subtitle cue
Returns
void
cueExit()
cueExit(
cue):void
The player will fire a CueExit event with the provided information.
Parameters
cue
the event containing data about the subtitle cue
Returns
void
disable()
disable(
subtitleID):void
Disabled an enabled subtitle track.
Parameters
subtitleID
string
the id of the subtitle track to disable
Returns
void
enable()
enable(
subtitleID,exclusive?):void
Enables a subtitle track. Multiple tracks can be enabled concurrently depending on the exclusive flag.
Parameters
subtitleID
string
the id of the subtitle track to enable
exclusive?
boolean
Optional, default is true and all other enabled tracks will be disabled. When set to
false, the given track will be enabled additionally.
Returns
void
list()
list():
SubtitleTrack[]
Returns the list of all registered subtitles.
Returns
the list of all registered subtitles
remove()
remove(
subtitleID):void
Removes a subtitle. Disables it in case it's enabled before removal.
Parameters
subtitleID
string
the id of the subtitle track to remove
Returns
void
SubtitleTrack
Interface
Definition of a subtitle/caption track.
Extends
Properties
enabled?
optionalenabled?:boolean
Tells if a subtitle track is enabled or disabled. If set to true, the track will be enabled by default.
forced?
optionalforced?:boolean
Tells if a subtitle track is forced. If set to true it means that the player should automatically select and
switch this subtitle according to the selected audio language.
id
id:
string
The id of the media track that is used to identify and set the track.
Inherited from
isFragmented?
optionalisFragmented?:boolean
Indicates whether the subtitle is fragmented.
Inherited from
isSideloaded?
optionalisSideloaded?:boolean
Indicates whether the subtitle is sideloaded, i.e. it has been added through PlayerSubtitlesAPI.add or SourceConfig.subtitleTracks.
Since: 8.177.0
Inherited from
kind
kind:
string
The subtitle type, either "caption" or "subtitle" (default: "subtitle").
Inherited from
label
label:
string
The text used to represent this track to the user (e.g. in the UI).
Inherited from
lang
lang:
string
The language of the subtitle/caption track.
Inherited from
metadata?
optionalmetadata?:MediaTrackMetadata[]
Optional custom metadata about the track.
This is currently only supported for DASH manifests, where these are populated from SupplementalProperty elements.
Since: 8.243.0
Inherited from
role?
optionalrole?:MediaTrackRole[]
The optional roles of the track.
Inherited from
url?
optionalurl?:string
The URL to the associated file.
Inherited from
VTTProperties
Interface
Properties
align
align:
"start"|"center"|"end"|"left"|"middle"|"right"
An alignment for all lines of text within the cue box, in the dimension of the writing direction.
https://w3.org/TR/webvtt1/#webvtt-cue-text-alignment
id?
optionalid?:string
An optional ID.
line
line:
string|number
The line defines positioning of the cue box.
https://www.w3.org/TR/webvtt1/#webvtt-cue-line
lineAlign
lineAlign:
"start"|"center"|"end"
An alignment for the cue box’s line.
https://www.w3.org/TR/webvtt1/#webvtt-cue-line-alignment
position
position:
number|"auto"
The position defines the indent of the cue box in the direction defined by the writing direction.
https://www.w3.org/TR/webvtt1/#webvtt-cue-position
positionAlign
positionAlign:
"center"|"auto"|"line-left"|"line-right"
An alignment for the cue box in the dimension of the writing direction.
https://www.w3.org/TR/webvtt1/#webvtt-cue-position-alignment
region?
optionalregion?:VTTRegionProperties
An optional WebVTT region to which a cue belongs.
https://www.w3.org/TR/webvtt1/#webvtt-cue-region
size
size:
number
A number giving the size of the cue box, to be interpreted as a percentage of the video,
as defined by the writing direction.
https://www.w3.org/TR/webvtt1/#webvtt-cue-size
snapToLines
snapToLines:
boolean
A boolean indicating whether the line is an integer number of lines,
or whether it is a percentage of the dimension of the video.
https://www.w3.org/TR/webvtt1/#webvtt-cue-snap-to-lines-flag
vertical
vertical:
""|"rl"|"lr"
Writing direction.
https://www.w3.org/TR/webvtt1/#webvtt-cue-writing-direction
VTTRegionProperties
Interface
Properties
id
id:
string
ID of the region.
https://www.w3.org/TR/webvtt1/#webvtt-region-identifier
lines
lines:
number
Number of lines in region.
https://www.w3.org/TR/webvtt1/#webvtt-region-lines
regionAnchorX
regionAnchorX:
number
X coordinate within the region which is anchored to the video viewport.
https://www.w3.org/TR/webvtt1/#webvtt-region-anchor
regionAnchorY
regionAnchorY:
number
Y coordinate within the region which is anchored to the video viewport.
https://www.w3.org/TR/webvtt1/#webvtt-region-anchor
scroll
scroll:
""|"up"
Scroll value of the region.
https://www.w3.org/TR/webvtt1/#webvtt-region-scroll
viewportAnchorX
viewportAnchorX:
number
X coordinate within the video viewport to which the region anchor point is anchored.
https://www.w3.org/TR/webvtt1/#webvtt-region-viewport-anchor
viewportAnchorY
viewportAnchorY:
number
Y coordinate within the video viewport to which the region anchor point is anchored.
https://www.w3.org/TR/webvtt1/#webvtt-region-viewport-anchor
width
width:
number
Width of the region.
https://www.w3.org/TR/webvtt1/#webvtt-region-width
VTTStyleDeclaration
Interface
Properties
background
background:
string
backgroundAttachement
backgroundAttachement:
string
backgroundClip
backgroundClip:
string
backgroundColor
backgroundColor:
string
backgroundImage
backgroundImage:
string
backgroundOrigin
backgroundOrigin:
string
backgroundPosition
backgroundPosition:
string
backgroundRepeat
backgroundRepeat:
string
backgroundSize
backgroundSize:
string
color
color:
string
font
font:
string
fontFamily
fontFamily:
string
fontSize
fontSize:
string
fontStretch
fontStretch:
string
fontStyle
fontStyle:
string
fontVariant
fontVariant:
string
fontWeight
fontWeight:
string
lineHeight
lineHeight:
string
opacity
opacity:
string
outline
outline:
string
outlineColor
outlineColor:
string
outlineStyle
outlineStyle:
string
outlineWidth
outlineWidth:
string
rubyPosition
rubyPosition:
string
textCombineUpright
textCombineUpright:
string
textDecoration
textDecoration:
string
textDecorationColor
textDecorationColor:
string
textDecorationLine
textDecorationLine:
string
textDecorationStyle
textDecorationStyle:
string
textDecorationThickness
textDecorationThickness:
string
textShadow
textShadow:
string
visibility
visibility:
string
whiteSpace
whiteSpace:
string
VTTStyleProperties
Interface
Properties
identifier?
optionalidentifier?:string
Optional identifier of a cue
style
style:
Partial<VTTStyleDeclaration>
Applied css styles
TextTrack
Interface
Definition of a text track.
Extends
Extended by
Properties
id
id:
string
The id of the media track that is used to identify and set the track.
Inherited from
isFragmented?
optionalisFragmented?:boolean
Indicates whether the subtitle is fragmented.
isSideloaded?
optionalisSideloaded?:boolean
Indicates whether the subtitle is sideloaded, i.e. it has been added through PlayerSubtitlesAPI.add or SourceConfig.subtitleTracks.
Since: 8.177.0
kind
kind:
string
The subtitle type, either "caption" or "subtitle" (default: "subtitle").
label
label:
string
The text used to represent this track to the user (e.g. in the UI).
Inherited from
lang
lang:
string
The language of the subtitle/caption track.
metadata?
optionalmetadata?:MediaTrackMetadata[]
Optional custom metadata about the track.
This is currently only supported for DASH manifests, where these are populated from SupplementalProperty elements.
Since: 8.243.0
Inherited from
role?
optionalrole?:MediaTrackRole[]
The optional roles of the track.
Inherited from
url?
optionalurl?:string
The URL to the associated file.
SubtitleCuePosition
Interface
Positioning information for CEA captions.
Properties
column
column:
number
Number of the column (range from 0 to 31)
row
row:
number
Number of the row (range from 0 to 14)