本文档适用于已通过 NPM 或插件方式成功集成视频直播微信小程序拉流 SDK 的场景。文中提供组件的使用示例和常见功能的接入方式，帮助您快速开发和调试播放页面。

使用前提

已完成 SDK 安装与组件引入，具体方式可参考：

• 通过 NPM 方式集成小程序拉流 SDK
• 通过插件方式集成小程序拉流 SDK

拉流播放

最简单的拉流播放只需通过 src 属性传入音视频地址，播放器组件会自动发起拉流并开始播放。

<!-- index.wxml -->
<ve-live-player
  autoplay
  src="https://pull-demo.volcfcdnrd.com/live/st-4536521.flv"
/>

关键参数说明：

• src：填写火山引擎控制台生成的 FLV/RTMP 拉流地址。
• autoplay：开启自动播放。

页面脚本中无需添加任何逻辑，保留空的页面声明即可正常播放。

// index.js
Page({});

播放控制

除了基础播放外，播放器还支持多种控制操作，如播放、暂停、停止、重新播放、静音、全屏等。您可以通过获取播放器实例并调用对应接口实现控制。

<!-- index.wxml -->
<view>播放控制示例</view>
<ve-live-player
  id="player"
  autoplay
  src="https://pull-demo.volcfcdnrd.com/live/st-4536521.flv" />

<button bindtap="play">播放</button>
<button bindtap="pause">暂停</button>
<button bindtap="stop">停止</button>
<button bindtap="resume">继续播放</button>
<button bindtap="retry">重新播放</button>
<button bindtap="requestFullscreen">全屏</button>
<button bindtap="mute">静音</button>
<button bindtap="unmute">取消静音</button>

// index.js
import { getVeLivePlayer } from 'veplayer-live-mp-wx';

Page({
  onLoad() {
    this.veLivePlayer = getVeLivePlayer(this, '#player');
  },
  play() {
    this.veLivePlayer.play();
  },
  pause() {
    this.veLivePlayer.pause();
  },
  stop() {
    this.veLivePlayer.stop();
  },
  resume() {
    this.veLivePlayer.resume();
  },
  retry() {
    this.veLivePlayer.replay();
  },
  mute() {
    this.veLivePlayer.mute();
  },
  unmute() {
    this.veLivePlayer.unmute();
  },
  requestFullscreen() {
    this.veLivePlayer.requestFullscreen({ direction: 90 });
  },
});

事件监听

播放器支持多种事件监听方式，方便您在播放过程中捕获和处理各种事件。

方式一：通过 bind 监听组件原生事件

通过 WXML 中 bind 绑定播放器内置事件，实现对播放状态的监听，适合绑定播放、暂停、结束等标准事件。代码示例如下所示。

<!-- index.wxml -->
<ve-live-player
  class="player"
  bindplay="onPlay"
  autoplay
  src="https://pull-demo.volcfcdnrd.com/live/st-4536521.flv"
/>

对应的页面逻辑：

Page({
  onPlay() {
    console.log('play event triggered');
  }
});

方式二：获取组件实例后监听自定义事件

您也可以通过 SDK 提供的接口获取播放器实例，使用 on 方法监听自定义事件，支持更灵活的事件管理，适合监听更多扩展事件，例如视频尺寸变化、用户自定义事件等。代码示例如下所示。

// index.js
import { getVeLivePlayer } from 'veplayer-live-mp-wx';

Page({
  onLoad() {
    const veLivePlayer = getVeLivePlayer(this, '.player');
    veLivePlayer.on('ok', () => {
      console.log('ok');
    });
    veLivePlayer.emit('ok');
    veLivePlayer.on('videoResize', detail => {
      console.log('videoResize: ', detail);
    });
  },
  onPlay() {
    console.log('play');
  },
});

报错监听

为提升用户体验，建议在播放器创建后监听报错事件，针对不同错误进行处理。

方式一：通过 binderror 绑定错误回调

通过 bind 绑定错误，实现报错监听。代码示例如下所示。

<!-- index.wxml -->
<ve-live-player class="player" binderror="onError" autoplay src="" />

方式二：通过 on 方法监听

通过播放器实例 on 方法监听 error 事件。代码示例如下所示。

// index.js
import { getVeLivePlayer } from 'veplayer-live-mp-wx';

Page({
  onLoad() {
    const veLivePlayer = getVeLivePlayer(this, '.player');
    veLivePlayer.on('error', detail => {
      console.log('error: ', detail);
    });
  },
  onError() {
    console.log('error');
  },
});

自适应容器

播放器会根据视频实际尺寸自动调整容器大小，支持以下两种常见自适应方式，方便适配不同布局需求。

方式一：固定宽度，自适应高度

容器宽度固定，高度根据视频高度进行自适应调整，代码示例如下所示。

<!-- index.wxml -->
<ve-live-player
  autoplay
  src="https://pull-demo.volcfcdnrd.com/live/st-4536521.flv"
  fit-video-size="fixWidth"
  width="100vw"
/>

方式二： 固定高度，自适应宽度

容器高度固定，宽度根据视频宽度进行自适应调整，代码示例如下所示。

<text>fit height</text>
<ve-live-player
  autoplay
  src="https://pull-demo.volcfcdnrd.com/live/st-4536524.flv"
  fit-video-size="fixHeight"
  height="300px"
/>

忽略内置插件

播放器内置了多个功能插件，用于显示加载状态、播放错误提示和封面图等。如果您希望关闭某些插件以定制界面，可以通过 ignores 参数传入插件名称列表。

播放器支持忽略以下内置插件：

• ve-loading：显示加载状态，在视频初始化或卡顿时展示 loading 动画。
• ve-error：播放失败提示插件，用于展示拉流错误信息，例如“资源不存在”等。
• ve-poster：封面图展示插件，用于播放前显示封面图。如设置忽略则不显示封面。

以下示例展示如何通过数据绑定设置忽略插件：

<!-- index.wxml -->
<ve-live-player
  autoplay
  ignores="{{ignores}}"
  src="https://pull-demo.volcfcdnrd.com/live/st-4536521.flv"
/>

// index.js
Page({
  data: {
    /**
     * 忽略内置插件列表
     * 有效值：'ve-loading', 've-error', 've-poster'
     */
    ignores: ['ve-loading'],
  },
});

日志上报

播放器默认开启日志上报，便于监控播放质量和定位问题。您可以选择关闭日志上报，或根据需求进行配置，配置可参考 LoggerConfig。

关闭日志上报

```html
<!-- index.wxml -->
<ve-live-player
  autoplay
  class="player"
  logger="{{logger}}"
  src="https://pull-demo.volcfcdnrd.com/live/st-4536521.flv"
/>
```

```js
// index.js
import { getVeLivePlayer } from 'veplayer-live-mp-wx';

Page({
  data: {
    logger: {
      enable: false,
    },
  },
});
```

开启日志上报

```html
<!-- index.wxml -->
<ve-live-player
  autoplay
  class="player"
  logger="{{logger}}"
  src="https://pull-demo.volcfcdnrd.com/live/st-4536521.flv"
/>
```

```js
// index.js
import { getVeLivePlayer } from 'veplayer-live-mp-wx';

Page({
  data: {
    logger: {
      enable: true,
      appId: '742***2',
      appName: 'app_name',
      userId: 'u_123456',
      deviceId: 'd_123456',
    },
  },
  onLoad() {
    const veLivePlayer = getVeLivePlayer(this, '.player');
  },
});
```

SEI 监听

播放器支持监听 SEI（Supplemental Enhancement Information）消息，用于获取视频流中的补充信息。代码示例如下所示。

<!-- index.wxml -->
<ve-live-player
  id="player"
  autoplay
  src="https://pull-demo.volcfcdnrd.com/live/st-4536521.flv"
/>

// index.js
import { getVeLivePlayer } from 'veplayer-live-mp-wx';

Page({
  onLoad() {
    const veLivePlayer = getVeLivePlayer(this, '#player');
    veLivePlayer.on('sei', e => {
      console.log('sei info: ', e);
    });
  },
});

封面图设置

您可以通过 poster 属性为播放器设置封面图，提升用户体验。

<!-- index.wxml -->
<ve-live-player poster="{{poster}}" id="player" autoplay src="" />

// index.js
import { getVeLivePlayer } from 'veplayer-live-mp-wx';

Page({
  data: {
    poster:
      'https://upload-images.jianshu.io/upload_images/5809200-a99419bb94924e6d.jpg?imageMogr2/auto-orient/strip%7CimageView2/2/w/1240',
  },
});