Skip to main content
Version: 11.7.0

How to detect active text track cues on Web

This article describes how you can use the TextTrack API to detect the active text track cues, by subscribing to the enter and exit events of a cue, or to the cuechange event of a text track.

Implementing this functionality can be a use-case for developers who want to build their own UI, and insert and style their subtitles with maximum freedom. Alternatively, you may need to access the active cues for analytics purposes, or to render them outside of the video player.

Another common use-case is to detect the active text track cue of timed metadata. This article also discusses this use-case.

Implementation for subtitles and closed captions​

Note that this section focuses on detecting active cues for subtitles and closed captions. Go to the section on "implementation for timed metadata" if you rather want to track timed metadata like ID3, emsg, EXT-X-DATERANGE and EventStream.

The Web SDK exposes the TextTrack API through player.textTracks. This textTracks property is a TextTrackList that inherits from the TrackList. This TrackList dispatches the events from the TrackListEventMap. This TrackListEventMap contains the addtrack event, as well as the change and removetrack event.

In the callback of your addtrack event, you want to track the addcue event through the TextTrack interface. Then, in the callback of your addcue event, you want to track the enter and exit events through the TextTrackCue interface. The enter event is dispatched when a cue becomes active and the exit event is dispatched when a cue becomes inactive. You can fetch the actual content in the callback of your enter event through its content property.

Alternatively, in the callback of your addtrack event, you could track the cuechange event through the TextTrack interface. Then, in the callback of your cuechange event, you want to iterate over the active cues. For each active cue, you could also query its content property.

The code below allows you to detect the active text track cues.

player.textTracks.addEventListener('addtrack', function (addTrackEvent) {
  const track = addTrackEvent.track;
  track.addEventListener('addcue', function (addCueEvent) {
    const cue = addCueEvent.cue;
    cue.addEventListener('enter', function (enterEvent) {
      console.log(enterEvent, enterEvent.cue.content);
    });
    cue.addEventListener('exit', console.log);
  });
  track.addEventListener('cuechange', function (cueChangeEvent) {
    const cues = cueChangeEvent.track.activeCues;
    for (let i = 0; i < cues.length; i++) {
      console.log('cuechange active cue', i, cues[i]);
    }
  });
});
// ...
// player.source = ...

You should invoke these event handlers before you configure your stream, because the player might have already dispatched the event before you were able to subscribe to it.

Implementation for timed metadata​

The implementation for timed metadata is identical to the one for subtitles and closed captions, except for three things.

  1. You do not necessarily use the enter event. For cues that span a period of time, for example EXT-X-DATERANGE cues, you might want to perform your action when the cue ends, so on the exit event instead.

  2. You might need to set the mode of the relevant text track to hidden, as documented in how to programmatically enable or disable text tracks. Some types of timed metadata, for example EXT-X-DATERANGE and EventStream, are disabled by default. You should add a condition to your addtrack callback to decide whether you want to set your track to hidden.

  3. You should set hlsDateRange to true in your player configuration or stream configuration, if you want to detect EXT-X-DATERANGE tags in an HLS stream.

The article on how to track ID3 cues might be useful to learn more about detecting ID3 tags specifically.