文档中心

视频点播

SDK API 参考

配置参数

IPlayerConfig

播放器实例化配置。

配置项	类型	必选	默认值	描述
id	string	否	-	播放器容器 ID。播放器将被插入在该容器中。说明 `id` 和 `root` 参数需至少传入 1 个。如果都传入，则优先使用 `root` 参数。
root	HTMLElement	否	-	播放器容器 DOM 元素。VePlayer 将被插入该容器中。说明 `id` 和 `root` 参数需至少传入 1 个。如果都传入，则优先使用 `root` 参数。
url	Url	否	-	视频播放地址。
vid	string	否	-	视频点播服务中的视频 ID。推荐填写，以方便跟踪该视频的播放质量。您将音视频上传至视频点播服务后，可通过以下方式获取 `Vid`：在视频点播控制台获取。通过 GetMediaList 接口获取 `Vid`。如果您设置了媒资上传完成的回调事件，会在 FileUploadComplete 中返回 `Vid`。
getVideoByToken	IPlayAuthTokenConfig	否	-	Vid 播放配置项。应用服务端需通过 `vid` 生成临时播放 Token，下发给客户端。
drmType	EDRMTYPE	否	-	视频加密类型
encryptSessionId	string	否	-	私有加密会话id
playAuthId	string	否	-	视频为加密视频时的密钥KeyId，对应GetPlayInfo 接口返回的PlayInfoList项中的 PlayAuthId
playAuth	string	否	-	私有加密播放的加密密钥，对应GetPlayInfo 接口返回的PlayInfoList项中的 PlayAuth
streamType	"mp4" \| "hls" \| "dash" \| "rtm" \| "flv"	否	-	视频格式。取值如下： `mp4` `hls` `dash` `flv` 说明如果 `url` 参数取值中不包含文件格式后缀，则 `streamType` 必填。
width	string \| number	否	`100%`	播放器宽度。可传入数字或者 CSS `width` 属性值。如为数字，单位为 px。
height	string \| number	否	`100%`	播放器高度。可传入数字或者 CSS `width` 属性值。如为数字，单位为 px。
volume	number	否	`0.6`	默认起播音量。取值范围为 [0,1]。
autoplay	boolean	否	`false`	是否开启自动播放。取值如下： `true`：是 `false`：否说明受限于浏览器策略，自动播放不一定能成功，取决于浏览器环境、用户行为、浏览器配置等。详情请参考自动播放。
poster	string \| IPoster	否	-	视频封面图配置。
autoplayMuted	boolean	否	`false`	是否开启静音自动播放。取值如下： `true`：开启静音自动播放。 `false`：关闭静音自动播放。
enableDegradeMuteAutoplay	boolean	否	`false`	是否开启降级静音自动播放。开启后，有声音自动播放失败时，会降级成静音自动播放。取值如下： `true`：开启降级静音自动播放 `false`：关闭降级静音自动播放
enableUserActionAutoplay	boolean	否	`false`	是否开启任意用户行为触发自动播放。开启后，第一次用户的任意点击可以触发播放器的自动播放。取值如下： `true`：开启 `false`：不开启
loop	boolean	否	`false`	是否开启循环播放。取值如下： `true`：开启循环播放。 `false`：关闭循环播放。
defaultPlaybackRate	number	否	`1`	默认起播倍速。可设为 `0.5`、`0.75`、`1`、`1.5`、`2`。
lang	"zh" \| "zh-cn" \| "en" \| "jp" \| "zh-hk"	否	`zh`	界面语言。取值如下： `zh` 或 `zh-cn` `en` `jp` `zh-hk`
languages	{ [key: string]: Record<string, any>; }	否	-	多语言词典。可设置每个语种的词典，例如： `javascript<br>{ zh: { PIP: '画中画' }, en: { PIP: 'pip' }}<br>` 说明了解更多，请参见默认词典。
pip	boolean \| IPIPConfig	否	`PC: {position: 'controlsRight', index: 2.5, showIcon: true}; mobile：false`	画中画配置。说明画中画功能由浏览器提供。如果浏览器不支持，即使传入此配置也不会显示画中画按钮。
fullscreen	IFullscreenConfig	否	`{position: 'controlsRight', index: 0, rotateFullscreen: false, useCssFullscreen: false, target: null, switchCallback: null, disable: false, needBackIcon: false }`	全屏配置。
alwaysShowDefinition	boolean	否	`false`	是否总是显示清晰度切换控件，即只有单个清晰度时也显示清晰度切换控件。
definitionText	string	否	`HD`	`url` 参数对应视频的清晰度文案。说明仅 `alwaysShowDefinition` 为 `true` 时有效。
definitionTextKey	string	否	-	`url` 参数对应视频的清晰度文案的多语言 key，对应参数 `languages` 中的文案。说明仅 `alwaysShowDefinition` 为 `true` 时有效，优先级高于 `definitionText`。
codec	ICodecType	否	-	视频编码格式。说明在已知视频编码方式的情况下推荐传入，以便日志分析。在 `useSoftDecoding` 参数为 `true`（开启 H.265 兼容降级模式）时，建议传入，可提升软解初始效率。
region	TRegionType	否	`cn`	点播服务所在区域，影响服务接口的请求域名
userRegion	TRegionType	否	`cn`	用户所在区域，影响日志请求的上报服务及动态依赖拉取的域名
pluginPublicPath	string	否	`https://lf-unpkg.volccdn.com/obj/vcloudfe/sdk/@volcengine/veplayer/${version}/plugin`	插件加载的路径。您可从 SDK 离线包中获取插件，然后将插件文件放置于应用服务器上，再在初始化播放器时指定插件地址。
startTime	number	否	`0`	起播时间，单位为秒。
playsinline	boolean	否	`true`	是否启用内联播放模式。`playsinline` 属性是 HTML5 视频标签的一个属性，用于指定视频是否应在页面文档内播放。 `true`：启用内联播放模式，表示视频将在页面文档内播放。 `false`：禁用内联播放模式。说明此参数仅在移动端生效。此参数取值为 `true` 时，会在初始化 `video` 或 `audio` 对象的时候，将 `playsinline`、`webkit-playsinline`、`x5-playsinline` 三个属性设置为 `true`，请参考 New Policies for iOS 了解内联播放模式相关知识。iOS 上内联播放模式的支持情况如下： iOS 10 及以上系统 Safari 浏览器支持配置内联播放模式。 iOS 10 以下系统 Safari 浏览器不支持配置内联播放模式，默认播放即进入系统全屏。
videoAttributes	Partial<HTMLVideoElement>	否	无	`video` 标签扩展属性。播放器初始化时会设置在 `videoElement` 或 `audioElement` 对象上。请参考 HTMLMediaElement 查看支持的属性。
fluid	boolean	否	`false`	是否启用流式布局。启用流式布局后，播放器会根据屏幕宽度进行自适应调整，以确保在不同屏幕尺寸上都能呈现良好的显示效果。取值如下： `true`：启用流式布局 `false`：停用流式布局说明启用流式布局时，播放器的宽高比与 `width` 和 `height` 的取值有关，具体如下：如果 `width` 和 `height` 是 `Number` 类型，则按照其数值计算播放器宽高比。如果 `width` 和 `height` 不是 `Number` 类型，默认使用 16:9 比例。
fitVideoSize	"fixWidth" \| "fixHeight" \| "fixed"	否	`fixed`	尺寸适配方式。在视频资源初始化之后，根据获取到的 `videoWidth` 和 `videoHeight` 的值对播放器容器宽高比进行调整。取值如下： `fixed`: 保持容器宽高比，不进行适配。 `fixWidth`: 保持容器宽度，仅适配高度。 `fixHeight`: 保持容器高度，仅适配宽度。
videoFillMode	"cover" \| "auto" \| "fillHeight" \| "fillWidth" \| "fill"	否	`auto`	视频画面填充模式，等同于设置CSS object-fit属性。取值如下： `auto`: 使用浏览器默认的视频画面填充模式，注意设置此值时，在视频的宽高与播放器容器的宽高不匹配时会出现黑边。 `fill`: 拉伸视频以填充播放器容器，等同于设置 CSS `object-fit: fill`，注意设置此值时，视频画面会被拉伸变形。 `cover`: 保持视频宽高比的同时填充整个播放器容器，等同于设置 CSS `object-fit: cover`，注意设置此值时，视频画面会被部分裁剪。 `fillWidth`: 填充宽度，高度溢出则裁剪高度，当播放器容器宽高比小于视频的宽高比，等同于设置CSS `object-fit: cover`。 `fillHeight`: 填充高度，宽度溢出则裁剪宽度，当播放器容器宽高比大于视频的宽高比，等同于设置CSS `object-fit: cover`。
marginControls	boolean	否	`false`	是否开启画面和控制栏分离模式。开启时，控制栏将会常驻，与视频画面不重叠。 `true`：开启 `false`：关闭
'x5-video-player-type'	string	否	无	是否启用 X5 内核浏览器的同层播放。
'x5-video-player-fullscreen'	boolean	否	无	是否启用 X5 内核浏览器的全屏播放模式。 `true`：启用 `false`：停用
'x5-video-orientation'	"landscape" \| "portrait" \| "landscape\|portrait"	否	`landscape\\|portrait（移动端）`	X5 内核浏览器的横竖屏控制。取值如下： `landscape`：横屏 `portrait`：竖屏 `landscape\|portrait`：跟随手机自动旋转
commonStyle	ICommonStyle	否	-	为播放器配置关键点样式。
isMusic	boolean	否	`false`	是否开启音乐播放模式。开启后，您可还通过 `music` 参数对音乐播放器进行配置。取值如下： `true`：开启音乐播放模式 `false`：停用音乐播放模式
closeVideoStopPropagation	boolean	否	`false`	是否关闭 `video` 标签的事件冒泡。取值如下： `true`：关闭。 `false`：开启。
enableMenu	boolean	否	`false`	是否开启右键菜单。取值如下： `true`：是。 `false`：否。
closeVideoClick	boolean	否	`false`	是否禁用 PC 端点击播放器区域切换播放和暂停功能。
closeVideoDblclick	boolean	否	`PC 端为 true，移动端为 false`	PC 端：是否关闭双击播放器进入全屏的功能。移动端：是否关闭双击切换暂停和播放的功能。
closeDelayBlur	boolean	否	`false`	（仅 PC 端生效）是否关闭播放器自动失焦的功能。
inactive	number	否	`pc端: 2000， mobile端: 3000`	播放器 focus 状态自动消失延迟时长，单位为毫秒。
leavePlayerTime	number	否	`0`	（仅 PC 端生效）用户鼠标离开播放器区域后，控制栏隐藏延时时间。若希望鼠标移出播放器区域即隐藏，可设置为 0。
closePlayVideoFocus	boolean	否	`PC 端为 true，移动端为 false`	是否禁用播放时触发播放器焦点状态的功能。
closePauseVideoFocus	boolean	否	`false`	是否关闭暂停时触发播放器焦点状态的功能。这样会导致强制呼出控制栏。
needFullscreenScroll	boolean	否	`false`	是否在退出全屏后将页面滚动定位到全屏之前的位置。通常在安卓设备上退出全屏后页面会发生滚动。
mobile	IMobileConfig	否	-	移动端交互插件配置。
start	IStartConfig	否	-	播放器中间切换暂停/播放的按钮插件配置
enableHlsMSE	boolean	否	`false`	是否开启 HLS 视频的 MSE 模式。仅移动端生效。默认情况下，在移动端使用原生 `video` 播放 HLS 视频。开启后，将采用 MSE 方式播放 HLS 视频，实现更好的兼容性、能控制缓存、节省流量。
enableMobileHlsPlugin	boolean	否	`false`	移动端播放 HLS 时优先使用 hls.js 插件（MSE/MMS）： Android：直接启用 hls.js 播放。 iOS：仅在设备支持 `ManagedMediaSource`（iOS 17.1+，即 `VePlayer.isMMSSupported()` 为 `true`）时启用；不满足时自动回退至原生 HLS 播放。开启后可在移动端解锁多音轨切换、`setAudioOption` 偏好持久化等 hls.js 特有能力。
enableHlsJs	boolean	否	`true`	是否启用 hls.js 插件播放HLS视频，默认为true，设置为false后，PC端播放HLS使用自研hls插件播放HLS视频
useHlsPluginForSafari	boolean	否	`true`	在 PC Safari 上是否 HLS 插件播放视频。取值如下： `true`：使用 HLS 插件。SDK 会自动加载 HLS 插件。 `false`：不使用 HLS 插件。
enableMp4MSE	boolean	否	`false`	是否开启 MP4 视频的 MSE 模式。开启后，将采用 MSE 方式播放 MP4，实现精确的 Seek 加载、视频的无缝切换、流量节省等功能。
playList	Stream[]	否	-	播放地址列表。
defaultDefinition	string	否	`playList第一项`	默认清晰度。仅当 `playList` 有值时生效。
audioPreference	AudioTrackOption	否	-	起播默认音轨偏好。字段与 `switchAudioTrack()` 参数一致，按需填写一个或多个字段进行匹配。 hls.js 路径下通过 `hls.setAudioOption()` 应用，支持跨清晰度自动持久化； iOS 原生路径按 `lang` 字段匹配。未匹配到时沿用 manifest 默认轨道。
audioTrackSwitchSeekOffset	number	否	`0.1`	用户主动切换音轨时执行的微小 seek 偏移量（秒），用于修复偶发的有画无声问题。设为 `0` 可关闭。
plugins	any[]	否	-	插件，可自行选择安装的插件，支持西瓜播放器插件。
ignores	string[]	否	`[]`	用于禁用插件。VePlayer 内置了一些常用的功能插件。如需禁用某一内置插件，可传入插件名称（不区分大小写）。
umdUrlMap	Record<string, string>	否	-	UMD 依赖备用地址。用于依赖的 CDN 发生网络错误时的降级备用地址。支持的依赖如下： `hls`：非加密 HLS 播放。 `flv`：FLV 播放。 `XGVideo`：软解播放。 `hlsEncrypt`：加密 HLS 播放。 `dash`：DASH 播放。 `mp4Encrypt`：加密 MP4 播放。 `danmujs`：弹幕。 `danmuMask`：蒙版弹幕。 `subtitle`：外挂字幕。
unionId	string	否	-	唯一 ID，用于私有加密方案。
useSoftDecoding	boolean	否	`false`	是否启用软解。取值如下： `true`：启用。 `false`：不启用。说明移动端浏览器不支持 FLV 格式，如果需要播放该格式的视频，请开启软解。软解播放的解码操作依赖设备 CPU，播放高码率、高分辨率的视频时，对 CPU 占用率较高。
enableH265Degrade	boolean	否	`false`	是否开启 H.265 自动降级模式。开启 H.265 兼容模式后，VePlayer 会在不支持 H.265 硬解的浏览器环境下，自动降级为兼容模式。取值如下： `true`：开启 H.265 自动降级模式。 `false`：不开启 H.265 自动降级模式。
enableUrlExpireCheck	boolean	否	`false`	是否开启视频播放地址过期检测。开启后，播放器会轮询地将播放器所在的客户端时间与过期时间戳进行比较，以判断视频播放地址是否过期。
urlExpireTimestamp	number	否	-	地址的过期时间戳，单位秒(s)，vid模式下不用输入，播放器自动获取。如果是火山引擎的CDN分发地址，在不传入过期时间戳时，则需指定urlType，支持A-E类型，其他云厂商或者业务服务器存储的地址不支持。
urlExpireDiff	number	否	`60`	判断视频播放地址过期的阈值。单位为秒。如设置为 500，则 SDK 会在地址过期前 500 秒时就触发过期事件 `Events.MEDIA_EXPIRED`，为您更新地址留足缓冲时间。
urlCheckExpireInterval	number	否	`400`	视频播放地址过期检测的时间间隔。单位为毫秒。播放器以这个时间间隔轮询地将播放器所在的客户端时间与过期时间戳进行比较，以判断地址是否过期。
debug	boolean	否	`false`	是否开启日志打印。
sdkErrorPlugin	ISdkErrorConfig	否	-	播放器报错信息。支持配置播放异常时显示的异常文案、图片以及是否提供刷新按钮等。
oriErrRetryCount	number	否	`3`	非 MSE 播放模式下（含加密 HLS），触发媒体错误后的窗口内最大重试次数。
oriErrRetryCycle	number	否	`10000`	重试滑动窗口时长（ms）。窗口内超过 `oriErrRetryCount` 次重试后停止并进行错误诊断。
oriErrRetryBaseDelay	number	否	`500`	重试指数退避基础延迟（ms）。第 n 次重试延迟为 `oriErrRetryBaseDelay * 2^(n-1)`。
oriErrMaxTotalRetry	number	否	`0`	最大总重试次数（跨窗口累计）。设为 `0` 表示不限制。
needSyncAnalyzeError	boolean	否	`true`	是否在重试耗尽后发起错误诊断请求，以细化错误码。
analyzeTimeout	number	否	`3000`	网络诊断请求超时时间（ms）。
ignoreErrorCodes	(string \| number)[]	否	`[]`	需要忽略、不上报的错误码列表。
AudioTrack	false \| IAudioTrackConfig	否	-	PC 端音频轨道切换插件配置。传 `false` 可禁用该插件。
AudioTrackMobile	false \| IAudioTrackMobileConfig	否	-	移动端音频轨道切换插件配置。传 `false` 可禁用该插件。
DanmuPlugin	boolean \| IDanmuConfig	否	-	弹幕及面板配置。支持配置弹幕文字大小、透明度、展示区域等参数。
DefinitionDemotePlugin	IDefinitionDemotePlugin	否	-	清晰度降级配置。
EncryptHlsPlugin	boolean \| Partial<IEncryptHlsPluginConfig>	否	-	HLS 加密播放配置。
vodLogOpts	Partial<IVodLogOptsConfig>	否	-	质量日志上报配置。
logTeaAppId	number	否	`火山国内：4951，海外：323254`	日志tea的id，一般不需要配置，播放器会自动设置。
autoBitrateOpts	IAutoBitrateOpts	否	-	多码率自适应播放配置。
adaptRange	IAdaptRange	否	-	动态 Buffer 配置。
Subtitle	ISubtitleConfig	否	-	外挂字幕配置。
MemoryPlay	boolean \| IMemoryPlayConfig	否	-	记忆播放配置。
music	IMusicConfig	否	-	音乐播放器配置。
AutoplayPlugin	IAutoplayPluginConfig	否	-	自动播放配置。
playListPlugin	IPlayListConfig	否	-	播放列表配置。
dynamicwatermark	IWatermarkConfig	否	-	动态水印配置。
thumbnail	IThumbnailConfig	否	-	进度条预览缩略图配置。
progressDot	IDot[]	否	-	进度条标记配置
mode	number	否	`0`	移动端下倍速、清晰度等选择弹窗的样式 `0`: 从页面底部弹出 `1`: 从播放器容器内部右侧弹出 `2`: 覆盖播放器整个容器的方式弹出
seekedStatus	"pause" \| "play" \| "auto"	否	`play`	seek操作结束之后播放器的状态，如果取值为auto，则维持原播放状态, 默认是seek之后直接播放 `play`: 播放 `pause`: 暂停 `auto`: 保持操作前的状态
onMediaExpired	`() => Promise<SourceConfig>`	否	-	播放源过期的回调函数。可用来更新播放源数据。
onTokenExpired	`() => Promise<IPlayAuthTokenConfig>`	否	-	临时播放 Token 过期时的回调函数，可用来更新临时播放 Token。

IPlayAuthTokenConfig

Vid 播放配置。

配置项	类型	必选	默认值	描述
playAuthToken	string	是	-	应用服务端生成的临时播放凭证。
defaultDefinition	string	否	-	默认清晰度。对应 GetPlayInfo 接口返回的 `Definition`。为空时默认为接口返回的最高清晰度。
playDomain	string	否	`https://vod.volcengineapi.com`	获取播放地址的请求域名。
needPoster	boolean	否	`false`	是否使用您在视频点播控制台上设置的封面图。取值如下： `false`：否。 `true`：是。说明请确保您已在视频点播控制台中生成和设置封面图，详见封面图和封面候选。
needThumbs	boolean	否	`false`	是否使用您在视频点播控制台上生成的雪碧图。取值如下： `false`：否。 `true`：是。说明请确保您已通过视频点播媒体处理服务生成雪碧图，详见雪碧图。
needBarrageMask	boolean	否	`false`	是否使用您在视频点播控制台上生成的蒙版弹幕。取值如下： `false`：否。 `true`：是。说明请确保您已通过视频点播媒体处理服务生成蒙版弹幕。
needDefinitionList	boolean	否	`true`	是否需要获取展示多个清晰度。
keyToken	string	否	-	用于 HLS 标准加密播放的 keyToken。
reqParams	Record<string, string \| number \| boolean>	否	-	可携带aid等透传参数，如: {aid: 1234}，以playAuthToken下发的参数的优先级最高。具体可传参数见签发 PlayAuthToken
definitionMap	Record<string, string \| definitionItem>	否	-	定义清晰度的映射。
retryCount	number	否	`1`	点播服务发生 502 错误时的重试次数。
autoDemoteDefinition	string	否	-	清晰度自动降级开启时的自动档位，对应GetPlayInfo返回的Definition字段
autoDemoteDefinitionTextKey	string	否	-	开启清晰度自动降级（`isNeedAutoDemote` 为 `true`）时的自动档位对应的多语言文案 key，取值对应 `languages` 字段中各语种的 `key`。
urlQueryParams	Record<string, string>	否	-	视频地址请求时携带的额外query参数
useMasterM3u8	boolean	否	-	HLS 播放时是否使用master m3u8 地址作为播放源
getDrmAuthToken	`(playAuthIds: string, vid: string, unionInfo: string) => Promise<string>`	否	-	获取 `PrivateDrmAuthToken` 的异步回调，回调入参为： `playAuthIds`: 视频的密钥 ID，对应 GetPlayInfo 接口返回的 `PlayAuthId`。有多个 Key ID 时以英文逗号隔开。 `vid`: 视频 ID `unionInfo`: 由 `unionId` 生成的 `unionInfo`，用来加密`PrivateDrmAuthToken`。

definitionItem

清晰度定义。

属性	描述
definition	清晰度。
definitionTextKey	清晰度多语言 Key

IPoster

封面配置

配置项	类型	必选	默认值	描述
poster	string	是	-	封面图 URL 地址。
isEndedShow	boolean	否	`true`	是否在播放结束之后显示封面图。
hideCanplay	boolean	否	`false`	是否播放后隐藏封面图。 `true`：播放后隐藏，在视频地址更新后会重新显示封面图。 `false`：在 `play` 事件触发后隐藏封面图。
notHidden	boolean	否	`false`	是否一直显示封面图。
fillMode	"fixWidth" \| "fixHeight" \| "cover" \| "contain"	否	-	封面图填充方式。取值如下： `fixWidth`：宽度方向填充，不会被拉伸压缩。 `fixHeight`：高度方向填充，不会被拉伸压缩。 `cover`：完全覆盖容器，多余部分会被裁剪。 `contain`：完全覆盖，与容器不匹配时会被拉伸压缩。

IPIPConfig

画中画配置。

配置项	类型	必选	默认值	描述
showIcon	boolean	否	`false`	是否显示画中画按钮。取值如下： `true`：显示画中画按钮。 `false`：不显示画中画按钮。
preferDocument	boolean	否	`false`	是否优先使用网页画中画。说明仅浏览器支持 `DocumentPictureInPicture` 时才生效。
width	number	否	-	网页画中画模式下窗口的宽度。
height	number	否	-	网页画中画模式下窗口的高度。
docPiPNode	HTMLElement	否	-	网页画中画模式下窗口的根节点。
docPiPStyle	`(...arg: any) => string`	否	-	文档画中画窗口的 css style

IFullscreenConfig

全屏配置。

配置项	类型	必选	默认值	描述
useCssFullscreen	boolean	否	`false`	是否使用页面全屏代替系统全屏。取值如下： `true`：页面全屏。 `false`：系统全屏。
rotateFullscreen	boolean	否	`false`	是否使用旋转横屏。取值如下： `false`：否。 `true`：是，即全屏后，如在竖屏状态下，播放器会把 `dom` 旋转 90 度实现横屏效果。说明该参数的优先级高于 `useCssFullscreen` 参数。该参数一般用于移动端。
useScreenOrientation	boolean	否	`false`	旋转全屏后，锁定屏幕方向。适应于移动端设备全屏观看横屏视频
lockOrientationType	string	否	`landscape`	旋转全屏后，锁定屏幕方向类型，默认是横屏，可选值见orientation
target	HTMLElement	否	`null`	自定义全屏功能的 `dom`。默认是播放器根节点。该参数必须是 `player.root` 的父辈节点，适用于解决全屏时和 `player.root` 同级的 `dom`需要显示的场景。
disable	boolean	否	`false`	是否禁用全屏按钮。 `true`：禁用。不渲染全屏按钮。 `false`：不禁用。
needBackIcon	boolean	否	`false`	全屏的时候是否显示右上角返回按钮。取值如下： `false`：不显示右上角返回按钮。 `true`：显示右上角返回按钮。说明此参数一般用于移动端。
switchCallback	`(...arg: any) => any`	否	`null`	全屏切换自定义实现。该函数配置相当于完全替代插件内部的切换逻辑。

ICommonStyle

播放器关键点样式。

配置项	类型	必选	默认值	描述
progressColor	string	否	无	进度条底色。
playedColor	string	否	无	播放完成部分进度条底色。
cachedColor	string	否	无	缓存部分进度条底色。
sliderBtnStyle	CSSStyleDeclaration	否	无	进度条滑块样式。
volumeColor	string	否	无	音量颜色。

Stream

播放地址列表，可配置多线路和多清晰度。

配置项	类型	必选	默认值	描述
streamType	string	否	-	URL 类型，取值为： `"rtm"` `"flv"` `"mp4"` `"hls"`
url	Url	是	-	视频播放地址。
definition	string	否	-	清晰度 key
mapDefinition	string	否	-	映射清晰度 key
definitionTextKey	string	否	-	多语言词典中对应的 key。比如设置 `definitionTextKey: HD_TEXT_KEY` 以及 `languages: {zh: {HD_TEXT_KEY: '高清'}}`，则清晰度切换选项显示 “高清”。不设置则显示 `definition` 的值。
codec	ICodecType	否	`unknown`	编码格式
lineId	string \| number	否	-	线路唯一 ID
lineTextKey	string	否	-	多语言词典中对应的 key。比如 `lineTextKey: LINE_ONE`。
width	number	否	-	该码流视频的宽度，单位为像素
height	number	否	-	该码流视频的高度，单位为像素
bitrate	number	否	-	码流的平均码率
bandwidth	number	否	-	码流流畅播放需要的带宽
urlExpireTimestamp	number	否	-	地址的过期时间戳，单位秒(s)，vid模式下不用输入，播放器自动获取。如果是火山引擎的CDN分发地址，在不传入过期时间戳时，则需指定urlType，支持A-E类型，其他云厂商或者业务服务器存储的地址不支持。
kid	string	否	-	视频为加密视频时的密钥KeyId，对应GetPlayInfo 接口返回的PlayInfoList项中的 PlayAuthId
secretKey	string	否	-	私有加密播放的加密密钥，对应GetPlayInfo 接口返回的PlayInfoList项中的 PlayAuth
drmType	EDRMTYPE	否	-	视频为加密视频时的加密类型

IVolume

音量配置。

配置项	类型	必选	默认值	描述
position	POSITIONS	否	`POSITIONS.CONTROLS_RIGHT`	插件Dom挂载的位置，默认播放器底部控制栏右侧
index	number	否	`1`	插件在挂载的位置的排序权重
disable	boolean	否	`false`	是否禁用插件交互行为，即是否隐藏音量调节按钮
showValueLabel	boolean	否	`false`	是否在音量调节slider上方显示当前音量数值
default	number	否	`0.6`	默认音量大小，取值范围0-1
miniVolume	number	否	`0.2`	静音恢复的时候最小音量

ISdkErrorConfig

播放器发生错误时的 UI 配置。

配置项	类型	必选	默认值	描述
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	否	`播放發生錯誤，點擊刷新試試吧`	香港繁体中文错误文案。

IDanmuConfig

弹幕配置。

配置项	类型	必选	默认值	描述
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`：字体大小为 14 px。 `50`：字体大小为 16 px。 `100`：字体大小为 20 px。
active	boolean	否	`false`	是否默认开启弹幕。取值如下： `false`：关闭。 `true`：开启。
danmuItems	DanmuItem[]	否	-	弹幕列表。
maskConfig	IMaskConfig	否	-	蒙版弹幕配置
maskActive	boolean	否	`false`	是否开启蒙版弹幕，即对应智能挡板开关

DanmuItem

弹幕项

配置项	类型	必选	默认值	描述
id	string	是	-	弹幕唯一 ID。
txt	string	是	-	弹幕文案。
start	number	否	`0`	弹幕出现时间，单位为毫秒。
duration	number	否	`5000`	弹幕持续显示时长，单位为毫秒。
style	CSSStyleDeclaration	否	-	弹幕样式。示例如下：`style : { color: '#ff9500', fontSize: '20px', padding: '2px 11px'}`

IDefinitionDemotePlugin

清晰度降级配置。

配置项	类型	必选	默认值	描述
isNeedAutoDemote	boolean	否	`true`	是否开启自动降级，取值如下： `false`：关闭自动降级。 `true`：开启自动降级。
demotePriority	string[]	是	`[]`	清晰度降级顺序。数组中的元素需与 `playList` 中的 `definition` 相对应。
longWaitingTime	number	否	`5000`	长时间卡顿的时间阈值，单位为毫秒。卡顿时长超过该值，即视为长时间卡顿。发生长时间卡顿时，SDK 会触发 `LONG_WAITING` 事件。
oftenWaitingCount	number	否	`3`	频繁卡顿的次数阈值。`oftenWaitingTime` 内卡顿次数大于或等于阈值时，SDK 会触发 `OFTEN_WAITING` 事件，提示发生了频繁卡顿。
oftenWaitingTime	number	否	`5000`	频繁卡顿监测的时间范围。`oftenWaitingTime` 内卡顿次数大于或等于 `oftenWaitingCount` 时，SDK 会触发 `OFTEN_WAITING` 事件，提示发生了频繁卡顿。
isNeedShowTips	boolean	否	`true`	卡顿时是否显示清晰度降级提示 toast。
toastShowTime	number	否	`3000`	清晰度降级提示 toast 的显示时长，单位为毫秒。

IDashPluginConfig

DASH 播放配置。

配置项	类型	必选	默认值	描述
vid	string	否	-	视频 ID。
definitionText	Record<string, string>	是	-	清晰度映射文案。
defaultDefinition	string	否	`列表第一个`	默认清晰度。
preloadTime	number	否	`50`	预加载时间，单位为毫秒。

IEncryptHlsPluginConfig

HLS 加密播放配置。

配置项	类型	必选	默认值	描述
playDomain	string	否	`https://vod.volcengineapi.com`	获取播放地址的请求域名。
playAuthToken	string	否	-	播放地址获取token，由服务端生成下发，详见播放临时安全凭证（PlayAuthToken）

IVodLogOptsConfig

质量日志上报配置。

配置项	类型	必选	默认值	描述
line_app_id	number	是	-	视频点播应用 ID。您可在视频点播控制台 > 点播SDK > 应用管理页面获取应用 ID（App ID）。
line_user_id	string \| number	是	-	用于识别单一用户的 ID，可在QoE指标中用于用户维度的筛选，也可以用于单点追查查找单用户的播放日志用户 ID 对应于单点追查功能的查询条件中的设备 ID 维度。如不设置用户 ID，VePlayer 将根据用户浏览器随机生成一个值，该值会在浏览器端缓存。
tag	string	否	`普通视频`	业务标签。对应于质量平台上的业务类型维度，其作用是区分业务中的不同场景，以便进行多维度分析。举例来说，假设您的应用中包含短视频和长视频两个场景，则可分别将 `tag` 设为 `short` 和 `long`。这样一来，您就能够在质量平台上通过业务标签维度查询或过滤不同场景的数据。
subtag	string	否	-	自定义子标签。对应于质量平台上的自定义标签维度，与 `tag` 配合使用，可用于区分同一业务类型下更为细分的音视频类型，比如加密视频、非加密视频、音频等。
codec_type	"h264" \| "h265"	否	`unknown`	视频编码类型，取值如下 `h264`：H.264 `h265`：H.265

IAutoBitrateOpts

自适应码率配置。

配置项	类型	必选	默认值	描述
enable	boolean	是	`false`	是否开启自适应码率功能。
startWithAuto	boolean	否	`false`	是否以自动清晰度档位起播。开启自适应码率功能且 `defaultDefinition` 为 `auto` 时，才会以自动清晰度档位起播。
showRealDefinition	boolean	否	`false`	自动清晰度档位是否展示当前实际清晰度，如自动（720p）。
autoDefinitionText	string	否	`自动`	自动清晰度档位的显示文案。
definitionTextKey	string	否	`DEFINITION_AUTO`	自动清晰度档位的多语言 key。

ISubtitleConfig

外挂字幕配置。

配置项	类型	必选	默认值	描述
position	string	否	`controlsRight`	图标位置。
index	number	否	`6`	图标排列权重。
list	ISubTitleItem[]	否	-	字幕列表。
isDefaultOpen	boolean	否	`true`	是否默认打开字幕。
isShowIcon	boolean	否	`true`	是否显示图标。
mode	"external" \| "native"	否	`external`	字幕渲染模式，取值如下： `"external"`：外挂字幕 `"native"`：原生字幕
style	ISubtitleStyle	否	-	字幕样式。

ISubTitleItem

字幕项。

配置项	类型	必选	默认值	描述
language	string \| number	否	-	字幕语言。
id	string \| number	否	-	字幕 ID。
isDefault	boolean	否	`false`	是否为默认选择的字幕。
text	string	否	-	字幕名称。
url	string	否	-	外挂字幕 URL 地址。
list	IListItem[]	否	无	字幕内容列表。非 `url` 形式时使用。

IListItem

字幕内容项。

配置项	类型	必选	默认值	描述
start	number	是	-	开始时间，单位为秒。
end	number	是	-	结束时间，单位为秒。
list	ITextItem[]	是	-	字幕数据列表。

ITextItem

字幕数据单元

配置项	类型	必选	默认值	描述
start	number	是	-	开始时间，单位为秒。
end	number	是	-	结束时间，单位为秒。
text	string[]	是	-	字幕文案数组。
index	number	否	-	字幕顺序。

ISubtitleStyle

字幕样式配置。

配置项	类型	必选	默认值	描述
follow	boolean	否	`false`	是否跟随控制栏调整位置。
mode	"stroke" \| "bg"	否	`'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	"double" \| "single" \| "three"	否	`double`	最大显示行数。取值如下： `"double"`：两行 `"single"`：一行 `"three"`：三行
fontColor	string	否	`#fff`	字体颜色。可设为 16 位颜色值或 RGB 值。

IMemoryPlayConfig

记忆播放配置。

配置项	类型	必选	默认值	描述
memoryId	string \| number	是	`options.vid \|\| options.url`	存储标识id
minStartTime	number	否	`1`	判断播放是否已开始的最小时间阈值。如果播放时长短于此阈值，则不算作已开始播放，存储的时间进度为 0。
minEndTime	number	否	`1`	判断播放是否已结束的最小时间阈值，即距离结束还剩余的时间不足此阈值时，即视为播放已结束。播放结束时，不再存储时间进度，并将之前的进度清零。
saveTime	`(id: number \| string, time: number) => unknown`	否	-	设置时间函数
getTime	`(id: number \| string) => number \| Promise<number>`	否	-	获取最后一次播放时间函数

IMusicConfig

音乐播放模式配置。

配置项	类型	必选	默认值	描述
offline	boolean	否	`false`	是否启用离线下载播放。
abCycle	IABCycle \| null	否	`null`	AB 循环播放配置。
timeScale	number	否	`15`	快进快退时间跨度，单位为秒。
mode	PlayModeType	否	`order`	循环模式。
list	IMusicListItem[]	否	`[]`	播放列表。

IABCycle

AB 循环播放配置。

配置项	类型	必选	默认值	描述
start	number	是	`0`	AB 循环段开始时间，单位为秒。
end	number	是	`音乐结束时间点`	AB 循环段结束时间，单位为秒。
loop	boolean	否	`false`	AB 段是否循环播放。

IAutoplayPluginConfig

自动播放配置。

配置项	类型	必选	默认值	描述
enableDegradeMuteAutoplay	boolean	否	`false`	是否开启降级静音自动播放。开启后，如果当前浏览器环境不支持有声音自动播放，则降级为静音自动播放。
userActionDom	Node	否	`window.document.body`	用户触发自动播放的目标 dom。
enableUserActionAutoplay	boolean	否	`false`	是否开启任意用户行为触发自动播放。开启后，第一次用户的任意点击可以触发播放器的自动播放。取值如下： `true`：开启 `false`：不开启
showUnmuteBtn	boolean	否	`true`	静音自动播放时，是否在播放器容器上居中展示取消静音的大按钮。

IPlayListConfig

播放列表插件配置。

配置项	类型	必选	默认值	描述
position	string	否	`controlsLeft`	按钮位置。取值如下： `controlsLeft`: 播控栏左侧 `controlsRight`: 播控栏右侧 `controlsCenter`: 播控栏中间 `rootLeft`：播放器根节点左侧 `rootRight`：播放器根节点右侧 `rootTop`：播放器根节点顶部 `root`：播放器根节点
index	number	否	`20`	按钮在所在区域的次序。默认值为 `2`，表示在播放按钮后。
list	IPlayListItem[]	是	`[]`	播放列表数据。
mode	EPlayMode	否	`order`	循环模式，取值如下： `order`: 不循环播放，即列表中最后一个视频播放完成后就停止播放。 `loop`: 列表循环，即列表中最后一个视频播放完成后将自动开始重新播放列表中的第一个视频。
defaultIndex	number	否	`order`	默认起始的播放次序。
isItemClickHide	boolean	否	`true`	列表点击之后是否隐藏。
toggleMode	TOGGLE_MODES	否	`click`	列表行为触发模式。
isShowIcon	boolean	否	`true`	是否显示播放列表按钮。

IPlayListItem

播放列表项配置，支持 DirectUrl 和 Vid + playAuthToken 两种播放模式。

配置项	类型	必选	默认值	描述
url	string	否	-	视频地址。说明 `playAuthToken` 为空时，此参数必传。
playAuthToken	string	否	-	播放临时安全凭证，由业务的 AppServer 签发。说明 `url` 为空时，此参数必传。
vid	string	是	-	视频的唯一 ID。不传则取视频所在列表数组的序号。
poster	string	否	-	视频封面图地址。
title	string	否	-	视频标题。
duration	number	否	-	视频时长，单位为秒。

IWatermarkConfig

动态水印配置。

配置项	类型	必选	默认值	描述
enable	boolean	是	`false`	是否开启动态水印，取值如下： `true`：开启动态水印 `false`：关闭动态水印
content	string	是	-	水印文案。
displayType	0 \| 1 \| 2	否	`1`	水印展示形式，取值如下： `0`：固定位置 `1`：全屏滚动 `2`：随机闪烁
fontSize	string \| number	否	`12`	水印字体大小。`number`类型时单位为 px，`string` 类型时需要携带单位。
fontColor	string	否	-	水印字体颜色。
opacity	number	否	`0.3`	水印不透明度。取值范围：[0~1]。
tickerSpeed	"SLOW" \| "MODERATE" \| "FAST"	否	`MODERATE`	水印闪烁速度，取值如下： `MODERATE`：适中 `FAST`：较快 `SLOW`：较慢
fontFamily	string	否	-	水印字体类型
top	number	否	`0`	水印相对于播放容器顶部的距离，单位为 px
left	number	否	`0`	水印相对于播放容器左侧的距离，单位为 px。
bottom	number	否	-	水印相对于播放容器底部的距离，单位为 px。
right	number	否	-	水印相对于播放容器右侧的距离，单位为 px。

IThumbnailConfig

进度条预览缩略图配置。

配置项	类型	必选	默认值	描述
urls	string[]	是	-	雪碧图地址数组。
pic_num	number	是	-	缩略小图总张数。
col	number	是	-	雪碧大图中每列包含的缩略小图数量。
row	number	是	-	雪碧大图中每行包含的缩略小图数量。
height	number	否	-	缩略小图高度，单位为 px。
width	number	否	-	缩略小图宽度，单位为 px。
hidePortrait	false	否	`false`	是否在竖屏的时候隐藏缩略图。

IDot

进度条标记点配置。

配置项	类型	必选	默认值	描述
id	string \| number	是	`1`	进度条标记点
time	number	是	`0`	标记点所在的播放时间
text	string	否	-	进度条自定义文案
duration	number	否	`1`	标记点持续的时间，单位秒
style	CSSStyleDeclaration	否	-	进度条自定义的CSS Style样式

CodecType

视频编码格式。

属性	描述

Url

URL 类型。支持字符串和数组。如果是数组形式，则每个数组项应包含视频播放地址 src 和视频容器格式类型 type，在 HTML <video /> 元素中使用 <source /> 元素设置多种格式的视频源。以 <source /> 元素设置的地址不支持 MSE（媒体源扩展）播放场景，例如 PC 上播放 HLS 视频或安卓上播放 HLS 加密视频。

类型

string | Array<{ src: string; type?: string; [propName: string]: any }>

StrategyInitOptions

播放器预初始化配置

类型

{
  appId: number;
  region?: TRegionType;
  strategies: StrategyConfigOptions;
  deviceId?: string;
  plugins?: any[];
  Module?: typeof VeStrategy;
}

成员

名称	类型	描述
appId	`number`	应用 ID
region	`TRegionType \| undefined`	用户所在区域
strategies	`StrategyConfigOptions`	策略配置
deviceId	`string \| undefined`	设备 ID
plugins	`any[] \| undefined`	手动注入依赖插件，默认自动加载
Module	`any`	策略 Module，默认自动加载

StrategyConfigOptions

策略配置。

类型

{
  [StrategyNames.H265]?: boolean | IH265Config;
  [StrategyNames.PRELOAD]?: boolean | IPreloadConfig;
  [StrategyNames.ADAPT_RANGE]?: boolean | IAdaptRangeConfig;
}

成员

名称	类型	描述
h265	`any`	H.265 策略配置。
preload	`boolean \| IPreloadConfig \| undefined`	预加载配置。
adaptRange	`boolean \| IAdaptRangeConfig \| undefined`	动态 Buffer 配置。

IPreloadConfig

预加载初始配置

类型

{
  preloadScene?: PreloadScene;
  format?: PreloadFormat;
  prevCount?: number;
  nextCount?: number;
  preloadTime?: number;
  preloadMaxCacheCount?: number;
  Strategy?: any;
  disabled?: boolean;
}

成员

名称	类型	描述
preloadScene	`PreloadScene \| undefined`	预加载场景 0：手动执行 1：字段执行
format	`PreloadFormat \| undefined`	视频格式 mp4: mp4格式 hls: hls格式
prevCount	`number \| undefined`	向前预加载视频个数。Feed 流场景时生效。
nextCount	`number \| undefined`	向后预加载视频个数。Feed 流场景生效
preloadTime	`number \| undefined`	单个视频预加载时长
preloadMaxCacheCount	`number \| undefined`	最大视频缓存个数
Strategy	`any`	预加载依赖 Module
disabled	`boolean \| undefined`	是否禁用预加载

PreloadScene

类型：enum

预加载场景

属性	值	描述
NORMAL	`0`	普通场景（手动执行预加载）
FEED	`1`	Feed 流场景（播放器自动执行预加载）

IPreloadStream

预加载视频资源

类型

{
  vid: string;
  url: string;
  definition: string;
  streamType: string;
  codec: string;
  bitrate: number;
  duration: number;
  size: number;
}

成员

名称	类型	描述
vid	`string`	视频 ID
url	`string`	视频播放地址
definition	`string`	视频清晰度
streamType	`string`	视频流类型，支持 mp4、hls
codec	`string`	视频编码格式，当前仅支持 mp4
bitrate	`number`	码率, 数据统计需要，选填
duration	`number`	视频时长，数据统计需要，选填
size	`number`	视频大小，数据统计需要，选填

StrategyNames

类型：enum

策略名称

属性	值	描述
H265	`'h265'`	H.265 策略
PRELOAD	`'preload'`	预加载策略
ADAPT_RANGE	`'adaptRange'`	动态 Buffer

最近更新时间：2026.10.28 18:49:02

这个页面对您有帮助吗？

有用

无用

视频点播

IPlayerConfig #

IPlayAuthTokenConfig #

definitionItem #

IPoster #

IPIPConfig #

IFullscreenConfig #

ICommonStyle #

Stream #

IVolume #

ISdkErrorConfig #

TipsTextConfig #

IDanmuConfig #

DanmuItem #

IDefinitionDemotePlugin #

IDashPluginConfig #

IEncryptHlsPluginConfig #

IVodLogOptsConfig #

IAutoBitrateOpts #

ISubtitleConfig #

ISubTitleItem #

IListItem #

ITextItem #

ISubtitleStyle #

IMemoryPlayConfig #

IMusicConfig #

IABCycle #

IAutoplayPluginConfig #

IPlayListConfig #

IPlayListItem #

IWatermarkConfig #

IThumbnailConfig #

IDot #

CodecType #

Url #

StrategyInitOptions #

StrategyConfigOptions #

IPreloadConfig #

PreloadScene #

IPreloadStream #

StrategyNames #