Add captions (Android)

If you have captions or subtitles for your video content, you can use the following sections to add embedded or sidecar captions to your app.

Although there are differences between the intended purposes of captions and subtitles, you use the same processes to add or to customize either type of synchronized text to your app. For simplicity, both captions and subtitles are referred to as captions in our documentation.

Add captions to your app

Embedded captions

To add videos or streams with embedded captions to your app, follow the steps to create a playlist. Replace step 2 of the process with the two steps below:

1. Copy the URL of your video. The video must contain CEA-608, CEA-708, or in-manifest WebVTT captions.
2. Define the file property of the PlaylisItem object with the URL of your video.

Sidecar captions

1. Create a List<Caption> object and name it, for example, captionTracks.
2. Use Caption.Builder() to create and name a Caption object for each caption track.
3. Add the caption track URL (file) and a language label (label).
4. (Optional) If you have multiple tracks, set isDefault(true) for the default caption track.
5. Add each caption track to captionTracks.
6. Add captionTracks to a playlist item.

List<Caption> captionTracks = new ArrayList<>();

Caption captionEn = new Caption.Builder()
    .file("https://www.yourdomain.com/caption-file_en.vtt")
    .label("English")
    .kind(CaptionType.CAPTIONS)
    .isDefault(true)
    .build();
captionTracks.add(captionEn);

Caption captionSp = new Caption.Builder()
    .file("https://www.yourdomain.com/caption-file_sp.vtt")
    .label("Español")
    .kind(CaptionType.CAPTIONS)
    .build();
captionTracks.add(captionSp);

PlaylistItem playlistItem = new PlaylistItem.Builder()
    .file("https://cdn.jwplayer.com/manifests/{MEDIA_ID}.m3u8")
    .image("https://www.mydomain.com/poster.jpg")
    .title("The Title")
    .description("The description")
    .tracks(captionTracks)
    .build();

List<PlaylistItem> playlist = new ArrayList<>();
playlist.add(playlistItem);
PlayerConfig config = new PlayerConfig.Builder()
    .playlist(playlist)
    .build();
mPlayer.setup(config);

Customize caption appearance

Starting with Android SDK 4.27.0, you can use CaptionsConfig to customize WebVTT, SRT, and TTML captions rendered by the player. Use CaptionPosition to control caption width, alignment, and placement.

By default, viewer accessibility preferences and styles defined in the caption track take precedence over CaptionsConfig. To make the configured styling take precedence, use overrideStrategy(CaptionsConfig.OVERRIDE_STRATEGY_ALWAYS). CEA-608/708 captions continue to use styling provided by the caption data and the viewer's device settings.

Use the following steps to configure caption appearance:

1. (Optional) Use CaptionPosition.Builder() to define the default width, alignment, and position of captions within the rendered video.
2. Use CaptionsConfig.Builder() to define the caption appearance.
3. Add the CaptionsConfig object to the PlayerConfig.

CaptionPosition captionPosition = new CaptionPosition.Builder()
    .width(80)
    .horizontalPosition(10)
    .alignment(CaptionPosition.ALIGNMENT_CENTER)
    .linePercentage(85)
    .build();

CaptionsConfig captionsConfig = new CaptionsConfig.Builder()
    .fontFamily("sans-serif")
    .fontSize(24)
    .color(Color.WHITE)
    .backgroundColor(Color.TRANSPARENT)
    .windowColor(0x80000000)
    .edgeStyle(CaptionsConfig.EDGE_STYLE_DROP_SHADOW)
    .position(captionPosition)
    .overrideStrategy(CaptionsConfig.OVERRIDE_STRATEGY_VIDEO_OVERRIDE_ONLY)
    .allowScaling(true)
    .build();

PlayerConfig config = new PlayerConfig.Builder()
    .playlist(playlist)
    .captionsConfig(captionsConfig)
    .build();

mPlayer.setup(config);

backgroundColor controls the background directly behind the caption text, while windowColor controls the caption region. CaptionPosition values are relative to the rendered video area. Track-defined positioning takes precedence over CaptionPosition, and the player does not automatically reposition captions to avoid the control bar.

For all properties and accepted values, see CaptionsConfig and CaptionPosition in the Android SDK reference.

Add captions to existing preview thumbnails

If you have existing preview thumbnails, you should add captions to that existing tracks list. Creating a new tracks list for captions will cause only the most recently added track to load.

The following code example illustrates how two caption tracks can be added to an existing preview thumbnail setup and associated with a playlist through PlaylistItem.Builder().

List < Caption > tracks = new ArrayList < > ();
Caption captionEn = new Caption.Builder()
    .file("https://www.yourdomain.com/caption-file_en.vtt")
    .label("English")
    .kind(CaptionType.CAPTIONS)
    .isDefault(true)
    .build();
tracks.add(captionEn);
Caption captionSp = new Caption.Builder()
    .file("https://www.yourdomain.com/caption-file_sp.vtt")
    .label("Español")
    .kind(CaptionType.CAPTIONS)
    .build();
tracks.add(captionSp);
Caption previewThumbnail = new Caption.Builder()
    .file("https://cdn.jwplayer.com/strips/{MEDIA_ID}-120.vtt")
    .kind(CaptionType.THUMBNAILS)
    .build();
tracks.add(previewThumbnail);
PlaylistItem playlistItem = new PlaylistItem.Builder()
    .file("https://cdn.jwplayer.com/manifests/{MEDIA_ID}.m3u8")
    .image("https://www.mydomain.com/poster.jpg")
    .title("Playlist-Item Title")
    .description("Some really great content")
    .tracks(tracks)
    .build();

Captions Methods and Callbacks

Methods

Callbacks