Add captions

Add embedded or sidecar captions to your Android app.


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.


📘

The JW Player SDK for Android respects the Caption Styling accessibility preferences of a viewer. This enables your viewers to maintain their customizations while still enjoying the video experience you have created.


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);

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

MethodDescription
List<Caption> getCaptionsList()Returns a List with captions tracks from the player
int getCurrentCaptions()Returns the index of the currently active captions track

The captions are off if the index is 0
setCurrentCaptions(int index)Change the visible captions track to the provided index

The index must be within the list provided by getCaptionsList().

Callbacks

CallbackDescription
onCaptionsList(CaptionsListEvent captionsListEvent)Fired when the list of available captions tracks is updated
onCaptionsChanged(CaptionsChangedEvent)Fired when the active captions track is changed


Frequently Asked Questions

Why does an Unknown CC option appear in the UI when there are in-manifest captions in the HLS stream?
Answer
If the following coding are true, the SDK sets the value of Unknown CC:
   • No NAME is specified in the HLS manifest for that #EXT-X-MEDIA entry.
   • The specified LANGUAGE specified cannot be decoded.
Why does an Unknown CC option appear in the UI when there are no captions in a simple HLS stream?
Answer
When the HLS manifest fails to specify CLOSED-CAPTIONS=NONE, the player must assume that in-band 608/708 captions exist. This prevents scenarios in which captions exist, but are not available via the UI.

For more context, see: CLOSED-CAPTIONS



Did this page help you?