接入下载功能

本文介绍如何接入 iOS 点播 SDK 的下载功能，包含功能介绍、前提条件、集成步骤等内容。

功能介绍

iOS 点播 SDK 提供下载功能，支持用户在播放器中将视频缓存至本地观看。iOS 点播 SDK 支持下载 DirectUrl 视频源和 Vid 视频源，并提供开始、暂停、恢复、删除等控制下载任务的方法。

前提条件

在接入下载功能前，您需要阅读集成准备以及快速开始 - 初始化点播 SDK 章节，确保已经完成 SDK 的初始化。

初始化下载功能

使用下载功能前，您需要先在点播 SDK 初始化过程中对下载功能进行一些必要的配置，例如是否开启下载 HLS 视频的能力、设置下载路径。此外您还可以设置最大并发数和空闲磁盘空间大小的限制等。

示例代码如下：

- (void)initTTSDK {
    // 开启 HLS 下载功能。可选，如业务中无需下载 HLS 视频，可跳过。
    [TTVideoEngine.ls_localServerConfigure setOptionForKey:@(VEKKeyHLSProxyProtocolEnable_BOOL) value:@YES];

    // 必填，设置下载文件存储路径
    [TTVideoEngine ls_localServerConfigure].downloadDirectory = @"xxxxx";
    
    // 初始化点播 SDK
    [TTSDKManager startWithConfiguration:configuration];
    
    // 选填，设置最大并发下载数，默认值为 1
    [TTVideoEngineDownloader shareLoader].maxDownloadOperationCount = 3;
    
    // 选填，设置空闲磁盘空间大小的限制，默认值 1G
    // 当前设为 1G，如果剩余磁盘大小不足 1G，则返回 TTVideoEngineErrorNotEnoughDiskSpace 错误
    [TTVideoEngineDownloader shareLoader].limitFreeDiskSize = 1024 * 1024 * 1024;
    
    // iOS 点播 SDK 默认支持缓存最多 50 个视频，如业务超出此限制，需进行以下设置
    [TTVideoEngine setGlobalForKey:VEGSKeyPlayerVideoModelMaxCache_NSInteger value:@(500)];
}

使用下载功能

创建下载任务

点播 SDK 支持播放 DirectUrl 视频源和 Vid 视频源。与之对应，点播 SDK 也提供了不同数据源的下载能力。创建新的下载任务之前，建议您调用 getAllTasksWithCompletionHandler 方法获取已有下载任务。点播 SDK 会自动保存未完成的下载任务，在对应业务启动时调用可以获取先前被中断的下载任务。您可以在 getAllTasksWithCompletionHandler 的 block 中创建下载任务，以保证调用顺序。

创建 DirectUrl 视频源下载任务

[[TTVideoEngineDownloader shareLoader] getAllTasksWithCompletionHandler:^(NSArray<__kindof TTVideoEngineDownloadTask *> * _Nonnull tasks) {
    TTVideoEngineDownloadURLTask *urlTask = [[TTVideoEngineDownloader shareLoader] urlTask:@[urlString] key:key videoId:nil];
    [urlTask resume];
  }];

创建 Vid 视频源下载任务

[[TTVideoEngineDownloader shareLoader] getAllTasksWithCompletionHandler:^(NSArray<__kindof TTVideoEngineDownloadTask *> * _Nonnull tasks) {
    TTVideoEngineDownloadVidTask *vidTask = [[TTVideoEngineDownloader shareLoader] vidTask:videoID playAuthToken:token resolution:TTVideoEngineResolutionTypeSD];
    [vidTask resume];
  }];

控制下载任务

通过以下方法控制单个下载任务：

// 开始/恢复单个下载任务。
// 支持断点续传。
[task resume];

// 暂停单个下载任务，支持断点续传。
// 此方法需要在主线程调用。
[task suspend];

// 删除单个下载任务。
// 下载任务被删除后，任务会停止，同时 TTVideoEngineDownloader 将不再管理这个任务。
// 此接口为异步操作，您需要在 `getAllTasksWithCompletionHandler` 的回调中检查是否被删除。
[task invalidateAndCancel];

通过以下方法控制所有下载任务：

// 暂停所有下载任务。
// 此方法必须在 `getAllTasksWithCompletionHandler` 之后调用。
- (void)suspendAllTasks;

// 开始/恢复所有下载任务。
// 此方法必须在 `getAllTasksWithCompletionHandler` 之后调用。
- (void)resumeAllTasks;

// 删除所有下载任务。
// 此方法必须在 `getAllTasksWithCompletionHandler` 之后调用。
- (void)removeAllTasks;

设置监听

下载任务的完成情况、进度和状态等信息都需要通过实现 TTVideoEngineDownloaderDelegate 中的方法来获取，示例代码如下：

// 设置回调接收
 [TTVideoEngineDownloader shareLoader].delegate = self;

/**
 * 下载任务完成回调。
 * @param downloadTask 当前下载任务。
  * @param error 错误。error 为 null 则为下载任务成功，否则为下载任务失败。
 */
- (void)VideoEngineDownloader:(TTVideoEngineDownloader *)downloader
         downloadTask:(TTVideoEngineDownloadTask *)downloadTask
     didCompleteWithError:(nullable NSError *)error;

/**
 * 下载任务进度更新回调。
 * @param downloadTask 当前下载任务。
 *                 - downloadTask.countOfBytesReceived 当前下载任务已下载的数据总量（HLS 不适用，见下方注意点）
 *                 - downloadTask.countOfBytesExpectedToReceive 当前下载任务需要下载的总数据量（HLS 不适用，见下方注意点）
 *                 - downloadTask.progress 当前下载任务进度 0.0~1.0
 * @param  bytesWritten 本次回调新增下载的数据量，单位为 Byte。
 * @param  timeMs 当前时间。
 */
- (void)VideoEngineDownloader:(TTVideoEngineDownloader *)downloader
         downloadTask:(TTVideoEngineDownloadTask *)downloadTask
          writeData:(int64_t)bytesWritten
         timeInterval:(double)timeMS;

/**
 * 下载任务开始/恢复回调。
 * @param downloadTask 当前下载任务。
 * @param  fileOffset 已下载的数据量。
 * @param  expectedTotalBytes 该任务要下载的总数据量。
 */
- (void)VideoEngineDownloader:(TTVideoEngineDownloader *)downloader
         downloadTask:(TTVideoEngineDownloadTask *)downloadTask
      didResumeAtOffset:(int64_t)fileOffset
      expectedTotalBytes:(int64_t)expectedTotalBytes;

/**
 * 下载任务状态变更回调。
 * @param downloadTask 当前下载任务。
 * @param  downloadState 当前下载任务状态：
 *                     - TTVideoEngineDownloadStateInit(0)：初始化。
 *                     - TTVideoEngineDownloadStateWaiting(1): 等待中。
 *                     - TTVideoEngineDownloadStateRunning(2): 运行中。
 *                     - TTVideoEngineDownloadStateSuspended(3): 暂停。
 *                     - TTVideoEngineDownloadStateCanceling(4): 正在取消。
 *                     - TTVideoEngineDownloadStateCompleted(5): 完成。
 */
- (void)VideoEngineDownloader:(TTVideoEngineDownloader *)downloader
         downloadTask:(TTVideoEngineDownloadTask *)downloadTask
         stateChanged:(TTVideoEngineDownloadState)downloadState;

播放视频

SDK 内部已经处理了下载缓存与播放的联动关系。SDK 会优先播放已经下载的视频，即使它们尚未完全下载完成，因此您播放时无需额外设置。

播放 DirectUrl 视频源

参考以下示例代码播放 DirectUrl 视频源：

// 播放已下载的 HLS 视频前必须设置以下 option
[self.videoEngine setOptionForKey:VEKKeyIsAllowAllExtensions value:@1];

// 注意 cacheKey 与下载时使用的 cacheKey 一致
TTVideoEngineUrlSource *urlSource = [[TTVideoEngineUrlSource alloc] initWithUrl:videoUrl cacheKey:cacheKey];
[self.videoEngine setVideoEngineVideoSource:urlSource];
[self.videoEngine play];

播放 Vid 视频源

参考以下示例代码播放 Vid 视频源：

// 离线播放已下载的视频前必须设置以下 option 
[self.videoEngine setOptionForKey:VEKKeyModelCacheVideoInfoEnable_BOOL value:@(YES)];
[self.videoEngine setOptionForKey:VEKKeyPlayerVideoModelPriority_ENUM value:@(TTVideoEngineVideoModelUseLocal)];

// 播放已下载的 HLS 视频前必须设置以下 option
[self.videoEngine setOptionForKey:VEKKeyIsAllowAllExtensions value:@1];

// 注意 resoluton 与下载时使用的 resolution 一致
TTVideoEngineVidSource *vidSource = [[TTVideoEngineVidSource alloc] initWithVid:vid playAuthToken:playAuthToken resolution:resolution];
[self.videoEngine setVideoEngineVideoSource:vidSource];
[self.videoEngine play];

错误码说明

以下是下载任务完成回调中可能会返回的错误码及其说明：