Skip to main content
Version: 11.8.0

How to insert subtitles on iOS

This article describes how you can side-load subtitles or closed captions, i.e. how you can add text tracks which are not part of your HLS or MPEG-DASH manifest.

Every source description has a text tracks property, which accepts an array of side-loaded text tracks. All valid tracks are available for playback as long as the player's source is not set again.

Text track descriptions can also be used for other purposes, e.g. for including preview thumbnails and chapters.

Prerequisites​

On iOS and tvOS, playback goes through AVFoundation, which cannot sideload subtitles by itself. To insert subtitles that are not part of your stream, you need the Sideloaded Subtitles connector in addition to the THEOplayer iOS SDK.

Add the connector to your Podfile and install it:

pod 'THEOplayer-Connector-SideloadedSubtitle'

Always use matching THEOplayer and connector versions, because the connector relies on an experimental API of the iOS SDK.

note

The connector is only needed for subtitle text tracks. Metadata text tracks, such as WebVTT thumbnails, are sideloaded by the THEOplayer iOS SDK itself.

Usage​

Each text track is described by a TextTrackDescription.

var sampleSource: SourceDescription {
    let textTrack1 = TextTrackDescription(src: "https://your.webvtt", srclang: "en", isDefault: true, kind: .subtitles, label: "English", format: .WebVTT)
    let textTrack2 = TextTrackDescription(src: "https://your.webvtt", srclang: "ar", isDefault: false, kind: .subtitles, label: "Arabic", format: .WebVTT)

    return SourceDescription(
        source: TypedSource(
            src: "https://your.m3u8",
            type: "application/x-mpegurl"
        ),
        textTracks: [textTrack1, textTrack2]
    )
}

Then set the source on the player through the connector's setSourceWithSubtitles method, instead of assigning it to player.source:

import THEOplayerConnectorSideloadedSubtitle

self.theoplayer.setSourceWithSubtitles(source: sampleSource)
warning

Replace every player.source = source call in your app with setSourceWithSubtitles(source:) if you sideload subtitles on at least one of your sources, even for sources without sideloaded subtitles. Mixing both approaches can lead to unexpected behavior.

Take note of the following limitations of sideloaded subtitles on iOS and tvOS:

  • Only WebVTT (iOS-compatible) and SRT subtitles are supported.
  • The label of the text track is generated by the operating system based on the language code, so the label you configure is disregarded.
  • The isDefault flag is ignored. To show a sideloaded subtitle track by default, listen for the ADD_TRACK event and set the mode of the track to showing, as described in how to programmatically enable or disable text tracks.

The connector documentation covers additional features, such as shifting the presentation of cues and caching sideloaded subtitles for offline playback.