Subtitles API

Suggest Edits

Subtitles API is exposed on source API under subtitles namespace. Full API type definitions is available in our documentation.

Getting all of the available subtitles

We can get a list of subtitle tracks by using sourceApi.subtitles.list.

// ...
const sourceApi = player.sources.add(sourceConfig);

// ...
// Once manifest has been loaded
console.info('Subtitle tracks', sourceApi.subtitles.list);
// ...

Activating the subtitle track

This can be achieved using subtitles.activate method. This takes either a subtitle track id, or a subtitle track as first parameter, and enables the subtitle track.

// ...
const sourceApi = player.sources.add(sourceConfig);

// ...
// Once manifest has been loaded
const availableSubtitles = sourceApi.subtitles.list;
const firstSubtitleTrack = availableSubtitles[0];

if (firstSubtitleTrack) {
	sourceApi.subtitles.activate(firstSubtitleTrack);
  // This is also valid
  // sourceApi.subtitles.activate(firstSubtitleTrack.id);
}
// ...

Second parameter is optional and it defines if it should disable other subtitle tracks before enabling the passed in one (Default is true).

// ...
const sourceApi = player.sources.add(sourceConfig);

// ...
// Once manifest has been loaded
const availableSubtitles = sourceApi.subtitles.list;

// We want to disable all subtitles, and to activate track 0 and 1.
sourceApi.subtitles.activate(availableSubtitles[0], true);
sourceApi.subtitles.activate(availableSubtitles[1], false);
// ...

Deactivating the subtitle track

We can deactivate subtitle track using subtitles.deactivate method which takes either a subtitle track id or a subtitle track as parameter.

// ...
const sourceApi = player.sources.add(sourceConfig);

// ...
// Once manifest has been loaded
const availableSubtitles = sourceApi.subtitles.list;

// Activate first track
sourceApi.subtitles.activate(availableSubtitles[0]);

// Deactivate first track
sourceApi.subtitles.deactivate(availableSubtitles[0]);
// ...

Adding subtitle track

We can add external subtitle track using subtitles.add method. It takes a track object that needs to contain language, url and label and it returns created SubtitleTrack.

// ...
const sourceApi = player.sources.add(sourceConfig);

sourceApi.subtitles.add({language: 'en', label: 'English', url: 'my-web-vtt-track.vtt'});
console.info('All tracks including my external track', sourceApi.subtitles.list);
// ...

Removing subtitle track

We can remove subtitle track (at the moment only external one) using subtitles.remove method, which takes either a subtitle track id or subtitle track itself.

// ...
const sourceApi = player.sources.add(sourceConfig);

const myExternalTrack = sourceApi.subtitles.add({language: 'en', label: 'English', url: 'my-web-vtt-track.vtt'});
console.info('All tracks including my external track', sourceApi.subtitles.list);
sourceApi.subtitles.remove(myExternalTrack);
// sourceApi.subtitles.remove(myExternalTrack.id)
// ...

Updated about 1 month ago