<img src="https://img.shields.io/badge/%20-ENTERPRISE-B10031" style="float:left"/><br /> <img src="https://img.shields.io/badge/iOS-V4-009727?logo=apple" style="float:left"/><br />

Captions provide your viewers synchronized text of the audio and non-speech elements of your video content. In addition, complimenting your video content with captions can have the following benefits:

  • Improved video SEO

  • Increased content retention

  • Increased engagement with autoplay content

  • Environment-independent content viewing

  • Legal compliance

955


Screenshot of an English caption in a video.



**NOTE: **The same processes are used to add or customize both **captions** and **subtitles** in your iOS app. For simplicity, we refer only to captions in our documentation.

<br /> <hr />

## Supported caption types

Captions can either be embedded in the video (embedded captions) or loaded from a separate file (side-loaded or sidecar captions). The iOS SDK supports both types of captions.

You can add embedded captions, sidecar captions, or both.



We strongly advise that you remotely self-host video content with embedded captions. If video content with embedded captions is uploaded to your JWP account, the embedded captions may be removed during the encoding process.



When the list of available caption tracks is retrieved from the player, the captions appear in the following order:

  • None track, denoting that no captions are available.

  • Embedded captions

  • Side-loaded captions

This is also the order in which the captions are listed in the player menu.

<br />

The following table lists common caption formats that the iOS SDK supports.

FormatTypeDescription
**<a href="https://www.w3.org/TR/webvtt1/" target="_blank">WebVTT</a> (.vtt)**Embedded or<br />Side-loadedCommon format used for online video<br /><br />Captions can be embedded as part of a live stream or can be side-loaded as a separate file. WebVTT captions can include the caption, a description, and metadata information.<br /><br />Your .vtt files should be saved using UTF8 encoding to prevent rendering issues.
**<a href="https://en.wikipedia.org/wiki/SubRip" target="_blank">SubRip Text</a> (.srt)**Side-loadedCommon format used for online video<br /><br />SubRip Text captions only include the caption. Neither description nor metadata information can be included.
**<a href="https://www.w3.org/TR/ttml1/" target="_blank">Timed Text Markup Language</a> (.ttml) **EmbeddedXML-based format used for online video

<br />

<hr />

## Add captions to your app

JWP supports embedded and side-loaded captions. The following sections explain how to add each type of caption to your video.

<br />

### Embedded captions

The recipe below demonstrates how to embed captions in your iOS app.

📱
iOS: Add embedded captions
Open Recipe




Do not add videos or streams with embedded captions to your JWP library. The embedded captions tracks of the content may be removed during JWP's video transcoding process.

<br />

### Side-loaded captions

The recipe below demonstrates how to side-load captions in your iOS app.

📱
iOS: Add and customize sidecar captions
Open Recipe


<br />

<hr />

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

<br />

### Text

(Script tags will be stripped)


<br />

### Background

(Script tags will be stripped)


<br />

### Advanced

(Script tags will be stripped)


<br /> <hr />

## Listening for caption events

The following table describes the `JWAVDelegate` methods that correspond to captions events.

MethodDescription
`jwplayer(_ player: JWPlayer, updatedCaptionList options: [JWMediaSelectionOption])`When captions are loaded for the content reports what captions are available.
`jwplayer(_ player: JWPlayer, captionTrackChanged index: Int)`Reports what caption was selected, represented as an index into the list of available captions.
`jwplayer(_ player: JWPlayer, captionPresented caption: [String], at time: JWTimeData)`Reports what strings were displayed and what time they are being presented on screen.


<br /> <hr />

## Setting a caption track programmatically

Setting a caption track programmatically has many benefits, including

  • Knowing and setting the language your user prefers

  • Mirroring a user’s language selection outside of the UI in `JWPlayerViewController`

  • Use in conjunction with your UI implementation when the user selects a language if you are only using `JWPlayerView`

<br />

To set the captions track programmatically, use the index of the captions according to the captions list or with the locale that was set for the captions.

MethodDescription
`func setCaptionTrack(index: Int) throws`Set the caption by using a valid index into the list of available captions. Using -1 will set to no captions.
`func setCaptionTrack(locale: String?) throws`Set captions using an RFC-5646 language tag—e.g, “en”.


<br /> <hr />

## Caption Rendering

Our SDK renders all side-loaded captions. For embedded captions, such as in an HLS stream, AVPlayer renders the captions. Specifying values within `JWCaptionStyle` will only affect side-loaded captions.

<br />

### Disabling Rendering

For some uses of our player, it may be desired that the player not render the captions. Instead, perhaps you wish to render the captions into a different view, elsewhere on the screen.

In JWPlayer, there is a property called `suppressesCaptionRendering`. If `true`, the player will not render captions on the screen if a caption track is selected, however, you will still receive caption events, including `func jwplayer(_ player: JWPlayer, captionPresented caption: [String], at time: JWTimeData)`. By default, this flag is `false`.



<br /> <hr />

## Setting Caption Insets

We can set the amount of space from the edges of the player to the captions container using the `JWPlayerView.captionInsets` API. This property is a `UIEdgeInsets`, which lets us specify the top, bottom, left, and right distance from the player edges you require.



<br /> <hr />

## Accessibility

On iOS devices, users can permit the SDK to select captions based on their device settings. When the caption tracks have been loaded for a video, the SDK chooses the initial caption track based on the following considerations in order:

  1. **User's Chosen Track**: If a user chooses a caption locale while watching videos in a playlist, the SDK will choose a caption in the same locale for subsequent videos in the playlist during the playback session.

  2. **User's Language if User has Disability**: If a user has enabled the Close Caption & Subtitles for the Deaf and Hard of Hearing (CC+SDH) on the device, the SDK will query the user's native language on the device and choose a caption with the same locale.

  3. **Default Caption Track**: The SDK chooses the default captions track as specified in the player configuration.

  4. **No Captions**: The SDK will turn off captions if the previous steps cannot determine a starting caption track

<br />

(Script tags will be stripped)