Subtitles

The SDK comes with a SubtitlesPlugin that adds support for sideloading custom subtitle tracks from a url as well as enabling subtitles rendering on DASH streams (or any other content played using the castlabs PlayerEngine). It supports the formats: TTML v1, IMSC1, WebVTT and SRT.

Setup plugin

Ensure the SubtitlesPlugin is enabled when registering the SDK, e.g.

let res = PRESTOPlaySDK.shared.register("licence", [SubtitlesPlugin()], "userId")

Side-load subtitle tracks

Subtitle tracks will be automatically generated from the streaming manifests. However you can also use the following method to manually side-load custom tracks:

PRESTOPlaySDK.shared.subtitles(for: player)?.sideloadTrack(
    url: url,
    format: TextFormat.web_vtt,
    languageCode: "en",
    displayName: "sideloaded english") { error in
    if let error = error {
        // Handle error
    } else {
        // Subtitle track is ready to use
    }
}

This method downloads and parses the subtitles content. Then it creates a new subtitle track appended after any existing subtitle tracks.

Styling

We support overriding the text rendering style specified by the subtitle content with a custom user specified style in compliance with FCC requirements. This done by configuring a SubtitlesStyle object and assigning it to the subtitlesStyle property of the Player. This property is by default nil, which indicates that the style is not overridden and the style defined in the media content will be used.

The style can be overriden as follows:

let subtitlesStyle = SubtitlesStyle(fromSystemSettings: false)
subtitlesStyle.foregroundColor = .red
subtitlesStyle.edgeType = .dropShadow
subtitlesStyle.edgeColor = .black
player.subtitlesStyle = subtitlesStyle

In addition, the SubtitlesStyle object can be pre-populated by reading the values that are currently stored in the iOS system settings (Settings > Accessibility > Subtitles & Captioning).

let subtitlesStyle = SubtitlesStyle(fromSystemSettings: true)
player.subtitlesStyle = subtitlesStyle

NOTE: Subtitles styling may appear differently when using the Apple player engine and some of the styling options may not be available there. See SubtitlesStyle.swift for details

NOTE: Subtitles styling is not available for the AppleTV app and during Airplay

Styling priority

In order to understand how the style is eventually rendered on the screen, please consider that the style rules can come from three places:

• the content (WebVTT CSS, TTML etc..)
• the iOS Device Accessibility settings
• programmatically set with our SDK

When programmatically setting a custom style with our SDK

• for DASH streams and sideloaded tracks
• every setting will be applied and it will take priority on the style defined by the content and the device settings
• for HLS streams
  • only a subset of the style settings are programmable in AVPlayer. The settings available there are: fonSizeScale, foregroundColor, backgroundColor, windowColor, typeface and edgeType.
  • if in the Device Settings the Video Override flag is disabled for a certain style property, the value of this property cannot be overwritten
  • if Video Override is enabled the priority is: content, SDK, system

As an example, this is the result of applying the priority rules above for the foregroundColor property of an HLS stream

Content	SDK	Device	Video Override	Result
White	Red	Yellow	YES	White
White	Red	Yellow	NO	Yellow
Undefined	Red	Yellow	YES	Red
Undefined	Red	Yellow	NO	Yellow

Preview

To make it easier to preview the effect of style changes and to enable creating a UI for style settings the SubtitlesAPI includes the ability to show a preview.

First, sideload a subtitle track to show on the preview:

if let player = player,
   let contentUrl = Bundle(identifier: "bundleId")?.url(forResource: "preview", withExtension:"webvtt")
{
     subtitles = PRESTOPlaySDK.shared.subtitles(for: player)
     subtitles?.sideloadTrack(url: contentUrl, format: TextFormat.web_vtt, languageCode: "en", displayName: "test", completionHandler: nil)
}

Then draw the preview by passing the style and a UIView object where it should be shown.

subtitles?.previewSubtitles(withStyle: subtitlesStyleUserPreferences(), onView: view)

Only the first cue in the subtitle file will be displayed. To change the style simply call this function again with a new style setting.

See SubtitlePreviewViewController.swift in the PlayermakerApp example which comes with the SDK package for an example.