link管理

链接快照平台

输入网页链接，自动生成快照
标签化管理网页链接

接口说明

更新时间： 2023.04.28 15:46:54

文档反馈

本文为您介绍 VePlayer 的参数与接口。

参数

VePlayer 在实例化时的参数，开发者可以根据自己的需求进行选择性地配置。

const playerSdk = new VePlayer(options);

options

VePlayer 类可配置的参数如下表所示。

参数	类型	默认值	描述
id	String	`undefined`	播放器容器 ID。VePlayer 将被插入在该容器中。 `id` 和 `root` 至少传入 1 个。
root	HTMLElement	`undefined`	播放器容器，VePlayer 将被插入在该容器中。 `id` 和 `root` 至少传入 1 个。如果都传入，则优先用 root。
url	String	`undefined`	视频地址。
streamType	String	`undefined`	视频格式类型。支持的取值如下所示。 mp4 hls flv dash 说明如果 `url` 地址不包含文件格式后缀，则 `streamType` 必传。
width	String｜ Number	`100%`	播放器宽度
height	String｜ Number	`100%`	播放器高度
volume	Number	`0.6`	默认音量。取值范围：[0,1]
autoplay	Boolean	`true`	是否自动播放
autoplayMuted	Boolean	`true`	是否开启静音自动播放
loop	Boolean	`false`	是否开启循环播放
poster	String	`undefined`	封面图 URL
defaultPlaybackRate	Number	`1`	默认起播倍速。参考值 `0.5/0.75/1/1.5/2`
pip	Boolean	`true`	是否显示画中画。
fullscreen	fullscreen	`undefined`	全屏相关配置。
lang	String	`zh`	国际化语言。支持自定义，默认语言类型包括： zh en jp zh-hk
languages	Object	`undefined`	自定义多语言词典。可设置每个语种的词典 `{ [key: string]: Object; }` 。例如： `{ zh: { PIP: '画中画' }, en: { PIP: 'pip' }}` 说明了解更多，请参见默认词典。
getVideoByToken	getVideoByToken	`undefined`	Vid+PlayAuthToken 播放的相关配置
useSoftDecoding	Boolean	`false`	是否启用软解。移动端浏览器不支持 flv 格式，如果需要播放该格式的视频，请开启软解。软解播放的解码操作依赖设备 CPU，播放高码率、高分辨率的视频时，对 CPU 占用率较高。
sdkErrorPlugin	SdkErrorConfig	`undefined`	播放器报错信息。支持配置播放异常时，播放器显示的异常文案、图片，以及是否提供刷新按钮等。
DanmuPlugin	Danmuconfig	`undefined`	弹幕及面板配置。支持配置弹幕文字大小、透明度、展示区域等参数。
EncryptHlsPluginConfig	EncryptHlsPluginConfig	`undefined`	hls加密播放相关配置。
DashPluginConfig	DashPluginConfig	`undefined`	dash播放相关配置，支持dash加密播放
VodLogOptsConfig	VodLogOptsConfig	`undefined`	点播质量日志接入配置。
enableContextmenu	Boolean	`false`	是否开启右键功能
closeVideoStopPropagation	Boolean	`false`	是否关闭 video 的事件冒泡
enableMp4MSE	Boolean	`false`	是否开启 mp4 的 MSE 模式，开启后采用 MSE 方式播放 MP4，同时带来精确的 seek 加载、视频的 `undefined` 缝切换、流量节省等功能。
Mp4EncryptPlayer	IMp4EncryptPlayerConfig	`undefined`	MP4 加密播放配置项。
Subtitle	ISubtitleConfig	`undefined`	外挂字幕配置项
MemoryPlay	IMemoryPlayConfig	`undefined`	记忆播放配置项
enableH265Degrade	Boolean	`false`	是否开启 H.265 兼容模式。开启时会在不支持H.265 硬解的浏览器环境下，自动降级为兼容模式。
codec	h264 \| h265	`h264`	视频的编码格式。在开启 H.265 兼容降级模式时，建议传入。
onMediaExpired	() => Promise	`undefined`	资源过期时的回调函数，用来自动更新视频资源。
onTokenExpired	() => Promise	`undefined`	playAuthToken 过期时的回调函数，用来更新 playAuthToken。
umdUrlMap	Object	`undefined`	umd 依赖备用地址。用于依赖的 CDN 发生网络错误时的降级备用地址。支持的依赖如下： hls：非加密 HLS 播放 flv：FLV 播放 XGVideo：软解播放 hlsEncrypt：加密 HLS 播放 dash（dash播放） mp4Encrypt：加密 MP4 播放 danmujs：弹幕 danmuMask：蒙版弹幕 subtitle：外挂字幕
unionId	String	`undefined`	唯一 id，用于私有 DRM 加密
isMusic	Boolean	`false`	是否为音乐播放器模式 false：否 true：是
music	IMusicConfig	`undefined`	音乐播放器配置项

fullscreen

全屏相关配置。
{ rotateFullscreen: boolean; useCssFullscreen: boolean; needBackIcon: boolean; }

参数	类型	默认值	描述
rotateFullscreen	Boolean	`false`	是否使用旋转横屏。该配置优先于 `useCssFullscreen` 配置；该配置为 true，全屏将会在竖屏状态下把 dom 旋转 90 度实现横屏效果，一般在移动端使用。
useCssFullscreen	Boolean	`false`	是否使用页面全屏代替全屏功能。该配置为 true，全屏按钮将会调用页面内全屏。
needBackIcon	Boolean	`false`	全屏的时候是否使用右上角返回按钮。该配置一般在移动端开启。

DanmuConfig

弹幕配置的详细参数如下表所示。

参数	类型	默认值	描述
opacity	Number	`99`	弹幕透明度。支持的取值如下所示。 0：透明度 0； 33：透明度 33%； 66：透明度 66%； 99：透明度 100%。
area	Number	`99`	弹幕区域大小。支持的取值如下所示。 0：弹幕区域占全屏的 1/4； 33：弹幕区域占全屏的 1/2； 66：弹幕区域占全屏的 3/4； 99：弹幕区域占满全屏。
speed	Number	`40`	弹幕滚动速度。支持的取值如下所示。 0：弹幕速度为 1/4； 20：弹幕速度为 1/2； 40：弹幕速度为 1； 60：弹幕速度为 5/4； 80：弹幕速度为 3/2； 100：弹幕速度为 2。
fontSize	Number	`50`	弹幕字体大小。支持的取值如下所示。 0：字体大小为 14px； 50：字体大小为 16px； 100：字体大小为 20px。
active	Boolean	`false`	是否打开面板。
usePanel	Boolean	`true`	是否展示弹幕设置面板。
danmuItems	Array 0f DanmuItem	`undefined`	弹幕列表。

DanmuItem

弹幕列表的详细参数如下表所示。

参数	类型	默认值	描述
id	String	`undefined`	弹幕唯一 ID。
txt	String	`undefined`	弹幕文案。
start	Number	`undefined`	弹幕出现时间。单位为 ms。
duration	Number	`undefined`	弹幕持续显示时间。单位为 ms。
style	Object	`undefined`	弹幕样式。例如， `style : { color: '#ff9500', fontSize: '20px', padding: '2px 11px'}`

SdkErrorConfig

参数	类型	默认值	描述
errorImg	Boolean	`true`	报错时是否显示提示图片。
errorTips	Boolean	`true`	报错时是否展示报错文案。
isNeedRefreshButton	Boolean	`true`	报错时是否展示“刷新”按钮。
retryLoopNum	Number	`1`	报错后重试次数。
errorTipsText	TipsTextConfig	`播放发生错误，点击刷新试试吧`	传入参数，填写不同语言对应的文案值。

TipsTextConfig

参数	类型	默认值	描述
zh	String｜ HTMLElement	`播放发生错误，点击刷新试试吧`	中文错误文案
en	String｜ HTMLElement	`An error occurred while playing, click refresh to try`	英文错误文案
jp	String｜ HTMLElement	`再生中にエラーが発生しました。[更新]をクリックして試してください`	日文错误文案
zh-hk	String｜ HTMLElement	`播放發生錯誤，點擊刷新試試吧`	香港繁体中文错误文案

getVideoByToken

Vid 播放配置信息的详细参数说明如下所示。

参数	类型	默认值	描述
playAuthToken	String	`undefined`	服务端生成的临时 `playAuthToken` 。
playDomain	String	`//vod.volcengineapi.com`	播放地址请求域名。
reqParams	Object	`undefined`	可携带 aid 等透传参数。如 `{aid: 1234}` ，当透传的参数与 `playAuthToken` 中包含的参数重复时，以 `playAuthToken` 下发的参数的优先级最高。具体可传参数见签发 PlayAuthToken
definitionMap	Object	`undefined`	定义清晰度的映射。
needPoster	Boolean	否	前提有封面图。是否启用控制台设置的封面图
needThumbs	Boolean	否	前提是已转码并生成雪碧图。是否启用控制台设置的雪碧图
needBarrageMask	Boolean	否	前提是已转码并生成蒙版弹幕。是否启用控制台设置的蒙版弹幕
keyToken	Boolean	否	HLS 标准加密播放所用的 keyToken
getDrmAuthToken	函数类型： `getDrmAuthToken?: (playAuthIds: string, vid: string, unionInfo: string) => Promise<string>;` 参数： playAuthIds：加密视频 playAuthId，多个 id 以英文逗号连接，类型 `string` vid：加密 vid，类型 `string` unionInfo：包含用户 unionId 的唯一 id，类型 `string` 返回值：异步函数返回 privateDrmToken，类型 `Promise<string>`	`undefined`	获取 `privateDrmAuthToken` 的回调
disDrmDegraded	`boolean`	`false`	是否禁用 DRM 解密播放降级，默认会降级到普通加密播放

EncryptHlsPluginConfig

HLS 加密播放配置的详细参数说明如下所示。

参数	类型	默认值	描述
playAuthToken	String	`undefined`	播放地址获取 token。由服务端生成下发，详见播放临时安全凭证 PlayAuthToken 。
playDomain	String	`undefined`	播放地址请求域名。
getKeyType	String	`undefined`	请求类型。固定值 'TOP'
keyDomain	String	`undefined`	密钥请求域名。
keyToken	String	`undefined`	密钥获取 token。由服务端生成下发，详见签发 Hls 标准加密AuthToken 。

DashPluginConfig

Dash 播放配置信息的详细参数说明如下所示。

参数	类型	默认值	描述
vid	String	`undefined`	视频 Vid
playInfoType	String	`TOP`	播放类型
definitionText	Object	`undefined`	清晰度映射文案。如：{ 360p: "流畅 360p",480p: "清晰 480p",720p: "高清 720p",1080p: "超高清 1080p"}
defaultDefinition	String	列表第一个	默认清晰度。
getLicenseUrl	String	`https://webmedia.zijieapi.com/video/drm/v1/play_licenses`	获取证书地址。 `https://webmedia.zijieapi.com/video/drm/v1/play_licenses` 。播放加密视频时必选。
dashOpts	Object	`undefined`	dash播放信息。由 `Service.url` 服务接口获取。
mp4Opts	Object	`undefined`	兜底的 mp4 播放列表。由 `Service.url` 服务接口获取。
preloadTime	Number	`undefined`	预加载时间。单位为 ms

VodLogOptsConfig

质量日志配置的详细参数说明如下所示。

参数	类型	默认值	描述
line_app_id	Number	`undefined`	业务来源。业务方使用自己的 AppID。
line_user_id	String	`undefined`	用于识别单一用户的 ID。
vtype	String	`undefined`	视频类型。支持的取值如下所示。 "MP4" "HLS" "DASH" "FLV"
tag	String	`default`	自定义标签。
codec_type	String	`h264`	视频解码器类型名称。
drm_type	String	`0`	是否加密。支持的取值如下所示。 0：非 DRM 视频； 1：DRM 视频。
playerCoreVersion	String	`undefined`	播放内核版本号。
playerVersion	String	`undefined`	播放器版本号。
dynamic_type	String	`undefined`	DASH 播放的封装类型。支持的取值如下所示。 "segment_template" "segment_base"
enable_bash	String	`0`	是否使用 bash。支持的取值如下所示。 0：不使用； 1：使用。
disableLocalCache	Boolean	`false`	是否禁用 localStorage 暂时缓存 onPlay 逻辑。
channel	String	`cn`	数据上报渠道。支持的取值如下。 cn：国内； va：美东； sg：新加坡。
closeResolutionLog	Boolean	`false`	是否关闭清晰度切换埋点。
closeSeekLog	Boolean	`false`	关闭 seek 相关埋点。
maxQueueCount	Number	`5`	最大队列日志数。
sendLocalCallback()	Function	`undefined`	发送的埋点日志是本地缓存时候的回调。

IMp4EncryptPlayerConfig

MP4 加密日志配置项的参数说明如下所示。

参数	类型	默认值	描述
isEncrypt	Boolean	`false`	是否加密。
vid	String	`undefined`	视频 Vid。
kid	String	`undefined`	视频密钥 ID。
getLicenseUrl	String	`undefined`	获取密钥凭证地址。
useEME	Boolean	`false`	是否使用 EME。
keyValue	String	`undefined`	视频密钥值。
secretKey	String	`undefined`	加密后的视频密钥值
withCredentials	Boolean	`false`	是否携带 cookie

ISubtitleConfig

外挂字幕配置项的参数说明如下所示。

参数	类型	默认值	描述
position	String	`controlsRight`	图标位置
index	Nummber	`6`	图标排列权重
list	Array of ISubTitleItem	`undefined`	字幕列表。
isDefaultOpen	Boolean	`true`	是否默认打开
style	ISubtitleStyle	`undefined`	字幕样式。详情请见 ISubtitleStyle 。

ISubTitleItem

参数	类型	默认值	描述
language	String \| Number	`undefined`	字幕语言
id	String \| Number	`undefined`	字幕 ID
isDefault	Boolean	`false`	是否是默认选择的字幕
text	any	`undefined`	字幕名称
url	String	`false`	外挂字幕地址
list	Array of IListItem	`undefined`	字幕内容列表，非 url 形式时使用。

IListItem

参数	类型	默认值	描述
start	Number	`undefined`	开始时间
end	Number	`undefined`	结束时间
list	IListItem	`undefined`	字幕文案列表

ISubtitleStyle

参数	类型	默认值	描述
follow	Boolean	`true`	是否跟随控制栏调整位置
mode	String	`stroke`	字体显示模式，支持的取值有 `stroke` 、 `bg`
followBottom	Number	`50`	跟随底部控制栏的高度
fitVideo	Boolean	`true`	是否跟随视频自动调整字号
offsetBottom	Number	`4`	字幕距离画面底部百分比
baseSizeX	Number	`49`	横屏视频适配基准字号
baseSizeY	Number	`28`	竖屏视频适配基准字号
minSize	Number	`16`	PC 端最小字号
minMobileSize	Number	`13`	移动端最小字号
line	String	`double`	最大显示行数。支持的取值有 `double` 、 `single` 、 `three`
fontColor	String	`#fff`	字体颜色, 16位颜色值或rgb值

IMemoryPlayConfig

存储时间函数的参数说明如下所示。

参数	类型	默认值	描述
memoryId	Number	String	`undefined`
saveTime	return (<PreCode lang="typescript" text={`(id: number \| string, time: number) => unknown`}>)	`undefined`	设置时间函数
getTime	return (<PreCode lang="typescript" text={`(id: number \| string) => number \| Promise<number>`}>)	`undefined`	获取最后一次播放时间函数

IMusicConfig

参数	类型	默认值	描述
offline	Boolean	`false`	是否启用离线下载播放
abCycle	IABCycle	`undefined`	AB 循环设置
timeScale	Number	`15`	快进快退时间跨度，大于 0 的整数，单位为秒。
mode	PLAY_MODE_TYPE	`order`	循环模式。 order sloop loop random
list	Array of IMusicListItem	`[]`	播放列表

IABCycle

参数	类型	默认值	描述
start	Number	`0`	AB 循环段开始时间
end	Number	`undefined`	AB 循环段结束时间
loop	Boolean	`false`	AB 段是否循环播放

IMusicListItem

参数	类型	默认值	描述
src	String	`undefined`	音乐地址
vid	string \| number	`undefined`	音乐唯一 Vid，可自定义
poster	String	`undefined`	音乐封面，支持您自定义设置
title	String	`undefined`	音乐标题，支持您自定义设置

方法

本节为您介绍 VePlayer 的方法，以 player.on() 为例，调用示例如下所示。

const playerSdk = new VePlayer(options)
playerSdk.on('player_create_finish', () => {
  console.log('播放器创建完成')
console.log('当前播放信息：', playerSdk.getCurrentPlayerConfig())

方法列表如下所示。

名称	描述
on()	监听事件。
once()	监听事件，事件处理函数只执行一次。
off()	解绑事件监听。
emit()	触发指定事件。
destroy()	销毁当前实例。
switchAuthToken()	播放时，更换 playAuthToken。
updateAuthToken()	更新 playAuthToken。
switchURL()	切换视频 url。
next()	针对不同格式的视频，重建播放器内核播放下一个视频。
playNext()	切换视频源，主要用于在视频过期时更新视频源。

on()

监听拉流相关的事件。
类型

(action: string, func: (...args: any[]) => void) => void

参数

action ：类型为 string
func ：类型为 (...args: any[]) => void
示例代码

const playerSdkIns = new VePlayer(options)
playerSdkIns.on('play', () => {
  // TODO
})

once()

监听事件，事件处理函数只执行一次。
类型

(action: string, func: (...args: any[]) => void) => void

参数

action ：类型为 string
func ：类型为 (...args: any[]) => void
示例代码

const playerSdkIns = new VePlayer(options)
playerSdkIns.once('play', () => {
  // TODO
})

off()

解绑事件监听。
类型

(action: string, func: (...args: any[]) => void) => void

参数

action ：类型为 string
func ：类型为 (...args: any[]) => void
示例代码

const playerSdkIns = new VePlayer(options)
const playCbk = () => {
  // TODO
// 监听事件
playerSdkIns.on('play', playCbk)
// 解绑事件监听
playerSdkIns.off('play', playCbk)

emit()

触发指定事件。
类型

(action: string, payload?: any) => void

参数

action ：类型为 string
payload ：类型为 any
示例代码

const playerSdkIns = new VePlayer(options)
playerSdkIns.emit('user_action', ...args)

destroy()

销毁当前实例。
类型

() => Promise<void>

switchAuthToken()

播放时更换 playAuthToken。
类型

(config: IPlayAuthTokenConfig, isNewVideo?: boolean) => Promise<void>

参数

config ，类型： IPlayAuthTokenConfig
isNewVideo ，类型： boolean ，是否是新视频，默认 false ，如果是 true ，则起播时间为 0。

updateAuthToken()

更新 playAuthToken。
类型

(config: IPlayAuthTokenConfig) => Promise<void>

参数

config ，类型： IPlayAuthTokenConfig

switchURL()

切换视频 url。
类型

(url: string) => Promise<void>

参数

url ，类型： String ，同一个视频，切换视频地址
返回值 ，类型： Promise<void>

next()

针对不同格式的视频，重建播放器内核播放下一个视频。
类型

(config: IPlayerConfig) => Promise<void>

参数

config ，类型： IPlayerConfig
返回值 ，类型： Promise<void>
示例
URL 模式下，不同格式的视频切换，代码示例如下所示。

const playerSdk = new VePlayer({
  streamType: 'flv',
  url: 'https://demo.xxx.com/bucket/demo.flv'
// ...
playerSdk.next({
  startTime: 0, // 从 0 开始播放
  streamType: 'hls',
  url: 'xxx.hls'
})

Vid + PlayAuthToken 模式下，不同格式的视频切换，需要在下发 playAuthToken 时指定所需要的格式 Format，具体请参考签发 PlayAuthToken ，代码示例如下所示。

playerSdk.next({
  startTime: 0, // 从 0 开始播放
  getVideoByToken: {
    playAuthToken: 'new_playAuthToken'
})

playNext()

切换视频源，主要用于在视频过期时更新视频源。

注意

playNext() 方法只适用于同种格式视频切换。不同格式视频切换使用 next() 方法。

类型

(config: IPlayerConfig) => Promise<void>

参数

config ，类型： IPlayerConfig
返回值 ，类型： Promise<void>
示例
URL 模式下，同种格式的视频切换，代码示例如下所示。

playerSdk.playNext({
  url: 'xxx.mp4'
})

Vid + PlayAuthToken 模式下，同种格式的视频切换，代码示例如下所示。

playerSdk.playNext({
  getVideoByToken: {
    playAuthToken: 'new_playAuthToken'
})

播放器内核

SDK 实例的播放功能是由播放器内核提供，播放器内核提供以下属性、API 等，供业务方自行开发实现灵活的播放功能。

获取播放器内核和调用 API 的示例代码如下所示。

const playerSdk = new VePlayer({
   id: 'video',
   width: 800,
   height: 500,
   url: 'xx.mp4'
 // 获取属性：当前播放时间
 const curTime = playerSdk.player.currentTime;
 // 获取状态属性：当前视频是否处于暂停状态
 const isPaused = playerSdk.player.paused;
 // 调用 API：播放视频
 playerSdk.player.play().then(() => {
   // 播放成功
 }).catch(() => {
   // 播放失败，一般发生于未经用户交互时的自动播放
 });

属性

播放器内核的属性大部分是只读类型的，某些属性还支持写入。以获取视频时长 durattion 为例，该属性是只读类型，不能通过 set 方式设置视频时长。而视频音量 volume 不仅支持播放器内核对象 get 方式获取，还支持 set 方式设置音量。

const playerSdk = new VePlayer({
    id: 'video',
    width: 800,
    height: 500,
    url: 'xx.mp4'
  // 获取视频时长
  const duration = playerSdk.player.duration;
  // 获取视频音量
  const curVolume = playerSdk.player.volume;
  // 设置音量
  playerSdk.player.volume = 0.1;

参数	类型	读写类型	描述
config	Object	只读	当前播放器的配置对象。
root	HTMLElement	只读	播放器外层容器 DOM 对象
video	Object	只读	媒体对象，通常是 videoElement/audioElement
autoplay	Boolean	可读可写	设置/返回自动播放属性
buffered	TimeRange	只读	返回当前已缓冲的时间范围
played	TimeRange	只读	返回已经播放的音频/视频的时间范围
crossOrigin	String	可读可写	设置/返回是否跨域
currentSrc	String	可读可写	设置/返回当前视频的播放地址
currentTime	Number	可读可写	设置/返回视频当前的播放时间，单位：s
duration	Number	只读	返回视频时长，单位：s
cumulateTime	Number	只读	返回视频累计播放时长，单位：s
volume	Number	可读可写	设置/返回视频的音量（0～1）
muted	Boolean	可读可写	设置/返回视频静音状态
defaultMuted	Boolean	只读	是否默认静音，只在初始化的时候生效
playbackRate	Number	可读可写	设置/返回当前视频播放倍速
error	MediaError \| String	只读	媒体错误对象，同 player.video.error
errorNote	String	只读	媒体错误对象常量，同 Media error code constants
loop	Boolean	可读可写	设置/返回是否开启循环播放
src	String	可读可写	设置/返回当前视频的地址（设置的时候相当于切换当前播放的视频源）
lang	String	可读可写	设置/返回当前语言
control	Plugin	可读可写	播放器控制栏插件对象，具体针对控制栏的说明，可参见 control
innerContainer	HTMLElement	只读	内置容器 DOM 对象，该属性只有在画面和控制栏互不重叠情况下存在，即当配置config.marginControls 为 true 的时候存在

状态属性

参数	类型	读写类型	描述
state	String	只读	播放器当前所处的状态，所有状态枚举值和说明如下：
			枚举名称	枚举值	描述
			ERROR	0	播放出现错误
			INITIAL	1	初始化
			READY	2	配置/事件/插件等均已经初始化/绑定/实例化完成
			ATTACHING	3	进入媒体对象挂载阶段
			ATTACHED	4	媒体对象已经挂载到了 DOM 中
			NOTALLOW	5	播放被阻止
			RUNNING	6	已经成功起播进入播放流程
			ENDED	7	播放结束
			DESTROYED	8	播放器实例处于已被销毁
ended	Boolean	只读	当前视频是否播放结束。
paused	Boolean	只读	当前视频是否处于暂停状态。
networkState	String	只读	视频的网络状态，具体取值列表如下：
			枚举名称	枚举值	描述
			NETWORK_EMPTY	0	目前还没有数据，readyState 的值是 `HAVE_NOTHING`
			NETWORK_IDLE	1	HTMLMediaElement 处于活动状态并已选择资源，但未使用网络
			NETWORK_LOADING	2	浏览器正在下载 HTMLMediaElement 数据
			NETWORK_NO_SOURCE	3	未找到 HTMLMediaElement src。
readyState	String	只读	视频的就绪状态，具体取值列表如下：
			枚举名称	枚举值	描述
			HAVE_NOTHING	0	没有关于媒体资源的可用信息
			HAVE_METADATA	1	已检索到足够多的媒体资源来初始化元数据, 快进/快退不会引发异常
			HAVE_CURRENT_DATA	2	当前播放位置的数据可用，但不足以播放下一帧
			HAVE_FUTURE_DATA	3	当前播放位置以及未来至少一小段时间的数据是可用的（至少有两帧以上的数据）
			HAVE_ENOUGH_DATA	4	有足够的数据可用，并且下载速率足够，媒体可以不间断地播放到最后
isFullscreen	Boolean	只读	播放器是否处于全屏状态。
isCssfullScreen	Boolean	只读	播放器是否处于网页全屏状态。
isSeeking	Boolean	只读	是否处于快进/快退状态。
isActive	Boolean	只读	是否处于焦点状态，处于焦点状态会显示控制栏。

API

play ：播放

调用 play() ，实现播放功能的代码示例如下：

@return { Promise<void> | null }

playerSdk.player.play()// OR
playerSdk.player.play().then(() => {// 播放成功}).catch(() => {// 播放失败，一般发生于未经用户交互时的自动播放})

pause：暂停

调用 pause() ，实现暂停功能的代码示例如下：

playerSdk.player.pause()

start：启动

启动播放器，开始加载媒体资源，初始化 video 元素。代码示例如下：

@param { string } url 视频地址。

playerSdk.player.start(url)

replay：重新播放

播放进度返回至片头，重新播放，一般在播放结束时调用。代码示例如下：

playerSdk.player.replay()

seek

调用 seek() ，实现跳转到某个时间点继续播放的功能，代码示例如下：

@param { number } time ，参数是 number 类型，单位是s(秒)。

playerSdk.player.seek(20)

reload：重新加载

调用 reload() ，实现重新加载的功能，代码示例如下：

playerSdk.player.reload()

resetState()：重置状态

重置当前实例状态，暂停视频并且将当前实例状态设置为起播之前的状态，累计播放时长的计算结果会清空，播放器容器 DOM 上的类名会重置为起播之前的状态。

reset()：重置

调用 resetState 重置实例状态，并且注销所有已经注册的组件，并且将当前实例的配置恢复为默认值。

setConfig：设置配置项

更新配置信息，如果新的配置列表中包含内置插件的配置项，则会调用内置插件的 setConfig 对其进行更新。代码示例如下：

@param {config)} newConfig

playerSdk.player.setConfig({url: '另一个url',})

changeDefinition：切换清晰度

调用 changeDefinition() ，实现切换清晰度的功能，代码示例如下：

@typedef { { url: any, definition: any, [propName: string]: any } } IDefinition

@param { IDefinition } to
@param { IDefinition? } from

playerSdk.player.changeDefinition({url: '另一个url',definition: 1，
  ...})

destroy：销毁

销毁播放器内核对象，该对象销毁的时候所有内置对象都会销毁，在调用的时候会下发 Events.DESTROY 事件。

注意

播放器内核实例销毁之后，请将播放器内核实例的引用置空，释放内存。
在播放器实例 destroy 之后再调用相关 API 有可能引发错误。

playerSdk.player.destroy() // 销毁播放器
playerSdk.player = null // 将实例引用置空

resetState：还原状态

尝试暂停 MediaElement ，并还原播放器 UI 状态。

playerSdk.player.resetState()

focus：获取焦点

播放器获取焦点，调用该 API， playerSdk.player.isActive 将会变为 true ，会触发 Events.playerSdk.player_FOCUS 事件。

@param { { autoHide?: boolean, delay?: number } } data

autoHide 是否需要自动隐藏，默认为 true ，即经过 delay 时长之后，会自动调用 playerSdk.player.blur()
delay 自动隐藏延迟时长，单位 ms，当 autoHide: false 的时候，忽略该配置项，默认取 playerSdk.player.config.inactive

blur：失去焦点

播放器失去焦点，调用该 API， playerSdk.player.isActive 将会变为 false ，会触发 Events.playerSdk.player_BLUR 事件

@param { { ignorePaused?: boolean } } data

ignorePaused 是否忽略暂停状态，默认值是 true ，默认暂停的时候不取消焦点状态。

canPlayType：检测视频类型

检测当前浏览器是否能播放指定类型的视频，实现的代码示例如下：

@param { string } mimeType 需要检测的MimeType
@return { boolean } 是否可播放

const mimeType = 'video/mp4; codecs="avc1.64001E, mp4a.40.5"'
playerSdk.player.canPlayType(mimeType);

getBufferedRange：获取缓冲时间范围

返回 currentTime 所处的缓冲时间范围，start 表示缓冲起始时间，end 表示缓存截止时间。

@param { TimeRanges? } buffered 如果不传则获取playerSdk.player.buffered
@return { [number, number] } [start, end] 返回缓冲开始时间和结束时间

const [start, end] = playerSdk.player.getBufferedRange();

checkBuffer：验证缓冲区间

验证某个时间点是否在当前缓冲区间内。

@param {number} time 时间点
@return { boolean }

const flag = playerSdk.player.checkBuffer(10);

getFullscreen：获取全屏状态

全屏作用的 DOM 节点，如果不传默认是 playerSdk.player.root，必须是 playerSdk.player.root 的父辈节点，如果该接口调用的时候处于网页全屏状态会自动退出网页全屏，下发事件 Events.FULLSCREEN_CHANGE 。

@param { HTMlElement? } el

// 监听全屏变化
playerSdk.player.on(Events.FULLSCREEN_CHANGE, (isFullscreen) => {if (isFullscreen) {// 全屏} else {// 退出全屏}})// 播放器进入全屏状态
playerSdk.player.getFullscreen()

exitFullscreen：退出全屏状态

全屏作用的 DOM 节点，默认不传会获取 getFullscreen 作用的节点，必须是 playerSdk.player.root 的父辈节点，该接口调用会下发事件 Events.FULLSCREEN_CHANGE ， isFullscreen 为 false。

@param { HTMlElement? } el

playerSdk.player.exitFullscreen()

getCssFullscreen：获取网页全屏状态

播放器进入网页全屏，利用CSS模拟实现全屏效果。全屏作用的 DOM 节点，传入参数须是播放器容器playerSdk.player.root 的父辈节点，默认为播放器容器 playerSdk.player.root，如果该接口调用的时候处于全屏状态，会自动退出全屏，下发事件 Events.CSS_FULLSCREEN_CHANGE 。

@param { HTMlElement? } el

// 监听网页全屏变化
playerSdk.player.on(Events.CSS_FULLSCREEN_CHANGE, (isFullscreen) => {if (isFullscreen) {// 网页全屏} else {// 退出网页全屏}})
playerSdk.player.getCssFullscreen()

exitCssFullscreen：退出网页全屏状态

全屏作用的 DOM 节点，默认不传会获取 getCssFullscreen 作用的节点, 必须是 playerSdk.player.root 的父辈节点，该接口调用会下发事件 Events.CSS_FULLSCREEN_CHANGE , isFullscreen 为 false 。

@param { HTMlElement? } el

playerSdk.player.exitCssFullscreen()

addClass：增加类名

给播放器容器 playerSdk.player.root 添加 CSS 类名。

@param { string } className 类名

playerSdk.player.addClass('className')

removeClass：移除类名

给播放器容器 playerSdk.player.root 移除 CSS 类名。

@param { string } className 类名

playerSdk.player.removeClass('className')

hasClass：判定类名

判断播放器容器 playerSdk.player.root 是否存在 CSS 类名。

@param { string } className 类名
@return { boolean }

const flag = playerSdk.player.hasClass('className')

setAttribute：设置属性

给播放器容器 playerSdk.player.root 设置属性

@param { string } key 属性名
@param { string } value 值

playerSdk.player.setAttribute('key', 'value')

resize：重置尺寸

调整播放器尺寸，如果初始化的时候有配置 fitVideoSize 或者 videoFillMode ，或者视频画面做了旋转，调用该 API 会触发整体的尺寸计算，根据视频画面和当前播放器容器尺寸做计算。

playerSdk.player.resize()

getPlugin：获取实例

从当前播放器获取插件的实例，代码示例如下：

@param { string } pluginName

const pluginInstance = playerSdk.player.getPlugin('pluginName')

registerPlugin：注册插件

在当前播放器上注册某个插件。

@param { {plugin: function, options: object} | function } plugin 插件构造函数。
@param { {[propName: string]: any}? } 可选配置，config 插件配置列表。
@return { object } pluginInstance 返回插件实例。

const pluginInstance = playerSdk.player.registerPlugin(MyPlugin)

unRegisterPlugin：销毁/注销插件

在当前播放器上销毁或者注销某个插件，代码示例如下：

@param { { pluginName: string } | string } Plugin 插件实例或者插件名称。
@param { boolean } removedFromConfig 注销实例的同时，是否同时将其从playerSdk.player.config.plugins 中移除，默认 false 。

const pluginInstance = playerSdk.player.unRegisterPlugin(pluginName)

事件

VePlayer 是基于事件驱动的逻辑模型，其在关键逻辑处理或状态变化时会触发相应事件。您可根据业务需要监听事件并执行自定义回调。

说明

您可调用以下方法进行事件相关操作：

on() : 监听指定事件。
once() : 一次性监听指定事件。
off() : 解绑事件监听。
emit() : 触发指定事件。

SDK 事件

SDK 事件指 VePlayer 视频点播业务相关的事件。

事件名	枚举值	回调参数	描述
PLAYER_CREATED_FINISH	`'player_create_finish'`	`undefined`	播放器完成创建
PLAYER_REBUILD	`'player_rebuild'`	`undefined`	播放器重建
DANMU_CHANGE	`'danmu_change'`	`{ active: boolean; // 是否激活 external: object; // 弹幕配置信息 }`	弹幕配置发生变化
CANCEL_UNMUTE	`'cancel_unmute'`	`undefined`	取消静音
REFRESH_CLICK	`'refresh_click'`	`undefined`	触发刷新
PLAY_URL_CHANGE	`'play_url_change'`	`{ url: string; from: string; }`	清晰度切换时地址切换
SHOW_PLAY_ERROR	`'show_play_error'`	`undefined`	展示报错
GET_PLAY_URL_ERR	`'get_play_url_err'`	`Error`	playAuthToken 获取 URL 失败
MEDIA_EXPIRED	`'MEDIA_EXPIRED'`	`undefined`	资源过期
TOKEN_EXPIRED	`'play_auth_token_expired'`	`{ type: string; token: string; }`	Token 过期
UMD_LOAD_FAIL	`'umd_load_fail'`	`{ name: string; error: Error; }`	UMD 加载失败
MUSIC_CHANGE	`'music_change'`	`{ title?: string; vid?: string; poster?: string; src: string; }`	音乐播放器切换音乐
MUSIC_LIST_CHANGE	`'music_list_change'`	Array of IMusicListItem	音乐播放列表发生变化
MUSIC_MODE_CHANGE	`'music_mode_change'`	`order \| sloop \| loop \| random`	音乐播放器播放模式改变
TIME_SCALE_CHANGE	`'time_scale_change'`	Number	音乐播放器快进快退时间跨度，单位秒

播放器媒体事件

播放器媒体事件指浏览器 video 原生触发的事件。

事件名	枚举值	回调参数	含义
`LOAD_START`	`loadstart`	`undefined`	视频内容开始加载
`LOADED_DATA`	`loadeddata`	`undefined`	视频起播数据加载完成
`PLAY`	`play`	`undefined`	播放
`PAUSE`	`pause`	`undefined`	暂停
`ENDED`	`ended`	`undefined`	结束
`ERROR`	`error`	`Error`	错误
`AUTOPLAY_PREVENTED`	`autoplay_was_prevented`	`undefined`	自动播放失败
`PLAYING`	`playing`	`undefined`	（暂停、卡顿后）恢复播放
`SEEKING`	`seeking`	`undefined`	seek 播放
`SEEKED`	`seeked`	`undefined`	seek 完成
`TIME_UPDATE`	`timeupdate`	`undefined`	播放时间改变
`WAITING`	`waiting`	`undefined`	等待加载数据
`CANPLAY`	`canplay`	`undefined`	视频缓冲足够数据，可以播放
`CANPLAY_THROUGH`	`canplaythrough`	`undefined`	视频可以流畅播放
`DURATION_CHANGE`	`durationchange`	`undefined`	视频时长发生变化
`VOLUME_CHANGE`	`volumechange`	`undefined`	音量发生变化
`RATE_CHANGE`	`ratechange`	`undefined`	播放速率发生变化

播放器扩展事件

播放器扩展事件指播放器在媒体事件之外扩展的事件。

事件名	枚举值	回调参数	含义
`READY`	`ready`	`undefined`	播放器完成实例化
`COMPLETE`	`complete`	`undefined`	播放器创建 video 完成，可以开始播放
`URL_CHANGE`	`urlchange`	`{ url: string }`	播放资源发生变化，player.src='xxx'
`PLAYER_FOCUS`	`focus`	`undefined`	播放器聚焦
`PLAYER_BLUR`	`blur`	`undefined`	播放器失焦
`FULLSCREEN_CHANGE`	`fullscreen_change`	`{ isFullScreen: boolean }`	全屏状态切换
`CSS_FULLSCREEN_CHANGE`	`cssFullscreen_change`	`{ isCssFullScreen: boolean }`	样式全屏状态切换
`MINI_STATE_CHANGE`	`mini_state_change`	`{ isPip: boolean }`	画中画播放模式切换
`DESTROY`	`destroy`	`undefined`	播放器销毁
`REPLAY`	`replay`	`undefined`	播放器重新播放
`RETRY`	`retry`	`undefined`	重试
`DEFINITION_CHANGE`	`definition_change`	`{ from: { url: string; definition: string}; to: { url: string; definition: string}; }`	清晰度发生变化
`VIDEO_RESIZE`	`video_resize`	`{ videoScale: number; vWidth: number; vHeight: number; cWidth: number; cHeight: number; }`	播放器容器尺寸发生变化
`PIP_CHANGE`	`pip_change`	`boolean`	画中画状态切换
`ROTATE`	`rotate`	`undefined`	播放器被旋转
`SHORTCUT`	`shortcut`	`{ data }`	播放器内置快捷键事件触发
`SEI_PARSED`	`SEI_PARSED`	`undefined`	SEI 信息解析
`USER_ACTION`	`user_action`	`{ data }`	内置插件用户行为触发，所有内置插件用户行为交互都会下发该事件，可用于用户行为埋点

事件相关示例代码

监听错误

playerSdkIns.on('error', (error) => {
  // error 处理
playerSdkIns.player.on

监听全屏状态变化

playerSdkIns.on('fullscreen_change', (isFullscreen) => {
  if (isFullscreen) {
    // 全屏 TODO
  } else {
    // 退出全屏 TODO
})

监听播放速度变化

playerSdkIns.on('ratechange', () => {
  const rate = playerSdkIns.playbackRate // 默认为 1
})

监听音量变化

playerSdkIns.on('volumechange', () => {
  const muted = playerSdkIns.muted // 是否静音 Boolean
  const volume = playerSdkIns.volume  // 音量 0-1
})

监听快捷键变化

playerSdkIns.on('shortcut', (data) => {
  // TODO
   * data = {
   *   action: String | Function,  // 该快捷键触发的行为
   *   disable:  Boolean,           // 是否禁用
   *   key: String,                // 功能定义 key
   *   keyCode: Number             // 快捷键键值
})

参数

options

fullscreen

DanmuConfig

DanmuItem

SdkErrorConfig

TipsTextConfig

getVideoByToken

EncryptHlsPluginConfig

DashPluginConfig

VodLogOptsConfig

IMp4EncryptPlayerConfig

ISubtitleConfig

ISubTitleItem

IListItem

ISubtitleStyle

IMemoryPlayConfig

IMusicConfig

IABCycle

IMusicListItem

方法

on()

once()

off()

emit()

destroy()

switchAuthToken()

updateAuthToken()

switchURL()

next()

playNext()

播放器内核

属性

状态属性

API

事件

SDK 事件

播放器媒体事件

播放器扩展事件

事件相关示例代码

视频点播

接口说明

参数 #

options #

fullscreen #

DanmuConfig #

DanmuItem #

SdkErrorConfig #

TipsTextConfig #

getVideoByToken #

EncryptHlsPluginConfig #

DashPluginConfig #

VodLogOptsConfig #

IMp4EncryptPlayerConfig #

ISubtitleConfig #

ISubTitleItem #

IListItem #

ISubtitleStyle #

IMemoryPlayConfig #

IMusicConfig #

IABCycle #

IMusicListItem #

方法 #

on() #

once() #

off() #

emit() #

destroy() #

switchAuthToken() #

updateAuthToken() #

switchURL() #

next() #

playNext() #

播放器内核 #

属性 #

状态属性 #

API #

play ：播放

pause：暂停

start：启动

replay：重新播放

seek

reload：重新加载

resetState()：重置状态

reset()：重置

setConfig：设置配置项

changeDefinition：切换清晰度

destroy：销毁

resetState：还原状态

focus：获取焦点

blur：失去焦点

canPlayType：检测视频类型

getBufferedRange：获取缓冲时间范围

checkBuffer：验证缓冲区间

getFullscreen：获取全屏状态

exitFullscreen：退出全屏状态

getCssFullscreen：获取网页全屏状态

exitCssFullscreen：退出网页全屏状态

addClass：增加类名

removeClass：移除类名

hasClass：判定类名

setAttribute：设置属性

resize：重置尺寸

getPlugin：获取实例

registerPlugin：注册插件

unRegisterPlugin：销毁/注销插件

事件 #

SDK 事件 #

播放器媒体事件 #

播放器扩展事件 #

事件相关示例代码 #

参数

options

fullscreen

DanmuConfig

DanmuItem

SdkErrorConfig

TipsTextConfig

getVideoByToken

EncryptHlsPluginConfig

DashPluginConfig

VodLogOptsConfig

IMp4EncryptPlayerConfig

ISubtitleConfig

ISubTitleItem

IListItem

ISubtitleStyle

IMemoryPlayConfig

IMusicConfig

IABCycle

IMusicListItem

方法

on()

once()

off()

emit()

destroy()

switchAuthToken()

updateAuthToken()

switchURL()

next()

playNext()

播放器内核

属性

状态属性

API

事件

SDK 事件

播放器媒体事件

播放器扩展事件

事件相关示例代码