VePlayer 中的功能,无论是简单的按钮,还是复杂的播放逻辑,均以插件的形式实现。这种插件化的设计可以提高代码的可维护性和灵活性。VePlayer 内置了一些常用的功能插件,同时也提供业务功能插件。对于内置插件,您可以获取插件实例、禁用插件或配置插件;对于业务功能插件,您需要自行注册并进行相应的配置。
本文详细介绍插件的功能和使用方法。
调用 getPlugin
并传入插件名称,即可获取插件实例。获取插件实例后,您可再调用插件的 API。示例代码如下:
const playerSdkIns = new VePlayer({ ... }) // 获取 pip 插件实例 const pipInstance = playerSdkIns.player.getPlugin('pip') // const pipInstance = playerSdkIns.player.plugins.pip // 调用 pip 插件的 API 切换画中画 pipInstance.switchPIP()
对于业务功能插件,您需要在初始化 VePlayer 实例时,设置 plugins
参数并传入插件名称注册插件。内置插件无需注册。示例代码如下:
import DemoPlugin from 'demoplugin' const playerSdkIns = new VePlayer({ ..., plugins: [DemoPlugin], })
您也可以在初始化完成之后调用 registerPlugin
注册插件。
import DemoPlugin from 'demoplugin' const playerSdkIns = new VePlayer({ ... }) playerSdkIns.player.registerPlugin(DemoPlugin)
对于内置插件,如需禁用,可采用以下方式:
在初始化 VePlayer 实例时,设置 ignores
参数,传入插件名称(不区分大小写),即可禁用指定插件。以禁用倍速调节插件和画中画插件为例:
ignores: ['playbackRate', 'pip']
对于部分插件,您也可以通过插件的配置项实现禁用。详见含 UI 的内置插件。
VePlayer 支持传入各个插件名称,配置插件的具体逻辑。例如配置播放进度条插件:
progress: { isDragingSeek: true, // 是否在拖拽的过程中更新 currentTime closeMoveSeek: true, // 是否关闭滑块 seek 能力 }
VePlayer 内置了一些功能插件,不需要您额外引入,默认显示或者在特定条件下显示。
插件名称(不区分大小写) | 说明 | 是否默认显示 | 禁用/不显示配置 |
---|---|---|---|
controls | 控制栏插件 | 是 |
|
progress | 播放进度条插件 | 是 |
|
fullscreen | 位于控制栏的全屏切换插件,用于将当前视频全屏切换。全屏插件默认调用系统全屏。 | 是 |
|
playbackRate | PC 端倍速调节插件 | 是 | |
PlaybackRateMobilePlugin | H5 端倍速调节插件 | 是 | |
volume | 音量调节插件 | 是 |
|
sdkDefinitionPlugin | 清晰度切换插件 | 仅配置了多个清晰度时显示 |
|
definitionMobilePlugin | H5 端清晰度切换插件 | 仅配置了多个清晰度时显示 | |
time | 控制栏播放时间、时长显示插件 | 是 |
|
poster | 播放器首帧预览图插件 | 仅配置了图片地址时才生效 | 不配置图片地址 |
start | 播放器中间切换暂停/播放的按钮 | 是 |
|
enter | 首次初始化播放器的时候,初始化过程中显示的加载按钮 | 是 | |
pip | 是否使用画中画插件 | 是 |
|
sdkToastPlugin | 信息提示插件 | 仅在切换清晰度、记忆播放时显示提醒信息 | |
sdkUnmutePlugin | 取消静音插件 | 仅设置了静音起播时生效
| |
sdkErrorPlugin | 错误信息显示插件 | 仅发生阻碍播放的严重错误时才显示,会展示错误信息,并提供重试功能 | |
DanmuPlugin | 弹幕插件 | 仅配置了 | |
progresspreview | PC 端进度条预览插件 | 仅配置了才显示 | |
MenuPlugin | 右键菜单插件 | 仅配置了才显示
| |
miniprogress | 是否启用迷你进度条 | 否 |
|
screenShot | 是否使用截图按钮快捷方式 | 否 |
|
rotate | 是否使用旋转按钮插件 | 否 |
|
download | 是否使用下载按钮插件 | 否 |
|
miniscreen | 进入小窗按钮插件 | 否 |
|
dynamicbg | 动态背景高斯模糊渲染插件 | 仅配置了生效
|
|
插件配置项 position
可用于指定 UI 插件的 DOM 挂载位置。以下为定义的位置:
默认布局
flex 布局
说明
position
,也没有指定 root
参数,插件默认挂载在根节点 root 下。Controls 插件配置项 mode 可用于指定控制栏布局方式。以下为三种布局方式的效果图:
normal
flex
bottom
插件配置项 index
是一个数字,用于指定 UI 插件在父节点上插入的位置,数字越小,越靠前。如果 index
相同,则按照注册顺序插入。index
可以通过配置覆盖来达到调整插件顺序的目的。
插件名称(不区分大小写) | 说明 | 是否启用 |
---|---|---|
keyboard | PC 端快捷键插件 | 仅 PC 端启用 |
mobile | 播放器在移动 Web 端交互插件 | 仅 H5 端启用 |
pc | 播放器在移动 PC 端交互插件 | 仅 PC 端启用 |
HlsPlayer | HLS 播放插件 | 仅播放非加密 HLS 格式时启用 |
FLVPlayer | FLV 播放插件 | 仅播放 FLV 格式时启用 |
EncryptHlsPlugin | HLS 加密播放插件 | 仅播放加密 HLS 格式时启用 |
DashPlugin | DASH 播放插件 | 仅播放 DASH 格式时启用 |
Mp4EncryptPlayer | MP4 加密插件,同时用来支持 MP4 格式的 MSE 播放模式 | 仅播放加密 MP4 格式或启用 MP4 格式的 MSE 播放模式时启用 |
xgVodLogger | 质量日志上报插件 | 仅配置了 |
VePlayer 提供的业务功能插件,需要您自行引入 plugins
配置项才可使用。
VePlayer 支持 WebVTT (Web Video Text Tracks) 格式的字幕文件。您需要在实例化播放器时通过 plugins
参数注册外挂字幕插件,再通过 Subtitle
参数设置字幕列表。外挂字幕的配置参数介绍详见 ISubtitleConfig。示例代码如下:
const playerSdk = new VePlayer({ id: 'mse', url: "https://xx.mp4", width: 600, height: 400, // 注册外挂字幕插件 plugins: [VePlayer.Subtitle], // 配置外挂字幕插件 Subtitle: { isDefaultOpen: true, list: [ { "url": "https://字幕1.vtt", "text": "中英", "isDefault": true }, { "url": "https://字幕2.vtt", "text": "中日", "isDefault": false } ] }, });
VePlayer 支持记忆播放功能,可以在您上次观看视频离开后的时间点继续播放。您需要在实例化播放器时通过 plugins
参数注册记忆播放插件,再传入 MemoryPlay
配置项,为视频配置唯一的 memoryId
。记忆播放的配置参数介绍详见 IMemoryPlayConfig。示例代码如下:
const playerSdk = new VePlayer({ id: 'mse', url: "https://xx.mp4", width: 600, height: 400, // 注册记忆播放插件 plugins: [VePlayer.MemoryPlay], // 配置记忆播放插件 MemoryPlay: { memoryId: 'example_memory_id' }, });
播放器默认使用浏览器的 localStorage API 存储播放时间,即默认情况下不能实现跨端跨平台共享存储记忆的播放时间点。如果您需要通过服务共享播放时间点,实现方式如下:
getTime
和 saveTime
两个函数。getTime
要求入参为 memoryId
,返回为时间的同步或异步函数。saveTime
要求入参数可接受 memoryId
和时间的函数。示例代码如下:
const playerSdk = new VePlayer({ id: 'mse', url: "https://xx.mp4", width: 600, height: 400, plugins: [VePlayer.MemoryPlay], MemoryPlay: { memoryId: 'example_memory_id', getTime: async (id) => { // ...异步处理 // const time = await getTimeApi(id); return time; }, saveTime: async (id, time) => { // 调用接口存储时间 } }, });
在页面被隐藏、播放器被销毁或者页面卸载时,VePlayer 会存储播放时间点。
注意
页面卸载时,如果传入的 saveTime
为异步函数,函数中的接口不一定能执行完成。
VePlayer 支持水平方向的视频镜像。您需要在实例化播放器时通过 plugins
参数注册视频镜像插件,即可实现镜像功能。示例代码如下:
const playerSdk = new VePlayer({ id: 'mse', url: "https://xx.mp4", height: 400, // 注册视频镜像插件 plugins: [VePlayer.MirrorPlugin], });
VePlayer 支持播放列表,即在给定一个视频列表后,按顺序自动播放列表中的视频。VePlayer 提供播放列表相关的 UI 以及“打开/隐藏播放列表”和“播放下一个视频”两个按钮。具体效果如下:
如需使用播放列表功能,您可在初始化播放器实例时设置 plugins
参数注册播放列表插件实例,再通过 playListPlugin
参数对播放列表功能进行初始化配置。播放列表配置项详见 IPlayListConfig。示例代码如下:
const playerSdkIns = new VePlayer({ id: 'video', width: 800, height: 600, // 注册播放列表插件 plugins: [VePlayer.PlayListPlugin], // 配置播放列表插件 playListPlugin: { list: [ { url: 'xx.demo.com/1.mp4', poster: 'xx.demo.com/1.jpg', vid: '67ghsadd8a78s9df8', title: 'Remember to bring a little simple everyday', }, { playAuthToken: 'demovideoplayAuthToken', poster: 'xx.demo.com/2.jpg', vid: '67ghsadd8a78s213df8', title: 'The night came quietly, with the heat and light', }, { url: 'xx.demo.com/3.mp4', poster: 'xx.demo.com/3.jpg', vid: '67ghsaddhh78s9df8', title: 'Watching a beautiful fireworks at night will make you feel good', }, { url: 'xx.demo.com/4.mp4', poster: 'xx.demo.com/4.jpg', vid: '67ghiodd8a78s9df8', title: 'Gentle and lazy sea breeze', }, ], }, });
此外,播放列表插件提供 API 和事件。
下表列出播放列表插件支持的 API。
API 名称 | 类型 | 参数说明 | 返回值 | 描述 |
---|---|---|---|---|
next |
| 无 | 无 | 播放下一个视频。如果当前正在播放最后一个视频,则跳转至第一个视频。 |
prev |
| 无 | 无 | 播放上一个视频,如果当前正在播放第一个视频,则跳转至最后一个视频。 |
changeList |
| 播放列表数组 | 无 | 更新播放列表。 |
setIndex |
| 待播放视频的序号 | 无 | 播放指定视频。 |
您可先调用 getPlugin
获取播放列表插件实例,再调用 API。以下示例展示了如何播放列表中的下一个视频:
// 播放下一个视频 playerSdkIns.getPlugin('playListPlugin').next();
下表列出播放列表插件支持的事件。
事件枚举值 | 参数 | 描述 |
---|---|---|
play_list_change |
| 播放列表更新。 |
play_list_item_change |
| 播放项变更。 |
以下示例展示了如何监听播放项变更:
playerSdkIns.on('play_list_item_change', data => console.log('play_list_item_change, current item: ', data), );
VePlayer 支持动态水印,可将自定义的文案动态地覆盖在播放器上,以便在版权视频发生录屏等泄漏时根据添加的水印追踪泄漏源。您需要在实例化播放器时通过 plugins
参数注册动态水印插件,再通过 dynamicwatermark
配置动态水印。动态水印配置参数介绍详见 IWatermarkConfig。示例代码如下:
var playerSdk = new VePlayer({ id: 'mse', url: "https://voddemo-play.volcvod.com/dem0.mp4", width: 640, height: 360, codec: 'h264', // 注册动态水印插件 plugins: [ VePlayer.DynamicWatermarkPlugin ], // 配置动态水印插件 dynamicwatermark: { enable: true, //【必填】 true-打开,false-关闭,默认值为false content: '火山引擎播放SDK', // 【必填】水印文案,String 类型,一行展示不折行,默认值为空 // 以下参数为可选项 // displayType: 1, // 水印展示形式,Number类型,0-固定位置,1-全屏滚动(播放容器),2-随机闪烁,默认值为1 // opacity: 0.3, // 不透明度,Number类型,设置范围:[0~1]。默认值 0.3 // tickerSpeed: 'MODERATE',// 移动/闪烁速度,String类型,"MODERATE"-适中, "FAST"-较快, "SLOW"-较慢,displayType为0时不设置tickerSpeed则不闪烁 // fontSize: 12,// 水印字体大小,Number或String类型,单位为px,String类型需携带单位,默认值12 // fontColor: '#FFFFFF',// 水印颜色,String类型,默认值为"#FFFFFF" // top: undefined, // 水印相对于播放容器顶部起始位置,Number类型,单位为px,默认值0 // left: undefined, // 水印相对于播放容器左边起始位置,Number类型,单位为px,默认值0 // right: undefined, // 水印相对于播放容器右边起始位置,Number类型,单位为px // bottom: undefined, // 水印相对于播放容器底部起始位置,Number类型,单位为px }, vodLogOpts: { vtype: 'MP4', tag: '普通视频', line_app_id: 348293, line_user_id: 'veplayer_web_demo' } });
动态水印效果如下:
VePlayer 支持在播放具备多个码率清晰度的视频时,根据网络带宽的变化自动切换到适合当前带宽的低码率清晰度的视频,以减少卡顿现象,提高播放体验。
在实现清晰度降级功能之前,你需要先了解一下卡顿和长时间卡顿的概念。
卡顿指视频无法继续播放,需要等待相关流程进行。这些流程包括:
卡顿开始以 WAITING
事件触发为准,触发 PLAYING
事件后表示播放恢复。可参考以下示例代码监听这些事件:
说明
WAITING
事件触发后,如果在 200 毫秒内播放未恢复,播放器会展示 loading 的 UI 状态。
veplayer.on(VePlayer.Events.WAITING, () => { console.log('开始卡顿') veplayer.once(VePlayer.Events.PLAYING, () => { console.log('卡顿结束') }) })
长时间卡顿是指因为网络状况不佳或视频码率过高,持续时间(从 WAITING
事件触发开始计时)过长的卡顿。默认情况下,播放器会将持续时间超过 5 秒视为一次长时间卡顿。您可通过 longWaitingTime
参数自定义修改持续时间的阈值。发生长时间卡顿时,播放器会触发清晰度降级逻辑,根据用户选择的清晰度档位,要么自动降级为低码率视频,要么提醒用户切换为低码率视频。可参考以下示例代码监听长时间卡顿事件:
// 长时间卡顿事件。播放器会在此事件触发时提醒降级或者自动降级。 veplayer.on(VePlayer.Events.LONG_WAITING, () => console.log('发生了长时间卡顿'))
实现清晰度降级功能,您需要在实例化播放器时通过 plugins
参数注册清晰度降级插件,再通过 DefinitionDemotePlugin
参数配置清晰度降级功能。清晰度降级的配置参数介绍详见 IDefinitionDemotePlugin。此外,你还需要将某一个清晰度档位设为自动档位。当用户选择不同档位时,播放器会触发不同的清晰度降级逻辑。具体说明如下:
isNeedAutoDemote
参数设为 true
开启自动降级。demotePriority
参数配置清晰度降级的顺序。如果已经降级到最低清晰度,则不再降级。注意
在网络恢复后,播放器不会自动切换回高码率视频播放。
不同的播放模式下,清晰度降级的示例代码如下:
在 playlist
中将自动档位的 definition
标记为auto
,再通过mapDefinition
设置实际映射的清晰度。
var veplayer = new VePlayer({ id: 'mse', url: "//demo.video.com/1.mp4", width: 640, height: 360, // 注册清晰度降级插件 plugins: [VePlayer.DefinitionDemotePlugin], // 配置清晰度降级插件 DefinitionDemotePlugin:{ // 配置清晰度降级的顺序 demotePriority: ['uhd', 'hd', 'ld'] }, // 指定默认档位,需要将 url 设置为 playList 中对应档位的 url url: 'https://voddemo-play.volcvod.com/10501b001bdd43ae89d7c0fc3d6792b5/main.m3u8?a=0&auth_key=1773925042-f0489f7ac9a14d92b96bbfb7b39a7a0d-0-4e57d65b22e9aefe63ba1c519218e9fe&br=966&bt=966&cd=0%7C0%7C0&ch=0&cr=0&cs=0&cv=1&dr=0&ds=4&er=0&l=2023032020544973DCCFE21CF4C02E38B1&lr=&mime_type=video_mp4&net=0&pl=0&qs=0&rc=amg6c2o0aTg6ZTQzNGRnM0ApOmZkZzg1PGVoNzhkOzxlZ2dfZy9gMHFrYTBgLS1kYy9zcy00L2JfL19eYF42Ly0vYi06Yw%3D%3D&vl=&vr=', playList: [ { streamType: 'hls', definition: 'ld', definitionTextKey: 'LD', // 清晰度多语言 key url: 'https://voddemo-play.volcvod.com/1f7e669aa403420f95d00ca7d95d1795/main.m3u8?a=0&auth_key=1773925042-b375d2f0822f4022ad39e153c3e55f58-0-8ffc2e8f845b6a8e74e6b77c25bd980d&br=448&bt=448&cd=0%7C0%7C0&ch=0&cr=0&cs=0&cv=1&dr=0&ds=2&er=0&l=2023032020544973DCCFE21CF4C02E38B1&lr=&mime_type=video_mp4&net=0&pl=0&qs=0&rc=amg6c2o0aTg6ZTQzNGRnM0ApZjNkOTZkZDs6NzVmZGU3ZGdfZy9gMHFrYTBgLS1kYy9zczUzMDIxMDVgYy8tNjA0NjI6Yw%3D%3D&vl=&vr=', }, { streamType: 'hls', definition: 'hd', definitionTextKey: 'HD', // 清晰度多语言 key url: 'https://voddemo-play.volcvod.com/9d71d44b87c74e29980bdad6fbf92664/main.m3u8?a=0&auth_key=1773925042-3e2dcf9a03bc48868a151241d472f769-0-f22f5fb0c822ab5999bab8282b1c4583&br=643&bt=643&cd=0%7C0%7C0&ch=0&cr=0&cs=0&cv=1&dr=0&ds=3&er=0&l=2023032020544973DCCFE21CF4C02E38B1&lr=&mime_type=video_mp4&net=0&pl=0&qs=0&rc=amg6c2o0aTg6ZTQzNGRnM0ApNDtoOzs3ODw2N2Q1aTg8aWdfZy9gMHFrYTBgLS1kYy9zc2E0YDRhMjQ0XzZjMjMzX186Yw%3D%3D&vl=&vr=', }, { streamType: 'hls', // 将此档位标记为自动档位 definition: 'auto', definitionTextKey: 'AUTO', // 标记此档位实际映射的清晰度 mapDefinition: 'uhd', url: 'https://voddemo-play.volcvod.com/10501b001bdd43ae89d7c0fc3d6792b5/main.m3u8?a=0&auth_key=1773925042-f0489f7ac9a14d92b96bbfb7b39a7a0d-0-4e57d65b22e9aefe63ba1c519218e9fe&br=966&bt=966&cd=0%7C0%7C0&ch=0&cr=0&cs=0&cv=1&dr=0&ds=4&er=0&l=2023032020544973DCCFE21CF4C02E38B1&lr=&mime_type=video_mp4&net=0&pl=0&qs=0&rc=amg6c2o0aTg6ZTQzNGRnM0ApOmZkZzg1PGVoNzhkOzxlZ2dfZy9gMHFrYTBgLS1kYy9zcy00L2JfL19eYF42Ly0vYi06Yw%3D%3D&vl=&vr=', }, ], languages: { // 清晰度多语言翻译 zh: { SD: '标清', LD: '流畅', HD: '高清', UD: '超清', UHD: '蓝光', AUTO: '自动', }, }, });