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",
                    "en-US-AD": "url/to/node_a.en-US-AD.srt",
                    "es-ES":    "url/to/node_a.es-ES.srt"
                }
            },
            "displayZoneLocks": ["bottom1"],
            "displayZonePriority": {
                 "top1": 2000
             }
         }
    }
}

Init Options

options : object

Initialization options for the subtitles plugin.

options.mode : Array.<string>
property

The operating mode of the plugin - see mode

Default: 'self'

options.autoShowIfAudioLocked : boolean
property

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

Default: false
Example

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

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",
                    "en-US-AD": "url/to/node_a.en-US-AD.srt",
                    "es-ES":    "url/to/node_a.es-ES.srt"
                },
                "node_b": {
                    "en-US":    "url/to/node_b.en-US.srt",
                    "en-US-AD": "url/to/node_b.en-US-AD.srt",
                    "es-ES":    "url/to/node_b.es-ES.srt"
                }
            }
        }
    }
}

options.languageMap : object
property

The languageMap option allows registering additional languages that can be used when attaching subtitles to nodes via the subtitlesMap init option or the attach method.
Keys are language codes (same as the first argument of registerLanguage), and values are LanguageDescriptionObjects or strings (same as 2nd argument of registerLanguage).

Default: {
"en-US-AD": {
"nativeName": "English (audio descriptions)",
"englishName": "English (audio descriptions)"
}
}

See: registerLanguage
Example

// playerOptions.json
{
    "languageMap": {
        "en-US-SDH": {
            "nativeName": "English (deaf and hard-of-hearing)",
            "englishName": "English (deaf and hard-of-hearing)"
        }
    },
    "subtitlesMap": {
        "node_a": {
            "en-US-SDH": "url/to/node_a.en-US-SDH.srt"
        }
    }
}

options.displayZoneLocks : object
property

The displayZoneLocks option is a list of display zones that will locked by default.

Default: []
See: position.lockDisplayZone
Example

// playerOptions.json
{
   "displayZoneLocks": ["bottom1"]
}

options.displayZonePriority : object
property

The displayZonePriority option is a map of display zones ids and priorities,
which allows you to override the default priority of a display zone to increase the chance of it being selected for the subtitles’ position

Default: {}
See: position.addDisplayZone
Example

// playerOptions.json
{
 "displayZonePriority": {
      "top1": 2000
  }
}

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.mode : string
property

The operating mode of the plugin - self or proxy. Self the subtitles will be displayed in the platform interface. Proxy means that the player only sends the subtitles-related events.

Example

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

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.position.addDisplayZone(zoneId, style, priority)
method

Adds a new subtitles display zone
Calling this method will trigger a subtitles.displayzonechange event if the new zone is selected as the currently selected display zone.

See: subtitles.displayzonechange

Param Type Description
zoneId string The id of the new zone
style object An object containing the CSS style for this display zone as a React style object.
priority integer The priority for the new display zone. If not specified, default priority will be -Infinity Display zone availability is ordered by first reverse number of locks, then priority. IE the currently selected zone is the one with the with highest priority from the non-locked zones, or if all zones are locked, the one with the least locks.

Example

// add a new display zone that's just slightly off vertical center, with a really high priority
player.subtitles.position.addDisplayZone('offCenter', { top: "40%" }, priority: 1500)

player.subtitles.position.getDisplayZone(zoneId) ⇒ object
method

Retrieves information about a display zone, or all display zones.

Returns: object - an object describing the requested display zone, or a dictionary object describing all display zones.

Param Type Description
zoneId string The id of the zone to retrieve, OR a special value ‘all’ which retrieves a list of all display zones.

Example

// get information about a specific display zone
console.log(player.subtitles.position.getDisplayZone('bottom1'))
// example output:
// {
//   locks: { myLock:true },
//   style: { bottom1: "90px"},
//   priority: 1000,
//   computedOrder: 3
// }

Example

// get information about all display zones
console.log(player.subtitles.position.getDisplayZone('all'))
// example output:
// {
//   bottom1: {
//     locks: { myLock:true },
//     style: { bottom: "90px"},
//     priority: 1000,
//     computedOrder: 1
//   },
//   bottom2: {
//     locks: { },
//     style: { bottom: "120px"},
//     priority: 900,
//     computedOrder: 0
//   }
// }

player.subtitles.position.lockDisplayZone(zoneId, lockerId)
method

Adds a lock to a display zone. This makes it less likely for subtitles to appear in this zone.
Calling this method will trigger a subtitles.displayzonechange event if the selected display zone has changed as the result of adding the lock.

See: subtitles.displayzonechange

Param Type Description
zoneId string The id of the zone to be locked
lockerId string The id of the lock

Example

// lock a display zone
player.subtitles.position.lockDisplayZone('bottom1', 'lockedByBottomMenu')

player.subtitles.position.unlockDisplayZone(zoneId, lockerId)
method

Removes a lock from a display zone. This makes it more likely for subtitles to appear in this zone.
Calling this method will trigger a subtitles.displayzonechange event if the unlocked zone is selected as the currently available display zone.

See: subtitles.displayzonechange

Param Type Description
zoneId string The id of the zone to be locked
lockerId string The id of the lock

Example

// unlock a display zone
player.subtitles.position.unlockDisplayZone('bottom1', 'lockedByBottomMenu')

player.subtitles.position.getSelectedDisplayZoneId() ⇒ string
method

Returns the currently selected display zone. (IE where would subtitles actually be displayed).

Returns: string - the id of the currently selected display zone id
Example

// get the currently selected display zone id
player.subtitles.position.getSelectedDisplayZoneId()

player.subtitles.position.resetDisplayZones([zoneConfig])
method

Resets all display zones to their default, unlocked state. Calling this method will reintroduce default zones that were manually removed.
Calling this method will trigger a subtitles.displayzonechange event if the new currently selected display zone id is different.

See: subtitles.displayzonechange

Param Type Description
[zoneConfig] array An optional configuration array. If supplied, the reset will include only those zones.

Example

// reset all display zones
player.subtitles.position.resetDisplayZones()

Example

// reset all display zones to a custom config
let myDisplayZones = [
  {
      id: 'uptop',
      style: { top: '20px' },
      priority: 1000
  },
  {
      id: 'downunder',
      style: { bottom: '10px' },
      priority: 900
  },
];
player.subtitles.position.resetDisplayZones(myDisplayZones)

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');

player.subtitles.registerLanguage(langCode, langDescObj)
method

Register an additional language, so you can later attach subtitles using the newly registered language code.

Param Type Description
langCode string The language code (id) to register. If already exists, will override previous LanguageDescriptionObject.
langDescObj LanguageDescriptionObject | string The language description object that describes the registered language code. If string is given, it’ll be used for both nativeName and englishName properties.

Example

// First let's register our additional language
player.subtitles.registerLanguage('myCustomLanguage', {
    nativeName: 'My bespoke language',
    englishName: 'My custom language'
});

// Now we can attach subtitles for that language
player.subtitles.attach('node_myNodeId', {
    'en-US': 'https://example.com/path/to/subtitles.english.srt',
    'myCustomLanguage': 'https://example.com/path/to/subtitles.myCustomLanguage.srt'
});

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.

“subtitles.displayzonechange”
event

Triggered when a new subtitle module:subtitles#displayzone is selected.

See: module:subtitles#displayzone

Param Type Description
zoneId string the id of the new selected display zone

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: {},

    // Which subtitle display zone is currently available
    displayZoneId: 'bottom1'
}

LanguageDescriptionObject : object
property

An object that describes a language.

See: registerLanguage, languageMap

Param Type Description
nativeName string The language’s native name.
englishName string The language’s english name.

Example

{
    "nativeName": "עברית",
    "englishName": "Hebrew"
}
Rate this page: X
Tell us more!