功能接入--视频直播-火山引擎

文档中心

立即注册

导航

功能接入

最近更新时间：2024.07.22 21:40:49首次发布时间：2022.09.09 16:30:28

在接入 Web 拉流 SDK（VePlayer）的过程中，您需要根据使用场景配置不同的参数，本文为您提供了部分常见场景的接入示例。

适用版本

本文档适用于 2.3.0 版本的 Web 拉流 SDK，其他版本请参考历史文档。

RTM 协议拉流

VePlayer 支持 RTM 协议拉流，详细功能介绍请参见超低延时直播。

注意

RTM 拉流需直播流中不含 B 帧，且需音频格式为 Opus，如果您的直播流不符合要求，请在使用 RTM 拉流前参考常见问题- Web 端播放 RTM 流时为何卡顿和无声添加转码配置，去除直播流中的 B 帧，并将音频格式转为 Opus。

使用视频直播控制台的地址生成器，生成符合要求的 RTM 转码流拉流地址。
为了防止出现兼容性问题，您需要为 RTM 拉流设置播放降级地址，代码示例参考下文。
说明
- RTM 拉流降级地址支持 FLV 和 HLS 两种格式。
- VePlayer 支持设置 RTM 播放降级地址（fallbackUrl），您可以将 PC 端的降级地址设置 FLV 拉流地址，手机端降级地址设置为 HLS 拉流地址。

创建 VePlayer 对象实例，设置 RTM 拉流地址和降级地址，代码示例如下所示。

通过 CND 集成时的代码示例：

// 判断是否支持 RTM
const isRTMSupported = await VePlayer.isRTMSupported();
// 判断 RTM 是否支持 H264 格式播放
const isRTMSupportH264 = await VePlayer.isRTMSupportCodec('h264');

// RTM 拉流使用去除 B 帧的 Opus 转码流拉流地址，以转码流后缀为 rtm 为例
const RTM_URL = 'https://pulldomain/appname/stream_rtm.sdp';
// 设置 FLV 拉流地址作为降级地址
const FLV_URL = 'https://pulldomain/appname/stream.flv';
// 设置 HLS 拉流地址作为降级地址
const M3U8_URL = 'https://pulldomain/appname/stream.m3u8';

// 设置移动端降级地址选择逻辑
const fallbackUrl = VePlayer.Sniffer.device === 'mobile' ? M3U8_URL : FLV_URL;

VePlayer.createLivePlayer({
  // v2.1.0 及后续版本不再需要判断是否支持 RTM 播放，播放器会自行判断，如果不支持播放 RTM 则降级到 fallbackUrl 地址。
  url: isRTMSupported && isRTMSupportH264 ? RTM_URL : fallbackUrl,
  width: 640,
  height: 360,
  rtm: {
    fallbackUrl: fallbackUrl,
  },
  logger: {
    appId: '5*****8',
  },
});

通过 NPM 集成时的代码示例：

import { createLivePlayer, register, isRTMSupportCodec, isRTMSupported, Sniffer} from '@volcengine/veplayer'
import { flv, hls, rtm } from '@volcengine/veplayer-plugin'
import '@volcengine/veplayer/style'

register([flv, hls, rtm]);
// 判断是否支持 RTM
const isSupported = await isRTMSupported();
// 判断 RTM 是否支持 H264 格式播放
const isRTMSupportH264 = await isRTMSupportCodec('h264');

// RTM 拉流使用去除 B 帧的 Opus 转码流拉流地址，以转码流后缀为 rtm 为例
const RTM_URL = 'https://pulldomain/appname/stream_rtm.sdp';
// 设置 FLV 拉流地址作为降级地址
const FLV_URL = 'https://pulldomain/appname/stream.flv';
// 设置 HLS 拉流地址作为降级地址
const M3U8_URL = 'https://pulldomain/appname/stream.m3u8';

const fallbackUrl = Sniffer.device === 'mobile' ? M3U8_URL : FLV_URL;

createLivePlayer({
  // v2.1.0 及后续版本不再需要判断是否支持 RTM 播放，播放器会自行判断，如果不支持播放 RTM 则降级到 fallbackUrl 地址。
  url: isSupported && isRTMSupportH264 ? RTM_URL : fallbackUrl,
  width: 640,
  height: 360,
  rtm: {
    fallbackUrl: fallbackUrl,
  },
  logger: {
    appId: '5*****8',
  },
});

主备流降级

VePlayer 支持同时设置多个拉流地址，实现主备流降级。

您可通过设置拉流失败时循环拉流的最大次数 maxFallbackRound 和备流地址 fallbackUrls，开启主流异常降级；主拉流地址异常后，播放器将自动切换为 fallbackUrls 中配置的备用拉流地址。

说明

VePlayer 主备流降级仅支持相同格式的拉流降级。

设置单一播放地址时，代码示例如下所示。

VePlayer.createLivePlayer({
  width: 640,
  height: 360,
  url: 'https://pulldomain/appname/mainstream.m3u8',
  fallbackUrls: ['https://pulldomain/appname/backupstream.m3u8'],
  maxFallbackRound: 1,
  logger: {
    appId: '5****8',
  },
});

设置多清晰度时，代码示例如下所示。

VePlayer.createLivePlayer({
  height: 360,
  defaultDefinition: 'ld',
  maxFallbackRound: 1,
  playlist: [
    {
      definitions: [
        {
          url: 'https://pulldomain/appname/mainstream_hd.m3u8',
          fallbackUrls: ['https://pulldomain/appname/backupstream_hd.m3u8'],
          definition: 'hd',
          text: { en: 'hd', 'zh-cn': '超清' },
        },
        {
          url: 'https://pulldomain/appname/mainstream_sd.m3u8',
          definition: 'sd',
          fallbackUrls: ['https://pulldomain/appname/backupstream_sd.m3u8'],
          text: { en: 'sd', 'zh-cn': '高清' },
        },
        {
          url: 'https://pulldomain/appname/mainstream_ld.m3u8',
          definition: 'ld',
          fallbackUrls: ['https://pulldomain/appname/backupstream_ld.m3u8'],
          text: { en: 'ld', 'zh-cn': '标清' },
        },
      ],
    },
  ],
  logger: {
    appId: '5****8',
  },
});

事件监听

直播播放器创建成功后，您可调用 on、once 方法设置事件监听，支持的事件及其说明可查看事件。

通过 CDN 集成时的代码示例

VePlayer.createLivePlayer({
  width: 640,
  height: 360,
  url: 'https://pulldomain/appname/mystream.m3u8',
  logger: {
    appId: '5****8',
  },
}).then(function (veplayer) {
  function eventHandler(data) {
    console.log('监听事件的回调数据', data);
  }
  // 监听指定事件
  veplayer.on(VePlayer.live.Events.PLAY, eventHandler);
  // 监听指定事件，事件处理函数只执行一次
  veplayer.once(VePlayer.live.Events.PLAY, eventHandler);
  // 解绑或移除指定事件的事件监听
  veplayer.off(VePlayer.live.Events.PLAY, eventHandler);
  // 解绑或移除所有事件监听。
  veplayer.offAll();
});

通过 NPM 集成时的代码示例

import { createLivePlayer, register, live} from '@volcengine/veplayer'
import { hls } from '@volcengine/veplayer-plugin'
import '@volcengine/veplayer/style'

register([hls]);

createLivePlayer({
  width: 640,
  height: 360,
  url: 'https://pulldomain/appname/mystream.m3u8',
  logger: {
      appId: '5****8',
  },
}).then(function (veplayer) {
  function eventHandler(data) {
      console.log('监听事件的回调数据', data);
  }
  // 监听指定事件
  veplayer.on(live.Events.PLAY, eventHandler);
  // 监听指定事件，事件处理函数只执行一次
  veplayer.once(live.Events.PLAY, eventHandler);
  // 解绑或移除指定事件的事件监听
  veplayer.off(live.Events.PLAY, eventHandler);
  // 解绑或移除所有事件监听。
  veplayer.offAll();
});

报错监听

直播播放器创建成功后，您可监听报错事件，针对不同的错误码区分处理，所有的错误码及说明可查看错误码。

通过 CDN 集成时的代码示例

VePlayer.createLivePlayer({
  width: 640,
  height: 360,
  url: 'https://pulldomain/appname/mystream.m3u8',
  logger: {
    appId: '5****8',
  },
}).then(function (veplayer) {
  function errorHandler(error) {
    console.log('监听到错误', error);
    console.log('错误码', error.errorCode);
    console.log('错误信息', error.message);
  }
  // 监听错误事件
  veplayer.on(VePlayer.live.Events.ERROR, errorHandler);
});

通过 NPM 集成时的代码示例

import { createLivePlayer, register, live} from '@volcengine/veplayer'
import { hls } from '@volcengine/veplayer-plugin'
import '@volcengine/veplayer/style'

register([hls]);

createLivePlayer({
  width: 640,
  height: 360,
  url: 'https://pulldomain/appname/mystream.m3u8',
  logger: {
    appId: '5****8',
  },
}).then(function (veplayer) {
  function errorHandler(error) {
    console.log('监听到错误', error);
    console.log('错误码', error.errorCode);
    console.log('错误信息', error.message);
  }
  // 监听错误事件
  veplayer.on(live.Events.ERROR, errorHandler);
});

DRM 加密流播放

Web 拉流 SDK 支持 DRM 加密流播放。

说明

当前仅支持在使用 Safari 浏览器的 PC 端和支持 Safari 或 Chrome 浏览器的 iOS 端使用 Web 拉流 SDK 播放 DRM 加密流。

参考最佳实践- 直播 DRM 加密获取以下信息：
- 获取 M3U8 格式的 DRM 加密流播放地址；
- 获取 DRM 授权许可文件；
- 获取 FairPlay 证书文件。

创建播放器并传入以上获取的信息，代码示例如下所示。

VePlayer.createLivePlayer({
    url: 'https://xxx.m3u8',
    height: 360,
    drm: {
      fairplay: {
        getDrmConfig: async ({url}) => {
          return {
             // FairPlay 证书查询地址 URL
             serverCertificatePath: 'https://xxx',
             // DRM 授权许可查询地址 URL
             serverProcessSPCPath: 'https://xxx',
          }
        },
      },
    },
  }).then(function (veplayer) {
    veplayer.on('error', function (error) {
      // 错误代码 7100 表示授权校验失败，请检查获取 DRM 许可证书和 FairPlay 证书的 URL 是否有效
      console.log(error.errorCode);
    });
  });

多线路和多清晰度

您可通过配置 playlist 实现多线路或多清晰度。配置 defaultSource 和 defaultDefinition 可以指定默认线路和默认清晰度。播放器创建成功后可调用 switch 方法切换线路或清晰度。

说明

当使用多线路或者多清晰度时，不支持 url 的配置。

设置多线路时，代码示例如下所示。

VePlayer.createLivePlayer({
  height: 360,
  defaultSource: 'lineOne',
  playlist: [
    {
      name: 'lineOne',
      text: { 'zh-cn': '线路一', en: 'lineone' },
      definitions: ['https://pulldomain/appname/mystream_hd.m3u8'],
    },
    {
      name: 'lineTwo',
      text: { 'zh-cn': '线路二', en: 'linetwo' },
      definitions: ['https://pulldomain/appname/mystream1_hd.m3u8'],
    },
  ],
  logger: {
    appId: '5****8',
  },
}).then(function (veplayer) {
  // 调用 switch 方法切换线路
  veplayer.switch({ source: 'lineTwo' });
});

设置多清晰度时，代码示例如下所示。

VePlayer.createLivePlayer({
  height: 360,
  defaultDefinition: 'ld',
  playlist: [
    {
      definitions: [
        {
          url: 'https://pulldomain/appname/mystream_hd.m3u8',
          definition: 'hd',
          text: { en: 'hd', 'zh-cn': '超清' },
        },
        {
          url: 'https://pulldomain/appname/mystream_sd.m3u8',
          definition: 'sd',
          text: { en: 'sd', 'zh-cn': '高清' },
        },
        {
          url: 'https://pulldomain/appname/mystream_ld.m3u8',
          definition: 'ld',
          text: { en: 'ld', 'zh-cn': '标清' },
        },
      ],
    },
  ],
  logger: {
    appId: '5****8',
  },
}).then(function (veplayer) {
  // 调用 switch 方法切换清晰度
  veplayer.switch({ definition: 'hd' });
});

设置多线路和多清晰度时，代码示例如下所示。

VePlayer.createLivePlayer({
  height: 360,
  defaultDefinition: 'ld',
  defaultSource: 'lineOne',
  playlist: [
    {
      name: 'lineOne',
      text: { 'zh-cn': '线路一', en: 'lineone' },
      definitions: [
        {
          url: 'https://pulldomain/appname/mystream_hd.m3u8',
          definition: 'hd',
          text: { en: 'hd', 'zh-cn': '超清' },
        },
        {
          url: 'https://pulldomain/appname/mystream_ld.m3u8',
          definition: 'ld',
          text: { en: 'ld', 'zh-cn': '标清' },
        },
      ],
    },
    {
      name: 'lineTwo',
      text: { 'zh-cn': '线路二', en: 'linetwo' },
      definitions: [
        {
          url: 'https://pulldomain/appname/mystream1_hd.m3u8',
          definition: 'hd',
          text: { en: 'hd', 'zh-cn': '超清' },
        },
        {
          url: 'https://pulldomain/appname/mystream1_sd.m3u8',
          definition: 'sd',
          text: { en: 'sd', 'zh-cn': '高清' },
        },
        {
          url: 'https://pulldomain/appname/mystream1_ld.m3u8',
          definition: 'ld',
          text: { en: 'ld', 'zh-cn': '标清' },
        },
      ],
    },
  ],
  logger: {
    appId: '5****8',
  },
}).then(function (veplayer) {
  // 调用 switch 方法切换线路和清晰度
  veplayer.switch({ definition: 'hd', source: 'lineTwo' });
});

视频过期处理

如果您的拉流域名开启了 URL 鉴权，则生成的拉流地址超过过期时间就会失效，可能导致观众看不到直播内容。为了保持不间断拉流，请获取新的拉流地址，并调用播放器的 switch 方法更新拉流地址，代码示例如下所示。

VePlayer.createLivePlayer({
  width: 640,
  height: 360,
  url: 'https://testpull.mycloud.com/live/mystream.m3u8?{鉴权参数}',
  logger: {
    appId: '5****8',
  },
}).then(function (veplayer) {
  // 最新的拉流地址
  const newUrl =
    'https://testpull.mycloud.com/live/mystream.m3u8?{新的鉴权参数}';
  // 更新拉流地址
  veplayer.switch(newUrl);
});

清晰度降级

您可以通过设置清晰度自动降级参数 definition.needFallback，开启清晰度降级提示。在播放等待超时后，播放器会提示观众是否需要降级到更低的清晰度。

进入控制台配置多个转码模版，操作方法可参考转码配置文档。
使用视频直播控制台的地址生成器，选择不同的转码模版，生成不同清晰度的播放地址。

创建 VePlayer 对象实例，在 playlist 中传入所有清晰度地址，代码示例如下所示。

VePlayer.createLivePlayer({
  width: 640,
  height: 360,
  definition: {
    //	可自定义降级顺序
    demotePriority: ['hd', 'sd', 'ld'],
    //	是否开启自动降级提示
    needFallback: true,
    //	单位（ms），等待超过该时间，则提示用户是否进行清晰度降级
    longWaitingTime: 5000,
  },
  playlist: [
    {
      definitions: [
        {
          url: 'https://testpull.mycloud.com/live/mystream_hd.m3u8',
          definition: 'hd',
          text: { en: 'hd', 'zh-cn': '超清' },
        },
        {
          url: 'https://testpull.mycloud.com/live/mystream_sd.m3u8',
          definition: 'sd',
          text: { en: 'sd', 'zh-cn': '高清' },
        },
        {
          url: 'https://testpull.mycloud.com/live/mystream_ld.m3u8',
          definition: 'ld',
          text: { en: 'ld', 'zh-cn': '标清' },
        },
      ],
    },
  ],
});

直播时移

参考时移配置说明在直播控制台中配置时移。
拼接直播时移播放地址，拼接规则为 {PullDomain}/{AppName}/{StreamName}.m3u8?{鉴权参数}，详细参数说明请参见拼接直播时移播放地址，
在播放器中传入拼接好的相对时移地址。
说明
- 直播时移的参数配置详情，请参考接口说明。
- liveStartTime 需使用浏览器本地时间。

引入直播时移插件，代码示例如下所示。

通过 CDN 集成时的代码示例

<script src="https://lf-unpkg.volccdn.com/obj/vcloudfe/sdk/@volcengine/veplayer/2.0.0/umd/veplayer.plugin.time.shift.production.js"></script>
<link rel="stylesheet" href="https://lf-unpkg.volccdn.com/obj/vcloudfe/sdk/@volcengine/veplayer/2.0.0/umd/veplayer.plugin.time.shift.production.css">

通过 NPM 集成时的代码示例

import { timeShift } from '@volcengine/veplayer-plugin';
import '@volcengine/veplayer-plugin/time-shift/style';

将直播时移插件作为配置传入播放器中，并配置时移相关参数，代码示例如下所示。
通过 CDN 集成时的代码示例

VePlayer.createLivePlayer({
  width: 640,
  height: 360,
  url: 'https://testpull.mycloud.com/live/mystream.m3u8',
  timeShift: {
    liveStartTime: Date.now() / 1000 - 60,
  },
  plugins: [window.VePlayerTimeShift],
  logger: {
    appId: '5****8',
  },
});

通过 NPM 集成时的代码示例

register([hls]);

createLivePlayer({
  width: 640,
  height: 360,
  url: 'https://testpull.mycloud.com/live/mystream.m3u8',
  timeShift: {
    liveStartTime: Date.now() / 1000 - 60,
  },
  plugins: [timeShift],
  logger: {
    appId: '5****8',
  },
});

日志上报

登录视频直播控制台的应用管理页面，查看已创建 Web 应用的 App ID。
在 logger 中传入 appId，开启日志上报。直播过程中，如果出现播放异常，您可以联系技术支持，定位并排查问题。

说明

强烈建议您传入与业务相关的用户 ID userId 和用户设备 ID deviceId。异常情况下需提供用户 ID 快速排查问题。
如果不传入 userId 和 deviceId，VePlayer 将根据用户浏览器随机生成，该值会在浏览器端缓存。

VePlayer.createLivePlayer({
  width: 640,
  height: 360,
  url: 'https://pulldomain/appname/mystream.flv',
  logger: {
    appId: '2****4',
    userId: '1********6',
    deviceId: '3********7',
  },
});

SEI 监听

在播放器创建完成后，您可以设置 SEI 补充增强信息监听，代码示例如下所示。

通过 CDN 集成时的代码示例

VePlayer.createLivePlayer({
  width: 640,
  height: 360,
  url: 'https://pull.example.com/live/stream1.flv',
  logger: {
    appId: '5****8',
  },
}).then(function (veplayer) {
  veplayer.on(VePlayer.live.Events.SEI, function (data) {
    console.info('SEI 信息', data);
  });
});

通过 NPM 集成时的代码示例

import { createLivePlayer, register, live} from '@volcengine/veplayer'
import { flv } from '@volcengine/veplayer-plugin'
import '@volcengine/veplayer/style'

register([flv]);

createLivePlayer({
  width: 640,
  height: 360,
  url: 'https://pull.example.com/live/stream1.flv',
  logger: {
    appId: '5****8',
  },
}).then(function (veplayer) {
  veplayer.on(live.Events.SEI, function (data) {
    console.info('SEI 信息', data);
  });
});

当解析到视频 SEI 消息时，播放器将触发监听，监听的数据如下所示。

interface Data {
  originPts: number; // 原始 PTS。视频帧在实际推流中的显示时间戳 PTS
  pts: number; // 修正后的 PTS。在直播场景中，播放器会根据观众进入直播间时间，从 0 开始重新定义显示时间戳 PTS
  time: number; // 该 SEI 消息在当前直播视频中的时间点，单位为 s
  data: {
    payload: Uint8Array; // SEI 数据
    type: number; // SEI 类型
    size: number; // SEI 大小
    uuid: string; // SEI UUID，不存在则为空字符串
  }
}