文档中心

视频点播

Web 播放器 SDK

接口说明（历史版本）

警告

本文档后续不再维护，最新内容请见 Web 点播 SDK API 参考。

本文为您介绍 VePlayer 的参数与接口。VePlayer 提供在线 Demo 和示例代码。您可进入体验功能效果，获取具体接入方法。

参数

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

const playerSdk = new VePlayer(options);

options

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

参数	类型	默认值	描述
id	String	-	播放器容器 ID。VePlayer 将被插入在该容器中。说明 `id` 和 `root` 参数至少传入 1 个。
root	HTMLElement	-	播放器容器，VePlayer 将被插入在该容器中。说明 `id` 和 `root` 参数至少传入 1 个。如果都传入，则优先用 `root` 参数。
url	String	-	视频地址。
streamType	String	-	视频格式类型。取值如下： `mp4` `hls` `flv` `dash` 说明如果 `url` 参数视频地址不包含文件格式后缀，则 `streamType` 必传。
width	String｜ Number	`100%`	播放器宽度。
height	String｜ Number	`100%`	播放器高度。
volume	Number	`0.6`	默认音量。取值范围为 [0,1]。
autoplay	Boolean	`true`	是否自动播放。取值如下： `true`：是。 `false`：否。
autoplayMuted	Boolean	`true`	是否开启静音自动播放。取值如下： `true`：是。 `false`：否。
enableDegradeMuteAutoplay	Boolean	`false`	是否开启降级静音自动播放。取值如下： `true`：是。 `false`：否。说明开启该配置同时参数 `autoplay` 为 `true` 时，如果当前浏览器环境不支持有声音自动播放，则降级为静音自动播放。注：静音自动播放也不一定能成功。
enableUserActionAutoplay	Boolean	`false`	是否开启任意用户行为触发自动播放。取值如下： `true`：是。 `false`：否。说明开启该配置时，第一次用户的任意点击可以触发播放器的自动播放。
loop	Boolean	`false`	是否开启循环播放。取值如下： `true`：是。 `false`：否。
poster	String	-	封面图 URL。
defaultPlaybackRate	Number	`1`	默认起播倍速。参考值 `0.5/0.75/1/1.5/2`
pip	Boolean	`true`	是否显示画中画。取值如下： `true`：是。 `false`：否。
fullscreen	fullscreen	-	全屏相关配置。
lang	String	`zh`	国际化语言。支持自定义，默认语言类型包括： `zh` `en` `jp` `zh-hk`
languages	Object	-	自定义多语言词典。可设置每个语种的词典 `{ [key: string]: Object; }`。例如： `{ zh: { PIP: '画中画' }, en: { PIP: 'pip' }}` 说明了解更多，请参见默认词典。
getVideoByToken	getVideoByToken	-	Vid+PlayAuthToken 播放的相关配置
useSoftDecoding	Boolean	`false`	是否启用软解。取值如下： `true`：启用。 `false`：不启用。说明移动端浏览器不支持 FLV 格式，如果需要播放该格式的视频，请开启软解。软解播放的解码操作依赖设备 CPU，播放高码率、高分辨率的视频时，对 CPU 占用率较高。
sdkErrorPlugin	SdkErrorConfig	-	播放器报错信息。支持配置播放异常时，播放器显示的异常文案、图片，以及是否提供刷新按钮等。
DanmuPlugin	Danmuconfig	-	弹幕及面板配置。支持配置弹幕文字大小、透明度、展示区域等参数。
EncryptHlsPluginConfig	EncryptHlsPluginConfig	-	hls加密播放相关配置。
useHlsPluginForSafari	Boolean	`true`	在 PC Safari 上是否使用 HLS 插件播放。取值如下： `true`：启用。 `false`：不启用。
DashPluginConfig	DashPluginConfig	-	DASH 播放相关配置，支持 DASH 加密播放。
VodLogOptsConfig	VodLogOptsConfig	-	点播质量日志接入配置。
enableContextmenu	Boolean	`false`	是否开启右键功能。取值如下： `true`：是。 `false`：否。
pluginPublicPath	String	-	插件加载的路径，默认为 `https://lf-unpkg.volccdn.com/obj/vcloudfe/sdk/@volcengine/veplayer/${version}/plugin/`，可将插件文件夹置于业务方服务器上，指定插件的地址即可。说明插件请从集成 SDK 离线包中下载。
enableMenu	Boolean	`false`	是否开启右键菜单。取值如下： `true`：是。 `false`：否。
closeVideoStopPropagation	Boolean	`false`	是否关闭 video 的事件冒泡。取值如下： `true`：是。 `false`：否。
enableMp4MSE	Boolean	`false`	是否开启 MP4 的 MSE 模式。取值如下： `true`：是。 `false`：否。说明开启后采用 MSE 方式播放 MP4，同时带来精确的 Seek 加载、视频无缝切换、流量节省等功能。
Mp4EncryptPlayer	IMp4EncryptPlayerConfig	-	MP4 加密播放配置项。
Subtitle	ISubtitleConfig	-	外挂字幕配置项。
MemoryPlay	IMemoryPlayConfig	-	记忆播放配置项。
playListPlugin	IPlayListConfig	-	播放列表配置项。
enableH265Degrade	Boolean	`false`	是否开启 H.265 兼容模式。取值如下： `true`：是。 `false`：否。说明开启 H.265 兼容模式后会，VePlayer 会在不支持 H.265 硬解的浏览器环境下，自动降级为兼容模式。
codec	h264 \| h265	`h264`	视频的编码格式。在开启 H.265 兼容降级模式时，建议传入。
onTokenExpired	`() => Promise<IPlayAuthTokenConfig>`	-	playAuthToken 过期时的回调函数，用来更新 playAuthToken。
umdUrlMap	Object	-	umd 依赖备用地址。用于依赖的 CDN 发生网络错误时的降级备用地址。支持的依赖如下： `hls`：非加密 HLS 播放。 `flv`：FLV 播放。 `XGVideo`：软解播放。 `hlsEncrypt`：加密 HLS 播放。 `dash`：DASH 播放。 `mp4Encrypt`：加密 MP4 播放。 `danmujs`：弹幕。 `danmuMask`：蒙版弹幕。 `subtitle`：外挂字幕。
unionId	String	-	唯一 ID，用于私有 DRM 加密。
isMusic	Boolean	`false`	是否为音乐播放器模式。取值如下： `false`：否。 `true`：是。
music	IMusicConfig	-	音乐播放器配置项。
plugins	`any[]`	-	用于注册插件。可传入插件实例，例如 `[VePlayer.playListPlugin]` 表示注册播放列表插件。
ignores	Array of String	-	用于禁用插件。VePlayer 内置了一些常用的功能插件。如需禁用某一内置插件，可传入插件名称（不区分大小写）。
alwaysShowDefinition	Boolean	false	是否总是显示清晰度切换控件，即只有单个清晰度时也显示清晰度切换控件。
definitionText	String	'HD'	实例化参数 `url` 对应视频的清晰度文案。警告仅 `alwaysShowDefinition` 为 `true` 时有效。
definitionTextKey	String	-	实例化参数 `url` 对应视频的清晰度文案的多语言 key，对应参数 `languages` 中的文案。警告仅 `alwaysShowDefinition` 为 `true` 时有效，优先级高于 `definitionText`。

fullscreen

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

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

参数

类型

默认值

描述

rotateFullscreen

Boolean

false

是否使用旋转横屏。取值如下：

false：否。
true：是，即全屏将会在竖屏状态下把 dom 旋转 90 度实现横屏效果。

说明

该配置优先于 useCssFullscreen 配置。
该配置一般在移动端使用。

useCssFullscreen

Boolean

false

是否使用页面全屏代替全屏功能。取值如下：

false：否。
true：是，即全屏按钮将会调用页面内全屏。

needBackIcon

Boolean

false

全屏的时候是否使用右上角返回按钮。取值如下：

false：否。
true：是。

说明

该配置一般在移动端开启。

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`	是否打开面板。取值如下： `false`：否。 `true`：是。
usePanel	Boolean	`true`	是否展示弹幕设置面板。取值如下： `false`：否。 `true`：是。
danmuItems	Array of DanmuItem	-	弹幕列表。

DanmuItem

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

参数	类型	默认值	描述
id	String	-	弹幕唯一 ID。
txt	String	-	弹幕文案。
start	Number	-	弹幕出现时间。单位为 ms。
duration	Number	-	弹幕持续显示时间。单位为 ms。
style	Object	-	弹幕样式。示例如下： `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	-	服务端生成的临时 `playAuthToken`。
playDomain	String	`//vod.volcengineapi.com`	播放地址请求域名。
reqParams	Object	-	可携带 aid 等透传参数。如`{aid: 1234}`，当透传的参数与 `playAuthToken` 中包含的参数重复时，以 `playAuthToken` 下发的参数的优先级最高。具体可传参数见签发 PlayAuthToken 。
definitionMap	Object	-	定义清晰度的映射。
needPoster	Boolean	否	是否启用控制台设置的封面图。取值如下： `false`：否。 `true`：是。说明前提有封面图。
defaultDefinition	String	从接口返回的最高清晰度	默认清晰度，对应获取播放地址接口返回的清晰度，取值如下： `240p` `360p` `480p` `540p` `720p` `1080p` `2k` `4k` `od`（原画转封装） `oe`（画质增强）
needThumbs	Boolean	否	是否启用控制台设置的雪碧图。取值如下： `false`：否。 `true`：是。说明前提是已转码并生成雪碧图。
needBarrageMask	Boolean	否	是否启用控制台设置的蒙版弹幕。取值如下： `false`：否。 `true`：是。说明前提是已转码并生成蒙版弹幕。
keyToken	String	否	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>`	-	获取 `privateDrmAuthToken` 的回调
disDrmDegraded	`boolean`	`false`	是否禁用 DRM 解密播放降级，默认会降级到普通加密播放

EncryptHlsPluginConfig

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

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

DashPluginConfig

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

参数	类型	默认值	描述
vid	String	-	视频 Vid。
playInfoType	String	`TOP`	播放类型。
definitionText	Object	-	清晰度映射文案。如：{ 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	-	DASH 播放信息。由 `Service.url` 服务接口获取。
mp4Opts	Object	-	兜底的 MP4 播放列表。由 `Service.url` 服务接口获取。
preloadTime	Number	-	预加载时间。单位为 ms。

VodLogOptsConfig

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

参数	类型	默认值	描述
line_app_id	Number	-	业务来源。业务方使用自己的 AppID。
line_user_id	String	-	用于识别单一用户的 ID。
vtype	String	-	视频类型。取值如下： `MP4` `HLS` `DASH` `FLV`
tag	String	`default`	自定义标签。
codec_type	String	`h264`	视频解码器类型名称。
drm_type	String	`0`	是否加密。取值如下： `0`：非 DRM 视频； `1`：DRM 视频。
playerCoreVersion	String	-	播放内核版本号。
playerVersion	String	-	播放器版本号。
dynamic_type	String	-	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	-	发送的埋点日志是本地缓存时候的回调。

IMp4EncryptPlayerConfig

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

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

ISubtitleConfig

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

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

ISubTitleItem

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

IListItem

参数	类型	默认值	描述
start	Number	-	开始时间，单位为秒。
end	Number	-	结束时间，单位为秒。
list	Array of ITextItem	-	字幕数据列表。

ITextItem

参数	类型	默认值	描述
start	Number	-	开始时间，单位为秒。
end	Number	-	结束时间，单位为秒。
text	Array of String	-	字幕文案数组。
index	Number	-	字幕顺序。

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	-	必填，存储标识 ID。
saveTime	return (<PreCode lang="typescript" text={`(id: number \| string, time: number) => unknown`}>)	-	设置时间函数。
getTime	return (<PreCode lang="typescript" text={`(id: number \| string) => number \| Promise<number>`}>)	-	获取最后一次播放时间函数。

IMusicConfig

参数	类型	默认值	描述
offline	Boolean	`false`	是否启用离线下载播放。
abCycle	IABCycle	-	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	-	AB 循环段结束时间。
loop	Boolean	`false`	AB 段是否循环播放。

IMusicListItem

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

IPlayListConfig

播放列表配置。

参数	类型	默认值	是否必填	描述
list	`listItem[]`	`[]`	是	视频列表。
defaultIndex	`number`	`0`	否	默认起始的播放次序。
position	`string`	`'controlsLeft'`	否	按钮位置。取值如下： `controlsLeft`: 播控栏左侧 `controlsRight`: 播控栏右侧 `controlsCenter`: 播控栏中间 `rootLeft`：播放器根节点左侧 `rootRight`：播放器根节点右侧 `rootTop`：播放器根节点顶部 `root`：播放器根节点说明此参数同时影响“打开/关闭播放列表”和“播放下一个”两个按钮的位置。
index	`number`	`2`	否	按钮在所在区域的次序。默认值为 `2` 表示在播放按钮后。
mode	`'order' \| 'loop'`	`'order'`	否	循环模式，取值如下： `order`: 不循环播放，即列表中最后一个视频播放完成后就停止播放。 `loop`: 列表循环，即列表中最后一个视频播放完成后将自动开始重新播放列表中的第一个视频。

IPlaylistItem

视频列表。支持 DirectUrl 和 Vid + playAuthToken 两种播放模式。

说明

列表数据由外部提供，播放器内部不直接获取播放列表数据。

参数	类型	是否必填	描述
url	string	否	视频地址。警告 `playAuthToken` 为空时，此参数必传。
playAuthToken	string	否	播放临时安全凭证，由业务的 AppServer 签发。警告 `url` 为空时，此参数必传。
vid	string	否	视频的唯一 ID。不传则取视频所在列表数组的序号。
poster	string	否	封面图地址。
title	string	否	视频标题。
duration	number	否	视频时长。

方法

本节为您介绍 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()	切换视频源，主要用于在视频过期时更新视频源。
getLogUserId()	获取日志上报的用户 ID。

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'
  }
})

getLogUserId()

获取日志上报的用户 ID，可用于登录视频点播控制台，单击左侧导航栏质量平台 > 单点追查，进入单点追查页面，根据筛选条件，查询用户播放日志。

类型

() => string

示例代码

const playerSdk = new VePlayer(options)
playerSdk.on('complete', () => {
  const userId = playerSdk.getLogUserId();
  console.log('log userId:', userId);
});

getPlugin()

获取插件实例。

类型

(pluginName: string) => null | BasePlugin

参数

pluginName：类型为 string，插件名称。

示例代码

const playerSdkIns = new VePlayer(options)

playerSdkIns.on('complete', () => {
  // 获取画中画插件
  const pipPlugin = playerSdkIns.getPlugin('pip')
  console.log('pipPlugin: ', pipPlugin)
})

播放器内核

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(() => {
   // 播放失败，一般发生于未经用户交互时的自动播放
 });

属性

播放器内核的属性大部分是只读类型的，某些属性还支持写入。以获取视频时长 duration 为例，该属性是只读类型，不能通过 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'`	-	播放器完成创建
PLAYER_REBUILD	`'player_rebuild'`	-	播放器重建
DANMU_CHANGE	`'danmu_change'`	`{ active: boolean; // 是否激活 external: object; // 弹幕配置信息 }`	弹幕配置发生变化
CANCEL_UNMUTE	`'cancel_unmute'`	-	取消静音
REFRESH_CLICK	`'refresh_click'`	-	触发刷新
PLAY_URL_CHANGE	`'play_url_change'`	`{ url: string; from: string; }`	清晰度切换时地址切换
SHOW_PLAY_ERROR	`'show_play_error'`	-	展示报错
GET_PLAY_URL_ERR	`'get_play_url_err'`	`Error`	playAuthToken 获取 URL 失败
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`	-	视频内容开始加载
`LOADED_DATA`	`loadeddata`	-	视频起播数据加载完成
`PLAY`	`play`	-	播放
`PAUSE`	`pause`	-	暂停
`ENDED`	`ended`	-	结束
`ERROR`	`error`	`Error`	错误
`AUTOPLAY_PREVENTED`	`autoplay_was_prevented`	-	自动播放被阻止
`PLAYING`	`playing`	-	（暂停、卡顿后）恢复播放
`SEEKING`	`seeking`	-	seek 播放
`SEEKED`	`seeked`	-	seek 完成
`TIME_UPDATE`	`timeupdate`	-	播放时间改变说明 `timeupdate` 属于媒体事件，由浏览器触发，不能控制触发频率，具体请参考 MDN Web 文档库中的 HTMLMediaElement: timeupdate这篇文档。
`AUTOPLAY_SUCCESS`	`autoplay_success`	`{ mode: 'unmute' \| 'mute' \| 'noSupport'}`	自动播放成功
`AUTOPLAY_FAILED`	`autoplay_failed`	`{ mode: 'unmute' \| 'mute' \| 'noSupport'}`	自动播放失败
`WAITING`	`waiting`	-	等待加载数据
`CANPLAY`	`canplay`	-	视频缓冲足够数据，可以播放
`CANPLAY_THROUGH`	`canplaythrough`	-	视频可以流畅播放
`DURATION_CHANGE`	`durationchange`	-	视频时长发生变化
`VOLUME_CHANGE`	`volumechange`	-	音量发生变化
`RATE_CHANGE`	`ratechange`	-	播放速率发生变化

播放器扩展事件

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

事件名	枚举值	回调参数	含义
`READY`	`ready`	-	播放器完成实例化
`COMPLETE`	`complete`	-	播放器创建 video 完成，可以开始播放
`URL_CHANGE`	`urlchange`	`{ url: string }`	播放资源发生变化，player.src='xxx'
`PLAYER_FOCUS`	`focus`	-	播放器聚焦
`PLAYER_BLUR`	`blur`	-	播放器失焦
`FULLSCREEN_CHANGE`	`fullscreen_change`	`{ isFullScreen: boolean }`	全屏状态切换
`CSS_FULLSCREEN_CHANGE`	`cssFullscreen_change`	`{ isCssFullScreen: boolean }`	样式全屏状态切换
`MINI_STATE_CHANGE`	`mini_state_change`	`{ isPip: boolean }`	画中画播放模式切换
`DESTROY`	`destroy`	-	播放器销毁
`REPLAY`	`replay`	-	播放器重新播放
`RETRY`	`retry`	-	重试
`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`	-	播放器被旋转
`SHORTCUT`	`shortcut`	`{ data }`	播放器内置快捷键事件触发
`SEI_PARSED`	`SEI_PARSED`	-	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             // 快捷键键值
   * }
   */
})

最近更新时间：2026.09.24 12:09:56

这个页面对您有帮助吗？

有用

无用

视频点播

参数 #

options #

fullscreen #

DanmuConfig #

DanmuItem #

SdkErrorConfig #

TipsTextConfig #

getVideoByToken #

EncryptHlsPluginConfig #

DashPluginConfig #

VodLogOptsConfig #

IMp4EncryptPlayerConfig #

ISubtitleConfig #

ISubTitleItem #

IListItem #

ITextItem #

ISubtitleStyle #

IMemoryPlayConfig #

IMusicConfig #

IABCycle #

IMusicListItem #

IPlayListConfig #

IPlaylistItem #

方法 #

on() #

once() #

off() #

emit() #

destroy() #

switchAuthToken() #

updateAuthToken() #

switchURL() #

next() #

playNext() #

getLogUserId() #

getPlugin() #

播放器内核 #

属性 #

状态属性 #

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

ITextItem

ISubtitleStyle

IMemoryPlayConfig

IMusicConfig

IABCycle

IMusicListItem

IPlayListConfig

IPlaylistItem

方法

on()

once()

off()

emit()

destroy()

switchAuthToken()

updateAuthToken()

switchURL()

next()

playNext()

getLogUserId()

getPlugin()

播放器内核

属性

状态属性

API

事件

SDK 事件

播放器媒体事件

播放器扩展事件

事件相关示例代码