本文介绍如何通过 uni-app 拉流 SDK 实现创建播放器、配置播放地址、调整播放画面等基础功能。

前提条件

已完成 SDK 的集成和初始化。详见集成 SDK 和初始化 SDK。

注意事项

真机调试：由于 SDK 使用了大量的音视频方法，这些方法在仿真模拟器下可能会出现异常，推荐您使用真机进行代码调试。

创建播放器

使用拉流 SDK，需要先创建直播播放器。完成以下步骤，创建播放器。

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

   注意

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

   <template>
     <VePlayerPlugin-VePlayerComponent viewId="viewId" @onLoad="handleLoaded" class="player" />
   </template>
   
   <style lang="scss" scoped>
     .player { width: 750rpx; flex: 1; }
   </style>
   

2. 在项目 vite.config.js 文件中，将 VePlayerPlugin-VePlayerComponent 设定为自定义组件标签，使得编辑器 HBuilderX 能识别该组件。

   import {defineConfig} from 'vite'
   import uni from '@dcloudio/vite-plugin-uni'
   const CUSTOM_TAG = ['VePlayerPlugin-VePlayerComponent']
   
   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_modules/volcengine-live-player';
   
   const player = await initPlayer({ 
       viewId: 'viewId',
       // 初始化配置。
   });
   this.player = player;
   

   注意

   • initPlayer 方法为异步方法。
   • 初始化配置参数，详见 VeLivePlayerConfiguration。

配置事件监听

您可以通过配置事件回调监听来获取播放器的内部状态信息，包括播放器状态、错误信息、音视频首帧回调以及周期性统计数据等。代码示例如下所示。

// 配置播放器回调。
this.player?.setObserver({
  onFirstVideoFrameRender() {
    console.log('视频首帧渲染');
  },
  onFirstAudioFrameRender() {
    console.log('音频首帧渲染');
  },
  onVideoRenderStall() {
    console.log('视频渲染卡顿');
  },
  onAudioRenderStall() {
    console.log('音频渲染卡顿');
  },
  onResolutionSwitch(_player, resolution) {
    console.log(`清晰度档位变化: ${VeLivePlayerResolution[resolution]}`);
  },
  onVideoSizeChanged(_player, width, height) {
    console.log(`视频宽高发生变化: ${width} * ${height}`);
  },
  onReceiveSeiMessage(_player, message) {
    console.log(`SDK 接收到 SEI 消息: ${message}`);
  },
  onMainBackupSwitch(_player, _streamType, _error) {
    console.log('主备流切换');
  },
  onPlayerStatusUpdate(_player, status) {
    console.log('播放状态变化' + status);
  },
  onSnapshotComplete(_player, _bitmap) {
    console.log('截图完成');
  },
  onStreamFailedOpenSuperResolution(_player, err) {
    console.log(`开启超分失败 (${err.errorCode || ''}) ${err.errorMsg || ''}`);
  },
  // 播放信息周期性回调。SDK 会周期性触发该回调。您可以通过该回调，获取以下信息。
  onStatistics(_player, info) {
    console.log(`当前直播的播放地址: ${info.url}
        当前播放延时: ${info.delayMs}
        下载码率: ${info.bitrate}
        当前播放格式: ${VeLivePlayerFormat[info.format]}
        当前帧率: ${info.fps}
        分辨率: ${info.width} * ${info.height}
        解码方式: ${info.isHardwareDecode ? '硬解' : '软解'}
        传输协议: ${VeLivePlayerProtocol[info.protocol]}
        累计卡顿时长: ${info.stallTimeMs}
        音频缓冲区大小: ${info.audioBufferMs}
        视频缓冲区大小: ${info.videoBufferMs}
        视频编码类型: ${info.videoCodec}`);
  },
  onError(_player, error) {
    console.log(`播放错误: (${error.errorCode}) ${error.errorMsg}`);
  },
});

配置播放地址

通过 setPlayUrl 方法配置单一播放地址，支持 RTMP、FLV、HLS 等直播协议地址。代码示例如下所示。

// 通过 URL 进行播放。
const playUrl = "http://pull.example.com/live/stream.flv";
// 配置播放地址。
this.player?.setPlayUrl(playUrl);

调整播放画面

您可以通过以下方法调整播放画面的填充模式、镜像和旋转角度，以获得更好的观看体验。

配置填充模式

通过播放器的 setRenderFillMode 方法可以配置播放画面的填充模式。播放器支持以下 3 种填充模式。

您可以参考以下代码示例配置填充模式。

// 配置填充模式。
this.player?.setRenderFillMode(
    VeLivePlayerFillMode.VeLivePlayerFillModeAspectFill,
);

配置镜像

通过播放器的 setRenderMirror 方法可以配置播放画面的镜像模式。播放器支持以下 3 种镜像模式。

您可以参考以下代码示例配置镜像。

// 配置水平镜像。
this.player?.setRenderMirror(VeLivePlayerMirror.VeLivePlayerMirrorHorizontal);

配置旋转

通过播放器的 setRenderRotation 方法可以配置播放画面的旋转角度。播放器支持以下 4 种旋转角度。

您可以参考以下代码示例配置旋转角度。

// 配置画面顺时针旋转 90 度。
this.player?.setRenderRotation(VeLivePlayerRotation.VeLivePlayerRotation90);

开始播放

调用播放器的 play 方法开始播放。代码示例如下所示。

this.player?.play(); 

获取播放器是否正在播放

调用播放器的 isPlaying 方法可以获取当前的播放状态。代码示例如下所示。

const isPlaying = this.player?.isPlaying(); 

暂停播放

调用播放器的 pause 方法暂停播放。代码示例如下所示。

this.player?.pause(); 

停止播放

调用播放器的 stop 方法停止播放。代码示例如下所示。

this.player?.stop(); 

销毁播放器

调用播放器的 destroy 方法销毁播放器并释放内存。如需在停止播放后销毁播放器，可调用该方法。代码示例如下所示。

this.player?.destroy(); 

前后台切换

在应用程序从前台切换到后台时，播放器默认会继续播放音频。如果您希望在后台状态停止播放，可参考以下代码示例。

// 监听应用切入后台事件。
this.appHideListener = () => {
  this.player?.pause() // 暂停播放。
};
uni.onAppHide(this.appHideListener);

// 监听应用从后台切回前台事件。
this.appShowListener = () => {
  this.player?.play() // 继续播放。
};
uni.onAppShow(this.appShowListener);

设置是否静音播放

调用播放器的 setMute 方法可以控制是否静音播放。代码示例如下所示。

this.player?.setMute(true); 

获取是否为静音状态

调用播放器的 isMute 方法可以获取当前是否为静音状态。代码示例如下所示。

boolean isMute = this.player?.isMute(); 

配置播放音量

调用播放器的 setPlayerVolume 方法可以控制播放音量。参数表示音量大小，默认值为 1.0，取值范围为 [0.0,1.0]。代码示例如下所示。

this.player?.setPlayerVolume(0.5);