最近更新时间:2024.02.29 20:45:00
首次发布时间:2022.09.09 16:30:28
在接入 Web 拉流 SDK(VePlayer)的过程中,您需要根据使用场景配置不同的参数,本文为您提供了部分常见场景的接入示例。
本文档适用于 2.3.0 版本的 Web 拉流 SDK,其他版本请参考历史文档。
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', }, });
直播播放器创建成功后,您可调用 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); });
您可通过配置 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', }, });
说明
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 补充增强信息监听,代码示例如下所示。
通过 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,不存在则为空字符串 } }