预加载是指在开始播放之前提前下载即将播放视频的头部数据，以实现快速起播，从而提升播放体验。预加载适用于各种播放场景，它的接入成本低，效果明显。

预加载规则说明

本节介绍不同播放场景中预加载的规则和效果。通过选择合理精细的预加载时机和设置，可以提高预加载命中率，从而提升首帧体验。需要注意的是，过度粗放或不合理的预加载时机可能会导致流量浪费，增加成本。

短视频场景（类似抖音）

• 场景特点：一屏只展示一个竖版视频，一次只滑动一个视频。
• 预加载时机：当前视频缓冲时长超过 20 秒或全部缓冲完成后，可以开始向下进行预加载。
• 预加载数量：推荐预加载 3 个视频。用户停留在当前视频位置观看视频，当前位置记为 index，向下预加载 n 个视频，预加载范围为 [index + 1, index+n]。
• 预加载大小：建议预加载的大小设置 800K。
• 取消预加载时机：滑动切换播放视频时，取消全部预加载，避免对当前播放视频带宽产生争抢，影响当前视频的首帧。

中视频场景（类似西瓜视频）

• 场景特点：一屏中同时存在 2 个或以上视频。Feed 流可以快速滑动，一次可能划过多个视频。
• 预加载时机：当前视频缓冲时长超过 20 秒或全部缓冲完成，可以开始向下进行预加载。
• 预加载数量：推荐预加载 5 个视频。用户停留在当前视频位置观看视频，当前位置记为 index，向下预加载 n 个视频，预加载范围为 [index + 1, index + n]。
• 预加载大小：建议预加载的大小设置 800K。
• 取消预加载时机：滑动切换播放视频时，取消全部预加载，避免对当前播放视频带宽产生争抢，影响当前视频的首帧。

长视频场景

• 场景特点：沉浸式的全屏播放场景和播放页场景，例如影视、综艺等长视频的播放场景。
• 预加载时机：可根据具体场景，例如影视或综艺，在当前剧集将要播放完成时，预加载下一剧集。

前提条件

仅高级版或企业版 SDK 支持预加载功能。请确保您已购买高级版或企业版的 License 并添加高级版 SDK 依赖，详见以下文档：

• License 包管理
• 集成准备 - 添加 SDK 依赖

DirectUrl 模式下自定义预加载

构造预加载数据源

预加载与播放使用相同的播放源结构。为保证播放能命中预加载缓存，需确保预加载与播放构造的播放源 vid、url、cacheKey 一致。代码示例如下所示。

#import <TTSDK/TTVideoEngineHeader.h>
-(TTVideoEngineUrlSource *)createUrlSource {
    NSString *vid = @"video id"; // 由业务指定的视频源唯一ID。是一组内容相同但分辨率、编解码格式、封装格式等不同的视频集合的ID。
    NSString *url = @"http://www.example.com/h264.mp4";
    // cacheKey 用作磁盘缓存的文件名，建议采用 url 中能标识视频文件的部分的 MD5 值
    NSString *cacheKey = [url md5String];
    // 如果需要指定 URL source 的 encodetype 和解密 key 或标明是否为 HDR 播放源可以使用其他重载的接口. 见： TTVideoEngineUrlSource.h
    TTVideoEngineUrlSource *source = [[TTVideoEngineUrlSource alloc] initWithUrl:url cacheKey:cacheKey videoId:vid];
    return source;
}
    

添加预加载任务

- (void)addPreloadTask {
    // preloadSize: 预加载大小，例如 800k
    TTVideoEnginePreloaderURLItem * urlItem = [TTVideoEnginePreloaderURLItem urlItemWithVideoSource:[self createUrlSource] preloadSize:800 * 1024];
    urlItem.preloadProgress = ^(TTVideoEngineLoadProgress * _Nonnull progress) {
        // preload progress
    };
    urlItem.preloadEnd = ^(TTVideoEngineLocalServerTaskInfo * _Nullable info, NSError * _Nullable error) {
        // preload end
    };
    [TTVideoEngine ls_addTaskWithURLItem:urlItem];
}

取消预加载任务

取消任务，对没开始执行的任务和正在下载的任务有影响，对已经完成的任务没有影响。

// 取消单个预加载任务
// cacheKey 为添加任务时对应的 key.
[TTVideoEngine ls_cancelTaskByKey:cacheKey]; 
// 取消全部预加载任务
[TTVideoEngine ls_cancelAllTasks];
    

Vid 模式下自定义预加载

构造播放源

预加载与播放使用相同的播放源结构。为保证播放能命中预加载缓存，需确保预加载与播放构造的播放源 vid、playAuthToken、encodeType、resolution 一致。

• 如您未指定分辨率 resolution， SDK 内部在预加载和播放时，将使用 TTVideoEngineResolutionTypeSD 作为默认值。
• 如您未指定编码类型 encodeType，SDK 内部在预加载和播放时，将使用TTVideoEngineH264 作为默认值。

#import <TTSDK/TTVideoEngineHeader.h>
- (TTVideoEngineVidSource *)createVidSource {
    NSString *vid = @"your video id"; // appServer 下发
    NSString *playAuthToken = @"your video id's play auth token"; // appServer 下发
    TTVideoEngineEncodeType encodeType = TTVideoEngineH264;
    // TTVideoEngineEncodeType encodeType = TTVideoEngineh265;
    TTVideoEngineResolutionType resolution = TTVideoEngineResolutionTypeSD;
    TTVideoEngineVidSource *vidSource = [[TTVideoEngineVidSource alloc] initWithVid:vid playAuthToken:playAuthToken resolution:resolution encodeType:encodeType isDash:NO isHLS:NO];
    return vidSource;
}
    

添加预加载任务

- (void)addPreloadTask1 {
    TTVideoEnginePreloaderVidItem *item = [TTVideoEnginePreloaderVidItem vidItemWithVideoSource:[self createVidSource] preloadSize:GLOBAL_CONFIG.cacheSize ?: (800 * 1024)];
    item.fetchDataEnd = ^(TTVideoEngineModel * _Nullable model, NSError * _Nullable error) {
        // get video model end
    };    
    item.preloadProgress = ^(TTVideoEngineLoadProgress * _Nonnull progress) {
        // preload progress
    };
    item.preloadEnd = ^(TTVideoEngineLocalServerTaskInfo * _Nullable info, NSError * _Nullable error) {
        // preload end
    };
    [TTVideoEngine ls_addTaskWithVidItem:item];
}
    

播放时通过 configResolution: 接口设置预期分辨率，确保播放和预加载设置分辨率信息一致，代码示例如下所示。

// 和上面预加载的分辨率一致
[engine configResolution:TTVideoEngineResolutionTypeSD];

取消预加载任务

取消任务，对没开始执行的任务和正在下载的任务有影响，对已经完成的任务没有影响。

// 取消单个预加载任务
[TTVideoEngine ls_cancelTaskByVideoId:vid];
// 取消全部预加载任务
[TTVideoEngine ls_cancelAllTasks];

验证是否命中预加载

通过播放器的 delegate 回调查看是否命中预加载。Engine 实例的代理方法的代码示例如下所示。

// engine 实例的代理方法
- (void)videoEngine:(TTVideoEngine *)videoEngine mdlKey:(NSString *)key hitCacheSze:(NSInteger)cacheSize {
    // cacheSize > 0 , 表示命中缓存信息
    // cacheSize = 0 , 未命中缓存，请排查预加载任务是否成功，如果是vid方式，请检查播放和预加载的reslution是否一致
}

设置预加载任务并发数

// 设置预加载任务的并发数，默认值为 2
// 如下设置为 1，串行执行预加载任务
[TTVideoEngine ls_localServerConfigure].preloadParallelNum = 1;