How to programmatically detect text track changes

This article describes how you can use the THEOplayer API to detect text track quality changes. A text track "change" is triggered by enabling (or disabling) a subtitle or closed captions track.

The TextTrack API provides this functionality. More specifically, as a developer, you'll subscribe to the change event in the TextTrack API.

Implementing this functionality is a common use-case for developers who want to build their own UI, and annotate the subtitle (or closed captions) track that is currently active.

Table of Contents

• SDKs
• Implementation
• Related articles

SDKs

THEOplayer allows you to track text track changes on the following SDKs.

Implementation

The TextTrack API is available across all of our 4 base SDKs. As described in the introduction, to detect text track changes, you want to detect the change event in the TextTrack API.

• Web SDK
• Android SDK
• iOS SDK
• Roku SDK

Web SDK

The implementation of the Web SDK applies to all web-based platforms, including Tizen and webOS.

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 change event, as well as the addtrack and removetrack event.

The code below allows you to detect text track changes.

player.textTracks.addEventListener("change", function (event) {
  const track = event.track
  const isEnabled = track.mode == "showing"
  console.log(track, track.label, track.kind, track.type, isEnabled)
})

The properties of a text track (e.g. mode, kind) are described at https://docs.theoplayer.com/api-reference/web/theoplayer.texttrack.md.

Android SDK

The implementation of the Android SDK applies to all Android-based platforms, including Android TV and Fire TV.

The Android SDK exposes the TextTrack API through player.getTextTracks(). This getTextTracks() method returns a TextTrackList that inherits from the TrackList. This TrackList dispatches the events from the TextTrackListEventTypes. The TextTrackListEventTypes contains the TRACKLISTCHANGE event, as well as the ADDTRACK and REMOVETRACK event.

The code below allows you to detect text track changes.

player.getTextTracks().addEventListener(TextTrackListEventTypes.TRACKLISTCHANGE, trackListChangeEvent -> {
    TextTrack track = trackListChangeEvent.getTrack();
    boolean isEnabled = (track.getMode().getMode().equals("showing"));
    System.out.println(track.getLabel() + ", " + track.getKind() + ", " + track.getType().getType() + ", " + isEnabled);
});

The properties of a text track (e.g. mode, kind) are described at https://docs.theoplayer.com/api-reference/android/com/theoplayer/android/api/player/track/texttrack/TextTrack.html and https://docs.theoplayer.com/api-reference/android/com/theoplayer/android/api/player/track/Track.html.

iOS/tvOS SDK and Legacy iOS/tvOS SDK (4.12.x)

The implementation of the iOS SDK applies to all iOS-based platforms, including iPadOS and tvOS.

The iOS SDK exposes the TrackTrack API through player.textTracks. This textTracks property is a TextTrackList. This TextTrackList dispatches the events from the TextTrackListEventTypes. The TextTrackListEventTypes contains the CHANGE event, as well as the ADD_TRACK and REMOVE_TRACK event.

The code below allows you to detect text track changes.

player?.textTracks.addEventListener(type: TextTrackListEventTypes.CHANGE, listener: { (event) in
    let track : TextTrack = event.track as! TextTrack
    let isEnabled = (track.mode.rawValue == "showing")
    print(track.label, track.kind, track.type, isEnabled)
})

The properties of a text track (e.g. mode, kind) are described at https://docs.theoplayer.com/api-reference/ios/Protocols/TextTrack.html and https://docs.theoplayer.com/api-reference/ios/Protocols/Track.html.

Roku SDK

This subsection is in maintenance. Reach out to our team if you need help.

Related articles

Are you reading this article because you're interested in subtitles and closed captions? Continue reading below.

• How to programmatically detect text tracks
• How to dynamically change the visible captions
• How to programmatically disable text tracks
• How to insert subtitles

Refer to "How to track id3 cues" if you're interested in timed metadata (id3, emsg, EventStream, EXT-X-DATERANGE, ...).

Are you reading this article because you're implementing a custom UI? Then you'll find the following articles interesting:

• How to build a Chromeless UI
• How to detect video track quality changes
• How to detect audio track changes