Player Settings
The player has a settings property, of type PKPlayerSettings, which can be configured for the instance. Some of the setting that can be configured for the player are the tracks selection style and/or language, the text track styling, whether to enable closed captions, whether to allow playing FairPlay on external screens and more.
On this page:
The PKPlayerSettings class
@objc public class PKPlayerSettings: NSObject {
@objc public var cea608CaptionsEnabled = false
/// The settings for network data consumption.
@objc public var network = PKNetworkSettings()
@objc public var trackSelection = PKTrackSelectionSettings()
@objc public var textTrackStyling = PKTextTrackStyling()
@objc public var contentRequestAdapter: PKRequestParamsAdapter?
@objc public var licenseRequestAdapter: PKRequestParamsAdapter?
@objc public var fairPlayLicenseProvider: FairPlayLicenseProvider?
@objc public var allowFairPlayOnExternalScreens = false
@objc public var shouldPlayImmediately = false
...
}
The PKNetworkSettings class
@objc public class PKNetworkSettings: NSObject {
/// Indicates the desired limit of network bandwidth consumption for this item.
///
/// Set preferredPeakBitRate to non-zero to indicate that the player should attempt to limit item playback to that bit rate, expressed in bits per second.
/// If network bandwidth consumption cannot be lowered to meet the preferredPeakBitRate, it will be reduced as much as possible while continuing to play the item.
///
/// @available(iOS 8.0, *) via AVPlayerItem
@objc public var preferredPeakBitRate: Double = 0 {
didSet {
self.onChange?(.preferredPeakBitRate(preferredPeakBitRate))
}
}
/// Indicates the media duration the caller prefers the player to buffer from the network ahead of the playhead to guard against playback disruption.
///
/// The value is in seconds. If it is set to 0, the player will choose an appropriate level of buffering for most use cases.
/// Note that setting this property to a low value will increase the chance that playback will stall and re-buffer, while setting it to a high value will increase demand on system resources.
/// Note that the system may buffer less than the value of this property in order to manage resource consumption.
///
/// @available(iOS 10.0, *) via AVPlayerItem
@objc public var preferredForwardBufferDuration: Double = 0 {
didSet {
self.onChange?(.preferredForwardBufferDuration(preferredForwardBufferDuration))
}
}
/// Indicates that the player is allowed to delay playback at the specified rate in order to minimize stalling
///
/// For further details please see Apple's documentation: https://developer.apple.com/documentation/avfoundation/avplayer/1643482-automaticallywaitstominimizestal
///
/// @available(iOS 10.0, tvOS 10.0, *) via AVPlayer
@objc public var automaticallyWaitsToMinimizeStalling: Bool = true {
didSet {
self.onChange?(.automaticallyWaitsToMinimizeStalling(automaticallyWaitsToMinimizeStalling))
}
}
/// Tells the player whether or not to buffer the media, or stop after initializing the asset and fetching the keys.
///
/// Default value is true, initialize the asset, fetch the keys and buffer the media.
/// If the value is set to false, the player will stop after initializing the asset and fetching the keys. A manual call to player startBuffering is needed.
///
/// This comes in handy when you would like to divide between the views and initialize the media before the user interacts with the player to show it, start buffering and playing.
/// In another case if you would like to start initializing the next media without buffering it, so that once the media is switched to the next one, it will be smother.
@objc public var autoBuffer: Bool = true
...
}
The PKTrackSelectionSettings class
@objc public class PKTrackSelectionSettings: NSObject {
// Text selection settings
@objc public var textSelectionMode: TrackSelec tionMode = .off
@objc public var textSelectionLanguage: String?
// Audio selection settings
@objc public var audioSelectionMode: TrackSelectionMode = .off
@objc public var audioSelectionLanguage: String?
}
The PKTextTrackStyling class
@objc public class PKTextTrackStyling: NSObject {
private(set) var textColor: RGBA?
private(set) var backgroundColor: RGBA?
private(set) var textSize: NSNumber?
private(set) var edgeStyle: PKTextMarkupCharacterEdgeStyle = .none
private(set) var edgeColor: RGBA?
private(set) var fontFamily: String?
...
}
Sample code
Tracks Selection
Swift
player.settings.trackSelection.textSelectionMode = .selection
player.settings.trackSelection.textSelectionLanguage = "en"
player.settings.trackSelection.audioSelectionMode = .selection
player.settings.trackSelection.audioSelectionLanguage = "en"
Objective-C
self.player.settings.trackSelection.textSelectionMode = TrackSelectionModeSelection;
self.player.settings.trackSelection.textSelectionLanguage = @"en";
self.player.settings.trackSelection.audioSelectionMode = TrackSelectionModeSelection;
self.player.settings.trackSelection.audioSelectionLanguage = @"en";
Text Track Styling
Swift
player.settings.textTrackStyling
.setTextColor(UIColor.black)
.setBackgroundColor(UIColor.white)
.setTextSize(percentageOfVideoHeight: 10)
.setEdgeStyle(.none)
.setFontFamily("Helvetica")
player.updateTextTrackStyling()
Objective-C
[[[[[self.player.settings.textTrackStyling setTextColor:UIColor.blackColor]
setBackgroundColor:UIColor.whiteColor]
setTextSizeWithPercentageOfVideoHeight:10]
setEdgeStyle:PKTextMarkupCharacterEdgeStyleNone]
setFontFamily:@"Helvetica"];
[self.player updateTextTrackStyling];
FairPlay on External Screens
In order to enable playing FP on external screens this property should be configured to true. The default value is false.
Swift
player.settings.allowFairPlayOnExternalScreens = true
Objective-C
self.player.settings.allowFairPlayOnExternalScreens = YES;
Closed Captions
In order to enable the CC this property should be configured to true. The default value is false.
Swift
player.settings.cea608CaptionsEnabled = true
Objective-C
self.player.settings.cea608CaptionsEnabled = YES;
Play Immediately
If this value is set to true, playImmediatelyAtRate will be called on the player. Otherwise play will be called.
When the player’s currentItem has a value of NO for playbackBufferEmpty, this method causes the value of rate to change to the specified rate, the value of timeControlStatus to change to AVPlayerTimeControlStatusPlaying, and the receiver to play the available media immediately, whether or not prior buffering of media data is sufficient to ensure smooth playback.
If insufficient media data is buffered for playback to start (e.g. if the current item has a value of YES for playbackBufferEmpty), the receiver will act as if the buffer became empty during playback, except that no AVPlayerItemPlaybackStalledNotification will be posted.
@available(iOS 10.0, tvOS 10.0, *)
Swift
player.settings.shouldPlayImmediately = true
Objective-C
self.player.settings.shouldPlayImmediately = YES;
Automatically Waits To Minimize Stalling
If this value is set to false, the player will cause playback to start immediately as long as the playback buffer is not empty. Default value is true.
Swift
player.settings.network.automaticallyWaitsToMinimizeStalling = true
Objective-C
player.settings.network.automaticallyWaitsToMinimizeStalling = YES;
Auto Buffer
If the value is set to false, the prepare called on the player will only initialize the asset and perform key fetching without buffering the media. Start buffering will be needed to be done manually on the client side. Default value is true.
Swift
player.settings.network.autoBuffer = false
Objective-C
player.settings.network.autoBuffer = NO;
When buffering is needed call startBuffering on the player.
Needs to be called before calling play on the player.
Swift
player.startBuffering()
Objective-C
[player startBuffering];