本文为您介绍如何使用 HarmonyOS NEXT 播放器 SDK 实现自定义预加载。

预加载是指在开始播放之前提前下载即将播放视频的头部数据，实现快速起播，提升播放体验。预加载实现成本低，效果显著，适用于各种播放场景。更多介绍，请见预加载规则说明。

DirectUrl 模式 #

1. 添加预加载任务：预加载与播放使用相同的数据源结构。DirectUrl 模式适用于播放来自火山引擎或第三方 CDN 的视频 URL 地址。通过传入视频的直接播放地址来指定播放内容。除了 url，您还必须提供以下参数：

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

   // 构造播放源
   let videoInfo = new VideoInfo();
   videoInfo.urls = [url]
   videoInfo.fileHash = fileHash
   
   let dataSource = new VideoModel();
   dataSource.videoInfos = [videoInfo];
   dataSource.vid = vid;
   
   let preloadSize = 800 * 1024; // 预加载大小 800KB
   let startPreloadOffset = 0;   // 预加载的起始位置
   // 构造预加载实例
   let preloadModel = new PreloadVideoModel(dataSource, startPreloadOffset, preloadSize,
         (type: PreloadTaskEventType, info: string, extraInfo: string) => {
       switch (type) {
         case PreloadTaskEventType.Success:  // 预加载成功
         case PreloadTaskEventType.Failed:   // 预加载失败
         case PreloadTaskEventType.Cancel:   // 预加载取消
           break;
       }
    })
   // 开始预加载
   preloadModel.create();
   

2. 取消预加载任务：取消未执行和正在下载的任务，已完成的任务不受影响。

   // 取消预加载任务
   preloadModel.cancel();
   

Vid 模式 #

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

   let vid = "your vid"; // appServer 下发
   let playAuthToken = "your video id's play auth token"; // appServer 下发
   let source = new VidSource(vid, playAuthToken)
   // 设置分辨率，如不设置起播分辨率，则使用清晰度列表里的第一个起播
   // let source = new VidSource(vid, playAuthToken, Resolution.resolution_360p)
   
   let preloadSize = 800 * 1024; // 预加载大小 800KB
   let startPreloadOffset = 0;   // 预加载的起始位置
   let preloadVid = new PreloadVid(source, startPreloadOffset, preloadSize,
       (type: PreloadTaskEventType, info: string, extraInfo: string) => {
         switch (type) {
             case PreloadTaskEventType.Success:  // 预加载成功
             case PreloadTaskEventType.Failed:   // 预加载失败
             case PreloadTaskEventType.Cancel:   // 预加载取消
               break;
           }
     })
   preloadVid.create();
   

2. 取消预加载任务：取消未执行和正在下载的任务，已完成的任务不受影响。

   // 取消预加载任务
   preloadVid.cancel();