Skip to content

Module: src/text/Subtitles

The Subtitles component enables custom and native subtitle rendering with track selection and layout control. It handles dynamic switching, SRT-to-VTT conversion, custom rendering with external renderer registration, and also supports a subtitle menu with font size selection and adaptive layout behavior.

Version
1.0.0
Author
Frank Kudermann - alphanull
License
MIT
Requires
DomSmith
srtParser
Menu
Source
Subtitles.js, line 17

Constructor

new Subtitles(player, parent, optionsopt)

Creates an instance of the Subtitles component.

Parameters:
Name Type Attributes Description
player Player

The main media player instance.
parent Popup

Reference to the parent instance (In this case the language popup).
options Object optional

Additional options.

Parameters:
Name Type Attributes Description
apiKey symbol optional

Token for extended access to the player API.

Members

Holds the configuration options for the Subtitles component.

Properties
Name Type Attributes Default Description
mode string optional "custom"

"custom" mode uses the builtin subtitle engine, while "native" uses the browser engine. Note that not all Browsers may support custom engine, in this case the native fallback is used.
allowHTML string optional "none"

When used in conjunction with the custom engine, specifies if subtitles formatted in HTML may be used not at all ("none"), only with some basic tags ("basic") or fully ("all"). WARNING: allowing HTML may be a potential security issue and may trigger XSS attacks. Only use this if you are in full control of your subtitles!
adaptLayout boolean optional false

If enabled, the layout is synchronized with the UI state of controller and title, meaning that if one of these is shown, subtitles get an additional offset to prevent overlapping. Only works with custom engine.
fontSize string optional "medium"

The text size of the subtitles, can be "small", "medium" or "big". Only works with custom engine.
showFontSizeControl boolean optional true

If enabled, provide a UI to the user to change the subtitle text size. Only works with custom engine.
showPlaceholder boolean optional false

If enabled, display a 'not available' placeholder if no subtitles are available, otherwise completely hide the menu.
preferredSubtitles boolean | string optional false

If enabled, try to display subtitles: if true, use the player locale as default, or use a string as language code and try to match with available subs.
Type
Object
Source
Subtitles.js, line 30

Reference to the main player instance.

Type
Player
Source
Subtitles.js, line 44

Reference to the parent component.

Type
Popup
Source
Subtitles.js, line 50

Reference to the current media element.

Type
HTMLMediaElement
Source
Subtitles.js, line 56

Holds tokens of subscriptions to player events, for later unsubscribe.

Type
Array<number>
Source
Subtitles.js, line 62

Secret key only known to the player instance and initialized components. Used to be able to restrict access to API methods in conjunction with secure mode.

Type
symbol
Source
Subtitles.js, line 69

DomSmith for the main container used by the custom engine.

Type
DomSmith
Source
Subtitles.js, line 75

Reference to the font menu.

Type
Menu
Source
Subtitles.js, line 87

Stores actual subtitle mode. May be different from the configuration if the target browser does not support custom subtitles.

Type
"custom" | "native"
Source
Subtitles.js, line 93

Flag indicating if subtitle was preloaded.

Type
boolean
Source
Subtitles.js, line 99

Allowed font size settings.

Type
Array<string>
Source
Subtitles.js, line 105

The current font size.

Type
"small" | "medium" | "big"
Source
Subtitles.js, line 111

Array holding current subtitle data.

Type
Array<Subtitles~SubtitleItem>
Source
Subtitles.js, line 117

Stores additional renderer components (like subtitle line renderers).

Type
Array<Object>
Source
Subtitles.js, line 123

Array holding the index of the currently active subtitle.

Type
number
Source
Subtitles.js, line 129

Map storing the currently active cues for rendering.

Type
Map<any, {ele: HTMLElement, renderer: Object}>
Source
Subtitles.js, line 135

Methods

registerRenderer(renderer)

Registers a renderer object that can handle the actual subtitle layout, like line placement etc.

Parameters:
Name Type Description
renderer Object

The renderer to register.
Source
Subtitles.js, line 220

private #onDataReady(mediaData)

Called when the media data is ready, extracts the text track info from "mediaData.text" if present.

Parameters:
Name Type Description
mediaData Data~mediaItem

Current mediaData.

Parameters:
Name Type Description
text Array<Data~mediaItem_text>

The Subtitle section of the mediaData.
Listens
data/ready
Source
Subtitles.js, line 232

private #onMediaReady()

Called when media is ready. If on iOS, we might preload the text tracks.

Listens
media/ready
Source
Subtitles.js, line 286

private #onSubtitleUpdate()

Called when "subtitles/update" is published, e.g. After external changes in textTracks. Rebuilds the menu and toggles the correct track if needed.

Listens
subtitles/update
Source
Subtitles.js, line 319

async, private #toggleSubTitle(index) → Subtitles~SubtitleItem

Changes active subtitle display after user interaction.

Parameters:
Name Type Description
index number

The index of the new subtitle.
Fires
subtitles/selected
Returns

Returns the selected subtitle data entry.

Type Subtitles~SubtitleItem
Source
Subtitles.js, line 361

private #loadTextTrack(srcopt, optionsopt) → Promise<{track: TextTrack, trackEle: HTMLTrackElement}>

Loads (and creates) a new text track. (see also https://developer.mozilla.org/de/docs/Web/HTML/Element/track).

Parameters:
Name Type Attributes Description
src string optional

The URL from where the text track should be loaded. If omitted, a new blank text track is created.
options Object optional

Additional options.

Parameters:
Name Type Attributes Description
kind string optional

The kind of text track to create. Can be 'subtitles', 'captions', 'descriptions', 'chapters' or 'metadata'.
lang string optional

Language of the track text data. It must be a valid BCP 47 language tag. If the kind attribute is set to subtitles, then lang must be defined.
label string optional

A user-readable title of the text track which is used by the browser when listing available text tracks.
index Object optional

The current id / index of the track.
Returns

The newly created text track.

Type Promise<{track: TextTrack, trackEle: HTMLTrackElement}>
Throws

Throws if attempting to load text tracks before the loadedmetadata event.

Type Error
Source
Subtitles.js, line 421

private #onTextTrackLoaded(event)

This handler is called if a text track (containing subtitles) was loaded. Shows the track (in native mode), or sets up an event handler for the "cuechange" event when in custom mode.

Parameters:
Name Type Description
event Event

The original track 'load' event.
Source
Subtitles.js, line 482

private #onTextTrackError(event)

This handler is called if a text track (containing subtitles) was loaded. Shows the track (in native mode), or sets up an event handler for the "cuechange" event when in custom mode.

Parameters:
Name Type Description
event Event

The original track 'error' event.
Source
Subtitles.js, line 505

private #removeTextTrackEvents(track)

Removes both 'load' and 'error' events from a given track element.

Parameters:
Name Type Description
track TextTrack

The track to remove events from.
Source
Subtitles.js, line 521

private #renderSubTitles(event)

When using the custom engine, this method listens to the cuechange event, and invokes any fitting renderer.

Parameters:
Name Type Description
event Event

The "cuechange" event.
Source
Subtitles.js, line 532

private #oniOSFullScreen(data, topic)

If we are on iOS, and using the custom engine, we need special handling when iOS enters fullscreen. As only the video, or audio tag itself can go fullscreen, we cannot display using the custom engine here. Instead we have to switch to the native engine in this case, and back to "custom" when leaving fullscreen.

Parameters:
Name Type Description
data Object

Event data.
topic string

The event topic.
Listens
fullscreen/enter
fullscreen/leave
Source
Subtitles.js, line 569

private #changeFontSize(index, item)

Changes the font size of the custom subtitles.

Parameters:
Name Type Description
index number

The index of the new fontsize.
item Object

The selected item.

Parameters:
Name Type Description
value string

The actual item value.
Fires
subtitles/fontsize
Source
Subtitles.js, line 606

private #translate(language) → string

Translates a language code or "off" to a user-readable label.

Parameters:
Name Type Description
language string | null

The language code or null for "off".
Returns

A translated language string or the code if not found.

Type string
Source
Subtitles.js, line 620

getElement() → HTMLElement

Returns the container element used by this component (for custom renderers to attach to).

Returns

The root element of the subtitles component.

Type HTMLElement
Source
Subtitles.js, line 631

destroy()

This method removes all events, subscriptions and DOM nodes created by this component.

Source
Subtitles.js, line 640

Type Definitions

Represents a single subtitle item.

Properties
Name Type Description
type string

The type of subtitle track, e.g. "subtitles" or "captions".
id string

The identifier of the subtitle track (if any).
language string

The language code of this subtitle track.
default boolean

Whether this track is the default (as indicated by the media data).
selected boolean

Whether this track is currently selected or active.
track TextTrack | Object

The underlying browser TextTrack (or custom track object).
loaded boolean

True if this subtitle track has finished loading.
Type
Object
Source
Subtitles.js, line 688

Events

subtitles/fontsize

Fired when the user changes the subtitle font size (custom engine).

Parameters:
Name Type Description
fontInfo Object

Object containing fontInfo.

Parameters:
Name Type Description
fontSize Object

New size of the font ('small', 'normal' or 'big').
Listeners
ChromeCast#onFontChange
Source
Subtitles.js, line 665

subtitles/selected

Fired when the user changes the displayed subtitle.

Parameters:
Name Type Description
subtitleInfo Object

Object containing information about the selected Subtitle.

Parameters:
Name Type Description
index Object

Index of the selected subtitle track.
language TextTrack

Language code (e.g. "en", "de") of the selected subtitle.
src Object

URL or data source of the selected subtitle.
type TextTrack

MIME type of the selected subtitle (e.g. "text/vtt").
Listeners
ChromeCast#onSubtitleChange
Dash#onSubtitlesSelected
Source
Subtitles.js, line 672

subtitles/update

The Subtitles component listens to this event to react to outside changes to the available subtitles. Rebuilds the menu according to the current TextTracks. Used mainly for external control by components as dash and hls.

Listeners
Subtitles#onSubtitleUpdate
Source
Subtitles.js, line 682