Add and customize captions (iOS v3)

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. Define the file property of the JWConfig object with the URL of your stream.
config.file = @"https://cdn.mydomain.com/manifests/A3Bc9z5.m3u8";
config.file = "https://cdn.mydomain.com/manifests/A3Bc9z5.m3u8"

Side Car Captions

  1. Create an array of JWTrack objects.
  2. Define the location of the subtitle file (file), language label (label), and the default subtitle file (isDefault).

πŸ“˜

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

config.tracks = @[[JWTrack trackWithFile:@"https://content.jwplatform.com/tracks/sample01.vtt" label:@"English" isDefault:YES],
	[JWTrack trackWithFile:@"https://content.jwplatform.com/tracks/sample02.vtt" label:@"Spanish"],
	[JWTrack trackWithFile:@"https://content.jwplatform.com/tracks/sample03.vtt" label:@"Russian"]];
config.tracks = [JWTrack (file: "https://content.jwplatform.com/tracks/sample01", label: "English", isDefault: true),
	JWTrack (file: "https://content.jwplatform.com/tracks/sample02.vtt", label: "Spanish"),
	JWTrack (file: "https://content.jwplatform.com/tracks/sample03.vtt", label: "Russian")]


Customize your captions

Using the JWCaptionStyling 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.

🚧

Any caption styling that you define applies only to in-manifest WebVTT (embedded) captions and sidecar captions. These captions inherit 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 JWCaptionStyling.

  1. Create a JWCaptionStyling object.
  2. Use the following example and table to define the properties of your JWCaptionStyling object. In the example below, we call this captionConfig.
JWConfig *config = [JWConfig new];

JWCaptionStyling *captionConfig = [[JWCaptionStyling alloc]init];
captionStyling.font = [UIFont fontWithName:@"Zapfino" size:20];
captionConfig.color = [UIColor blueColor];
captionConfig.windowColor = [UIColor orangeColor];
captionConfig.backgroundColor = [UIColor colorWithRed:0.3 green:0.6 blue:0.3 alpha:0.7];
captionConfig.edgeStyle = JWEdgeStyleRaised;
config.captions = captionConfig;
let config = JWConfig()

	var captionConfig: JWCaptionStyling = JWCaptionStyling()
	captionConfig.font = UIFont (name: "Zapfino", size: 20)
	captionConfig.color = UIColor.blueColor()
	captionConfig.edgeStyle = JWEdgeStyleRaised
	captionConfig.windowColor = UIColor.purpleColor()
	captionConfig.backgroundColor = UIColor(red: 0.3, green: 0.6, blue: 0.3, alpha: 0.7)
	config.captions = captionConfig


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 settingJWCaptionStyling property
Fontfont (UIColor)
Sizefont (UIColor)
Colorcolor (UIColor)

Background

iOS settingJWCaptionStyling property
ColorbackgroundColor (UIColor)
OpacitybackgroundColor (UIColor:alpha)
windowColor (UIColor:alpha)

Advanced

iOS settingJWCaptionStyling property
Text Opacitycolor (UIColor:alpha)
Text Edge StyleedgeStyle
Text HighlightN/A