功能使用--视频点播-火山引擎

文档中心

立即注册

导航

功能使用

最近更新时间：2024.09.18 14:01:56首次发布时间：2024.09.10 17:39:33

本文介绍如何使用 React Native 点播 SDK 以最简单快捷的方式播放视频。

前提条件

您已集成 SDK。

基础功能

初始化 SDK

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

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

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, // 是否开启日志上报，建议仅 debug 模式开启
  MaxCacheSize: 300 * 1024 * 1024, // 最大缓存，单位 byte
})

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

参数	类型	是否必填	默认值	说明
AppID	string	是	`-`	应用 ID，可在视频点播控制台应用管理页面获取。详情请见创建应用。
AppName	string	是	`-`	应用英文名，可在视频点播控制台应用管理页面获取。详情请见创建应用。
AppVersion	String	是	`-`	App 版本号。合法版本号应包含大于或等于 2 个 `.` 分隔符，如 `"1.3.2"`。
AppChannel	String	是	`-`	渠道号。由您自定义，如小米应用商店 (xiaomi)、华为应用市场 (huawei) 等。
PackageName	string	否	`-`	Android 项目包名，对应 `buid.gradle` 中的`applicationId` 的值
BundleID	string	否	`-`	iOS 项目包名，对应 Xcode 中 TARGETS 下 Bundle Identifier 的值
LicenseUri	string	是	`-`	License 文件路径，注意 iOS 和 Android 在各自的文件夹下，通常路径不同
OpenLog	boolean	否	`false`	是否开启日志上报
UserUniqueID	string	否	`-`	用户 ID，由您自定义，可用于在视频点播控制台单点追查页面查看单设备的播放数据。详见单点追查。
MaxCacheSize	number	否	100M	最大缓存，单位 byte

创建播放器

在需要播放器的组件中插入播放容器组件 PlayerViewComponent，并对其 viewId 属性赋值唯一的 ID。

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

function Player() {
    // ...
    
    return (
        <PlayerViewComponent
          viewId="player_container"
          onLoad={onLoad}
          style={{
            width: '100%',
            height: '100%',
          }}
        >
        </PlayerViewComponent>
    );
}

在播放容器组件 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: '80%',
        }}
      >
      </PlayerViewComponent>
  );
}

设置播放源

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

Vid 播放源

DirectUrl 播放源

调用 createVidSource 方法创建 vidSource 对象，然后通过 setVideoSource 方法设置给播放器。您需要设置 vid 和 playAuthToken 参数。这两个参数是由应用服务端下发的。客户端需调用服务端提供的接口来获取。详情请见通过临时播放 Token 播放。

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

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

调用 createDirectUrlSource 方法创建 urlSource 对象，然后通过 setVideoSource 方法设置给播放器。您需要设置视频播放地址。播放地址可以是第三方点播地址或火山引擎视频点播服务生成的播放地址。

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

const urlSource = createDirectUrlSource({
  url: 'https://demo.video.com/1.mp4', // 视频地址
  cacheKey: 'cacheKeyDemo01', // source 的缓存唯一 key
  vid: 'xxxxxx',  // 视频 vid
});
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 的枚举值如下表所示。

枚举 key	值	说明
STOP	0	播放停止。
PLAYING	1	播放中。
PAUSE	2	播放暂停。
ERROR	3	播放错误

获取加载状态

const loadState = player.getLoadState();

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

枚举 key	值	说明
PLAYABLE	1	播放器加载完成，可开始或恢复播放。
STALLED	2	播放器发生卡顿，正在加载数据。您可通过加载状态是否为 `2` 来添加 loading 图标。
ERROR	3	播放器加载数据报错。
UNKNOWN	4	未知

获取视频信息

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

获取设备 ID

如果您在初始化 SDK 时没有设置自定义用户 ID，可参考以下示例代码获取设备 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 只解码音频会更省电。

注意

该功能仅高级版或企业版支持。请确保您已购买高级版或企业版的 License 并添加高级版 SDK 依赖，详见 License 包管理。

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

设置旋转角度

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

设置填充模式

player.setDisplayMode(value);

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

枚举 key	值	说明
FillModeNone	1	无拉伸，不会变形，可能有黑边
FillModeAspectFit	2	等比例适配，不会有变形，按照视频宽高等比适配画面，可能有黑边
FillModeAspectFill	3	等比例填充，不会有变形，按照视频宽高等比充满画面，可能有画面裁切
FillModeFill	4	拉伸填充，视频宽高比例与画面比例不一致，会导致画面变形

设置镜像模式

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

切换清晰度

player.configResolution('Standard');

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

枚举 key	值	说明
Undefine	Undefine	未知
Standard	Standard	标清 360p
High	High	高清 480p
HighH	HighH	540p
SuperHigh	SuperHigh	超清 720p
ExtremelyHigh	ExtremelyHigh	1080p
TwoK	TwoK	2K
FourK	FourK	4k
Auto	Auto	自动调节。该选项仅适用于 DASH 视频，表示根据网速动态调节清晰度。

DirectUrl 模式下如果需要切换清晰度，请先缓存当前播放时间点，然后通过设置新的 source 来切换视频源，再通过设置起播时间来跳转到对应的时间点，示例代码如下：

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 和 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、首帧、播放完成及播放错误等的回调，示例代码如下。

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

进阶功能

预加载策略

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

注意

该功能仅高级版或企业版支持。请确保您已购买高级版或企业版的 License 并添加高级版 SDK 依赖，详见 License 包管理。

接入预加载策略

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

调用 enableEngineStrategy 开启预加载策略。

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

// 支持 SmallVideo（短视频场景）和 ShortVideo（中视频场景）
enableEngineStrategy('Preload', 'SmallVideo');

调用 setStrategySources 设置预加载源。

Vid 播放源

DirectUrl 播放源

import { setStrategySources } from '@volcengine/react-native-vod-player';
   
   const vidData = [
     {
       playAuthToken: 'playAuthToken1',
       vid: 'vid1',
     },
     {
       playAuthToken: 'playAuthToken2',
       vid: 'vid2',
     },
     // ...
     ];
   
   // 设置预加载列表的播放源  
   setStrategySources(vidData.map(u => createVidSource(u)));

import { setStrategySources } from '@volcengine/react-native-vod-player';
   
   const urlData = [
     {
       url: 'https://voddemo-play.volcvod.com/1.mp4',
       vid: 'vid1',
     },
     {
       url: 'https://voddemo-play.volcvod.com/2.mp4',
       vid: 'vid2',
     },
   // ...
   ];
   
   // 设置预加载列表的播放源  
   setStrategySources(
     urlData.map(u =>
       createDirectUrlSource({
         ...u,
         cacheKey: u.vid,
       } as DirectUrlSourceInitProps),
     ),
   );

如需新添加预加载列表，则调用 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);
    }
  }
});

关闭预加载策略

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

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

清除缓存

预加载会占据一定的存储空间，可通过 clearAllCaches 清除缓存。

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

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