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

功能介绍

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

初始化下载功能

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

示例代码如下：

//（非必需）自定义下载文件存储路径，默认路径："/data/user/0/包名/cache/video_cache/mdlDownload"。
// 如需自定义下载文件存储路径，必须在播放器 SDK 初始化之前调用。
TTVideoEngine.setStringValue(DATALOADER_KEY_STRING_DOWNLOAD_DIR, getApplicationContext().getExternalFilesDir(Environment.DIRECTORY_DOWNLOADS).getAbsolutePath());

// 开启 HLS 下载功能。可选，如业务中无需下载 HLS 视频，可跳过。
TTVideoEngine.setIntValue(DataLoaderHelper.DATALOADER_KEY_INT_ENABLE_HLS,1); // 开启 HLS
TTVideoEngine.setIntValue(DataLoaderHelper.DATALOADER_KEY_ENABLE_HLS_PROXY,1); // 开启 HLS proxy

// 播放器 SDK 初始化，详见快速开始文档
Env.init(...);

// Vid 下载时，会有下载数量限制，可通过以下两种设置方式调整限制
// 方式一：去除下载数量限制，存入 db 数据库直至磁盘空间不足
VideoModelDBManager.setEnableSizeLimit(false);
// 方式二：根据业务需求自行设置下载数量限制
VideoModelDBManager.setCacheSize(Integer.MAX_VALUE);

//（非必需）设置最大并发下载数，默认值为 1。
Downloader.getInstance().setMaxDownloadOperationCount(1);

//（非必需）设置空闲磁盘空间大小的限制（单位为 Byte）。默认值为 1 GB，如果剩余磁盘大小不足 1 GB，则返回 ERROR_CODE_DOWNLOAD_DISK_FULL错误。
Downloader.getInstance().setLimitFreeDiskSize(1024 * 1024 * 1024);

获取已有下载任务

初始化后，调用 loadAllTasks 方法获取已有下载任务，包括已完成的任务和未完成的任务。执行完成后，SDK 会触发 downloaderDidLoadAllTask 回调。

// 加载已有下载任务，包括已完成的任务和未完成的任务。
// 执行完成会触发 downloaderDidLoadAllTask 回调。
// 初始化后即可调用此接口。
// 可用来做持久化：app 退出重新进入，通过调用此接口，可获取已下载完成和未完成的下载任务列表。
Downloader.getInstance().loadAllTasks(this.getApplicationContext());

创建下载任务

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

创建 DirectUrl 视频源下载任务

// 视频源
String[] urls = { httpUrl };
// 缓存 key，不可为空，需与视频源一一对应，比如使用 HTTP URL 的 MD5 值
String cacheKey = MD5(httpUrl); 
String vid = "videoID"; 
DownloadTask downloadTask = Downloader.getInstance().urlTask(urls, cacheKey, vid);

创建 Vid 视频源下载任务

// 视频 ID
String videoId = "your video id";
// 播放鉴权 token
String playAuthToken = "your video id's play auth token";
// 分辨率
Resolution resolution = Resolution.High;

DownloadTask downloadTask = Downloader.getInstance().vidTask(videoId, resolution, playAuthToken);

控制下载任务

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

// 开始/恢复单个下载任务。
// 执行完毕后，SDK 会触发 downloaderDidResume 回调。
// 支持断点续传。
downloadTask.resume(); 

// 暂停单个下载任务。
downloadTask.suspend();

// 删除单个下载任务。
// 删除过程为异步，删除完成后 SDK 会触发 downloaderDidComplete 回调。回调参数 error 不为空，error.code 为 -9995。 
downloadTask.invalidateAndCancel();

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

// 开始/恢复所有下载任务
Downloader.getInstance().resumeAllTasks();

// 暂停所有下载任务
Downloader.getInstance().suspendAllTasks();

// 删除所有下载任务
Downloader.getInstance().invalidateAndCancelAllTasks();

获取下载状态和进度

为了让您的应用能够实时响应下载过程中的各种变化，例如在 UI 上展示进度条、更新任务状态或处理下载结果，您需要实现 IDownloaderListener 接口。SDK 会在任务进度更新、状态变更（如等待、运行中、暂停）以及最终完成或失败时，自动调用您实现的回调方法。

Downloader.getInstance().setListener(new IDownloaderListener() {
    /**
     * 下载任务完成回调。
     *
     * @param task 当前下载任务。
     * @param error 错误信息。如果 error 为 null，表示下载成功；否则表示下载失败。
     */
    @Override
    public void downloaderDidComplete(Downloader downloader, DownloadTask task, @Nullable Error error) {
        // 在此处理下载完成或失败的逻辑。
    }

    /**
     * @deprecated 该回调已废弃，请使用 downloaderOnProgress() 替代。
     *             对于 HLS 视频，其 receivedSize/totalSize 返回的是 TS 分片计数。
     */
    @Deprecated
    @Override
    public void downloaderProgress(Downloader downloader, DownloadTask task, long receivedSize, long totalSize) {
    
    }

    /**
     * （1.48.2 新增）下载任务进度回调。
     *
     * @param task 当前下载任务。
     * @param receivedSize 已下载的文件大小，单位为 Byte。对于 HLS，此值可以正确返回已下载的字节数。
     * @param totalSize 文件总大小，单位为 Byte。对于 HLS，由于总大小未知，此值在下载过程中为 -1，下载结束后才能获取。
     */
    @Override
    public void downloaderOnProgress(Downloader downloader, DownloadTask task, long receivedSize, long totalSize) {
        // 推荐调用 task.getProgress() 获取所有视频格式（包括 HLS）的精确下载百分比。
        float progress = task.getProgress(); // progress 范围为 [0.0, 1.0]。
        int percent = (int) (progress * 100);
        
        // 您现在可以使用 receivedSize 参数向用户展示 HLS 视频已下载的具体大小（例如 MB）。
        // 在此更新您的进度条 UI。
        // Log.d("Downloader", String.format("任务 %s 进度: %d%%, 已下载: %.2f MB", 
        //        task.getVid(), percent, receivedSize / 1024.0 / 1024.0));
    }

    /**
     * 下载任务开始或恢复时回调。
     *
     * @param task 当前下载任务。
     * @param fileOffset 文件偏移量，代表已下载的数据量。
     * @param expectedTotalBytes 任务预期要下载的总数据量。
     */
    @Override
    public void downloaderDidResume(Downloader downloader, DownloadTask task, long fileOffset, long expectedTotalBytes) {
        // 在此处理任务开始或恢复的逻辑。
    }

    /**
     * 所有下载任务完成回调。
     *
     * @param allTasks 所有任务列表，包含已完成的和未完成的。
     */
    @Override
    public void downloaderDidLoadAllTask(Downloader downloader, @Nullable List<DownloadTask> allTasks, @Nullable Error error) {
        // 在此可以获取持久化的下载任务列表。
    }

    /**
     * 下载任务状态变更回调。
     *
     * @param task 当前下载任务。
     * @param state 当前下载任务状态：
     *              - DOWNLOAD_TASK_STATE_INIT(0)：初始化。
     *              - DOWNLOAD_TASK_STATE_WAITING(1)：等待中。
     *              - DOWNLOAD_TASK_STATE_RUNNING(2)：运行中。
     *              - DOWNLOAD_TASK_STATE_SUSPENDED(3)：暂停。
     *              - DOWNLOAD_TASK_STATE_COMPLETED(4)：完成。
     *              - DOWNLOAD_TASK_STATE_FAILED(5)：失败。
     */
    @Override
    public void downloaderTaskStateDidChange(Downloader downloader, DownloadTask task, int state) {
        // 在此可以根据任务状态更新 UI。
    }
});

播放视频

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

播放 DirectUrl 视频源

// 播放已下载的 HLS 视频前必须设置以下 option
ttVideoEngine.setIntOption(PLAYER_OPTION_INT_ALLOW_ALL_EXTENSIONS, 1);

final String vid = "video id"; // 视频源与 vid 必须一一对应
final String url = "http://www.example.com/h264.mp4";
// 播放 cacheKey 与下载 cacheKey 保持一致
final String cacheKey = TTVideoEngine.computeMD5(url);

// 1.组装 DirectUrl 视频源
StrategySource directUrlSource = new DirectUrlSource.Builder()
        .setVid(vid)
        .addItem(new DirectUrlSource.UrlItem.Builder()
                .setUrl(url)
                .setCacheKey(cacheKey)
                .build())
        .build();
       
// 2.设置播放源
ttVideoEngine.setStrategySource(directUrlSource);
// 3.播放
ttVideoEngine.play();

播放 Vid 视频源

if (/* 该 vid 的视频已下载完成 */) {
    // 离线播放已下载的文件需开启强制使用 VideoModel 缓存
    ttVideoEngine.setIntOption(PLAYER_OPTION_USE_VIDEOMODEL_CACHE_FORCE, 1);
}
// 播放已下载的 HLS 视频前必须设置以下 option
ttVideoEngine.setIntOption(PLAYER_OPTION_INT_ALLOW_ALL_EXTENSIONS, 1);
ttVideoEngine.setIntOption(PLAYER_OPTION_USE_VIDEOMODEL_CACHE, 1);

final String vid = "your video id"; // appServer 下发
final String playAuthToken = "your video id's play auth token"; // appServer 下发

final int encodeType = TTVideoEngine.CODEC_TYPE_H264;
// final int encodeType = TTVideoEngine.CODEC_TYPE_H265;
// final int encodeType = TTVideoEngine.CODEC_TYPE_H266;

// 1.组装 Vid 播放源
StrategySource vidSource = new VidPlayAuthTokenSource.Builder()
        .setVid(vid)
        .setPlayAuthToken(playAuthToken)
        // 设置 Codec 类型（h264、h265、h266），不传则使用默认值 h264
        .setEncodeType(encodeType)
        // 预期播放的分辨率，需和下载时设置的分辨率一致 
        .setResolution(Resolution.High)
        .build();
// 2.设置播放源
ttVideoEngine.setStrategySource(vidSource);
// 3.播放
ttVideoEngine.play();