本文为您介绍如何使用 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 项目包名，对应 build.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';
   // （可选）若您需要在初始化播放器时指定填充模式，还需额外引入 FillModeType
   // import { FillModeType } from '@volcengine/react-native-vod-player';
   
   function Player() {
     const playerRef = useRef();
   
     // 创建播放器
     const onLoad = useCallback(async () => {
       playerRef.current = await initPlayer({viewId: 'player_container'});
       // 创建播放器时设置起播画面填充模式 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
      // playerRef.current = await initPlayer({viewId: 'player_container', fillMode: FillModeType.FillModeAspectFill});
     }, []);
   
     return (
         <PlayerViewComponent
           viewId="player_container"
           onLoad={onLoad}
           style={{
             width: '100%',
             height: '100%',
           }}
         >
         </PlayerViewComponent>
     );
   }
   

设置播放源 #

播放器 SDK 支持多种播放源，您可以根据视频的来源和业务场景选择最合适的方式。

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

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

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();

关闭播放器 #

不需要播放时，及时调用 close 关闭播放器，释放播放器实例，以避免内存泄漏。

// 关闭播放器，实现异步释放播放器实例，当播放器释放后，不应该调用实例的任何方法
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();

// 切换音量调节目标（应用内音量或系统音量）。如需调节应用内音量，必须在首次调用 play() 方法前调用 setTrackVolumeEnabled(true) 进行设置。播放开始后，不支持切换此模式。
// true: 调整播放音量。
// false: 调整系统音量
// 默认值 false
player.setTrackVolumeEnabled(true);

iOS 下如需在静音模式下实现播放声音，需调用 setActiveAudioSession 开启音频会话。

import { setActiveAudioSession } from '@volcengine/react-native-vod-player'
setActiveAudioSession(true); // enable audio session, usually for ios

纯音频播放 #

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

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

设置旋转角度 #

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

设置画面填充模式 #

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

player.setDisplayMode(FillModeType.FillModeAspectFill);

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

设置镜像模式 #

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

设置屏幕常亮 #

// 设置屏幕常亮，true: 常亮, false：关闭常亮
player.setKeepScreenOn(true);

// 获取屏幕常亮状态，true: 常亮, false：未开启常亮
const flag = player.getKeepScreenOn();

设置起播时间 #

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

设置业务类型 #

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

player.setTag('feed');

设置子业务类型 #

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

player.setSubTag('audio');

多清晰度切换 #

Vid 模式 #

Vid 播放模式下，播放器 SDK 能够自动获取视频所有可用的清晰度，并支持在播放过程中动态切换。核心流程如下：

1. 获取清晰度信息：​当播放器 SDK 通过 Vid 和临时播放 Token 成功获取到视频信息后，会触发 onFetchedVideoInfo 回调。
2. 获取清晰度列表：​调用 supportedResolutionTypes() 方法，从播放器实例中获取一个包含所有可用清晰度的数组。您可以基于此数组动态生成 UI 上的清晰度切换菜单。
3. 执行切换： 调用 configResolution() 方法，并传入目标清晰度的枚举值，即可完成切换。

获取可用清晰度列表

在播放器 SDK 触发 onFetchedVideoInfo 回调后，按如下方式获取清晰度列表。

// 在 onFetchedVideoInfo 回调后调用
const availableResolutions = player.supportedResolutionTypes();

获取当前清晰度

在视频 onPrepared 回调触发后，通过 getCurrentResolution() 获取当前的清晰度。

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

切换清晰度

调用 configResolution() 并传入 ResolutionType 枚举中定义的目标清晰度。

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

// 切换到标清
player.configResolution(ResolutionType.Standard);

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

清晰度无缝切换

无缝切换（或称平滑切换）指的是在切换清晰度时，视频能够不间断、不黑屏、不跳跃地过渡到新的码率流，从而提供丝滑的观看体验。无缝切换依赖于视频流本身（如 HLS 或 DASH）的特性，因此仅在 Vid 模式下，且视频源格式支持时才能生效。

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

// 为 HLS 视频开启无缝切换
player.enableHLSSeamlessSwitch(true);

// 为 MP4 视频开启无缝切换（如有支持）
// player.enableMP4SeamlessSwitch(true);

// 后续的切换操作与普通切换相同
// 获取清晰度列表
const list = player.supportedResolutionTypes();
// 切换清晰度
player.configResolution(ResolutionType.Standard);

DirectUrl 模式 #

DirectUrl 模式由于是直接播放单个 URL，本身不包含多清晰度的概念，因此不具备上述的自动切换能力。如果您需要在 DirectUrl 模式下实现切换清晰度，您必须自行实现以下过程：

1. 获取并记录当前视频的播放进度。
2. 使用新的视频 URL 创建并设置一个新的播放源。
3. 在新播放源上，通过 setStartTime() 方法将播放进度设置为第一步中记录的时间点。
4. 调用 play() 开始播放。

这种方式本质上是重新播放一个新视频，可能会伴随短暂的黑屏和加载过程，无法实现无缝切换。示例代码如下：

// 1. 记录当前播放时间
const currentTime = player.getCurrentPlaybackTime();

// 2. 创建并设置新的播放源 (URL 指向不同清晰度的视频)
const newSource = createDirectUrlSource({
  vid: 'your_vid_2',
  url: 'https://www.example.com/video_720p.mp4', // 新的清晰度 URL
  cacheKey: 'newCacheKey',
});
player.setVideoSource(newSource);

// 3. 设置起播时间
player.setStartTime(currentTime);

// 4. 开始播放
player.play();

生成 UnionInfo #

UnionInfo 是播放端从设备中提取的用于标识访问或设备唯一性的信息。播放器 SDK 通过 UnionInfo 向应用服务端发起播放请求，应用服务端通过服务端 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({
  /**
   * 视频准备就绪可随时开始播放
   */
  onPrepared(_engine: TTVideoEngine) {
    console.log('video prepared');
  },
  /**
   * 播放器加载状态发生变化。
   */
  onLoadStateChanged(engine: TTVideoEngine, loadState) {
    console.log(`loadStateChange: ${loadState}`);
  },
  /**
   * 播放状态发生变化。
   * 用于监听播放、暂停、停止等核心状态。
   */
  onPlaybackStateChanged(engine: TTVideoEngine, playbackState) {
    console.log(`playbackStateChange: ${playbackState}`);
  },
  /**
   * 播放进度实时更新。
   */
  onCurrentPlaybackTimeUpdate(currentTime) {
    console.log(`onCurrentPlaybackTimeUpdate: ${currentTime}`);
  },
  /** 
   * 视频码率、清晰度变化回调，码率单位
   */
  onVideoBitrateChanged?(resolution: ResolutionType, bitrate: number){
    console.log(`onVideoBitrateChanged: ${resolution}, ${bitrate}`);
  }
  /**
   * 视频尺寸变化回调
   */
  onVideoSizeChanged?(width: number, height: number) {
    console.log(`onVideoSizeChanged: ${width}, ${height}`);
  }
  /**
   * 视频首帧渲染成功。
   */
  onReadyToDisplay(_engine: TTVideoEngine) {
    console.log('ready to display');
  },
  /**
   * 视频播放至结尾。
   */
  onDidFinish(_engine: TTVideoEngine) {
    console.log('play finish');
  },
  /**
   * 播放过程中发生错误。
   * 详情请参阅[播放器 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 播放模式] 已成功获取到视频的详细信息。
   * 回传的 videoModel 对象包含了视频的分辨率、码率、URL等元数据。
   */
  onFetchedVideoInfo(videoModel) {
    console.log('fetched video info', videoModel);
  },
  
  /**
   * 字幕缓存状态变化。
   * 当字幕命中预加载缓存时触发。
   */
  onSubtitleHitCacheChange: (subtitleKey, subCacheSize) => {
    if (subCacheSize > 0) {
      console.log('subtitle hit preload', subtitleKey, subCacheSize);
    }
  },
});