Web 拉流 SDK (VePlayer)的接入步骤包括:引入依赖、添加播放器容器、播放器实例化和接入其他功能。您可参考本文档,在网页上添加一个视频播放器。
适用版本
本文档适用于 2.0.0 及以上版本的 Web 拉流 SDK,其他版本请参考历史文档。
前提条件
- 创建 SDK 应用,获取 License 文件、License URL 和 App ID。详见获取 SDK License。
注意
- 自 2.11.2 版本开始,您必须通过 License 管理 Web 拉流 SDK 及其增值服务的使用权限和时间。
- 试用版 License 仅用于项目测试,不支持续签。过期的试用版 License 会导致鉴权失败,进而中断服务。请在项目上线前升级为正式版 License。详见升级试用版 License 为基础版或高级版 License。
- 更多有关 License 类型的信息,详见Web 拉流 SDK。
- 如果您使用火山引擎的 CDN,请先完成以下操作。
步骤一:引入依赖
通过以下任一方式引入依赖。
在本地工程的 index.html 文件中添加以下代码,引入以下播放器的 CSS 样式文件和 JavaScript 脚本文件。
<link rel="stylesheet" href="https://lf-unpkg.volccdn.com/obj/vcloudfe/sdk/@volcengine/veplayer/2.11.2/umd/veplayer.production.css">
<script src="https://lf-unpkg.volccdn.com/obj/vcloudfe/sdk/@volcengine/veplayer/2.11.2/umd/veplayer.production.js"></script>
执行以下命令,安装播放器依赖包和播放器插件依赖包。
npm install @volcengine/veplayer@next
npm install @volcengine/veplayer-plugin@next
在本地工程的 index.html 文件中添加以下代码,引入播放器依赖包及依赖包样式。
import { createLivePlayer, register } from '@volcengine/veplayer';
import '@volcengine/veplayer/style';
按需引入并注册插件。代码示例如下所示。
// 播放 HLS 流。
import { hlsjs } from '@volcengine/veplayer-plugin';
register([hlsjs]);
// 播放 FLV 流。
import { flv } from '@volcengine/veplayer-plugin';
register([flv]);
// 播放 RTM 流。
import { rtm } from '@volcengine/veplayer-plugin';
register([rtm]);
// 播放多种协议的流。
import { flv, hlsjs, rtm } from '@volcengine/veplayer-plugin';
register([rtm, flv, hlsjs]);
如需减少包体积,您可以通过插件路径按需引入某个插件。例如,将 import { hlsjs } from '@volcengine/veplayer-plugin'; 替换为 import * as hlsjs from '@volcengine/veplayer-plugin/hlsjs'; 从而引入 hlsjs 插件。同样,您也可以按需引入以下插件:flv、rtm、abr、drm 和 timeshift。
步骤二:添加播放器容器
在需要展示播放器的页面添加播放器容器,例如,在 index.html 中加入以下代码。
<div id="veplayer"></div>
步骤三:配置 License
注意
- 自 2.11.2 版本起,您必须按以下操作配置 License,才可使用 Web 拉流 SDK。
- 请确保您计划嵌入播放器的页面的域名与您 SDK 应用配置的泛域名相匹配。否则,License 校验将失败。例如,如果您配置的泛域名为
*.example.com,则您页面的域名必须是该泛域名的一级子域名,例如 a.example.com。
License 校验采用页面级校验机制,即使在单页面多实例场景下,您也只需进行一次设置,多实例可共享同一配置。此外,为优化播放体验,建议在初始化播放器前配置 License,以提升首帧加载速度,确保流畅播放。
通过以下任一方式配置 License。
调用 setLicenseConfig 并设置以下参数,配置 License:
sign:对应 License 文件中的 Signature 字段,用于鉴权。content:对应 License 文件中的 Content 字段,包含该 License 的权限等级、版本信息等。mainUrl:(非必填,推荐设置)License URL,对应 License 文件中的 MainUrl 字段。若您设置该字段,则 License 升级或续签后,SDK 会自动更新至最新 License 版本,无需您手动更新。有关如何获取 License URL,详见步骤二:获取 License 文件。
示例代码如下:
CDN
VePlayer.live.setLicenseConfig({
license: {
sign: "xxx",
content: "xxx",
mainUrl: "https://example.com/obj/license/license.lic",
}
})
NPM
import { live } from '@volcengine/veplayer';
live.setLicenseConfig({
license: {
sign: "xxx",
content: "xxx",
mainUrl: "https://example.com/obj/license/license.lic",
}
})
调用 setLicenseConfig 并设置 license 参数,传入 License URL。有关如何获取 License URL,详见步骤二:获取 License 文件。
SDK 会自动处理鉴权逻辑,并开启自动 License 更新。示例代码如下所示。
CDN
VePlayer.setLicenseConfig({
// License URL。License 升级或续签后,SDK 会自动更新至最新 License 版本,无需您手动更新。
license: "https://example.com/obj/license/license.lic"
})
NPM
import { live } from '@volcengine/veplayer';
live.setLicenseConfig({
// License URL。License 升级或续签后,SDK 会自动更新至最新 License 版本,无需您手动更新。
license: "https://example.com/obj/license/license.lic"
})
说明
初始化播放器后,播放器界面若无 License 相关错误提示,且可以正常播放视频,则表示 License 校验成功。
步骤四:创建 VePlayer 实例并开启日志上报
通过以下代码,创建 VePlayer 实例并开启日志上报。页面加载后,即可播放音视频资源。在直播场景下,您可通过传入拉流地址,拉取直播流进行播放。
VePlayer.createLivePlayer({
width: 640,
height: 360,
url: 'https://livepull.example.com/appname/streamname.flv',
logger:{
// 开启日志上报。开启后,SDK 会将播放相关信息发送至视频直播服务器,用于故障排查和分析,帮助提升应用的稳定性和用户体验。
appId: 'APP_ID', // 必选。将 APP_ID 替换为您创建 Web 类型应用后获得的 AppID。
userId: 'USER_ID', // 可选。将 USER_ID 替换为应用中的用户 ID。
deviceId: 'DEVICE_ID', // 可选。将 DEVICE_ID 替换为用户设备的 ID。
}
}).then(function(veplayer){
console.log('创建播放器成功,播放器实例为', veplayer)
}).catch(function(err){
console.log('创建播放器失败,失败报错为', err)
});
createLivePlayer({
width: 640,
height: 360,
url: 'https://livepull.example.com/appname/streamname.flv',
logger:{
// 开启日志上报。开启后,SDK 会将播放相关信息发送至视频直播服务器,用于故障排查和分析,帮助提升应用的稳定性和用户体验。
appId: 'APP_ID', // 必选。将 APP_ID 替换为您创建 Web 类型应用后获得的 AppID。
userId: 'USER_ID', // 可选。将 USER_ID 替换为应用中的用户 ID。
deviceId: 'DEVICE_ID', // 可选。将 DEVICE_ID 替换为用户设备的 ID。
}
}).then(function(veplayer){
console.log('创建播放器成功,播放器实例为', veplayer)
}).catch(function(err){
console.log('创建播放器失败,失败报错为', err)
});
如果在直播过程中出现播放异常,请收集异常发生时间、用户 ID 等信息,并通过创建工单,联系火山引擎技术支持进行问题定位。
说明
- 从 2.5.1 版本开始,未配置 AppID 时,控制台会报错提示,并使用默认 AppID 上报日志。
- 强烈建议传入
userId 和 deviceId。这有助于在出现播放异常时,快速定位和排查问题。如果不传入,SDK 会根据用户浏览器随机生成并在本地缓存。
后续步骤
Web 拉流 SDK 支持封面设置、画中画、预览缩略图等功能,同时结合直播场景,提供了清晰度自动降级、RTM 拉流播放等高级功能,接入方法详见功能集成文档。
Web 拉流 SDK 针对多种播放场景,提供了丰富的功能,您可在线体验视频云播放器,全面了解功能效果和接入方法。