Add and customize captions (Android v3)

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.



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.

πŸ“˜

If you define a single track, the label value is ignored and not shown.

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

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

Caption captionSp = new Caption.Builder()
    .file("https://www.yourdomain.com/caption-file_sp.vtt")
    .label("EspaΓ±ol")
    .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("Playlist-Item Title")
    .description("Some really great content")
    .tracks(captionTracks)
    .build();

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


Customize your captions

Using the CaptionsConfig.Builder(), you can customize the font, font color, window color, background color, and edge style of the captions in your app. If you do not define any styling, your captions are styled based upon the Accessibility settings on the viewer's device.

🚧

Any caption styling that you define applies only when a viewer disables Use Caption in the Accessibility section of his or her device settings.

CEA-608 and CEA-708 captions cannot be styled with CSS.


  1. Use CaptionsConfig.Builder() to create and name a CaptionsConfig object.
  2. Use the following example and table to define the properties of the captionsConfig object.
  3. Add captionsConfig to the captionsConfig property of the PlayerConfig object (config)
CaptionsConfig captionsConfig = new CaptionsConfig.Builder()
    .fontFamily("zapfino")
    .fontSize(12)
    .fontOpacity(100)
    .color("#FFFFFF")
    .edgeStyle(CaptionsConfig.CAPTION_EDGE_STYLE_RAISED)
    .windowColor("#000000")
    .windowOpacity(50)
    .backgroundColor("#000000")
    .backgroundOpacity(100)
    .build();

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

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

Caption captionSp = new Caption.Builder()
    .file("https://www.yourdomain.com/caption-file_sp.vtt")
    .label("EspaΓ±ol")
    .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("Playlist-Item Title")
    .description("Some really great content")
    .tracks(captionTracks)
    .build();

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

Android settings mapping

The following tables map the specific Android settings to the Android SDK property. Remember that viewers must disable Use Caption in the Accessibility section of the device settings for your customizations to render when they use your app.


Standard options

Android settingCaptionsConfig.Builder() property
Language-
Text sizefontSize
Caption style-

Custom options

Android settingCaptionsConfig.Builder() property
Font familyfontFamily
Text colorcolor
Text opacityfontOpacity
Edge typeedgeStyle
Edge color-
Background colorbackgroundColor
Background opacitybackgroundOpacity
Caption window colorwindowColor
Caption window opacitywindowOpacity


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. Note 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