播放器 SDK 支持下载功能。用户可在有网络的条件下将视频下载至本地，随后在无网络的环境下观看。SDK 支持下载 DirectUrl 视频源和 Vid 视频源，并提供开始、暂停、恢复、删除等控制下载任务的方法。

初始化下载功能 #

示例代码如下：

// 开启 HLS 下载功能。可选，如业务中无需下载 HLS 视频，可跳过。
TTVideoEngineDownloadTaskManager.enableHlsProxy(true);

// 必填，设置下载文件存储路径    
String platformDir;
if (Platform.isIOS) {
    platformDir = (await getApplicationDocumentsDirectory()).path;
} else {
    platformDir = (await getDownloadsDirectory())!.path;
}
platformDir = "$platformDir/xxxx";
TTVideoEngineDownloadTaskManager.setDownloadDirectory(platformDir);

// 初始化 SDK    
FlutterTTSDKManager.startWithConfiguration(sdkConfig);

// 选填，设置最大并发下载数，默认值为 1        
TTVideoEngineDownloadTaskManager.setMaxDownloadOperationCount(3); 

// 选填，设置设备可用磁盘空间的最低阈值（单位：byte）。默认值 1G。当可用磁盘空间低于此值将无法执行下载任务，并会触发错误码为 -9947 的错误。注意该剩余空间通常小于系统设置显示的剩余空间大小。
TTVideoEngineDownloadTaskManager.setLimitFreeDiskSize(1024 * 1024 * 1024); 

// 默认支持缓存最多 50 个视频。如业务超出此限制，需进行以下设置
TTVideoEngineDownloadTaskManager.setLimitFreeDiskCount(500);

创建下载任务 #

SDK 支持播放 DirectUrl 视频源和 Vid 视频源。与之对应，SDK 也提供了不同数据源的下载能力。

创建 DirectUrl 视频源下载任务 #

适用于下载来自火山引擎或第三方 CDN 的视频 URL 地址。通过传入视频的直接播放地址来指定播放内容。除了 url，您还必须提供以下两个关键参数：

• vid：视频的唯一标识。可以是您自己的视频管理系统中的唯一标识，也可以在 App 层自行生成一个 ID。此 ID 会用于播放器 SDK 的日志上报、预加载、预渲染等功能中。
• cacheKey：视频的缓存索引 Key。为确保唯一性，推荐使用 URL 的 MD5 值。为确保播放器缓存和下载功能的稳定性，强烈建议您遵循以下规范来设置 cacheKey：
  • 使用字符范围：cacheKey 的取值应仅包含字母 (a-z, A-Z) 和数字 (0-9)。
  • 避免特殊符号：不要在 cacheKey 中使用任何特殊符号，例如 _、-、/、?、& 等。

// 传入 urls、cacheKey、videoId，其中 urls 和 cacheKey 必填，cacheKey 需和视频源一一对应
TTVideoEngineDownloadURLTask task = TTVideoEngineDownloadURLTask(urls: <urls>, cacheKey: <cachekey>, videoId: <videoId>);
task.resume();

创建 Vid 视频源下载任务 #

适用于下载已上传至火山引擎视频点播服务的视频。通过视频的 Vid 和其对应的临时播放凭证 PlayAuthToken 来指定播放内容。这两个参数通常由您的业务服务端下发，客户端直接使用即可。详情请见通过临时播放 Token 播放。

// 传入 videoId、playAuthToken 和目标清晰度
// codecType：指定需下载的视频编码格式，默认下载 H.264
TTVideoEngineDownloadVidTask task = TTVideoEngineDownloadVidTask(
                            videoId: <videoId>,
                            playAuthToken: <playAuthToken>,
                            resolution: <resolution>,
                            codecType: <codecType>);
task.resume();

控制下载任务 #

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

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

// 暂停单个下载任务，支持断点续传。
task.suspend();

// 删除单个下载任务。
// 下载任务被删除后，任务会停止，同时 TTVideoEngineDownloadTaskManager 将不再管理这个任务。
task.invalidateAndCancel();

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

// 开始/恢复所有下载任务
TTVideoEngineDownloadTaskManager.resumeAllTask();

// 暂停所有下载任务
TTVideoEngineDownloadTaskManager.suspendAllTask();

// 删除所有下载任务
TTVideoEngineDownloadTaskManager.removeAllTask();

设置监听 #

/**
 * 下载任务完成回调。
 * @param task 当前下载任务。
 * @param error 错误。error 为 null 则为下载任务成功，否则为下载任务失败。
 */
TTVideoEngineDownloadTaskManager.onComplete = (TTVideoEngineDownloadTask task, TTError? error) {
  print('Download-onComplete: $task, $error');
};

/**
 * 下载任务进度更新回调。
 * @param task 当前下载任务。
 *             - downloadTask.countOfBytesReceived 当前下载任务已下载的数据总量（HLS 不适用，见下方注意点）
 *             - downloadTask.countOfBytesExpectedToReceive 当前下载任务需要下载的总数据量（HLS 不适用，见下方注意点）
 *             - progress 当前下载任务进度 0.0~1.0
 */
TTVideoEngineDownloadTaskManager.onProgress = (TTVideoEngineDownloadTask task, double progress) {
  print('Download-onProgress: $task, $progress');
};

/**
 * 下载任务开始/恢复回调。
 * @param downloadTask 当前下载任务。
 * @param  fileOffset 已下载的数据量。
 * @param  expectedTotalBytes 该任务要下载的总数据量。
 */
TTVideoEngineDownloadTaskManager.onResume = (TTVideoEngineDownloadTask task, int fileOffset, int expectedTotalBytes) {
  print('Download-onResume: $task, $fileOffset, $expectedTotalBytes');
};

/**
 * 下载任务状态变更回调。
 * @param task 当前下载任务。
 * @param state 当前下载任务状态：
 *              - init(0)：初始化。
 *              - waiting(1): 等待中。
 *              - running(2): 运行中。
 *              - suspended(3): 暂停。
 *              - canceling(4): 正在取消。
 *              - completed(5): 完成。
 */ 
TTVideoEngineDownloadTaskManager.onStateChanged = (TTVideoEngineDownloadTask task, TTVideoEngineDownloadState state) {
  print('Download-onStateChanged: $task, $state');
};

播放视频 #

SDK 内部已处理下载缓存与播放的协同关系。您需要调用 enablePlayCachedSource 开启离线播放已下载视频，SDK 会优先播放已经下载的视频，即使它们尚未完全下载完成。

播放 DirectUrl 视频源 #

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

// 设置source前，开启离线播放已下载视频
player.enablePlayCachedSource();

// 注意 cacheKey 与下载时使用的 cacheKey 一致
TTVideoEngineUrlSource source = TTVideoEngineUrlSource.initWithURLS(<urls>, <cacheKey>);
player.setMediaSource(source);

播放 Vid 视频源 #

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

// 设置 source 前，开启离线播放已下载视频
player.enablePlayCachedSource();

// 注意 resoluton 与下载时使用的 resolution 一致
TTVideoEngineVidSource source =
        TTVideoEngineVidSource.init(vid: <vid>, playAuthToken: <playAuthToken>, resolution: <resolutionType>);
player.setMediaSource(source);

获取下载任务列表 #

调用 loadAllTask 获取完整的下载任务列表。SDK 会返回所有任务的状态。

List<TTVideoEngineDownloadTask> taskList = await TTVideoEngineDownloadTaskManager.loadAllTask();