Subtitles

Subtitles support is implemented as a plugin, meaning it must be installed and enabled separately.

Setup

First, install the @castlabs/react-native-prestoplay-subtitles package:

npm install @castlabs/react-native-prestoplay-subtitles

Once the plugin is installed, enable it when initializing the SDK, by passing the SubtitlesPlugin class. For example:

import { Sdk } from "@castlabs/react-native-prestoplay";
import { SubtitlesPlugin } from "@castlabs/react-native-prestoplay-subtitles";

Sdk.initialize({
  licenseKey: {
    /* Valid license here */
  },
  plugins: [SubtitlesPlugin],
});

Showing Subtitles

Text tracks embedded in a stream are automatically accessible through the Player.getTrackManager method. The TrackManager provides utilities to manage subtitle tracks, such as selecting or disabling tracks.

To display subtitles, select a specific text track using the TrackManager.setTextTrack method. For example:

const selectedTextTrack = player
  .getTrackManager()
  .getTextTracks()
  .find((t) => t.language === "en");

if (selectedTextTrack) {
  trackManager.setTextTrack(selectedTextTrack);
}

Hiding Subtitles

To hide the subtitles overlay, use the TrackManager.setTextTrack method with null as the argument. For example:

player.getTrackManager().setTextTrack(null);

Adding Side-Loaded Subtitles

If a stream lacks embedded subtitles or additional subtitles need to be added, side-loaded subtitles can be defined through the PlayerConfiguration.remoteTextTracks configuration. This allows specifying subtitles that are loaded from external URLs.

const playerConfiguration = {
  source: {
    /* ... */
  },
  remoteTextTracks: [
    {
      language: "en",
      label: "English",
      url: "https://example.com/en.vtt",
      mimeType: "text/vtt",
    },
  ],
};

Styling Subtitles

Override subtitles style defined in the content by providing custom subtitles style:

const subtitlesExtension = useSubtitlesExtension();
subtitlesExtension.setStyle({
  autoFlow: true,
  fontScale: 1.5,
  foregroundColor: {
    // white
    red: 255,
    green: 255,
    blue: 255,
    alpha: 1,
  },
  backgroundColor: {
    // black
    red: 0,
    green: 0,
    blue: 0,
    alpha: 1,
  },
});

...or use system's default subtitle style:

const subtitlesExtension = useSubtitlesExtension();
subtitlesExtension.setStyle({
  extendSystemStyle: true,
});

Supported Formats

For a full list of supported subtitle formats, refer to the Features page.