在接入 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 ( ); ``` ## 事件监听直播播放器创建成功后，您可调用 `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，不存在则为空字符串 } } ```