本文为您介绍如何实现 uni-app 播放器 SDK 的基础功能。

初始化 SDK

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

import { initEnv } from '@/uni-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 应用唯一标识
  // 渠道号。由您自定义，如小米应用商店 (xiaomi)、华为应用市场 (huawei) 等。
  AppChannel: uni.getSystemInfoSync().platform === 'android' ? 'GoogleStore' :'AppStore', 
  AppVersion: '1.0.0', // App 版本号。合法版本号应包含大于或等于 2 个 . 分隔符，如 "1.3.2"。
  // License 文件路径，对应 nativeResources 下 Licesne 所在的相对路径，注意 Android 和 iOS 的相对路径形式有所区别
  LicenseUri: uni.getSystemInfoSync().platform === 'android' ? 'assets:///ttsdk.lic' : 'ttsdk.lic', 
  UserUniqueID: 'ReactNativeExample', // 自定义用户 ID。配置后，您可在视频点播控制台单点追查页面，查询单用户的播放数据。详情请见[单点追查](https://www.volcengine.com/docs/4/106093)
  OpenLog: true, // 是否开启日志，建议仅 debug 模式开启
  MaxCacheSize: 300 * 1024 * 1024, // 最大缓存，单位为 byte
})

初始化配置参数详细说明如下表所示：

创建播放器

1. 在需要播放器的组件中插入播放容器组件 <TTSDKPlugin-TTSDKComponent />，并对其 viewId 属性赋值唯一的 ID。

   注意

   <TTSDKPlugin-TTSDKComponent /> 组件为扩展 component。该类型组件只能在 .nvue 文件中使用，使用时不需要引入即可直接使用，请确保播放器所在页面组件是 .nvue 文件，具体参看在 uni-app 中使用组件。注意 nvue 开发与 vue 开发的区别，尤其注意 CSS 布局不支持使用百分比。

   <template>
     <view class="container">
       <view class="view">
         <TTSDKPlugin-TTSDKComponent
           viewId="viewId-jhx2uy21"
           class="palyer"
         >
         </TTSDKPlugin-TTSDKComponent>
       </view>
     </view>
   </template>
   
   <style scoped>
     .container{
       width: 750rpx;
     }
     .player {
       height: 600px;
       width: 750rpx;
       position: relative;
     }
   </style>
   

2. 在项目 vite.config.js 文件中，将 TTSDKPlugin-TTSDKComponent 添加自定义组件标签，这样使得编辑器 HBuilderX 能识别该组件。

   import {defineConfig} from 'vite'
   import uni from '@dcloudio/vite-plugin-uni'
   
   const CUSTOM_TAG = ['TTSDKPlugin-TTSDKComponent']
   
   export default defineConfig({
     plugins: [uni({
       vueOptions: {
         template: {
           compilerOptions: {
             isCustomElement: tag => CUSTOM_TAG.includes(tag) //这样就可以让编译器知道哪些是自定义组件  
           }
         }
       }
     })],
     build: {
       minify: false,
     },
     transpileDependencies: ['@dcloudio/uni-ui'],
   })
   

3. 调用 initPlayer 方法创建播放器（注意该方法是异步方法）。注意需要传入 viewId，对应播放容器组件的 viewId。

   import { initPlayer } from "@/uni-vod-player";
   
   const player = await initPlayer({ viewId: this.viewId });
   this.player = player;
   

设置播放源

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

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

  import { createVidSource } from '@/uni-vod-player';
  
  const vidSource = createVidSource({
    playAuthToken: playAuthTokenxxx, // 临时播放 Token，由应用服务端签出下发
    vid: xxxvid, // 视频 ID
    resolution: 'Standard', // 默认起播清晰度
  });
  this.player.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 '@/uni-vod-player';
  
  const urlSource = createDirectUrlSource({
    url: 'https://demo.video.com/1.mp4', // 视频地址
    cacheKey: 'cacheKeyDemo01', // source 的缓存唯一 key
    vid: 'xxxxxx',  // 视频 vid
  });
  this.player.setVideoSource(urlSource);
  

播放控制

可对播放器进行播放、暂停、seek 等操作。

// 播放
this.player.play();

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

// 准备
this.player.prepare();

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

// 停止，实现停止播放的功能，即停止拉流，一般业务不需要调用
this.player.stop();

关闭播放器

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

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

获取当前播放时间

const currentTime = this.player.getCurrentPlaybackTime();

获取视频已缓存时长

const progress = this.player.getProgress();

获取播放状态

const playbackState = this.player.getPlaybackState();

获取的播放状态对应枚举 PlaybackState，有效值如下：

获取加载状态

const loadState = this.player.getLoadState();

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

获取视频信息

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

获取设备 ID

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

import { getDeviceID } from '@/uni-vod-player';

const did = getDeviceID();

倍速播放

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

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

循环播放

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

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

静音

// 静音
this.player.setMuted(true);

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

调节音量

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

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

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

纯音频播放

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

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

设置画面旋转

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

设置画面填充模式

this.player.setDisplayMode(value);

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

设置画面镜像

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

设置起播时间

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

设置业务类型

// 业务类型（tag）用于区分同一应用（appid）内，不同类型的音视频。可以根据业务需要按视频场景、视频时长等划分：比如沉浸式 feed 流、短视频视频、长视频等。
this.player.setTag('feed');

设置自定义标签

// 自定义标签 subtag 用于区分同一业务类型下的不同细分，比如加密视频、非加密加密、音频等。代码示例如下所示
this.player.setSubTag('audio');

设置清晰度

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

获取当前清晰度

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

获取清晰度列表

const list = this.player.supportedResolutionTypes();

切换清晰度

this.player.configResolution('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 '@/uni-vod-player';

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

// 设置加密播放的播放源
const vidSource = createVidSource({playAuthToken: playAuthTokenWithUnionInfo, vid: xxxvid});

播放状态回调

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

import { PlaybackState } from '@/uni-vod-player';

this.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}`);
    if (playbackState === PlaybackState.PLAYBACK_STATE_PLAYING) {
      // 隐藏封面图
      this.showPoster = false;
    }
  },
  // 视频首帧出现回调
  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);
  },
});