Eko | api | 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
             }
         }
    }
}

Table of Contents
- Init Options
  - modep
  - autoShowIfAudioLockedp
  - subtitlesMapp
  - languageMapp
  - displayZoneLocksp
  - displayZonePriorityp
- Properties
  - availableLanguagespro
  - languagep
  - effectiveLanguagepro
  - visiblep
  - stylep
  - modep
  - versionpro
- Methods
- Events

Init Options

options : `object`

Initialization options for the subtitles plugin.

options : object
- .mode : Array.<string>
- .autoShowIfAudioLocked : boolean
- .subtitlesMap : object
- .languageMap : object
- .displayZoneLocks : object
- .displayZonePriority : object

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

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"
}

Init Options

options : object

options.mode : Array.<string>property

options.autoShowIfAudioLocked : booleanproperty

options.subtitlesMap : objectproperty

options.languageMap : objectproperty

options.displayZoneLocks : objectproperty

options.displayZonePriority : objectproperty

Properties

player.subtitles.availableLanguages : objectpropertyreadonly

player.subtitles.language : stringproperty

player.subtitles.effectiveLanguage : stringpropertyreadonly

player.subtitles.visible : booleanproperty

player.subtitles.style : objectproperty

player.subtitles.mode : stringproperty

player.subtitles.version : stringpropertyreadonly

Methods

player.subtitles.position.addDisplayZone(zoneId, style, priority)method

player.subtitles.position.getDisplayZone(zoneId) ⇒ objectmethod

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

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

player.subtitles.position.getSelectedDisplayZoneId() ⇒ stringmethod

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

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

player.subtitles.detach(nodeId)method

player.subtitles.registerLanguage(langCode, langDescObj)method

Events

“subtitles.substart”event

“subtitles.subend”event

“subtitles.visibilitychange”event

“subtitles.availablelanguageschange”event

“subtitles.languagechange”event

“subtitles.effectivelanguagechange”event

“subtitles.stylechange”event

“subtitles.displayzonechange”event

Objects

reduxState : objectproperty

LanguageDescriptionObject : objectproperty

options : `object`

options.mode : `Array.<string>`
property

options.autoShowIfAudioLocked : `boolean`
property

options.subtitlesMap : `object`
property

options.languageMap : `object`
property

options.displayZoneLocks : `object`
property

options.displayZonePriority : `object`
property

player.subtitles.availableLanguages : `object`
propertyreadonly

player.subtitles.language : `string`
property

player.subtitles.effectiveLanguage : `string`
propertyreadonly

player.subtitles.visible : `boolean`
property

player.subtitles.style : `object`
property

player.subtitles.mode : `string`
property

player.subtitles.version : `string`
propertyreadonly

player.subtitles.position.addDisplayZone(zoneId, style, priority)
method

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

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

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

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

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

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

player.subtitles.detach(nodeId)
method

player.subtitles.registerLanguage(langCode, langDescObj)
method

“subtitles.substart”
event

“subtitles.subend”
event

“subtitles.visibilitychange”
event

“subtitles.availablelanguageschange”
event

“subtitles.languagechange”
event

“subtitles.effectivelanguagechange”
event

“subtitles.stylechange”
event

“subtitles.displayzonechange”
event

reduxState : `object`
property

LanguageDescriptionObject : `object`
property