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.
Modification
There are cases when you want to modify subtitles track content before you pass it to the CastlabsSubtitles
parser or renderer. For example:
- You want to experiment on the client-side, before you modify the backend content
- Text is embeded in segments and it is hard to modify them on the server side
- The text is not standard compliant
SubtitlesAPI
exposes a modification method:
subtitles?.onTextSegmentContent = { content, format in
guard let data = content.data(using: .utf8) else { return content }
if format == .ttml {
let parser = FixIMSC1Subtitles(content: content)
let xml = XMLParser(data: data)
xml.delegate = parser
xml.parse()
return parser.getContent()
}
return content
}
Formats
Supported subtitles formats:
Type | Supported |
---|---|
SRT | Yes |
WebVTT | Yes |
TTML | Yes |
IMSC1 | Yes* |
HLSPlayer
forIMSC1
supports text profile only.
Styling profile presence in fMP4 may cause the player to hang when IMSC1
track is selected.
Native subtitles rendering can be styled via Media Accessibility system settings (https://developer.apple.com/documentation/mediaaccessibility).