预加载是指在开始播放之前提前下载即将播放视频的头部数据，以实现快速起播，从而显著优化播放体验。详细功能介绍，请见 Android 自定义预加载。

实现步骤 #

步骤 1：构造播放源并添加预加载任务 #

您可以根据播放源的类型（Vid 或 DirectUrl）调用相应的 API 来添加预加载任务。

// 使用vid和playAuthToken初始化vid source, resolution为期望预加载的档位
TTVideoEngineVidSource source = TTVideoEngineVidSource.init(
        vid: <vid>,
        playAuthToken: <playAuthToken>,
        resolution: <TTVideoEngineResolutionType>);

// 使用source和preloadSize初始化PreloaderVidItem, 预加载字节数preloadSize默认800 KB 
TTVideoEnginePreloaderVidItem item = TTVideoEnginePreloaderVidItem.vidItemWithVideoSource(source, 800 * 1024);

// 添加预加载任务
TTVideoEnginePreload.addTaskWithVidItem(item);

// 使用url和url cacheyKey初始化 url source, cacheKey 用作磁盘缓存的文件名，建议采用 url 中能标识视频文件的部分的 MD5 值
TTVideoEngineUrlSource source = TTVideoEngineUrlSource.initWithURL(<url>,  <cacheKey>);
// 由业务指定的视频源唯一ID
source.vid = <vid>;

// 使用source和preloadSize初始化PreloaderURLItem, 预加载字节数preloadSize默认800 KB 
TTVideoEnginePreloaderURLItem item = TTVideoEnginePreloaderURLItem.urlItemWithVideoSource(source, 800 * 1024);

// 添加预加载任务
TTVideoEnginePreload.addTaskWithURLItem(item);

步骤 2：监听预加载任务状态（可选） #

您可以为每个预加载任务 item 设置回调，以监听其完成、取消或失败的状态。

// 对已添加的预加载任务PreloaderURLItem，监听item的cancel和end回调
// 预加载任务取消
item.onPreloadCancel = () {
    print('TTF --  预加载cancel 回调到dart');
};
 
// 预加载任务完成
// taskInfo - 预加载任务的文件信息和下载信息
// error - 预加载任务的error信息
item.onPreloadEnd = (TTVideoEngineLocalServerTaskInfo? taskInfo, TTError? error) {
    Map<dynamic, dynamic>? map = taskInfo?.toJson();
    String errorStr = error.toString();
    print('TTF --  预加载end 回调到dart end = $map error = $errorStr');
};

步骤 3：取消预加载任务（可选） #

如果业务逻辑判断某个视频不再需要被预加载，可以将其任务从队列中取消，以节省网络资源。

// 取消全部预加载任务
TTVideoEnginePreload.cancelAllTask();

// 根据 key (即创建任务时使用的 cacheKey) 取消一个指定的预加载任务
TTVideoEnginePreload.cancelTaskByKey(<cacheKey>);

步骤 4：监听并验证缓存命中 #

要验证预加载是否生效，您可监听播放器实例的 onMediaCacheChange 回调。当播放器开始播放一个视频时，如果该视频成功命中了预加载的缓存，此回调便会被触发，且 cacheSize 会大于 0。

void Function(String key, int cacheSize)? onMediaCacheChange;