BCOVPlaybackController Protocol Reference

Conforms to NSObject
Declared in BCOVPlaybackController.h

Overview

Protocol adopted by objects that provide playback functionality.

Implementations of this formal protocol must support its standard playback operations, but may extend the API to perform additional functions specific to their feature set.

  delegate required method

Delegate for this BCOVPlaybackController.

@property (nonatomic, assign) id<BCOVPlaybackControllerDelegate> delegate

Discussion

Delegate for this BCOVPlaybackController.

Declared In

BCOVPlaybackController.h

  autoAdvance required method

Whether to advance to the next playback session when its previous playback session sends kBCOVPlaybackSessionLifecycleEventEnd. If this event is sent more than once by a playback session, the subsequent sends are ignored.

@property (nonatomic, assign, getter=isAutoAdvance) BOOL autoAdvance

Return Value

True if this queue should send the next session when the previous session sends kBCOVPlaybackSessionLifecycleEventEnd.

Discussion

Whether to advance to the next playback session when its previous playback session sends kBCOVPlaybackSessionLifecycleEventEnd. If this event is sent more than once by a playback session, the subsequent sends are ignored.

Defaults to NO.

Declared In

BCOVPlaybackController.h

  autoPlay required method

Whether to begin playing a new playback session as soon as it is received.

@property (nonatomic, assign, getter=isAutoPlay) BOOL autoPlay

Return Value

Whether to begin playback as soon as a new session is received.

Discussion

Whether to begin playing a new playback session as soon as it is received.

Defaults to NO.

NOTE: Enabling autoPlay in conjunction with setting a custom rate on AVPlayer may cause unexpected behavior.

Declared In

BCOVPlaybackController.h

  view required method

Returns a UIView to present playback in a view hierarchy. The view is reused across all playback sessions sent to this controller.

@property (nonatomic, readonly, strong) UIView *view

Return Value

A UIView to present playback in a view hierarchy.

Discussion

Returns a UIView to present playback in a view hierarchy. The view is reused across all playback sessions sent to this controller.

Declared In

BCOVPlaybackController.h

  options required method

A dictionary of key-value pairs used to set options in the playback controller. When setting options, you should preserve the current options in the dictionary by making a mutable copy of the existing dictionary, setting your value, and then assigning your new dictionary to this property. May be nil.

@property (nonatomic, readwrite, copy) NSDictionary *options

Return Value

The current options dictionary used by the playback controller.

Discussion

A dictionary of key-value pairs used to set options in the playback controller. When setting options, you should preserve the current options in the dictionary by making a mutable copy of the existing dictionary, setting your value, and then assigning your new dictionary to this property. May be nil.

Declared In

BCOVPlaybackController.h

  analytics required method

Returns the playback controller’s analytics object.

@property (nonatomic, readonly, copy) id<BCOVMutableAnalytics> analytics

Discussion

Returns the playback controller’s analytics object.

Declared In

BCOVPlaybackController.h

  adsDisabled required method

SSAI Only: If using other ad plug-ins, use seekWithoutAds:completionHandler: instead.

@property (nonatomic, readwrite) BOOL adsDisabled

Discussion

SSAI Only: If using other ad plug-ins, use seekWithoutAds:completionHandler: instead.

Disables ad playback which otherwise might occur after a forward -seekTo:. The intended use is, for example, to resume video playback when an app has quit and relaunched; the app can seek to a saved time and ads which have been previously viewed will not play again. Set adsDisabled to YES, then call one of the -seekToTime: methods, and finally set adsDisabled to NO in the -seekToTime: completion handler. The default value of adsDisabled is NO.

Note that unless the BCOVPlaybackSessionLifecycleEvent kBCOVPlaybackSessionLifecycleEventReady has been received, the -seekTo: completion handler will never be called. For that reason, it is recommended that you call -seekTo: from within the -playbackController:playbackSession:didReceiveLifecycleEvent delegate method for the kBCOVPlaybackSessionLifecycleEventReady event.

Declared In

BCOVPlaybackController.h

  allowsBackgroundAudioPlayback required method

Allow playback of audio when the app has switched to the background.

@property (nonatomic, readwrite) BOOL allowsBackgroundAudioPlayback

Discussion

Allow playback of audio when the app has switched to the background.

Default value is NO.

Declared In

BCOVPlaybackController.h

  allowsExternalPlayback required method

The allowsExternalPlayback property of the current playback session’s AVPlayer, as well as that of any subsequent sessions, is set to this value.

@property (nonatomic, readwrite) BOOL allowsExternalPlayback

Discussion

The allowsExternalPlayback property of the current playback session’s AVPlayer, as well as that of any subsequent sessions, is set to this value.

Declared In

BCOVPlaybackController.h

  usesExternalPlaybackWhileExternalScreenIsActive required method

The usesExternalPlaybackWhileExternalScreenIsActive property of the current playback session’s AVPlayer, as well as that of any subsequent sessions, is set to this value. This property has no effect if allowsExternalPlayback is false.

@property (nonatomic, readwrite) BOOL usesExternalPlaybackWhileExternalScreenIsActive

Discussion

The usesExternalPlaybackWhileExternalScreenIsActive property of the current playback session’s AVPlayer, as well as that of any subsequent sessions, is set to this value. This property has no effect if allowsExternalPlayback is false.

Declared In

BCOVPlaybackController.h

  pictureInPictureActive required method

Set this to YES if picture-in-picture becomes active, and NO when it deactivates.

@property (nonatomic, readwrite, assign, getter=isPictureInPictureActive) BOOL pictureInPictureActive

Discussion

Set this to YES if picture-in-picture becomes active, and NO when it deactivates.

This only needs to be toggled if allowsBackgroundAudioPlayback is set to YES. If allowsBackgroundAudioPlayback is set to NO, this property can be ignored.

Default value is NO.

Declared In

BCOVPlaybackController.h

– setPreferredPeakBitRate: required method

Set this to your preferred peak bit rate value. This value will be set on the current session and future sessions unless changed via the (optional) Preferred Bitrate menu.

- (void)setPreferredPeakBitRate:(double)preferredPeakBitRate

Discussion

Set this to your preferred peak bit rate value. This value will be set on the current session and future sessions unless changed via the (optional) Preferred Bitrate menu.

Declared In

BCOVPlaybackController.h

– updateAudienceSegmentTargetingValues: required method

Sets the audience segment targeting key/values you want to be be passed on in ad requests. This is only currently supported with IMA + VAST.

- (void)updateAudienceSegmentTargetingValues:(NSDictionary *)audienceSegmentTargetingValues

Discussion

Sets the audience segment targeting key/values you want to be be passed on in ad requests. This is only currently supported with IMA + VAST.

Declared In

BCOVPlaybackController.h

  thumbnailSeekingEnabled required method

Enables or disables thumbnail seeking for this playback controller.

@property (nonatomic, readwrite, assign) BOOL thumbnailSeekingEnabled

Discussion

Enables or disables thumbnail seeking for this playback controller.

Default value is YES

Declared In

BCOVPlaybackController.h

  streamConcurrencyEnabled required method

Enables or disables stream concurrency for this playback controller.

@property (nonatomic, readwrite, assign) BOOL streamConcurrencyEnabled

Discussion

Enables or disables stream concurrency for this playback controller.

Default value is NO

Declared In

BCOVPlaybackController.h

  ) required method

When enabled an array of AVInterstitialTimeRange objects will be created based on the ads for each BCOVVideo and will be set on the interstitialTimeRanges property of the AVPlayerItem for that BCOVVideo. The default value of generateInterstitialTimeRanges is YES.

@property (nonatomic, assign) BOOL generateInterstitialTimeRanges API_AVAILABLE ( tvos ( 9.0 API_UNAVAILABLE ( macos , ios , watchos )

Discussion

When enabled an array of AVInterstitialTimeRange objects will be created based on the ads for each BCOVVideo and will be set on the interstitialTimeRanges property of the AVPlayerItem for that BCOVVideo. The default value of generateInterstitialTimeRanges is YES.

Declared In

BCOVPlaybackController.h

  shutter required method

A view which obscures or reveals the player view.

@property (nonatomic, readwrite) BOOL shutter

Discussion

Set shutter to YES to hide the current player view behind an opaque black shutter view. Set shutter to NO to make the shutter view transparent, revealing the player view.

The shutter property setter method dispatches to the main thread.

Declared In

BCOVPlaybackController.h

  shutterFadeTime required method

Set the shutterFadeTime to the duration, in seconds, of the shutter state transition animation. The default value is zero.

@property (nonatomic, readwrite) NSTimeInterval shutterFadeTime

Discussion

Set the shutterFadeTime to the duration, in seconds, of the shutter state transition animation. The default value is zero.

Declared In

BCOVPlaybackController.h

  viewProjection required method

Position of virtual camera when viewing Video 360 streams Default values are: pan: 0 degrees tilt: 0 degrees zoom: 1.0 roll: 0 degrees

@property (nonatomic, readwrite, copy) BCOVVideo360ViewProjection *viewProjection

Discussion

Position of virtual camera when viewing Video 360 streams Default values are: pan: 0 degrees tilt: 0 degrees zoom: 1.0 roll: 0 degrees

Declared In

BCOVPlaybackController.h

  playbackRate required method

The rate (speed) desired for playback. If a value less than or equal to 0 is set the default value will be used. If a valid value other than 1.0 is set the audioTimePitchAlgorithm of the current AVPlayer item will be set to AVAudioTimePitchAlgorithmTimeDomain. Defaults to 1.0 Acts as a proxy for rate on AVPlayer. See AVPlayer documentation for more information: https://developer.apple.com/documentation/avfoundation/avplayer/1388846-rate

@property (nonatomic, assign) float playbackRate

Discussion

The rate (speed) desired for playback. If a value less than or equal to 0 is set the default value will be used. If a valid value other than 1.0 is set the audioTimePitchAlgorithm of the current AVPlayer item will be set to AVAudioTimePitchAlgorithmTimeDomain. Defaults to 1.0 Acts as a proxy for rate on AVPlayer. See AVPlayer documentation for more information: https://developer.apple.com/documentation/avfoundation/avplayer/1388846-rate

Declared In

BCOVPlaybackController.h

  enableCaptionPersistence required method

When enabled the SDK will store the localeIdentifier from the locale of the user’s selected legible AVMediaSelectionOption.

@property (nonatomic, assign) BOOL enableCaptionPersistence

Discussion

When enabled the SDK will store the localeIdentifier from the locale of the user’s selected legible AVMediaSelectionOption.

The SDK will attempt to match available AVMediaSelectionOptions using the stored localeIdentifier.

Storage is via an NSString in NSUserDefaults using kBCOVClosedCaptionPersistenceKey as the key.

When a user selects “Off” or “Auto” for the text track the value stored in NSUserDefaults is set to nil.

You can subscribe to the NSUserDefaultsDidChangeNotification notification to be notified when a user has changed their preference.

Defaults to YES

Declared In

BCOVPlaybackController.h

– addSessionConsumer: required method

Registers a session consumer with a container, to be notified of new sessions. Added consumers will be retained by this container. If a session already existed in the container at the time of subscription, the specified consumer will be sent the -didAdvanceToPlaybackSession: message.

- (void)addSessionConsumer:(id<BCOVPlaybackSessionConsumer>)consumer

Parameters

consumer

The session consumer being added to the container.

Discussion

Registers a session consumer with a container, to be notified of new sessions. Added consumers will be retained by this container. If a session already existed in the container at the time of subscription, the specified consumer will be sent the -didAdvanceToPlaybackSession: message.

Declared In

BCOVPlaybackController.h

– removeSessionConsumer: required method

Removes a session consumer from the container. The effect of this is that the container releases its ownership of the consumer, and the consumer will no longer be given new sessions to consume.

- (void)removeSessionConsumer:(id<BCOVPlaybackSessionConsumer>)consumer

Parameters

consumer

The session consumer being removed from the container.

Discussion

Removes a session consumer from the container. The effect of this is that the container releases its ownership of the consumer, and the consumer will no longer be given new sessions to consume.

Declared In

BCOVPlaybackController.h

– advanceToNext required method

Instructs this instance to advance to the next playback session. This has no effect if there are no further playback sessions. Note that the next playback session may be delivered asynchronously.

- (void)advanceToNext

Discussion

Instructs this instance to advance to the next playback session. This has no effect if there are no further playback sessions. Note that the next playback session may be delivered asynchronously.

Declared In

BCOVPlaybackController.h

– play required method

Plays the content video. On first play, cue points at position kBCOVCuePointPositionTypeBefore will be fired, and the video will play using [AVPlayer play].

- (void)play

Discussion

Plays the content video. On first play, cue points at position kBCOVCuePointPositionTypeBefore will be fired, and the video will play using [AVPlayer play].

This default behaviour may be overridden when using plugins. For more information on plugin overrides, refer to BCOVSessionProviderExtension category methods in the plugin for a method like abc_play:.

Declared In

BCOVPlaybackController.h

– pause required method

Pauses the content video. This is a proxy call to [AVPlayer pause].

- (void)pause

Discussion

Pauses the content video. This is a proxy call to [AVPlayer pause].

This default behaviour may be overridden when using plugins. For more information on plugin overrides, refer to BCOVSessionProviderExtension category methods in the plugin for a method like abc_pause:.

Declared In

BCOVPlaybackController.h

– seekToTime:completionHandler: required method

Proxy call to [AVPlayer seekToTime:toleranceBefore:toleranceAfter:completionHandler:] with a tolerance of .1 seconds. Do not call this method until after receiving kBCOVPlaybackSessionLifecycleEventReady event.

- (void)seekToTime:(CMTime)time completionHandler:(void ( ^ ) ( BOOL finished ))completionHandler

Parameters

time

Time to move to.
completionHandler

The block to invoke when the seek operation has either been completed or been interrupted.

Discussion

Proxy call to [AVPlayer seekToTime:toleranceBefore:toleranceAfter:completionHandler:] with a tolerance of .1 seconds. Do not call this method until after receiving kBCOVPlaybackSessionLifecycleEventReady event.

This default behaviour may be overridden when using plugins. For more information on plugin overrides, refer to BCOVSessionProviderExtension category methods in the plugin for a method like abc_seekToTime:completionHandler:.

Declared In

BCOVPlaybackController.h

– seekToTime:toleranceBefore:toleranceAfter:completionHandler: required method

Proxy call to [AVPlayer seekToTime:toleranceBefore:toleranceAfter:completionHandler:] Do not call this method until after receiving kBCOVPlaybackSessionLifecycleEventReady event.

- (void)seekToTime:(CMTime)time toleranceBefore:(CMTime)toleranceBefore toleranceAfter:(CMTime)toleranceAfter completionHandler:(void ( ^ ) ( BOOL finished ))completionHandler

Parameters

time

Time to move to.
toleranceBefore

Allowable tolerance before the seek target.
toleranceAfter

Allowable tolerance before the seek target.
completionHandler

The block to invoke when the seek operation has either been completed or been interrupted.

Discussion

Proxy call to [AVPlayer seekToTime:toleranceBefore:toleranceAfter:completionHandler:] Do not call this method until after receiving kBCOVPlaybackSessionLifecycleEventReady event.

This default behaviour may be overridden when using plugins. For more information on plugin overrides, refer to BCOVSessionProviderExtension category methods in the plugin for a method like abc_seekToTime:completionHandler:.

Declared In

BCOVPlaybackController.h

– seekWithoutAds:completionHandler: required method

Proxy call to [AVPlayer seekToTime:completionHandler:] Sets the current playback time to the specified time and executes the specified block when the seek operation has either been completed or been interrupted. Ads scheduled before the seek time will not be played. Ads scheduled before the seek time are not considered to have been played and any user seeks to an earlier playback time will cause those ads to play.

- (void)seekWithoutAds:(CMTime)time completionHandler:(void ( ^ ) ( BOOL finished ))completionHandler

Parameters

time

Time to move to.
completionHandler

The block to invoke when the seek operation has either been completed or been interrupted.

Discussion

Proxy call to [AVPlayer seekToTime:completionHandler:] Sets the current playback time to the specified time and executes the specified block when the seek operation has either been completed or been interrupted. Ads scheduled before the seek time will not be played. Ads scheduled before the seek time are not considered to have been played and any user seeks to an earlier playback time will cause those ads to play.

seekWithoutAds:completionHandler: is for the purpose of resuming playback after a client app has been quit and re-launched. It is recommended that playbackController.autoPlay be set to NO when using seekWithoutAds.

Do not call this method until after receiving the kBCOVPlaybackSessionLifecycleEventReady event.

Declared In

BCOVPlaybackController.h

– resumeVideoAtTime:withAutoPlay: required method

Instructs this instance to reinitialize the current session. If there is no current session, this method has no effect. Once this method is called, it will send the kBCOVPlaybackSessionLifecycleEventResumeBegin event to indicate reinitializing has begun. If an error occurs anywhere during the reinitialization, this method will send the kBCOVPlaybackSessionLifecycleEventResumeFail event. If the reinitialization succeeds, the kBCOVPlaybackSessionLifecycleEventResumeComplete will be sent.

- (void)resumeVideoAtTime:(CMTime)time withAutoPlay:(BOOL)autoPlay

Parameters

time

Seek time to set after reinitialization.
autoPlay

Automatically play new session once it is restarted.

Discussion

Instructs this instance to reinitialize the current session. If there is no current session, this method has no effect. Once this method is called, it will send the kBCOVPlaybackSessionLifecycleEventResumeBegin event to indicate reinitializing has begun. If an error occurs anywhere during the reinitialization, this method will send the kBCOVPlaybackSessionLifecycleEventResumeFail event. If the reinitialization succeeds, the kBCOVPlaybackSessionLifecycleEventResumeComplete will be sent.

Do not call this method a second time until you have received either kBCOVPlaybackSessionLifecycleEventResumeFail or kBCOVPlaybackSessionLifecycleEventResumeComplete from the first call.

Declared In

BCOVPlaybackController.h

– setVideos: required method

Specifies the source from which this instance will draw its upcoming videos for playback. The first playback session will be sent as soon as it becomes available, replacing any current playback session. Playback sessions may be delivered asynchronously.

- (void)setVideos:(NSArray<BCOVVideo*> *)videos

Parameters

videos

The source of BCOVVideo objects from which this instance should construct playback sessions.

Discussion

Specifies the source from which this instance will draw its upcoming videos for playback. The first playback session will be sent as soon as it becomes available, replacing any current playback session. Playback sessions may be delivered asynchronously.

Declared In

BCOVPlaybackController.h

– resumeAd required method

Instructs this instance to resume ad playback. This method has no effect when an ad is already playing, or if no advertising component has been integrated with this playback controller.

- (void)resumeAd

Discussion

Instructs this instance to resume ad playback. This method has no effect when an ad is already playing, or if no advertising component has been integrated with this playback controller.

Declared In

BCOVPlaybackController.h

– pauseAd required method

Instructs this instance to pause ad playback. This method has no effect when an ad is already paused, or if no advertising component has been integrated with this playback controller.

- (void)pauseAd

Discussion

Instructs this instance to pause ad playback. This method has no effect when an ad is already paused, or if no advertising component has been integrated with this playback controller.

Declared In

BCOVPlaybackController.h

– insertVideo:afterVideoAtIndex: required method

This method is used to insert an additional BCOVVideo into the player queue for this playback controller.

- (void)insertVideo:(BCOVVideo *)video afterVideoAtIndex:(NSUInteger)afterIndex

Parameters

video

The video to insert
afterIndex

The index of the video to insert after

Discussion

This method is used to insert an additional BCOVVideo into the player queue for this playback controller.

Declared In

BCOVPlaybackController.h

– addFairPlayApplicationCertificate:identifier: required method

This method is used to add a FairPlay application certificate to the playback controller’s list of available FairPLay application certificates. Certificates will be retained for the life of the playback controller.

- (void)addFairPlayApplicationCertificate:(NSData *)applicationCertificateData identifier:(NSString *)identifier

Discussion

This method is used to add a FairPlay application certificate to the playback controller’s list of available FairPLay application certificates. Certificates will be retained for the life of the playback controller.

If you are using Dynamic Delivery, application certificates are retrieved automatically by the FairPlay plugin, so this method is not needed. You can, however, use this method to pre-load your application certificate to speed up playback of the first FairPlay-encrypted video. Certificates are stored and re-used for subsequent videos.

@param applicationCertificateData The FairPlay application certificate in an NSData object. If set to nil, any existing application certificate for the given identifier will be removed. @param identifier A string used to locate the application certificate. This string may not be nil. - For Dynamic Delivery, the identifier must be the URL that was used to retrieve this certificate. - For legacy Video Cloud accounts, this should be set to kBCOVDefaultFairPlayApplicationCertificateIdentifier to apply to all accounts. - If you are using multiple legacy Video Cloud accounts, set this param to the acount ID.

Declared In

BCOVPlaybackController.h