5 Video Download

PLVVodDownloadManager is a singleton class in the VOD SDK, primarily responsible for video download, download information callbacks, and download queue management. Download information is encapsulated in the class PLVVodDownlaodInfo, with each download task corresponding to a PLVVodDownlaodInfo object.

For usage of the downloader, refer to the implementation of PLVDownloadManagerViewController in the demo.

5.1 Download Settings

Before downloading, we need to perform some configurations.

5.1.1 AppDelegate

First, in AppDelegate, we need to configure the following:

- (void)application:(UIApplication *)application handleEventsForBackgroundURLSession:(NSString *)identifier
    completionHandler:(void (^)(void))completionHandler {
    // 处理后台下载完成回调的事件
    [[PLVVodDownloadManager sharedManager] handleEventsForBackgroundURLSession:identifier completionHandler:completionHandler];
}
- (void)applicationDidEnterBackground:(UIApplication *)application {
    // app 退到后台时进行相关设置
    [[PLVVodDownloadManager sharedManager] applicationDidEnterBackground];
}

- (void)applicationWillEnterForeground:(UIApplication *)application {
    // app 回到前台时进行相关设置
    [[PLVVodDownloadManager sharedManager] applicationWillEnterForeground];
}

- (void)applicationWillTerminate:(UIApplication *)application {
    // 程序即将结束时，修改并保存下载中视频的下载状态，用于程序下次启动后，恢复视频下载状态
    [[PLVVodDownloadManager sharedManager] applicationWillTerminate];
}

5.1.2 Downloader Settings

PLVVodDownloadManager contains the following download properties. Developers can configure them as needed or keep the default settings.

5.1.2.1 Setting the Download Directory

The default download directory is the sandbox folder "Library/Caches/PolyvVodCache". Note that after changing the download directory, offline videos from the previous directory will not be indexed. The download directory can be modified by changing the property downloadDir of PLVVodDownloadManager, or by using the method -setDownloadDir:skipBackup:error:.

// 下载目录，默认为 Library/Caches/PolyvVodCache
@property (nonatomic, copy) NSString *downloadDir;

/**
 设置下载目录
 @param downloadDir 设置的下载目录
 @param skipBackup 是否忽略 iCloud 的备份
 @param error 错误回调
 @return 是否成功
 */
- (BOOL)setDownloadDir:(NSString *)downloadDir skipBackup:(BOOL)skipBackup error:(NSError **)error;

5.1.2.2 Allowing Downloads over Cellular Network

Allowed by default. To prohibit downloads over cellular networks, set the property value allowsCellularAccess to NO.

// 是否允许使用蜂窝移动网络进行下载，默认 YES
@property (nonatomic, assign) BOOL allowsCellularAccess;

5.1.2.3 Maximum Concurrent Downloads

The download concurrency of PLVVodDownloadManager is set via maxRuningCount, with a default value of 1 and a maximum of 3.

// 允许同时下载的最大任务数, 默认为1，最大为3 
@property (nonatomic, assign) NSUInteger maxRuningCount;

5.2 Download Information Model

PLVVodDownloadInfo is the download information model class, containing the following read-only properties:

// 唯一标识
@property (nonatomic, copy, readonly) NSString *identifier;

// 队列ID
@property (nonatomic, assign, readonly) NSInteger downloadId;

// PLVVodVideo 对象
@property (nonatomic, strong, readonly) PLVVodVideo *video;

// vid 便捷属性
@property (nonatomic, copy, readonly) NSString *vid;

// 清晰度
@property (nonatomic, assign, readonly) PLVVodQuality quality;
// 文件类型,默认为视频
@property (nonatomic, assign, readonly) PLVDownloadFileType fileType;


// 下载相关
@property (nonatomic, assign, readonly) PLVVodDownloadState state; // 下载状态
@property (nonatomic, assign, readonly) double bytesPerSeconds; // 下载速率（单位：byte/s）
@property (nonatomic, assign, readonly) double progress; // 下载进度（0-1）
@property (nonatomic, assign, readonly) double unzipProgress; // 解压进度（0-1）
@property (nonatomic, strong, readonly) NSError *error; // 下载错误


// UI展示
@property (nonatomic, copy, readonly) NSString *snapshot; // 封面
@property (nonatomic, copy, readonly) NSString *title;    // 视频名称
@property (nonatomic, assign, readonly) NSUInteger filesize; // 文件大小

For the definition of clarity enumeration values, refer to VOD documentation 4.2.1. The enumeration definitions for download status and file type are as follows:

// 下载状态
typedef NS_ENUM(NSInteger, PLVVodDownloadState) {
    PLVVodDownloadStatePreparing = 0,	// 准备，默认值
    PLVVodDownloadStatePreparingStart = 7, // 准备中，正在创建任务
    PLVVodDownloadStateReady = 1,		// 就绪，下载任务已创建
    PLVVodDownloadStateRunning = 2,		// 正在下载
    PLVVodDownloadStateStopping = 3,	// 正在停止
    PLVVodDownloadStateStopped = 4,		// 停止下载
    PLVVodDownloadStateSuccess = 5,		// 下载成功
    PLVVodDownloadStateFailed = 6		// 下载失败
};

// 下载文件类型
typedef NS_ENUM(NSUInteger, PLVDownloadFileType) {
    PLVDownloadFileTypeVideo = 1 << 0,  // 视频文件
    PLVDownloadFileTypeAudio = 1 << 1   // 音频文件
};

5.3 Video Download

5.3.1 Adding a Download Task

Use the method -downloadVideo: to add a video object PLVVodVideo to the download queue. If the property autoStart is set to the default value NO, you need to call the method -startDownload to start the download; otherwise, it is not required. The relevant properties and method declarations are as follows:

// 添加任务后是否自动启动，默认 NO
@property (nonatomic, assign) BOOL autoStart;

/**
 使用后台设置的默认画质添加至下载队列
 @param video PLVVodVideo 视频对象
 @return 下载信息
 */
- (PLVVodDownloadInfo *)downloadVideo:(PLVVodVideo *)video;
/**
 开始队列下载
 */
- (void)startDownload;

/**
 停止队列下载
 */
- (void)stopDownload;

Code examples for adding a video and starting/stopping the download:

[[PLVVodDownloadManager sharedManager] downloadVideo:video]; // 将视频 video 添加到下载队列
[[PLVVodDownloadManager sharedManager] startDownload]; // 开始下载
[[PLVVodDownloadManager sharedManager] stopDownload]; // 停止下载

You can also start or stop the download of a video specified by vid using the following methods:

/**
 从指定视频开始下载
 @param vid 视频vid
 */
- (void)startDownloadWithVid:(NSString *)vid;

/**
 停止下载指定视频
 @param vid 视频vid
 */
- (void)stopDownloadWithVid:(NSString *)vid;

5.3.2 Removing a Download Task

The method declaration for removing a download task is as follows:

/**
 移除下载任务，并删除对应文件
 @param vid vid
 @param error 错误回调
 */
- (void)removeDownloadWithVid:(NSString *)vid error:(NSError **)error;

/**
 移除所有下载任务，并删除对应文件，与已完成下载的视频无关
 @param completion 删除任务后的回调
 */
- (void)removeAllDownloadWithComplete:(void(^)(void *result))completion;

Note: After a task is removed, the corresponding video file will also be deleted. Removing all download tasks does not include those that have been successfully downloaded.

5.3.3 Reading Download Tasks

Use the following methods to retrieve information about all successfully downloaded videos/local videos, or to obtain download information for a specific video based on vid.

/**
 获取所有已缓存成功视频信息
 @return 下载完成的视频数组
 */
- (NSArray<PLVVodDownloadInfo *> *)requestDownloadCompleteList;

/**
 根据vid 获取视频下载信息
 @param vid 视频vid
 */
- (PLVVodDownloadInfo *)requestDownloadInfoWithVid:(NSString *)vid;

/**
 获取已下载的本地视频
 @return 一组 PLVVodLocalVideo 对象
 */
- (NSArray<PLVVodLocalVideo *> *)localVideos;

5.4 Download Callbacks

5.4.1 Downloader Callbacks

PLVVodDownloadManager uses the following callbacks to monitor video downloads:

// 完成所有下载回调
@property (nonatomic, copy) void(^completeBlock)(void);

// 单个视频下载完成回调
@property (nonatomic, copy) void(^downloadCompleteBlock)(PLVVodDownloadInfo *info);

// 下载错误回调
@property (nonatomic, copy) void (^downloadErrorHandler)(PLVVodVideo *video, NSError *error);

Example code:

PLVVodDownloadManager *downloadManager = [PLVVodDownloadManager sharedManager];

downloadManager.downloadCompleteBlock = ^(PLVVodDownloadInfo *info) {
    NSLog(@"video vid %@ download success", info.vid);
};

downloadManager.downloadErrorHandler = ^(PLVVodVideo *video, NSError *error) {
    NSLog(@"video vid %@ download error: %@", video.vid, error);
};
downloadManager.completeBlock = ^{
    NSLog(@"all video download success");
};

5.4.2 Download Task Callbacks

Each video download information object PLVVodDownloadInfo also has its own callbacks. Developers can implement these callbacks to update the UI:

// 下载状态变更回调
@property (nonatomic, copy) void (^stateDidChangeBlock)(PLVVodDownloadInfo *info);

// 下载速率（单位：byte/s）变更回调
@property (nonatomic, copy) void (^bytesPerSecondsDidChangeBlock)(PLVVodDownloadInfo *info);

// 下载进度（0-1）变更回调
@property (nonatomic, copy) void (^progressDidChangeBlock)(PLVVodDownloadInfo *info);

// 解压进度（0-1）变更回调
@property (nonatomic, copy) void (^unzipProgressDidChangeBlock)(PLVVodDownloadInfo *info);