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 and custom rendering with external renderer registration.

Version
2.0.0
Author
Frank Kudermann - alphanull
License
MIT
Requires
DomSmith
srtParser
Source
Subtitles.js, line 14

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 27

Reference to the main player instance.

Type
Player
Source
Subtitles.js, line 41

Reference to the current media element.

Type
HTMLMediaElement
Source
Subtitles.js, line 47

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

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

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 60

DomSmith for the main container used by the custom engine.

Type
DomSmith
Source
Subtitles.js, line 66

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 72

Flag indicating if subtitle was preloaded.

Type
boolean
Source
Subtitles.js, line 78

Allowed font size settings.

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

The current font size.

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

Array holding current subtitle data.

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

Stores additional renderer components (like subtitle line renderers).

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

Array holding the index of the currently active subtitle.

Type
number
Source
Subtitles.js, line 108

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 148

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 160

private #onMediaReady()

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

Listens
media/ready
Source
Subtitles.js, line 197

private #onSubtitleUpdate()

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

Listens
subtitles/update
Source
Subtitles.js, line 230

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/active
Returns

Returns the selected subtitle data entry.

Type Subtitles~SubtitleItem
Source
Subtitles.js, line 283

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 349

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 410

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 435

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 453

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 464

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 489

private #applyFontSize(fontSize)

Applies a new font size to the subtitle container and publishes the change.

Parameters:
Name Type Description
fontSize string

The requested font size.
Source
Subtitles.js, line 523

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 538

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 549

private #onNoMedia()

Handles clearing state when no media is present.

Source
Subtitles.js, line 558

private #onEngineSet(data)

Invoked when the engine is switched.

Parameters:
Name Type Description
data Object

The event data.

Parameters:
Name Type Description
from Object

The previous engine.
to Object

The new engine.
options Object

The options for the engine switch.
Listens
player/engine/set
Source
Subtitles.js, line 574

private #reset()

Resets the subtitles component to its initial state.

Source
Subtitles.js, line 614

destroy()

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

Source
Subtitles.js, line 636

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 680

Events

subtitles/fontsize

Fired when the subtitle font size changes (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 649

subtitles/active

Fired when a subtitle track becomes active.

Parameters:
Name Type Description
subtitleInfo Object

Object containing information about the active Subtitle.

Parameters:
Name Type Description
index Object

Index of the active subtitle track.
language TextTrack

Language code (e.g. "en", "de") of the active subtitle.
type TextTrack

MIME type of the active subtitle (e.g. "text/vtt").
Listeners
SubtitlesUi#onActive
Source
Subtitles.js, line 656

subtitles/selected

Fired when a new subtitle track was selected.

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.
type TextTrack

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

subtitles/update

The Subtitles component listens to this event to react to outside changes to the available subtitles. Rebuilds the internal subtitle data from the current TextTracks and fires the subtitles/update event. Used mainly for external control by components as dash and hls.

Listeners
Subtitles#onSubtitleUpdate
Source
Subtitles.js, line 674