BCOVOfflineVideoManager Class Reference

Inherits from NSObject
Declared in BCOVOfflineVideoManager.h

Overview

BCOVOfflineVideoManager This singleton class handles most aspects of video file downloading

  authProxy

Proxy object that handles specific subtasks of FairPlay key exchange as defined by the BCOVFPSAuthorizationProxy protocol.

@property (nonatomic, strong) id<BCOVFPSAuthorizationProxy> authProxy

Declared In

BCOVOfflineVideoManager.h

  delegate

Delegate for this BCOVOfflineVideoManager.

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

Declared In

BCOVOfflineVideoManager.h

  offlineVideoTokens

Returns an array of all the offline video tokens.

@property (nonatomic, readonly) NSArray<BCOVOfflineVideoToken> *offlineVideoTokens

Discussion

Each token refers to a video download in device storage, including videos that are currently being downloaded, and videos that were cancelled, paused, or failed.

Declared In

BCOVOfflineVideoManager.h

+ sharedManager

The shared instance used to access the singleton BCOVOfflineVideoManager object.

+ (BCOVOfflineVideoManager *)sharedManager

Declared In

BCOVOfflineVideoManager.h

+ initializeOfflineVideoManagerWithDelegate:options:

Initialize the Offline Video Manager.

+ (void)initializeOfflineVideoManagerWithDelegate:(id<BCOVOfflineVideoManagerDelegate>)delegate options:(NSDictionary *)options

Parameters

delegate

The delegate object conforming to the BCOVOfflineVideoManagerDelegate protocol.
options

An NSDictionary of options. The only valid dictionary entries are kBCOVOfflineVideoManagerAllowsCellularDownloadKey, kBCOVOfflineVideoManagerAllowsCellularPlaybackKey, kBCOVOfflineVideoManagerAllowsCellularAnalyticsKey, and kBCOVOfflineVideoManagerAnalyticsStorageLimitKey.

Discussion

This should be the first call to the Offline Video Manager. You can call this method again to update the delegate and options.

Declared In

BCOVOfflineVideoManager.h

– requestVideoDownload:mediaSelections:parameters:completion:

Initiate a request for a video download.

- (void)requestVideoDownload:(BCOVVideo *)video mediaSelections:(NSArray<AVMediaSelection*> *)mediaSelections parameters:(NSDictionary *)parameters completion:(void ( ^ ) ( BCOVOfflineVideoToken offlineVideoToken , NSError *error ))completionHandler

Parameters

video

BCOVVideo to be downloaded. The video should have an HLS source with an HTTPS scheme, and may use FairPlay encryption.
mediaSelections

An array of AVMediaSelections to be downloaded, in addition to the main video. The available AVMediaSelections for a BCOVVideo can be retrieved by calling -urlAssetForVideo:error: followed by [AVAsset preferredMediaSelection] or [AVAsset allMediaSelections]. Passing nil for mediaSelections will cause the preferred AVMediaSelections to be fetched. Note that with iOS 13+, all video assets must be downloaded using a single call to requestVideoDownload:mediaSelections:parameters:completion:. Additional tracks cannot be downloaded later.
parameters

NSDictionary of parameters used in this download request. May be nil. Valid parameters are: kBCOVOfflineVideoManagerRequestedBitrateKey, kBCOVFairPlayLicensePurchaseKey, kBCOVFairPlayLicenseRentalDurationKey.
completionHandler

A block that receives the new offlineVideoToken after the request is successfully made. If there is an error, offlineVideoToken will be nil, and error will report any NSError.

Discussion

If you are using FairPlay videos with Video Cloud Dynamic Delivery, FairPlay application certificates will be downloaded automatically and used as needed. If you are using legacy Video Cloud FairPlay videos, you should add any needed application certificates to the BCOVOfflineVideoManger before initiating a download, using -[addFairPlayApplicationCertificate:identifier:].

Declared In

BCOVOfflineVideoManager.h

– offlineVideoStatus

Returns an array of the status of all video downloads, including videos that are currently being downloaded, and videos that were cancelled, paused, or failed.

- (NSArray<BCOVOfflineVideoStatus*> *)offlineVideoStatus

Discussion

All objects in the array are copies, so although you can modify an object, it will have no effect on the download manager.

This method provides information about each download, like the download status, start time, progress percent, underlying AVAssetDownloadTask, and error (if any when complete).

Declared In

BCOVOfflineVideoManager.h

– offlineVideoStatusForToken:

Returns a copy of the BCOVOfflineVideoStatus object for a specific video download.

- (BCOVOfflineVideoStatus *)offlineVideoStatusForToken:(BCOVOfflineVideoToken)offlineVideoToken

Parameters

offlineVideoToken

Offline video token used to identify the downloaded video.

Discussion

BCOVOfflineVideoStatus provides information about the download, like the download status, start time, progress percent, underlying AVAggregateAssetDownloadTask, and error (if any when complete).

Declared In

BCOVOfflineVideoManager.h

– pauseVideoDownload:

Pause a current video download task.

- (void)pauseVideoDownload:(BCOVOfflineVideoToken)offlineVideoToken

Parameters

offlineVideoToken

Offline video token used to identify the download task.

Declared In

BCOVOfflineVideoManager.h

– resumeVideoDownload:

Resume a suspended video download task

- (void)resumeVideoDownload:(BCOVOfflineVideoToken)offlineVideoToken

Parameters

offlineVideoToken

Offline video token used to identify the download task.

Declared In

BCOVOfflineVideoManager.h

– cancelVideoDownload:

Cancel a video download task

- (void)cancelVideoDownload:(BCOVOfflineVideoToken)offlineVideoToken

Parameters

offlineVideoToken

Offline video token used to identify the download task.

Declared In

BCOVOfflineVideoManager.h

– deleteOfflineVideo:

Delete all files in local storage related to this offline video token.

- (void)deleteOfflineVideo:(BCOVOfflineVideoToken)offlineVideoToken

Parameters

offlineVideoToken

Offline video token used to identify the downloaded video.

Discussion

offlineVideoToken will be considered invalid after this call.

Declared In

BCOVOfflineVideoManager.h

– forceStopAllDownloadTasks

Stop all download tasks in progress.

- (void)forceStopAllDownloadTasks

Discussion

This method forces all download tasks to terminate with an error by deleting their underlying download folder. Downloads that have already completed are not affected.

WARNING: This method should only be used in very specific cases. iOS 11.0.x and iOS 11.1.x have an issue where a download task will resume to completion if it was paused and then cancelled. In that case, you cannot cancel or delete the runaway task, so your best option is to delete all download tasks.

This method is not guaranteed to stop all download tasks.

In iOS 11.2 and later, you should cancel download tasks individually using cancelVideoDownload:

Declared In

BCOVOfflineVideoManager.h

– estimateDownloadSize:options:completion:

Estimate the size of a video download in megabytes.

- (void)estimateDownloadSize:(BCOVVideo *)video options:(NSDictionary *)options completion:(void ( ^ ) ( double megabytes , NSError *error ))completionHandler

Parameters

video

The BCOVVideo object from Video Cloud. The video object should contain a valid HLS source.
options

NSDictionary of options used in this request. Use the kBCOVOfflineVideoManagerRequestedBitrateKey to specify the bitrate you plan to download.
completionHandler

A block that receives the estimated size of the video after the request is successfully made. If there is an error, megabytes will be set to zero, and error will report any NSError.

The completion handler is not called on any specific thread. You should switch to the main thread if you need to perform any UI work. It may be called synchronously or asynchronously.

Discussion

This method calls the completion handler with an estimate of the video size of the largest rendition in the HLS manifest, in megabytes. If there are any problems retrieving the value, error will be set, and size will be zero.

Declared In

BCOVOfflineVideoManager.h

– urlAssetForVideo:error:

Given a BCOVVideo, returns an AVURLAsset which represents the video source that will be used for offline downloads. BCOVVideo objects can contain multiple video sources with the preferred source being secure and appropriate for playback on iOS. Do not use this method in the context of online playback.

- (AVURLAsset *)urlAssetForVideo:(BCOVVideo *)video error:(NSError **)error

Declared In

BCOVOfflineVideoManager.h

– variantAttributesDictionariesForVideo:completion:

Retrieve an array of NSDictionary objects, one for each variant stream in the specified online HLS video.

- (void)variantAttributesDictionariesForVideo:(BCOVVideo *)video completion:(void ( ^ ) ( NSArray<NSDictionary*> *variantAttributesDictionariesArray , NSError *error ))completionHandler

Parameters

video

The BCOVVideo object from Video Cloud. The video object should contain a valid online HLS source.
completionHandler

Block that receives the array of variant attributes NSDictionary objects if the request is successfully made. If there is an error, variantAttributesDictionariesArray will be nil, and error will report any NSError.

The completion handler is not called on any specific thread. You should switch to the main thread if you need to perform any UI work. It may be called synchronously or asynchronously.

Discussion

Each dictionary contains a key:value pair for each of the variant stream’s attributes as specified by its corresponding EXT-X-STREAM-INF tag in the HLS manifest.

These attributes can be used when selecting a particular bitrate for download. If all you need are the bitrate values, use -[variantBitratesForVideo:completion:].

Declared In

BCOVOfflineVideoManager.h

– alternativeRenditionAttributesDictionariesForVideo:completion:

Retrieve an array of NSDictionary objects, one for each alternative rendition in the specified online HLS video. Alternative renditions include captions, subtitles, and secondary audio tracks.

- (void)alternativeRenditionAttributesDictionariesForVideo:(BCOVVideo *)video completion:(void ( ^ ) ( NSArray<NSDictionary*> *alternativeRenditionAttributesDictionariesArray , NSError *error ))completionHandler

Parameters

video

The BCOVVideo object from Video Cloud. The video object should contain a valid online HLS source.
completionHandler

A block that receives the array of rendition attributes NSDictionary objects if the request is successfully made. If there is an error, alternativeRenditionAttributesDictionariesArray will be nil, and error will report any NSError.

The completion handler is not called on any specific thread. You should switch to the main thread if you need to perform any UI work. It may be called synchronously or asynchronously.

Discussion

Each dictionary contains a key:value pair for each of the rendition’s attributes as specified by its corresponding EXT-X-MEDIA tag in the HLS manifest. These attributes can be used to determine what languages are available for text and audio tracks, so that these languages can be presented to the end user, or selected for download yourself based on the locale or some other criteria.

Declared In

BCOVOfflineVideoManager.h

– variantBitratesForVideo:completion:

Retrieve an array of available bitrates for the specified online HLS video.

- (void)variantBitratesForVideo:(BCOVVideo *)video completion:(void ( ^ ) ( NSArray<NSNumber*> *bitrates , NSError *error ))completionHandler

Parameters

video

The BCOVVideo object from Video Cloud. The video object should contain a valid online HLS source.
completionHandler

A block that receives the array of bitrates if the request is successfully made. If there is an error, bitrates will be nil, and error will report any NSError.

The completion handler is not called on any specific thread. You should switch to the main thread if you need to perform any UI work. It may be called synchronously or asynchronously.

Discussion

The array will be sorted from smallest to largest bitrate.

Declared In

BCOVOfflineVideoManager.h

– videoObjectFromOfflineVideoToken:

Convert an offline video token into a playable BCOVVideo object.

- (BCOVVideo *)videoObjectFromOfflineVideoToken:(BCOVOfflineVideoToken)offlineVideoToken

Parameters

offlineVideoToken

Offline video token used to identify the downloaded video.

Discussion

The returned BCOVVideo also contains all the new properties listed above, such as the downloaded thumbnail and poster image file paths, FairPlay license expiration date, download start and end times, and more.

If the downloadState of the video is BCOVOfflineVideoDownloadStateCompleted then the video associated with the token will be cached. If you need to clear the cache for any reason you can call clearOfflineVideoCache on BCOVOfflineVideoManager.

Declared In

BCOVOfflineVideoManager.h

– clearOfflineVideoCache

Clears cache of offline BCOVVideo objects

- (void)clearOfflineVideoCache

Discussion

When videoObjectFromOfflineVideoToken: is used with a video which has a downloadState of BCOVOfflineVideoDownloadStateCompletedthen BCOVOfflienVideoManager will cache that object to increase performance. This method will clean out the cache so that the next time videoObjectFromOfflineVideoToken: is called a brand new BCOVVideo object will be created.

Declared In

BCOVOfflineVideoManager.h

– preloadFairPlayLicense:parameters:completion:

Preload the FairPlay license before a video download begins.

- (void)preloadFairPlayLicense:(BCOVVideo *)video parameters:(NSDictionary *)parameters completion:(void ( ^ ) ( BCOVOfflineVideoToken offlineVideoToken , NSError *error ))completionHandler

Parameters

video

BCOVVideo to be downloaded. The video should have a source that uses FairPlay encryption and the HTTPS scheme.
parameters

NSDictionary of parameters used in this download request. Valid parameters are: kBCOVFairPlayLicensePurchaseKey, kBCOVFairPlayLicenseRentalDurationKey.
completionHandler

Block that receives the new offlineVideoToken after the request is successfully made. If there is an error, offlineVideoToken will be nil, and error will report any NSError.

Discussion

This will return an error if the video does not have a FairPlay source. When downloading multiple FairPlay-protected videos, you should call this method for each video to acquire a license for each one before beginning any of the downloads. This ensures that videos can be properly stored even when the downloads are initiated in the background.

Declared In

BCOVOfflineVideoManager.h

– renewFairPlayLicense:video:parameters:completion:

Initiate a request for a new FairPlay license.

- (void)renewFairPlayLicense:(BCOVOfflineVideoToken)offlineVideoToken video:(BCOVVideo *)video parameters:(NSDictionary *)parameters completion:(void ( ^ ) ( BCOVOfflineVideoToken offlineVideoToken , NSError *error ))completionHandler

Parameters

offlineVideoToken

Offline video token used to identify the downloaded video for which to acquire a new license.
video

BCOVVideo object for an online video object retrieved through the Playback API or the BCOVPlaybackService class. This video must not have been created by ‘-videoObjectFromOfflineVideoToken:’.
parameters

NSDictionary of parameters used in this license renewal request. May be nil. Valid parameters are: kBCOVFairPlayLicensePurchaseKey, kBCOVFairPlayLicenseRentalDurationKey.
completionHandler

A block that is called after the license renewal request has completed. If the request resulted in an error, it will be returned here as an NSError. The offlineVideoToken parameter will be the same offline video token that was passed in as the first parameter.

Discussion

You can request a new FairPlay license any time after the initial license has been acquired.

In the parameters you can specify a new rental duration, or you can convert a rental license to a purchase license.

The video does not need to be re-downloaded to use a new FairPlay license, but you do need to retrieve a new video object from the Playback API (either directly or through the BCOVPlaybackService class). If the referenced video is no longer available through the Playback API, you can use a substantially similar video, meaning the video should be from the same account, and also have the same FairPlay configuration.

You should not specify a bitrate in the parameters. To change the bitrate you need to delete the current download, and then initiate a completely new download at the new bitrate.

Declared In

BCOVOfflineVideoManager.h

– renewFairPlayLicense:video:authToken:parameters:completion:

Initiate a request for a new FairPlay license.

- (void)renewFairPlayLicense:(BCOVOfflineVideoToken)offlineVideoToken video:(BCOVVideo *)video authToken:(NSString *)authToken parameters:(NSDictionary *)parameters completion:(void ( ^ ) ( BCOVOfflineVideoToken offlineVideoToken , NSError *error ))completionHandler

Parameters

offlineVideoToken

Offline video token used to identify the downloaded video for which to acquire a new license.
video

BCOVVideo object for an online video object retrieved through the Playback API or the BCOVPlaybackService class. This video must not have been created by ‘-videoObjectFromOfflineVideoToken:’.
authToken

The authentication token with which to validate the video’s license
parameters

NSDictionary of parameters used in this license renewal request. May be nil. Valid parameters are: kBCOVFairPlayLicensePurchaseKey, kBCOVFairPlayLicenseRentalDurationKey.
completionHandler

A block that is called after the license renewal request has completed. If the request resulted in an error, it will be returned here as an NSError. The offlineVideoToken parameter will be the same offline video token that was passed in as the first parameter.

Discussion

You can request a new FairPlay license any time after the initial license has been acquired.

In the parameters you can specify a new rental duration, or you can convert a rental license to a purchase license.

The video does not need to be re-downloaded to use a new FairPlay license, but you do need to retrieve a new video object from the Playback API (either directly or through the BCOVPlaybackService class). If the referenced video is no longer available through the Playback API, you can use a substantially similar video, meaning the video should be from the same account, and also have the same FairPlay configuration.

You should not specify a bitrate in the parameters. To change the bitrate you need to delete the current download, and then initiate a completely new download at the new bitrate.

Declared In

BCOVOfflineVideoManager.h

– addFairPlayApplicationCertificate:identifier:

This method is used to add a FairPlay application certificate to the Offline Video Manager’s list of available FairPlay application certificates.

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

Parameters

applicationCertificateData

The FairPlay application certificate in an NSData object. If set to nil, any existing application certificate for the given identifier will be removed.
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.

Discussion

Certificates will be retained for the life of the application. To remove a certificate, add the same identifier with a nil as the certificate data.

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.

Declared In

BCOVOfflineVideoManager.h

– invalidateFairPlayLicense:

Invalidate the FairPlay license for the specified offline video token.

- (void)invalidateFairPlayLicense:(BCOVOfflineVideoToken)offlineVideoToken

Parameters

offlineVideoToken

Offline video token used to identify the downloaded video whose license will be invalidated.

Discussion

This method deletes the FairPlay license for the video associated with the offline video token, if there is one.

Attempts to play back a FairPlay-protected video without a license will result in a kBCOVOfflineVideoManagerErrorCodeInvalidLicense error.

If needed you can request a new FairPlay license for the video after it has been deleted.

Declared In

BCOVOfflineVideoManager.h

– fairPlayLicenseExpiration:

Returns an NSDate representing the expiration of the FairPlay license for the video associated with the offline video token.

- (NSDate *)fairPlayLicenseExpiration:(BCOVOfflineVideoToken)offlineVideoToken

Parameters

offlineVideoToken

Offline video token used to identify the downloaded video.

Return Value

NSDate representing the expiration of the FairPlay license, NSDate.distantFuture for purchase licenses or clear (no FairPlay) videos, or nil if there is no license.

Discussion

Returns NSDate.distantFuture for “purchase” licenses.

Returns NSDate.distantFuture if the video is not encrypted with FairPlay.

Returns nil if the video has no FairPlay license.

Declared In

BCOVOfflineVideoManager.h

– mediaSelectionGroupForMediaCharacteristic:offlineVideoToken:

Returns the media selection group for a downloaded video specified by the offline video token.

- (AVMediaSelectionGroup *)mediaSelectionGroupForMediaCharacteristic:(NSString *)mediaCharacteristic offlineVideoToken:(BCOVOfflineVideoToken)offlineVideoToken

Parameters

mediaCharacteristic

The media characteristic that you are interested in. Supported values are AVMediaCharacteristicAudible and AVMediaCharacteristicLegible.
offlineVideoToken

Offline video token used to identify the downloaded video. Must not refer to a download in progress.

Discussion

The downloaded video must be complete, or this method will return nil.

Declared In

BCOVOfflineVideoManager.h

– downloadedMediaSelectionOptionsForMediaCharacteristic:offlineVideoToken:

Returns the downloaded media selection options for a downloaded video specified by the offline video token, as reported by the AVMediaCache for the underlying AVURLAsset. May return nil.

- (NSArray<AVMediaSelectionOption*> *)downloadedMediaSelectionOptionsForMediaCharacteristic:(NSString *)mediaCharacteristic offlineVideoToken:(BCOVOfflineVideoToken)offlineVideoToken

Parameters

mediaCharacteristic

The media characteristic that you are interested in. Supported values are AVMediaCharacteristicAudible and AVMediaCharacteristicLegible.
offlineVideoToken

Offline video token used to identify the downloaded video.

Declared In

BCOVOfflineVideoManager.h