本文为您介绍如何实现 uni-app 播放器 SDK 的进阶功能。
为了帮助您快速搭建“抖音”同款短视频场景，播放器 SDK 基于抖音亿级日活跃用户的真实反馈和大规模实践经验，提供两大最佳策略：预加载策略和预渲染策略。详细功能介绍，请见抖音同款短视频最佳实践。
注意
该功能仅高级版支持。请确保您已购买高级版的 License，详见播放器 License。
按如下步骤接入预加载策略：
开启预加载策略。仅需开启一次，不要重复开启。
import { enableEngineStrategy, StrategyType } from '@/uni-vod-player'; enableEngineStrategy(StrategyType.Preload, StrategyScene.SmallVideo);
场景类型 StrategyScene 枚举值如下表所示。
枚举 Key | 值 | 说明 |
|---|---|---|
SmallVideo | SmallVideo | 短视频场景 |
ShortVideo | ShortVideo | 中视频场景 |
在首次加载播放源数据或在刷新页面以显示新数据的场景中，设置播放列表的播放源。
说明
vid 和 cacheKey 都是唯一的。setStrategySources。调用后会取消之前设置的预加载任务，因此请勿重复设置相同的播放列表。Vid 模式下：
import { setStrategySources } from '@/uni-vod-player'; const vidData = [ { playAuthToken: 'playAuthToken1', vid: 'v0d032g1*******5q6nkalr3ig' }, { playAuthToken: 'playAuthToken2', vid: 'v0d032g1*******5q6nkalr3ig' }, // ... ]; // 设置预加载列表的播放源 setStrategySources(vidData.map(u => createVidSource(u)));
DirectUrl模式：
import { setStrategySources } from '@/uni-vod-player'; const urlData = [ { url: 'https://voddemo-play.volcengine.com/1.mp4', vid: 'v0d032g1*******5q6nkalr3ig', cacheKey: 'v0d032g1*******5q6nkalr3ig' }, { url: 'https://voddemo-play.volcengine.com/2.mp4', vid: 'v0d032g1*******5q6nkalr3ig', cacheKey: 'v0d032g1*******5q6nkalr2ik' }, // ... ]; // 设置预加载列表的播放源 setStrategySources(urlData.map(u => createDirectUrlSource(u)));
如需添加新的播放源至预加载列表，则调用 addStrategySources。
const newVidData = [...]; addStrategySources(newVidData.map(u => createVidSource(u)));
说明
可通过设置播放状态回调的 onCacheChange 来监听预加载是否命中。
this.player.setListener({ // cacheSize大于0时表示预加载命中。 onCacheChange(cacheKey: string, cacheSize: number) { if (cacheSize > 0) { console.log('video hit preload: ', cacheKey, cacheSize); } } });
预加载会占据一定的存储空间，可通过 clearAllCaches 清除缓存。
import {clearAllCaches} from '@/uni-vod-player'; // true: 强制删除所有缓存数据。 // false: 不全部删除所有缓存数据，而是会按照 Least Recently Used (LRU) 算法保留最近播放的 10 条左右数据，从而优化实际播放体验。 clearAllCaches(true);
其参数支持传入true和false，其含义如下：
true: 强制删除所有缓存数据。false: 不全部删除所有缓存数据，而是会按照 Least Recently Used (LRU) 算法保留最近播放的 10 条左右数据，从而优化实际播放体验。为了帮助您快速搭建“抖音”同款短视频场景，播放器 SDK 基于抖音亿级日活跃用户的真实反馈和大规模实践经验，提供预渲染策略。详细功能介绍，请见抖音同款短视频最佳实践。
注意
该功能仅高级版支持。请确保您已购买高级版的 License，详见播放器 License。
调用 enableEngineStrategy 开启预渲染策略。
import { enableEngineStrategy, StrategyType } from '@/uni-vod-player'; enableEngineStrategy(StrategyType.PreRender, StrategyScene.SmallVideo);
在适当的时机设置预渲染源：
在首次加载播放源数据或在下拉刷新页面以显示新数据的场景中，调用 setStrategySources 重置播放列表。
设置 Vid 预渲染源：
import { setStrategySources } from '@/uni-vod-player'; const vidData = [ { playAuthToken: 'playAuthToken1', vid: 'v0d032g1*******5q6nkalr3ig', cacheKey: 'v0d032g1*******5q6nkalr3ig' }, { playAuthToken: 'playAuthToken2', vid: 'v0d032g1*******5q6nkalr3ig', cacheKey: 'v0d032g1*******5q6nkalr2ik' }, // ... ]; // 设置预渲染列表的播放源 setStrategySources(vidData.map(u => createVidSource(u)));
设置 DirectUrl 预渲染源：
import { setStrategySources } from '@/uni-vod-player'; const urlData = [ { url: 'https://demo.volcengine.com/1.mp4', vid: 'v0d032g1***kalr3ig', cacheKey: 'v0d032g1***nkalr3ig' }, { url: 'https://demo.volcengine.com/2.mp4', vid: 'v0d032g1***q6nkalr3ig', cacheKey: 'v0d032g1***q6nkalr2ik' }, // ... ]; // 设置预渲染列表的播放源 setStrategySources(urlData.map(u => createDirectUrlSource(u)));
在加载更多数据的场景中，调用 addStrategySources 添加新的播放源至播放列表。
const newVidData = [...]; addStrategySources(newVidData.map(u => createVidSource(u)));
调用 setPreRenderCallback 方法设置预渲染策略回调，再根据自身业务对播放器实例进行其它操作。例如您可监听 onPlayerCreated 回调，设置视频填充模式、起播时间、监听播放状态等。
import {setPreRenderCallback} from '@/uni-vod-player'; import type {TTVideoEngine,VideoSource} from '@/uni-vod-player'; setPreRenderCallback({ // 预渲染播放器创建回调 onPlayerCreated: (player: TTVideoEngine, source: VideoSource) => { // player: 播放器 // source: 播放源 // 可通过播放源的 vid 判断哪个播放源的播放实例命中了预渲染 const vid = source.vid(); // 设置字幕 player.setSubtitleAuthToken('subtit***letoken'); }, });
注意
注意预渲染播放器的外挂字幕，暂时只支持在预渲染回调 onPlayerCreated 中设置。
在用户向下滑动出现下个视频的视图时调用 getFirstFrameEngine，传入当前视图对应的 source 判断预渲染是否完成，并通过 setView 方法处理预渲染封面逻辑。
import { createDirectUrlSource, getFirstFrameEngine, setView, } from '@/uni-vod-player'; // 当前视图在 feed 流列表中的序号 const index = 2; // 当前视图对应的播放数据 const data = { url: 'https://demo.volcengine.com/%E8%A7%86%E9%A2%91%E6%98%AF%E4%B8%80%E7%A7%8D%E7%94%9F%E4%BA%A7%E5%8A%9B.mp4?auth_key=1820024284-20b113404b8d4ac181ba3234fb0b03b8-0-601dbd326b875bb997b33244d96a9139', vid: 'v02dfag10001cmmdn38fcpimkm239jdg', cacheKey: 'v02dfag10001cmmdn38fcpimkm239jdg', poster: 'https://voddemo-cover.volcengine.com/tos-vod-cn-v-8a997967cc533b04/e12bfb23246b487584e5145a9f4d15c2~tplv-vod-noop.image', }; const viewId = 'viewid-xshh67d'; // .... const source = createDirectUrlSource(data); const preRenderEngine = getFirstFrameEngine(source); if (preRenderEngine) { // 命中预渲染，设置 veiw，显示首帧 await setView(preRenderEngine, viewId); // 设置填充模式 preRenderEngine.setDisplayMode(FillModeType.FillModeAspectFill); }
说明
getFirstFrameEngine 返回的播放器实例只用于调用 setView 设置首帧画面。您不应持有该播放器实例，即不要在函数之外引用该实例，或者在vue组件上下文挂载该实例引用，也不要使用该实例进行播放和暂停等操作。
用户向下滑动完成时（即轮播组件的 index 发生变化时），调用 getPreRenderEngine 方法判断预渲染是否完成。如果该方法返回播放器实例，则持有该播放器实例，并处理播放逻辑。如果没有返回则表示未命中预渲染，您需要调用 initPlayer 自行创建播放器实例。
import { createDirectUrlSource, getPreRenderEngine, setView, initPlayer, TTVideoEngine, } from '@/uni-vod-player'; // 当前视图在 feed 流列表中的序号 const index = 2; // 当前视图对应的播放数据 const data = { url: 'https://demo.volcengine.com/1.mp4?auth_key=182***39', vid: 'v02dfa***m239jdg', cacheKey: 'v02dfag***imkm239jdg', poster: 'https://voddemo-cover.volcengine.com/tos-***967cc533b04/e12bf***4d15c2~tplv-vod-noop.image', }; const viewId = 'viewid-xshh67d'; // ... const source = createDirectUrlSource(data); const preRenderEngine = getPreRenderEngine(source); if (preRenderEngine && index !== 0) { // 命中了预渲染，设置预渲染的播放器容器 await setView(preRenderEngine, viewId); // 业务方持有播放器实例 this.player = preRenderEngine; } else { // 没有命中预渲染，则通过 initPlayer 创建播放器 const player = await initPlayer({viewId}); player.setVideoSource(source); this.player = player; } // 播放视频 this.player?.play();
关闭所有策略，包括预加载和预渲染。
import { clearAllStrategy } from '@/uni-vod-player'; clearAllStrategy(); // 关闭所有策略
外挂字幕是指字幕文件与视频文件分开存储，用户在播放视频时按需导入字幕文件。uni-app SDK 支持配置外挂字幕、切换字幕及字幕显示与加载的相关回调。
注意
该功能仅高级版支持。请确保您已购买高级版的 License，详见播放器 License。
创建播放器后，调用 enableSubThread 方法开启播放器的字幕总开关，提升字幕加载性能。
const player = await initPlayer({viewId: 'player'}); // 字幕总开关 player.enableSubThread(true);
调用 enableSubtitle 方法开启或关闭字幕解析。开启后，播放器将解析字幕并通过回调返回数据。如果传入 false，则播放器停止解析字幕，字幕回调也将停止触发。您可以使用此方法作为字幕显示的开关。
// 字幕解析开关 player.enableSubtitle(true);
设置字幕源：播放器 SDK 支持以下两种方式设置字幕源。您可根据实际情况选择。
注意
预渲染播放器的外挂字幕，暂时只支持在预渲染回调 onPlayerCreated 中设置。
使用 Vid + SubtitleToken 方式设置字幕源。您需在应用服务端使用视频点播服务端 SDK 签发临时播放 Token 和字幕鉴权 Token，然后在客户端调用 setSubtitleAuthToken 方法设置字幕源。
import { createVidSource } from '@/uni-vod-player'; // 视频的 vid const vid = 'videovid'; // 基于 vid 由服务端签发的临时播放 Token const playAuthToken = 'playAuthToken'; // 创建 source const source = createVidSource({ vid, playAuthToken, cacheKey: vid, }); // 设置视频 source player.setVideoSource(source); // 设置用于字幕获取的 subAuthToken player.setSubtitleAuthToken(subtitleToken);
注意
生成 playAuthToken、subAuthToken 和调用 createVidSource 方法创建播放源时所用的 Vid 必须保持一致，否则会导致解析错误。
使用 DirectURL 方式设置字幕源。应用服务端下发字幕地址，组建字幕数据，通过setSubDesInfoModel方法设置字幕信息。
import { createDirectUrlSource } from '@/uni-vod-player'; // 字幕信息 const subtitleInfo = { list: [ { id: 1, language: 'cmn-Hans-CN', language_id: 1, url: 'https://*******.***.com/e87a83f58eb94d20***00eb0a6f1961e?auth_key=1760759306-******-0-74813847533f23d059943fafb97571f5&mime_type=text_plain', format: 'webvtt', sub_id: 1, }, { id: 2, language: 'eng-US', language_id: 2, url: 'https://*******.***.com/e87a83f58eb94d20***00eb0a6f3432e?auth_key=1760759306-******-0-74813847533f23d059943fafb97571f5&mime_type=text_plain', format: 'webvtt', sub_id: 2, }, ], }; const source = createDirectUrlSource({ vid: 'v0d032g1*******5q6nkalr3ig', url: 'https://******.****.com/9fc0da16f21a41***7e97a10b7f9ca7?a=0&auth_key=1760758121-422b49cadc7*****d83c7950128e5-0-aaaba803f73b7309aed6fe4c2861cd79&br=8476&bt=8476&cd=0%7C0%7C0&ch=0&cr=0&cs=0&dr=0&ds=4&er=0&l=202210191127110102100500481553D7CA&lr=&mime_type=video_mp4&net=0&pl=0&qs=13&rc=ajhyeXY6dnBwZzQzNGRnM0ApOGRsczRoZHE6ZjMzamk1eWcyXmZtLmJeazRgLS1kYy9zc2QybHNwNHBqamEuLS5eYS06Yw%3D%3D&vl=&vr=', cacheKey: 'v0d032g1*******5q6nkalr3ig', }); player.setVideoSource(source); // 设置字幕信息 player.setSubDesInfoModel(subtitleInfo);
说明
字幕数据各个字段含义详见字幕信息说明。
调用 setSubtitleCallback 方法设置字幕回调来更新字幕状态及字幕显示内容。
this.player.setSubtitleCallback({ onSubtitleInfoCallback: (subInfo) => { // 字幕信息回调，用于更新显示字幕 console.log(`subtitle update to ${subInfo.content}`); // 更新显示的字幕文案 this.curSubText = subInfo.content; }, onSubtitleInfoRequested:(jsonInfo: string, error?: Error) => { // 针对 vid 播放，当请求到字幕时播放器回调，此时可以调用getSubtitleIDs获取字幕id列表 if (!error) { const ids = player.getSubtitleIDs(); if (ids && ids.length) { // 切换到第一个字幕 player.switchSubtitleById(ids[0]); } try { const json = JSON.parse(jsonInfo); // 用于渲染播放列表UI this.vidSubList = json.list; } catch (err) { console.error(err); } } }, onSubLoadFinished:(success: boolean) => { // 当前字幕加载完成 console.log(`current subtitle load ${success ? 'success' : 'fail'}`); }, onSubSwitchCompleted:(success: boolean, id: number) => { // 字幕切换完成，currentLangId：当前语言ID console.log(`subtitle ${id} switch ${success ? 'success' : 'fail'}`); }, });
其中最重要的回调是 onSubtitleInfoCallback，该回调会在字幕随播放进度发生字幕变化时触发（包括字幕清除），业务方根据回调的subInfo信息更新显示的字幕。subInfo包含以下信息：
content：字幕内容。duration：该段字幕持续时间。pts：该段字幕对应的视频播放时间切换字幕：可通过 getSubtitleIDs 获取字幕 ID 列表，再调用 switchSubtitleById 传入字幕 ID 进行字幕切换。
// 获取字幕 ID 列表 const ids = player.getSubtitleIDs(); // 切换字幕 player.switchSubtitleById(ids[0]);
如果要设置起播的默认字幕，则可在调用 play 前调用 switchSubtitleById 设置字幕 ID。
（可选）Vid 模式下渲染字幕切换 UI 列表：字幕回调 onSubtitleInfoRequested 的第一个回调参数 jsonInfo 是一个 JSON 字符串。解析后对象的 list 属性是一个每项为 SubDesInfoModel 类型的数组，其每项的具体数据类型如下，各个字段含义详见字幕信息说明。
{ id: number, language: string, language_id: number, url: string, format: string, sub_id: number, }
您可以基于此列表数据渲染字幕切换 UI 列表，其中 sub_id 可用于切换字幕接口 switchSubtitleById 的参数使用。
onSubtitleInfoRequested: (jsonInfo: string, error?: Error) => { // 针对 vid 播放，当请求到字幕时播放器回调，此时可以调用getSubtitleIDs获取字幕id列表 if (!error) { try { const json = JSON.parse(jsonInfo); // 用于渲染播放列表UI this.vidSubList = json.list; } catch (err) { console.error(err); } } },