火山引擎VePlayer

在接入 Web 拉流 SDK（VePlayer）的过程中，您需要根据使用场景配置不同的参数，本文为您提供了部分常见场景的接入示例。 ## 适用版本本文档适用于 **最新版本**的 Web 拉流 SDK，版本信息请参考[发布历史](https://www.volcengine.com/docs/6469/1130998)，历史版本请参考[历史文档](https://www.volcengine.com/docs/6469/1167746)。 ## FLV 拉流 Web 拉流 SDK 支持检查浏览器是否支持播放 FLV 直播流，各端浏览器播放 FLV 直播流需满足以下条件。 - PC 端和 Android 端浏览器：需支持 [Media Source Extensions](https://caniuse.com/?search=Media%20Source%20Extensions) API。 - iOS 端浏览器：需支持 [ManagedMediaSource](https://caniuse.com/?search=ManagedMediaSource) API。 :::tip 播放 FLV 格式的直播流时，直播流视频等级不可超过 level 6，视频等级说明请参见 [Advanced Video Coding](https://en.wikipedia.org/wiki/Advanced_Video_Coding#Levels)。 ::: :::warning 并非所有不支持 MSE 的安卓端浏览器都无法播放 FLV 格式。有些浏览器可能已经劫持了播放流程，并且浏览器自带的播放器也可能支持 FLV 格式播放，只是这部分无法通过代码进行探测。因此，在移动端需要播放 FLV 格式的流时，可以先判断浏览器是否支持 MSE，并根据判断结果选择使用 FLV 格式还是 HLS 格式的流地址。但需要注意，由于无法通过代码进行探测，我们无法提供一种通用的方法来判断浏览器是否支持播放 FLV 格式。 ::: 判断浏览器是否支持播放 FLV 直播流，以及根据判断结果配置不同的播放地址的代码示例如下所示。针对不支持播放 FLV 的播放器，您可以配置 HLS 流地址，代码示例如下所示。 ```mixin-react return ( ); ``` ## RTM 拉流 ### 背景信息 VePlayer 支持 RTM 协议拉流，详细的 RTM 特性协议介绍请参见[超低延时直播](https://www.volcengine.com/docs/6469/101042)。 RTM 拉流播放需满足直播流中不含 B 帧且音频格式为 Opus，通常情况下直播流不满足此播放条件，需提前对直播流添加转码配置（本章节示例中以 \_webrtm 转码后缀为例）。 HLS 和 FLV 协议拉流时不支持音频格式为 Opus，故在 RTM 拉流降级的适配上存在常见的几种情况在下文分别向您介绍。 ### 注意事项 RTM 内部降级仅支持配置单一降级地址，且会根据拉流报错自动触发内部降级。如果内部降级无法满足您的需求，您需要关闭内部降级（即在 RTM 中配置 `enableFallback: false`），并参考以下场景示例自定义降级。 ### 场景一：单地址拉流单地址 RTM 拉流时，支持使用播放器提供的 RTM 内部降级，同时您可以自行实现**区分错误码降级**和**按顺序降级**，示例代码参考下文。 #### RTM 内部降级 VePlayer 的 RTM 拉流配置默认开启了内部降级（enableFallback: true），并需要设置一个降级地址（fallbackUrl）。当 RTM 拉流出现浏览器不支持播放 RTM 、RTM 拉流请求失败或建联失败和播放过程中报错时会触发内部降级。 :::tip - 使用 RTM 内部降级时， fallbackUrl 必须传入一个音频非 Opus 的 HLS 或 FLV 拉流地址作为降级地址。PC 和 Android 端可降级到 FLV 或 HLS 拉流地址，iOS 端可降级到 HLS 拉流地址，您可以自行根据客户端类型判断并设置 fallbackUrl。 - RTM 协议拉流时如果发生内部降级，因降级后拉流协议不同，后续切换直播间时需重新创建 RTM 播放器。 ::: 使用 RTM 内部降级并配置降级地址为 HLS 拉流地址示例如下： ```mixin-react return ( ); ``` #### 区分错误码降级 RTM 内部降级不支持区分错误码降级，如需根据不同错误实现降级，需要关闭内部降级，并参考以下示例代码集成。 ```mixin-react return ( ); ``` #### 按顺序降级 RTM 内部降级仅支持从 RTM 降级到 FLV 或者 HLS, 如果您需要其他的降级顺序，比如 FLV、RTM、HLS, 请关闭内部降级并参考以下示例代码集成。 ```mixin-react return ( ); ``` ### 场景二：多清晰度或多线路拉流使用 RTM 多清晰度或多线路拉流时，不支持内部降级，需要关闭内部降级并参考以下代码示例集成。本场景集成示例以多清晰度 RTM 拉流为例进行介绍。 #### 区分错误码降级使用 RTM 多清晰度或多线路拉流时，不支持内部降级，如需区分错误码降级，请参考以下示例代码集成。 ```mixin-react return ( ); ``` #### 按顺序降级 RTM 内部降级仅支持从 RTM 降级到 FLV 或者 HLS, 如果您需要其他的降级顺序，比如 FLV、RTM、HLS, 请关闭内部降级并参考以下示例代码集成。 ```mixin-react return ( ); ``` ## LL-HLS 拉流 VePlayer 支持低延时 HLS 拉流。 :::tip Android 端使用 VePlayer 播放低延迟 HLS 直播流时需要开启 Media Source Extensions API。 ::: ```mixin-react return ( ); ``` ## 主备流降级 VePlayer 支持同时设置多个拉流地址，实现主备流降级。您可通过设置拉流失败时循环拉流的最大次数 `maxFallbackRound` 和备流地址 `fallbackUrls`，开启主流异常降级；主拉流地址异常后，播放器将自动切换为 `fallbackUrls` 中配置的备用拉流地址。 :::tip VePlayer 主备流降级仅支持相同格式的拉流降级。 ::: - 设置单一播放地址时，代码示例如下所示。 ```mixin-react return ( ); ``` - 设置多清晰度时，代码示例如下所示。 ```mixin-react return ( ); ``` ## 自动播放自动播放是指在用户没有主动交互（如鼠标点击、手指触摸）的情况下，通过 autoplay 配置、JavaScript 代码调用 play() 方法，或者定时器、Promise 回调、事件监听等方式，在页面加载完成后自动启动视频播放的功能。这种功能允许视频在页面加载后立即开始播放，而无需用户手动点击播放按钮。 :::tip 由于浏览器策略的限制，自动播放并非总能成功。浏览器从用户角度考虑，认为网页或应用程序没有警告自动发出噪音可能会令人讨厌、不便或令人反感，因此通常仅允许在特定情况下进行自动播放。 ::: ### 自动播放的配置和条件 VePlayer 提供 `autoplay` 配置可实现自动播放和静音自动播放，详细请参见 [播放器配置](https://www.volcengine.com/docs/6469/1155423#liveveplayeroptions)。但是自动播放能否成功，在不同浏览器环境中还需要满足以下条件。 #### 浏览器自动播放根据最新的浏览器策略，允许自动播放至少需要满足以下任意条件，具体请参见 [Google Chrome](https://www.chromium.org/audio-video/autoplay/) 和 [WebKit](https://webkit.org/blog/7734/auto-play-policy-changes-for-macos/) 的自动播放策略。 - 音频被静音或其音量设置为 0。 - 以下条件允许自动播放： - 用户和网页已有交互行为（包括点击、触摸、按下某个键等等）。 :::warning 交互行为的回调中执行 `play()` 的上下文中必须能跟踪到真实的用户交互行为，伪造的用户交互行为不被接受。 ::: - 网站已被列入白名单，如果浏览器确定用户经常与媒体互动，就会被列入允许自动播放的白名单，有时也支持用户自行设置。 - Chrome 通过 Media Engagement Index (MEI) 自动对网站是否允许自动播放进行评分。 - Safari 通过**偏好设置 > 网站 > 自动播放**或**地址栏右键**对该网站设置是否允许自动播放。 - 顶部框架可以将自动播放权限委派给其 iframe，以允许自动播放声音。 #### WebView WebView 默认禁止有声音的自动播放，您可以选择**自动静音播放**，示例代码如下： ```javascript VePlayer.createLivePlayer({ // 默认 muted 为 true autoplay: { muted: true } }).then(function(veplayer) { }); ``` 如果是在业务方可控的 WebView 上运行网站应用，还需开启 WebView 自动播放相关配置以实现自动播放，配置示例如下： - **Android** Android 设置 [setMediaPlaybackRequiresUserGesture](https://developer.android.com/reference/android/webkit/WebSettings.html#setMediaPlaybackRequiresUserGesture(boolean)) 设置为 false，示例代码如下： ```java myWebView.getSettings().setMediaPlaybackRequiresUserGesture(false); ``` - **iOS** WKWebView 设置 [mediaTypesRequiringUserActionForPlayback](https://developer.apple.com/documentation/webkit/wkwebviewconfiguration/1851524-mediatypesrequiringuseractionfor) 设置为 NO，示例代码如下： ```objectivec [self.webvie mediaTypesRequiringUserActionForPlayback:NO]; ``` :::tip iOS 端低电模式下，即使添加上 WebView 自动播放参数、或者是默认静音也都无法自动播放，因为播放视频被系统认定为耗能行为。 ::: - **iOS 端微信内置 WebView** :::tip 由于[安卓微信 WebView 的自动播放策略调整](https://developers.weixin.qq.com/community/develop/doc/000e640d77cfa001132a6cb8456c01)，在安卓微信下，禁止任何方式的 m3u8 和 FLV 文件自动播放。 ::: ```html 火山引擎VePlayer

``` ### 判断自动播放是否成功您可以通过以下方式判断自动播放是否成功。 #### 通过 API 返回结果判断通过 JavaScript 代码调用 `play()` 方法实现自动播放不一定能成功。通常来说可以根据 `play()` 返回的 Promise 操作结果来判断是否成功： - 成功时会返回状态为 `resolve` 的 Promise 结果。 - 失败时则返回携有 `NotAllowedError` 错误且状态为 `rejected` 的 Promise 结果。示例代码如下： ```javascript let startPlayPromise = veplayer.play(); if (startPlayPromise !== undefined) { startPlayPromise.catch(error => { if (error.name === "NotAllowedError") { // TODO Do something when not autoplay success } else { // Handle a load or playback error } }).then(() => { // Start whatever you need to do only after playback has begun. }); } ``` #### 通过监听自动播放失败事件您可以监听 Web 点播 SDK 的 `AUTOPLAY_PREVENTED` （自动播放失败）事件来判断自动播放是否被阻止。示例代码如下： ```javascript VePlayer.createLivePlayer({ autoplay: { muted: false } }).then(function(veplayer) { veplayer.on(VePlayer.live.Events.AUTOPLAY_PREVENTED, () => { // TODO something console.log('自动播放被阻止'); }); }) }); ``` ## 事件监听直播播放器创建成功后，您可调用 `on`、`once` 方法设置事件监听，支持的事件及其说明可查看[事件](https://www.volcengine.com/docs/6469/1158676)。 ```mixin-react return ( ); ``` ## 报错监听直播播放器创建成功后，您可监听报错事件，针对不同的错误码区分处理，所有的错误码及说明可查看[错误码](https://www.volcengine.com/docs/6469/1158675)。 ```mixin-react return ( ); ``` ## DRM 加密流播放 Web 拉流 SDK 支持 DRM 加密流播放。 :::tip 当前仅支持在使用 Safari 浏览器的 PC 端和支持 Safari 或 Chrome 浏览器的 iOS 端使用 Web 拉流 SDK 播放 DRM 加密流。 ::: 1. 参考[最佳实践- 直播 DRM 加密](https://www.volcengine.com/docs/6469/1219836)获取以下信息： - 获取 M3U8 格式的 DRM 加密流播放地址； - 获取 DRM 授权许可文件； - 获取 FairPlay 证书文件。 2. 创建播放器并传入以上获取的信息，代码示例如下所示。 ```mixin-react return ( { 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); }); }); `} /> { 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` 方法切换线路或清晰度。 :::tip - 当使用多线路或者多清晰度时，不支持 `url` 的配置。 - 使用 RTM 拉流地址进行多线路多清晰度拉流配置时，不支持开启 RTM 播放降级，即您需要在 RTM 配置中设置 `rtm: {enableFallback: false}` 。 ::: - 设置多线路时，代码示例如下所示。 ```mixin-react return ( ); ``` - 设置多清晰度时，代码示例如下所示。 ```mixin-react return ( ); ``` - 设置多线路和多清晰度时，代码示例如下所示。 ```mixin-react return ( ); ``` ## 视频过期处理如果您的拉流域名开启了 [URL 鉴权](https://www.volcengine.com/docs/6469/1274178)，则生成的拉流地址超过过期时间就会失效，可能导致观众看不到直播内容。为了保持不间断拉流，请获取新的拉流地址，并调用播放器的 `switch` 方法更新拉流地址，代码示例如下所示。 ```mixin-react return ( ); ``` ## 清晰度降级您可以通过设置清晰度自动降级参数 [`definition.needFallback`](https://www.volcengine.com/docs/6469/1155423#definitionconfig)，开启清晰度降级提示。在播放等待超时后，播放器会提示观众是否需要降级到更低的清晰度。 1. 进入控制台配置多个转码模版，操作方法可参考[转码配置](https://www.volcengine.com/docs/6469/78331)文档。 2. 使用视频直播控制台的[地址生成器](https://console.volcengine.com/live/main/locationGenerate)，选择不同的转码模版，生成不同清晰度的播放地址。 ![alt](https://portal.volccdn.com/obj/volcfe/cloud-universal-doc/upload_b3824211e62a2de79dded651a0fdb367.png =500x) 3. 创建 VePlayer 对象实例，在 `playlist` 中传入所有清晰度地址，代码示例如下所示。 ```mixin-react return ( ); ``` ## 直播时移 1. 参考[时移配置说明](https://www.volcengine.com/docs/6469/101056)在直播控制台中配置时移。 2. 拼接直播时移播放地址，拼接规则为 `{PullDomain}/{AppName}/{StreamName}.m3u8?{鉴权参数}`，详细参数说明请参见[拼接直播时移播放地址](https://www.volcengine.com/docs/6469/101056#拼接直播时移播放地址)， 3. 在播放器中传入拼接好的相对时移地址。 :::tip - 直播时移的参数配置详情，请参考[接口说明](https://www.volcengine.com/docs/6469/1155423#timeshiftconfig)。 - `liveStartTime` 需使用浏览器本地时间。 ::: 4. 引入直播时移插件，代码示例如下所示。 ```mixin-react return ( `} /> ); ``` 5. 将直播时移插件作为配置传入播放器中，并配置时移相关参数，代码示例如下所示。 ```mixin-react return ( ); ``` ## 日志上报 1. 登录[视频直播控制台](https://console.volcengine.com/live/main/sdk)的应用管理页面，查看已创建 Web 应用的 AppID。 2. 在 `logger` 中传入 `appId`，开启日志上报，代码示例如下。 :::warning - AppID 是您的 Web 应用标识，正确配置 AppID 可有助于您 Web 应用质量日志的数据上报、集中管理和可视化查询。 - 从 2.5.1 版本开始，未配置 AppID 时，会在 Web 开发者工具的控制台（Console）中进行报错提示，并使用默认 AppID 进行日志上报。 ::: :::tip - 强烈建议您传入与业务相关的用户 ID `userId` 和用户设备 ID `deviceId`。异常情况下需提供用户 ID 快速排查问题。 - 如果不传入 `userId` 和 `deviceId`，VePlayer 将根据用户浏览器随机生成，该值会在浏览器端缓存。 - 直播过程中，如果出现播放异常，您可以[创建工单](https://console.volcengine.com/workorder/create?step=2&SubProductID=P00000076)联系技术支持，定位并排查问题。 ::: ```mixin-react return ( ); ``` ## SEI 监听在播放器创建完成后，您可以设置 SEI 补充增强信息监听，代码示例如下所示。 ```mixin-react return ( ); ``` 当解析到视频 SEI 消息时，播放器将触发监听，监听的数据如下所示。 ```javascript 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，不存在则为空字符串 } } ```