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
| Name | Type | Description |
|---|---|---|
subtitle | SubtitleTrack | the subtitle to add |
Returns
void
cueEnter
▸ cueEnter(cue): void
The player will fire a CueEnter event with the provided information.
Parameters
| Name | Type | Description |
|---|---|---|
cue | SubtitleCueEvent | 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
| Name | Type | Description |
|---|---|---|
cue | SubtitleCueEvent | the event containing data about the subtitle cue |
Returns
void
disable
▸ disable(subtitleID): void
Disabled an enabled subtitle track.
Parameters
| Name | Type | Description |
|---|---|---|
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
| Name | Type | Description |
|---|---|---|
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
| Name | Type | Description |
|---|---|---|
subtitleID | string | the id of the subtitle track to remove |
Returns
void
SubtitleTrack
Interface
Definition of a subtitle/caption track.
Hierarchy
-
↳
SubtitleTrack
Properties
enabled
• Optional enabled: boolean
Tells if a subtitle track is enabled or disabled. If set to true, the track will be enabled by default.
forced
• Optional forced: 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
• Optional isFragmented: boolean
Indicates whether the subtitle is fragmented.
Inherited from
isSideloaded
• Optional isSideloaded: 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
• Optional metadata: 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
• Optional role: MediaTrackRole[]
The optional roles of the track.
Inherited from
url
• Optional url: 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
• Optional id: 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
• Optional region: 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
• Optional identifier: string
Optional identifier of a cue
style
• style: Partial<VTTStyleDeclaration>
Applied css styles
TextTrack
Interface
Definition of a text track.
Hierarchy
-
↳
TextTrack
Properties
id
• id: string
The id of the media track that is used to identify and set the track.
Inherited from
isFragmented
• Optional isFragmented: boolean
Indicates whether the subtitle is fragmented.
isSideloaded
• Optional isSideloaded: 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
• Optional metadata: 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
• Optional role: MediaTrackRole[]
The optional roles of the track.
Inherited from
url
• Optional url: 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)