subtitles

The subtitles plugin adds support for playing back .srt formatted subtitles and attaching them to nodes.
Note that this plugin depends on the ui plugin (used in order to display the subtitles).

This plugin does not auto initialize and should be initialized manually

Example

// playerOptions.json
{
    "plugins": {
        "subtitles": {
            "subtitlesMap": {
                "node_a": {
                    "en-US": "url/to/node_a.en-US.srt",
                    "es-ES": "url/to/node_a.es-ES.srt"
                }
            }
        }
    }
}

Init Options

options : object

Initialization options for the subtitles plugin.

options.autoShowIfAudioLocked : boolean
property

If set to true, subtitles will automatically be visible if player’s audio is locked.

Default: true
Example

// playerOptions.json
{
    "plugins": {
        "subtitles": {
            "autoShowIfAudioLocked": false
        }
    }
}

options.subtitlesMap : object
property

The subtitlesMap option allows attaching subtitles to nodes via configuration (as opposed to calling the attach method).
Keys are node IDs and values are the same as the 2nd argument (src) of an attach call.

Default: null
See: attach
Example

// playerOptions.json
{
    "plugins": {
        "subtitles": {
            "subtitlesMap": {
                "node_a": {
                    "en-US": "url/to/node_a.en-US.srt",
                    "es-ES": "url/to/node_a.es-ES.srt"
                },
                "node_b": {
                    "en-US": "url/to/node_b.en-US.srt",
                    "es-ES": "url/to/node_b.es-ES.srt"
                }
            }
        }
    }
}

Properties

player.subtitles.availableLanguages : object
propertyreadonly

An object describing all the languages that were attached to nodes and are available to be displayed.
Keys in the object are language codes, and values are objects with nativeName and englishName properties.
Whenever this value changes, a subtitles.availablelanguageschange event is triggered.

See: subtitles.availablelanguageschange, language, effectiveLanguage
Example

console.log(player.subtitles.availableLanguages);
// {
//     'en-US': {
//         nativeName: "English (US)",
//         englishName: "English (US)"
//     },
//     'es': {
//         nativeName: "Español",
//         englishName: "Spanish"
//     }
// }

player.subtitles.language : string
property

Getter/setter for selecting the displayed subtitles language.
Setting will fail if value is not a valid language code (for a list of valid language codes, click here).
Subtitles displayed will either be an exact match to language code (if exists), or a partial match.
For example, if language is set to en-US but availableLanguages only includes another locale such as en-GB, it will be displayed.
If no matches (exact or partial) are found within availableLanguages, no subtitles will be displayed, even if visible is set to true.
Changing the value will trigger a subtitles.languagechange event.

See: subtitles.languagechange, effectiveLanguage, availableLanguages
Example

// Switch subtitles language to Spanish
player.subtitles.language = 'es';

player.subtitles.effectiveLanguage : string
propertyreadonly

A readonly string representing the effectively selected language.
Unlike the language property, which could be set to any valid language code (even if it’s not available),
effectiveLanguage value is always guaranteed to be either a key of availableLanguages or an empty string (if no matching available language is found).
Whenever this value changes, a subtitles.effectivelanguagechange event is triggered.

See: subtitles.effectivelanguagechange, language, availableLanguages
Example

if (player.subtitles.effectiveLanguage) {
    console.log(
        'The effectively selected language is:',
        player.subtitles.availableLanguages[player.subtitles.effectiveLanguage].englishName
    );
} else {
    console.log(
        `No match was found for "${player.subtitles.language}" out of currently available languages:`,
        Object.keys(player.subtitles.availableLanguages)
    );
}

player.subtitles.visible : boolean
property

Getter/setter for showing and hiding the subtitles.
When set to false subtitles will be hidden.
Setting this to true will show the subtitles.
Changing the value will trigger a subtitles.visibilitychange event.

See: subtitles.visibilitychange
Example

function toggleSubtitlesVisibility() {
    player.subtitles.visible = !player.subtitles.visible;
}

player.subtitles.style : object
property

Getter/setter for modifying the subtitles appearance.
The style property accepts a JavaScript object with camelCased properties (rather than a CSS string).
This object is passed onto the React component that renders the subtitles.
Changing the value will trigger a subtitles.stylechange event.

See: subtitles.stylechange, React style
Example

function changeFontSize(newSize) {
    player.subtitles.style = {
        fontSize: `${newSize}px`
    };
}

player.subtitles.version : string
propertyreadonly

The subtitles plugin’s version string.

Example

console.log('The subtitles plugin version is', player.subtitles.version);

Methods

player.subtitles.attach(nodeId, src, [options])
method

Associate .srt subtitles with the specified node.
Calling this method will overwrite any previously attached subtitles for given node (on a per-language basis).

Param Type Description
nodeId string | Node The node id (or node object) to attach the subtitles to.
src object | string An object mapping language codes to URLs (or subtitle contents), or a URL to the .srt file or the contents of an .srt file. See language-mapping-list for a list of valid language codes.
[options] object Optional. An options object.
[options.offset] number Default 0. Shift the subtitles timing by this many seconds (can also be negative).

Example

// Attach English and Spanish subtitles
player.subtitles.attach('myNodeId', {
    'en-US': 'https://example.com/path/to/subtitles.english.srt',
    'es': 'https://example.com/path/to/subtitles.spanish.srt'
});

// Attach single language subtitles (default language is 'en').
// This is the same as giving an object with a single property with key 'en' and the URL as value.
player.subtitles.attach('myNodeId', 'https://example.com/path/to/srtfile.srt');

// Attach subtitles with SRT content (instead of URL)
player.subtitles.attach('myOtherNodeId',
`1
00:02:17,440 --> 00:02:20,375
Senator, we're making
our final approach into <i>Coruscant</i>.

2
00:02:20,476 --> 00:02:22,501
Very good, Lieutenant.
`);

player.subtitles.detach(nodeId)
method

Remove any previously attached subtitles from given node.

Param Type Description
nodeId string | Node The node id (or node object) to remove the subtitles from.

Example

player.subtitles.detach('myNodeId');

Events

“subtitles.substart”
event

Triggered when a subtitle (single subtitle record) starts playing.

Param Type Description
subObj object An object that contains the subtitle’s info.
subObj.id string The SRT id of the current subtitle record. This is usually a numeric string, but other strings are also supported.
subObj.text string The text contents of the subtitle record.
subObj.startTime number The start time of the subtitle record in seconds from start of node.
subObj.endTime number The end time of the subtitle record in seconds from start of node.

“subtitles.subend”
event

Triggered when a subtitle (single subtitle record) ends.

Param Type Description
subObj object An object that contains the subtitle’s info.
subObj.id string The SRT id of the current subtitle record. This is usually a numeric string, but other strings are also supported.
subObj.text string The text contents of the subtitle record.
subObj.startTime number The start time of the subtitle record in seconds from start of node.
subObj.endTime number The end time of the subtitle record in seconds from start of node.

“subtitles.visibilitychange”
event

Triggered when visible value changes.

See: visible

Param Type Description
visible boolean New value of visible.

“subtitles.availablelanguageschange”
event

Triggered when availableLanguages value changes.

See: availableLanguages

Param Type Description
availableLanguages object New value of availableLanguages.

“subtitles.languagechange”
event

Triggered when language value changes.

See: language

Param Type Description
language string New value of language.

“subtitles.effectivelanguagechange”
event

Triggered when effectiveLanguage value changes.

See: effectiveLanguage

Param Type Description
effectiveLanguage string New value of effectiveLanguage.

“subtitles.stylechange”
event

Triggered when style value changes.

See: style

Param Type Description
style object New value of style.

Objects

reduxState : object
property

Subtitles plugin’s redux state sub-object (i.e. player.reduxStore.getState().subtitles).

See: reduxStore
Example

// player.reduxStore.getState().subtitles
{
    // Boolean. True if subtitles are visible (on), false if they're hidden (off).
    visible: false,

    // The text of current subtitle, or an empty string.
    text: '',

    // An object with available languages (languages that have been attached to nodes).
    availableLanguages: {
        'en-US': {
            nativeName: 'English (US)',
            englishName: 'English (US)'
        },
        'es': {
            nativeName: 'Español',
            englishName: 'Spanish'
        }
    },

    // The selected subtitles language.
    language: 'es-VE',

    // The effectively selected subtitles language,
    // guaranteed to either be an exact key of "availableLanguages" or an empty string.
    effectiveLanguage: 'es',

    // Style object to be applied to subtitles React component.
    style: {}
}
Rate this page: X
Tell us more!