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
- Copy the URL of your stream. The stream must contain CEA-608, CEA-708, or in-manifest WebVTT captions.
- 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
- Create an array of JWTrack objects.
- 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
.
- Create a
JWCaptionStyling
object. - Use the following example and table to define the properties of your
JWCaptionStyling object
. In the example below, we call thiscaptionConfig
.
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
Background
iOS setting | JWCaptionStyling property |
---|---|
Color | backgroundColor (UIColor ) |
Opacity | backgroundColor (UIColor:alpha ) windowColor ( UIColor:alpha ) |
Advanced
Updated over 1 year ago