Add and customize captions

Add embedded or sidecar captions to your iOS 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

  1. Copy the URL of your stream. The stream must contain CEA-608, CEA-708, or in-manifest WebVTT captions.
  2. Build a JWPlayerItem passing the URL of your stream as the argument for the file method of the item builder.
NSString *urlString = @"https://cdn.mydomain.com/manifests/A3Bc9z5.m3u8";
NSURL *url = [NSURL URLWithString:urlString];
NSError *error;
JWPlayerItemBuilder *builder = [[JWPlayerItemBuilder alloc]init];
[builder file:url];
JWPlayerItem *item = [builder buildAndReturnError:&error];
let urlString = "https://cdn.mydomain.com/manifests/A3Bc9z5.m3u8"
let url = URL(string:urlString)!
do {
    let jwItem = try JWPlayerItemBuider().file(url).build()
} catch is JWError {
    // Handle error
}

Sidecar Captions

  1. Build a JWMediaTrack for each caption.
  2. Create an array of JWMediaTrack objects.

📘

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

// Build the JWMediaTrack
NSString *urlString = @”https://content.jwplatform.com/tracks/sample01.vtt”;
NSURL *url = [NSURL URLWithString:urlString];
NSString *label = @”English”;
NSError *error;
JWCaptionTrackBuilder *builder = [[JWCaptionTrackBuilder alloc] init];
[builder file:url];
[builder label:label];
[builder defaultTrack:YES]; // In the case that the track is the default

JWMediaTrack *englishTrack = [builder buildAndReturnError:&error];
// Create array with tracks
NSArray<JWMediaTrack *> *tracks = @[englishTrack];
// Build the JWMediaTrack
var captions = [JWMediaTrack]()
let urlString = "https://content.jwplatform.com/tracks/sample01"
let url = URL(string: urlString)!
let builder = JWCaptionTrackBuilder()
.file(url)
.label(“English”)
.defaultTrack(true)

do {
    let englishTrack = try JWCaptionTrackBuilder().build()
    captions.append(englishTrack)
} catch {
    // Handle error
}


Customize your captions

Using the JWCaptionStyle class, 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 Settings > Accessibility > Subtitles & Captioning settings on the viewer's device.

👍

IMPORTANT

Any caption styling that you define applies only to in-manifest WebVTT (embedded) captions and sidecar captions. These captions inherent your styling only when a viewer enables Video Override in his or her device's Settings > Accessibility > Subtitles & Captioning settings.

CEA-608 and CEA-708 captions do not inherit caption styling defined by JWCaptionStyle.


  1. Build a JWCaptionStyle object.
  2. Use the following examples to set the properties of the JWCaptionStyle object that the builder will output.
JWCaptionStyleBuilder *builder = [[JWCaptionStyleBuilder alloc] init];
[builder font:[UIFont fontWithName:@”Zapfino” size:20]];
[builder fontColor: [UIColor blueColor]];
[builder highlightColor: [UIColor orangeColor]];
[builder backgroundColor: [UIColor colorWithRed:0.3 green:0.6 blue:0.3 alpha:0.7]];
[builder edgeStyle: JWCaptionEdgeStyleRaised];

NSError *error;
JWCaptionStyle *style = [builder buildAndReturnError:&error];
let builder = JWCaptionStyleBuilder()
.font(UIFont(name: "Zapfino", size: 20))
.fontColor(.blue)
.highlightColor(.white)
.backgroundColor(UIColor(red: 0.3, green: 0.6, blue: 0.3, alpha: 0.7))
.edgeStyle(.raised)
do {
  let style = try builder.build() 
} catch {
  // Handle error
}


iOS settings mapping

The following tables map the specific iOS Settings > Accessibility > Subtitles & Captioning settings to the iOS SDK property. Remember that viewers must enable Video Override in each of these areas for your customizations to render when they use your app.

Text

iOS SettingJWCaptionStyle Property
Fontfont (UIFont)
Sizefont (UIFont)
ColorfontColor (UIColor)

Background

iOS SettingJWCaptionStyle Property
ColorbackgroundColor (UIColor)
OpacitybackgroundColor (UIColor:alpha)

Advanced

iOS SettingJWCaptionStyle Property
Text Opacitycolor (UIColor:alpha)
Text Edge StyleedgeStyle(JWCaptionEdgeStyle)
Text HighlighthighlightColor(UIColor)


Did this page help you?