Docs | iOS

External Subtitles

Supported from PlayKit v3.13.0

The player enables the option to add external subtitles to the media.

On this page:

Usage

What to do in order to add the external subtitles to the media:

  1. Create a PKMediaEntry.
  2. On the created pkMediaEntry, set the ‘externalSubtitles’ property, which requires an Array of PKExternalSubtitle objects.

That’s it.

The PKExternalSubtitles class

Check the class to get further information for each property.

@objc public class PKExternalSubtitle: NSObject {
    @objc public let id: String
    @objc public let name: String
    @objc public let language: String
    @objc public let isDefault: Bool
    @objc public let autoSelect: Bool
    @objc public let forced: Bool
    @objc public let characteristics: String
    @objc public let vttURLString: String
    @objc public let duration: Double

    ...
}

Sample code to create the PKExternalSubtitle

Note: The duration must be set with the correct value.
We can not set it from the player duration because that value is not initialized until the media is prepared.

Swift

PKExternalSubtitle(id: "Deutsch-de",
                   name: "Deutsch",
                   language: "de",
                   vttURLString: "http://brenopolanski.com/html5-video-webvtt-example/MIB2-subtitles-pt-BR.vtt",
                   duration: 570.0)

Objective-C

[[PKExternalSubtitle alloc] initWithId:@"Deutsch-de"
                                  name:@"Deutsch"
                              language:@"de"
                          vttURLString:@"http://brenopolanski.com/html5-video-webvtt-example/MIB2-subtitles-pt-BR.vtt"
                              duration:570.0
                             isDefault:NO
                            autoSelect:NO
                                forced:NO
                       characteristics:nil]

Complete Sample code

Swift

let contentURL = "https://cdnapisec.kaltura.com/p/2215841/sp/2215841/playManifest/entryId/1_9bwuo813/flavorIds/0_vfdi28n9,1_5j0bgx4v,1_x6tlvn4x,1_zj4vzg46/deliveryProfileId/19201/protocol/https/format/applehttp/a.m3u8"
        
// Create media source and initialize a media entry with that source
let entryId = "1_9bwuo813"
let source = PKMediaSource(entryId, contentUrl: URL(string: contentURL), drmData: nil, mediaFormat: .hls)
    
// Setup media entry
let mediaEntry = PKMediaEntry(entryId, sources: [source], duration: -1)
mediaEntry.externalSubtitles = [PKExternalSubtitle(id: "Deutsch-de",
                                                   name: "Deutsch",
                                                   language: "de",
                                                   vttURLString: "http://brenopolanski.com/html5-video-webvtt-example/MIB2-subtitles-pt-BR.vtt",
                                                   duration: 570.0),
                                PKExternalSubtitle(id: "English-en",
                                                   name: "English",
                                                   language: "en",
                                                   vttURLString: "http://externaltests.dev.kaltura.com/player/captions_files/eng.vtt",
                                                   duration: 570.0)]

Objective-C

NSURL *contentURL = [[NSURL alloc] initWithString:@"https://cdnapisec.kaltura.com/p/2215841/sp/2215841/playManifest/entryId/1_9bwuo813/flavorIds/0_vfdi28n9,1_5j0bgx4v,1_x6tlvn4x,1_zj4vzg46/deliveryProfileId/19201/protocol/https/format/applehttp/a.m3u8"];
    
// Create media source and initialize a media entry with that source
NSString *entryId = @"1_9bwuo813";
PKMediaSource* source = [[PKMediaSource alloc] init:entryId contentUrl:contentURL mimeType:nil drmData:nil mediaFormat:MediaFormatHls];
NSArray<PKMediaSource*>* sources = [[NSArray alloc] initWithObjects:source, nil];

// Setup media entry
PKMediaEntry *mediaEntry = [[PKMediaEntry alloc] init:entryId sources:sources duration:-1];
    
mediaEntry.externalSubtitles = @[[[PKExternalSubtitle alloc] initWithId:@"Deutsch-de"
                                                                   name:@"Deutsch"
                                                               language:@"de"
                                                           vttURLString:@"http://brenopolanski.com/html5-video-webvtt-example/MIB2-subtitles-pt-BR.vtt"
                                                               duration:570.0
                                                              isDefault:NO
                                                             autoSelect:NO
                                                                 forced:NO
                                                        characteristics:nil],
                                 [[PKExternalSubtitle alloc] initWithId:@"English-en"
                                                                   name:@"English"
                                                               language:@"en"
                                                           vttURLString:@"http://externaltests.dev.kaltura.com/player/captions_files/eng.vtt"
                                                               duration:570.0
                                                              isDefault:YES
                                                             autoSelect:YES
                                                                 forced:NO
                                                        characteristics:nil]];

In case you are using our Providers (PlayKitProviders) when you load the media you will get the PKMediaEntry object in the callback, just set the external subtitles to it.

Code Sample

The Complete Sample code can be found in the PlayKitSamples repo, in the TracksSample.

Known limitations