本文为您介绍如何使用 React Native 点播 SDK 的进阶功能。

预加载和预渲染策略

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

预加载策略

接入预加载策略

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

1. 调用 enableEngineStrategy 开启预加载策略。

   import { enableEngineStrategy, StrategyType } from '@volcengine/react-native-vod-player';
   
   enableEngineStrategy(StrategyType.Preload, StrategyScene.SmallVideo);
   

   场景类型 StrategyScene 枚举值如下表所示。

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

2. 在首次加载播放源数据或在刷新页面以显示新数据的场景中，调用 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),
       ),
     );
     

3. 在加载更多数据的场景中，调用 addStrategySources 添加新的播放源至播放列表。

   const newVidData = [...];
   addStrategySources(newVidData.map(u => createVidSource(u)));
   

判断预加载是否命中

可通过设置播放状态回调的 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); 

预渲染策略

接入预渲染策略

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

1. 调用 enableEngineStrategy 开启预渲染策略。

   import { enableEngineStrategy, StrategyType } from '@volcengine/react-native-vod-player';
   
   enableEngineStrategy(StrategyType.PreRender, StrategyScene.SmallVideo);
   

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

   1. 在首次加载播放源数据或在下拉刷新页面以显示新数据的场景中，调用 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)));
        

   2. 在加载更多数据的场景中，调用 addStrategySources 添加新的播放源至播放列表。

      const newVidData = [...];
      addStrategySources(newVidData.map(u => createVidSource(u)));
      

3. 调用 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');
     },
     // 预渲染播放器即将 prepare 回调
     onPlayerWillPrepare(player: TTVideoEngine) {
       // player: 播放器
       // 设置播放画面填充模式
       player.setDisplayMode(1);
       // 设置起播时间
       player.setStartTime(20);
     },
     onPlayerExtraSetup(player: TTVideoEngine, source: VideoSource): void {
       // player: 播放器
       // source: 播放源
       // 播放器的额外操作
     },
   });
   

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

   import {
     createDirectUrlSource,
     getFirstFrameEngine,
     setView,
   } from '@volcengine/react-native-vod-player';
   import {useMemo} from 'react';
   
   // 当前视图在 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);
   }
   

   说明

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

5. 用户向下滑动完成（即轮播组件的 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();

外挂字幕

外挂字幕是指字幕文件与视频文件分开存储，用户在播放视频时按需导入字幕文件。React Native SDK 支持配置外挂字幕、切换字幕及字幕显示与加载的相关回调。

前提条件

• 外挂字幕为高级版或企业版功能。请确保您已购买高级版或企业版 License，购买方式详见 License 包管理。
• 如果您通过 Vid 方式播放视频，需要准备字幕文件：
  • 如果您已有单独的字幕文件，可选择在视频点播控制台指定空间内的视频管理 > 视频详情页面上传字幕文件，如下图所示：
    
  • 如果您没有单独的字幕文件，可在视频点播控制台配置智能字幕模板，生成字幕文件。
• 在接入外挂字幕功能前，请阅读集成 SDK，确保已经完成 SDK 的初始化。

实现方法

1. 创建播放器后，调用 enableSubThread 方法开启播放器的字幕总开关，提升字幕加载性能。

   const player = await initPlayer({viewId: 'player'});
   
   // 字幕总开关
   player.enableSubThread(true);
   

2. 调用 enableSubtitle 方法开启或关闭字幕解析。开启后，播放器将解析字幕并通过回调返回数据。如果传入 false，则播放器停止解析字幕，字幕回调也将停止触发。您可以使用此方法作为字幕显示的开关。

   // 字幕解析开关
   player.enableSubtitle(true);
   

3. 设置字幕源：点播 SDK 支持以下两种方式设置字幕源。您可根据实际情况选择。

   • 使用 Vid + SubtitleToken 方式设置字幕源。您需在应用服务端使用视频点播服务端 SDK 签发临时播放 Token 和字幕鉴权 Token，然后在客户端调用 setSubtitleAuthToken 方法设置字幕源。详见签发字幕鉴权 Token。

     import { createVidSource } from '@volcengine/react-native-vod-player';
     
     // 视频 vid
     const vid = 'videovid';
     // 由服务端签发的临时播放 Token
     const playAuthToken = 'playAuthToken';
     // 创建播放源
     const source = createVidSource({
       vid,
       playAuthToken,
       cacheKey: vid,
     });
     // 设置播放源
     player.setVideoSource(source);
     // 设置用于字幕获取的 subAuthToken
     player.setSubtitleAuthToken(subtitleToken);
     

     说明

     生成 playAuthToken、subAuthToken 和调用 createVidSource 方法创建播放源时所用的 Vid 必须保持一致，否则会导致解析错误。

   • 使用 DirectURL 方式设置字幕源。应用服务端下发字幕地址，组建字幕数据，客户端通过 setSubDesInfoModel 方法设置字幕信息。

     import { createDirectUrlSource } from '@volcengine/react-native-vod-player';
     
     // 字幕信息
     const subtitleInfo = {
       list: [
         {
           id: 1,
           language: 'cmn-Hans-CN',
           language_id: 1,
           url: 'https://demo.com/e87a83***961e?auth_key=17607***xt_plain',
           format: 'webvtt',
           sub_id: 1,
         },
         {
           id: 2,
           language: 'eng-US',
           language_id: 2,
           url: 'https://demo.com/e87a83***00eb0a6f3432e?auth_key=1760759306-****lain',
           format: 'webvtt',
           sub_id: 2,
         },
       ],
     };
     const source = createDirectUrlSource({
       vid: 'v0d032g1***5q6nkalr3ig',
       url: 'https://demo.com/9fc0da***7e97a10b7f9ca7?a=0&auth_key=1760758121-422b49c****w%3D%3D&vl=&vr=',
       cacheKey: 'v0d032g1***alr3ig',
     });
     player.setVideoSource(source);
     // 设置字幕信息
     player.setSubDesInfoModel(subtitleInfo);
     

     说明

     详见字幕信息说明。

4. 调用 setSubtitleCallback 方法设置字幕回调来更新字幕状态及字幕显示内容。

   player.setSubtitleCallback({
     onSubtitleInfoCallback(subInfo) {
       // 字幕信息回调，用于更新显示字幕
       console.log(`subtitle update to ${subInfo.content}`);
     },
     onSubtitleInfoRequested(jsonInfo: string, error?: Error) {
       // 针对 vid 播放，当请求到字幕时播放器回调，此时可以调用 getSubtitleIDs 获取字幕 ID 列表
       if (!error) {
         const ids = player.getSubtitleIDs();
         if (ids && ids.length) {
           // 切换到第一个字幕
           player.switchSubtitleById(ids[0]);
         }
       }
     },
     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：该段字幕对应的视频播放时间。
     以下为在 React Native 组件中更新显示字幕的示例代码：

   import {useState} from 'react';
   
   // ....
   
   const [curText, setCurText] = useState('');
   const [enableSub, setEnableSub] = useState(true);
   
   player.setSubtitleCallback({
     onSubtitleInfoCallback(subInfo) {
       // 字幕信息回调，用于更新显示字幕
       setCurText(subInfo.content)
     },
   });
   
   // ....
   
   return (
       <View>
         {enableSub && (
             <View style={[styles.sub]}>
               <Text>{curText}</Text>
             </View>
         )}
       </View>
   )
   

5. 切换字幕：可通过 getSubtitleIDs 获取字幕 ID 列表，再调用 switchSubtitleById 传入字幕 ID 进行字幕切换。

   // 获取字幕 ID 列表
   const ids = player.getSubtitleIDs();
   // 切换字幕
   player.switchSubtitleById(ids[0]);
   

   如果要设置起播的默认字幕，则可在调用 play 前调用 switchSubtitleById 设置字幕 ID。