预加载和预渲染策略--视频点播-火山引擎

文档中心

立即注册

导航

预加载和预渲染策略

最近更新时间：2025.09.01 11:34:48首次发布时间：2024.10.17 17:46:58

为了帮助您快速搭建“抖音”同款短视频场景，播放器 SDK 基于抖音亿级日活跃用户的真实反馈和大规模实践经验，提供两大最佳策略：预加载策略和预渲染策略。详细功能介绍，请见抖音同款短视频最佳实践。

注意

该功能仅高级版支持。请确保您已购买高级版的 License，详见播放器 License。

预加载策略

接入预加载策略

按如下步骤接入预加载策略：

调用 enableEngineStrategy 开启预加载策略。
```
import { enableEngineStrategy, StrategyType } from '@volcengine/react-native-vod-player';

enableEngineStrategy(StrategyType.Preload, StrategyScene.SmallVideo);
```
场景类型 StrategyScene 枚举值如下表所示。
枚举 Key
值
说明
SmallVideo
SmallVideo
短视频场景
ShortVideo
ShortVideo
中视频场景

枚举 Key	值	说明
SmallVideo	SmallVideo	短视频场景
ShortVideo	ShortVideo	中视频场景

在首次加载播放源数据或在刷新页面以显示新数据的场景中，调用 setStrategySources 设置播放列表的播放源。

说明

请确保每个播放源的 vid 和 cacheKey 都是唯一的。

设置 Vid 播放源：

import { setStrategySources } from '@volcengine/react-native-vod-player';

const vidData = [
  {
    playAuthToken: 'playAuthToken1',
    vid: 'vid1',
  },
  {
    playAuthToken: 'playAuthToken2',
    vid: 'vid2',
  },
  // ...
  ];

// 设置预加载列表的播放源 
setStrategySources(vidData.map(u => createVidSource(u)));

DirectUrl 播放源：

import { setStrategySources } from '@volcengine/react-native-vod-player';

const urlData = [
  {
    url: 'https://demo/1.mp4',
    vid: 'vid1',
  },
  {
    url: 'https://demo/2.mp4',
    vid: 'vid2',
  },
// ...
];

// 设置预加载列表的播放源  
setStrategySources(
  urlData.map(u =>
    createDirectUrlSource({
      ...u,
      cacheKey: u.vid,
    } as DirectUrlSourceInitProps),
  ),
);

在加载更多数据的场景中，调用 addStrategySources 添加新的播放源至播放列表。
```
const newVidData = [...];
addStrategySources(newVidData.map(u => createVidSource(u)));
```

注意

错误的播放列表会导致预加载失败。
预加载策略会查询到当前播放视频在播放列表中的 index，并预加载 index+1、index+2 ... index+n 的视频。

判断预加载是否命中

可通过设置播放状态回调的 onCacheChange 来监听预加载是否命中。

player.setListener({
  // cacheSize 大于 0 时表示预加载命中。
  onCacheChange(cacheKey: string, cacheSize: number) {
    if (cacheSize > 0) {
       console.log('video hit preload: ', cacheKey, cacheSize);
    }
  }
});

清除缓存

预加载会占据一定的存储空间。您可调用 clearAllCaches 清除缓存。

import {clearAllCaches} from '@volcengine/react-native-vod-player';

// true: 强制删除所有缓存数据。
// false: 不全部删除所有缓存数据，而是会按照 Least Recently Used (LRU) 算法保留最近播放的 10 条左右数据，从而优化实际播放体验。
clearAllCaches(true);

预渲染策略

接入预渲染策略

按如下步骤接入预加载策略：

调用 enableEngineStrategy 开启预渲染策略。

import { enableEngineStrategy, StrategyType } from '@volcengine/react-native-vod-player';

enableEngineStrategy(StrategyType.PreRender, StrategyScene.SmallVideo);

在适当的时机设置预渲染源：

在首次加载播放源数据或在下拉刷新页面以显示新数据的场景中，调用 setStrategySources 重置播放列表。

设置 Vid 预渲染源：

import { setStrategySources } from '@volcengine/react-native-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 '@volcengine/react-native-vod-player';

const urlData = [
  {
    url: 'https://demo/1.mp4',
    vid: 'v0d032g1***kalr3ig',
    cacheKey: 'v0d032g1***nkalr3ig'    
  },
  {
    url: 'https://demo/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 '@volcengine/react-native-vod-player';
import type {
  TTVideoEngine,
  VideoSource,
} from '@volcengine/react-native-vod-player';

setPreRenderCallback({
  // 预渲染播放器创建回调
  onPlayerCreated(player: TTVideoEngine, source: VideoSource) {
    // player: 播放器
    // source: 播放源
    // 可通过播放源的 vid 判断哪个播放源的播放实例命中了预渲染
    const vid = source.vid();
    // 设置字幕
    player.setSubtitleAuthToken('subtit***letoken');
  },
});

在用户向下滑动出现下个视频的视图时调用 getFirstFrameEngine，传入当前视图对应的 source 判断预渲染是否完成，并通过 setView 方法处理预渲染封面逻辑。

import {
  createDirectUrlSource,
  getFirstFrameEngine,
  setView,
} from '@volcengine/react-native-vod-player';
import {useMemo} from 'react';

// （可选）若您需要在处理预渲染封面逻辑时指定填充模式，还需额外引入 FillModeType
// import { FillModeType } from '@volcengine/react-native-vod-player';

// 当前视图在 feed 流列表中的序号
const index = 2;
// 当前视图对应的播放数据
const data = {
  url: 'https://demo/example.mp4?auth_key=1820***4d96a9139',
  vid: 'v02dfag***km239jdg',
  cacheKey: 'v02dfag10***m239jdg',
  poster: 'https://demo.com/to***c533b04/e12b***5c2~tplv-vod-noop.image',
};
const viewId = useMemo<string>(() => `pre-player-${index}`, [index]);

// ....

const source = createDirectUrlSource(data);
const preRenderEngine = getFirstFrameEngine(source);
if (preRenderEngine) {
  // 命中预渲染，设置 veiw，显示首帧
  await setView(preRenderEngine, viewId);
  // 设置画面填充模式 FillModeType，枚举值说明详见 https://www.volcengine.com/docs/4/1338561#%E8%AE%BE%E7%BD%AE%E7%94%BB%E9%9D%A2%E5%A1%AB%E5%85%85%E6%A8%A1%E5%BC%8F
  // setView(preRenderEngine, viewId, FillModeType.FillModeAspectFill);
}

说明

getFirstFrameEngine 返回的播放器实例只用于调用 setView 设置首帧画面。您不应持有该播放器实例，即不用该播放器实例进行播放和暂停等操作。

用户向下滑动完成（即轮播组件的 index 发生变化时）时，调用 getPreRenderEngine 方法判断预渲染是否完成。如果该方法返回播放器实例，则持有该播放器实例，并处理播放逻辑。如果没有返回则表示未命中预渲染，您需要调用 initPlayer 自行创建播放器实例。

import {
  createDirectUrlSource,
  getPreRenderEngine,
  setView,
  initPlayer,
  TTVideoEngine,
} from '@volcengine/react-native-vod-player';
import {useMemo, useRef} from 'react';

// 当前视图在 feed 流列表中的序号
const index = 2;
// 当前视图对应的播放数据
const data = {
  url: 'https://demo/1.mp4?auth_key=182***39',
  vid: 'v02dfa***m239jdg',
  cacheKey: 'v02dfag***imkm239jdg',
  poster:
    'https://demo.com/tos-***533b04/e12bf***4d15c2~tplv-vod-noop.image',
};
const viewId = useMemo<string>(() => `pre-player-${index}`, [index]);
const playerRef = useRef<TTVideoEngine | undefined>();

// ...

const source = createDirectUrlSource(data);
const preRenderEngine = getPreRenderEngine(source);
if (preRenderEngine && index !== 0) {
  // 命中了预渲染，设置预渲染的播放器容器
  await setView(preRenderEngine, viewId);
  // 业务方持有播放器实例
  playerRef.current = preRenderEngine;
} else {
  // 没有命中预渲染，则通过 initPlayer 创建播放器
  const player = await initPlayer({viewId});
  player.setVideoSource(source);
  playerRef.current = player;
}

// 播放视频
playerRef.current?.play();

完整示例代码

视频点播提供详细的预渲染示例代码，以帮助您更好地理解如何使用预渲染功能。

关闭所有策略

在退出短视频页面或切换到其他页面时调用 clearAllStrategy 关闭所有策略，释放资源。

import { clearAllStrategy } from '@volcengine/react-native-vod-player';

// 关闭所有策略
clearAllStrategy();