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

前提条件

您已集成 SDK。

初始化 SDK

按如下代码示例在创建播放器前初始化 SDK。仅需初始化一次。

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

initEnv({
  AppID: xxx,  // 应用 ID，可在视频点播控制台应用管理页面获取。详见[创建应用](https://www.volcengine.com/docs/4/79594)
  AppName: 'democeshi', // 应用英文名，可在视频点播控制台应用管理页面获取。详见[创建应用](https://www.volcengine.com/docs/4/79594)
  PackageName: com.xxx.xxxx, // Android 项目包名，对应 buid.gradle 中的applicationId 的值
  BundleID: com.xxx.xxxx.x, // iOS 项目包名，对应 Xcode 中 TARGETS 下 Bundle Identifier 的值
  AppChannel: Platform.select({
    android: 'GoogleStore',
    ios: 'AppStore',
  }), // 渠道号。由您自定义，如小米应用商店 (xiaomi)、华为应用市场 (huawei) 等
  AppVersion: '1.0.0', // App 版本号。合法版本号应包含大于或等于 2 个 . 分隔符，如 "1.3.2"。
  LicenseUri: Platform.select({
    android: 'assets:///VeVod.lic',
    ios: 'VeVod.lic',
  }), // License 文件路径，注意 iOS 和 Android 在各自的文件夹下，通常路径不同
  UserUniqueID: 'ReactNativeExample', // 用户 ID，由您自定义，可用于在视频点播控制台单点追查页面查看单设备的播放数据。详见[单点追查](https://www.volcengine.com/docs/4/106093)
  OpenLog: true, // 是否开启日志打印。Android 可以通过 logcat 捕获日志；iOS 可以通过 Xcode 捕获日志。
  MaxCacheSize: 300 * 1024 * 1024, // 最大缓存，单位 byte
})

初始化参数说明如下表所示。

创建播放器

1. 在需要播放器的组件中插入播放容器组件 PlayerViewComponent，并为其 viewId 属性赋值。请确保 viewId 的唯一性。

   import { PlayerViewComponent } from '@volcengine/react-native-vod-player';
   
   function Player() {
       // ...
       
       return (
           <PlayerViewComponent
             viewId="player_container"
             onLoad={onLoad}
             style={{
               width: '100%',
               height: '100%',
             }}
           >
           </PlayerViewComponent>
       );
   }
   

2. 在 PlayerViewComponent 的 onLoad 回调中调用 initPlayer 方法创建播放器，并传入您在上一步赋值的 viewId。该方法是异步的。

   import { initPlayer, PlayerViewComponent } from '@volcengine/react-native-vod-player';
   
   function Player() {
     const playerRef = useRef();
   
     // 创建播放器
     const onLoad = useCallback(async () => {
       playerRef.current = await initPlayer({viewId: 'player_container'});
     }, []);
   
     return (
         <PlayerViewComponent
           viewId="player_container"
           onLoad={onLoad}
           style={{
             width: '100%',
             height: '100%',
           }}
         >
         </PlayerViewComponent>
     );
   }
   

设置播放源

点播 SDK 支持设置 Vid 和 DirectUrl 播放源。

• 设置 Vid 播放源：调用 createVidSource 方法创建 vidSource 对象，再调用 setVideoSource 方法将 vidSource 对象设置给播放器。您需要将 vid 参数设为视频点播服务生成的 Vid，将 playAuthToken 参数设为临时播放 Token。Vid 和临时播放 Token 由应用服务端下发。应用客户端无需关心，调用应用服务端的接口获取即可，详情请见通过临时播放 Token 播放。

  import { createVidSource } from '@volcengine/react-native-vod-player';
  
  const vidSource = createVidSource({
    playAuthToken: playAuthTokenxxx, // 临时播放 Token，由应用服务端签出下发
    vid: xxxvid, // 视频点播服务生成的视频 vid
    resolution: 'Standard', // 默认起播清晰度
  });
  playerRef.current.setVideoSource(vidSource);
  

• DirectUrl 播放源：调用 createDirectUrlSource 方法创建 urlSource 对象，再调用 setVideoSource 方法将 urlSource 对象设置给播放器。您需将 url 参数设为视频播放地址。播放地址可以是第三方点播地址或视频点播服务生成的播放地址。此外，对于 DirectUrl 播放源， vid 和 cacheKey 也为必填参数，说明如下：

  • vid：视频的唯一标识，必须与视频源一一对应。vid 可以是您自己的视频管理系统中的唯一标识，也可以在 App 层自行生成一个 ID。此 ID 会用于点播 SDK 的日志上报、预加载、预渲染等功能中。
  • cacheKey：推荐使用 URL 的 MD5 作为缓存 key。缓存 key 也需能和视频资源文件一一对应，不带特殊字符，能作为文件名。

  import { createDirectUrlSource } from '@volcengine/react-native-vod-player';
  
  const urlSource = createDirectUrlSource({
    url: 'https://demo.video.com/1.mp4', // 视频地址
    cacheKey: 'cacheKeyDemo01', // Source 的缓存唯一 key
    vid: 'xxxxxx',  // 视频 id
  });
  playerRef.current.setVideoSource(urlSource);
  

播放控制

const player = playerRef.current;

// 播放
player.play();

// 暂停，再次调用 play 可由暂停恢复到播放
player.pause();

// 准备
player.prepare();

// 从指定位置起播，单位：秒。
player.seek(value, success => {
  if (success) {
    // seek 成功
    // do something
  }
});

// 停止播放
player.stop();

// 异步释放播放器实例。当播放器释放后，不应该调用实例的任何方法
player.close();

获取当前播放时间

// 单位为秒
const currentTime = player.getCurrentPlaybackTime();

获取视频已缓存时长

// 单位为秒
const progress = player.getProgress();

获取播放状态

const playbackState = player.getPlaybackState();

播放状态 PlaybackState 的枚举值如下表所示。

获取加载状态

const loadState = player.getLoadState();

加载状态 TTVideoEngineLoadState 的枚举值如下表所示。

获取视频信息

const duration = player.getDuration(); // 视频时长
const videoWidth = player.getVideoWidth(); // 视频宽度
const videoHeight = player.getVideoHeight(); // 视频高度

获取设备 ID

如果您在初始化 SDK 时没有设置自定义用户 ID，可参考以下示例代码获取 SDK 生成的设备 ID，用于在视频点播控制台单点追查页面查看单设备的播放数据。

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

const did = getDeviceID();

设置倍速播放

// 设置倍速，取值范围 0.5 - 3
player.setPlaybackSpeed(2);

// 获取当前倍速
const speed = player.getPlaybackSpeed();

设置循环播放

// 设置循环播放
player.setLooping(true);

// 获取当前是否循环播放
const isLoop = player.getIsLooping();

静音

// 静音
player.setMuted(true);

// 获取当前是否静音
const isMute = player.isMute();

调节音量

// 调节音量，范围 0 - 1
player.setVolume(0.6);

// 获取音量，范围 0 - 1
player.getVolume();

// true: 调整播放音量，更改到 true 时需要在 play() 之前调用
// false: 调整系统音量
// 默认值 false
player.setTrackVolumeEnabled(true);

纯音频播放

点播 SDK 支持在播放视频时，只解码音频而不解码视频，适用于纯音频播放场景。相比您根据自身业务逻辑实现的纯音频播放，SDK 只解码音频会更省电。

// 设置纯音频播放
player.setRadioMode(true); // 仅高级版支持

设置旋转角度

// 支持 0、90、180、270 四个值
player.setRotation(90);

设置填充模式

import { FillModeType } from '@byteplus/react-native-vod-player';

player.setDisplayMode(FillModeType.FillModeAspectFill);

填充模式 FillModeType 的枚举值如下表所示。

设置镜像模式

// 0: 无镜像，1：水平镜像，2：垂直镜像，3：水平且垂直镜像
player.setMirror(1);

设置起播时间

// 单位为秒。以下示例表示从 20 秒起播
player.setStartTime(20);

设置业务类型

业务类型（tag）用于区分同一应用（appid）内，不同类型的音视频。可以根据业务需要按视频场景、视频时长等划分：比如沉浸式 feed 流、短视频视频、长视频等。示例代码如下：

player.setTag('feed');

设置自定义标签

自定义标签 subtag 用于区分同一业务类型下的不同细分，比如加密视频、非加密加密、音频等。示例代码如下：

player.setSubTag('audio');

设置清晰度

播放 Vid 视频源时，视频点播服务端会下发多个清晰度的播放地址。

获取当前清晰度

// 获取视频清晰度信息，需要在 onPrepared 之后获取
const curResolution = player.getCurrentResolution()

获取清晰度列表

const list = player.supportedResolutionTypes();

切换清晰度

import { ResolutionType } from '@volcengine/react-native-vod-player';
player.configResolution(ResolutionType.Standard);

清晰度 ResolutionType 的枚举值如下表所示。

如需在 DirectUrl 模式下切换清晰度，参考以下步骤：

1. 缓存当前播放时间点。
2. 设置新的播放源。
3. 设置起播时间跳转到缓存的时间点。

示例代码如下：

const currentTime = player.getCurrentPlaybackTime();
const source = createDirectUrlSource({
  vid: 'xxxx'
  url: 'https://www.video.com/2.mp4',
  cacheKey: 'cacheKeyDef2',
});
player.setVideoSource(source);
player.setStartTime(currentTime);
player.play();

播放私有加密视频

火山引擎视频点播私有加密方案采用火山引擎自研加密算法，安全级别高，能够便捷、高效、安全地保护您的音视频版权。更多信息，请见火山引擎私有加密方案介绍。点播 SDK 支持通过 Vid 模式播放私有加密视频。应用服务端通过视频点播服务端 SDK 本地签发包含 UnionInfo 的 PlayAuthToken 并下发给点播 SDK，即可播放火山引擎私有加密视频。您可参考以下代码获取 UnionInfo：

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

// 获取 UnionInfo
getEngineUniqueId().then((id) => {
  // do something
});

// 设置私有加密视频源
const vidSource = createVidSource({playAuthToken: playAuthTokenWithUnionInfo, vid: xxxvid});

播放状态回调

调用 setListener 方法设置播放状态、加载状态、prepare、视频首帧渲染成功、播放完成、播放错误、缓存变化和 Vid 播放模式下获取到视频信息等回调，示例代码如下。

player.setListener({
  // 视频 prepare 回调
  onPrepared(_engine: TTVideoEngine) {
    console.log('video prepared');
  },
  // 加载状态改变回调
  onLoadStateChanged(engine: TTVideoEngine, loadState) {
    console.log(`loadStateChange: ${loadState}`);
  },
  // 播放状态改变回调
  onPlaybackStateChanged(engine: TTVideoEngine, playbackState) {
    console.log(`playbackStateChange: ${playbackState}`);
  },
  // 视频首帧渲染成功回调
  onReadyToDisplay(_engine: TTVideoEngine) {
    console.log('ready to display');
  },
  // 播放完成回调
  onDidFinish(_engine: TTVideoEngine) {
    console.log('play finish');
  },
  // 播放错误回调。回传错误 message 和错误码，详见[点播 SDK 错误码](https://www.volcengine.com/docs/4/66441)
  onError(message: string, code: number) {
    console.log(`Error: code: ${code}, message: ${message || ''},`);
  },
  // 缓存变化回调。预加载命中时会触发
  onCacheChange(cacheKey: string, cacheSize: number) {
    if (cacheSize > 0) {
       console.log('video hit preload: ', cacheKey, cacheSize);
    }
  },
  // Vid 播放模式下获取到视频信息
  onFetchedVideoInfo(videoModel) {
    console.log('fetched video info', videoModel);
  },
});