You need to enable JavaScript to run this app.
导航

功能接入

最近更新时间2024.02.29 20:45:00

首次发布时间2022.09.09 16:30:28

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

适用版本

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

RTM 协议拉流

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

  1. 使用视频直播控制台的地址生成器,生成 RTM 拉流地址
  2. 创建 VePlayer 对象实例,设置拉流地址为 RTM 地址,代码示例如下所示。

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

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

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

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

import { createLivePlayer, register, isRTMSupportCodec, isRTMSupported} 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');

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

说明

RTM 拉流支持降级为 FLV 和 HLS 两种格式。

主备流降级

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

事件监听

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

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

多线路和多清晰度

您可通过配置 playlist 实现多线路或多清晰度。配置 defaultSourcedefaultDefinition 可以指定默认线路和默认清晰度。播放器创建成功后可调用 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,开启清晰度降级提示。在播放等待超时后,播放器会提示观众是否需要降级到更低的清晰度。

  1. 进入控制台配置多个转码模版,操作方法可参考转码配置文档。

  2. 使用视频直播控制台的地址生成器,选择不同的转码模版,生成不同清晰度的播放地址。

    alt

  3. 创建 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': '标清' },
            },
          ],
        },
      ],
    });
    

直播时移

  1. 参考时移配置说明在直播控制台中配置时移。

  2. 拼接直播时移播放地址,拼接规则为 {PullDomain}/{AppName}/{StreamName}.m3u8?{鉴权参数},详细参数说明请参见拼接直播时移播放地址

  3. 在播放器中传入拼接好的相对时移地址。

    说明

    • 直播时移的参数配置详情,请参考接口说明
    • liveStartTime 需使用浏览器本地时间。
  4. 引入直播时移插件,代码示例如下所示。

    通过 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';
    
  5. 将直播时移插件作为配置传入播放器中,并配置时移相关参数,代码示例如下所示。
    通过 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',
      },
    });
    

日志上报

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

说明

  • 强烈建议您传入与业务相关的用户 ID userId 和用户设备 ID deviceId。异常情况下需提供用户 ID 快速排查问题。
  • 如果不传入 userIddeviceId,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,不存在则为空字符串
  }
}