## IPlayerConfig 播放器实例化配置。 | 配置项 | 类型 | 必选 | 默认值 | 描述 | | :-- | :-- |:-- | :-- | :-- | | id | string | 否 | \- | 播放器容器 ID。播放器将被插入在该容器中。 |\ ||||| :::tip|\ |||||`id` 和 `root` 参数需至少传入 1 个。如果都传入，则优先使用 `root` 参数。 |||||| | root | HTMLElement | 否 | \- | 播放器容器 DOM 元素。VePlayer 将被插入该容器中。 |\ ||||| :::tip|\ |||||`id` 和 `root` 参数需至少传入 1 个。如果都传入，则优先使用 `root` 参数。 |||||| | url | [Url](#url) | 否 | - | 视频播放地址。 | | vid | string | 否 | \- | 视频点播服务中的视频 ID。推荐填写，以方便跟踪该视频的播放质量。您将音视频上传至视频点播服务后，可通过以下方式获取 `Vid`：
\ |||||- 在视频点播控制台获取。 |\ |||||- 通过 [GetMediaList](https://www.volcengine.com/docs/4/69205) 接口获取 `Vid`。 |\ |||||- 如果您设置了媒资上传完成的回调事件，会在 [FileUploadComplete](https://www.volcengine.com/docs/4/4655) 中返回 `Vid`。 | | | getVideoByToken | [IPlayAuthTokenConfig](#iplayauthtokenconfig) | 否 | - | Vid 播放配置项。应用服务端需通过 `vid` 生成临时临时播放 Token，下发给客户端。 | | drmType | [EDRMTYPE](1248901#edrmtype) | 否 | - | 视频加密类型 | | encryptSessionId | string | 否 | - | 私有加密会话id | | playAuthId | string | 否 | - | 视频为加密视频时的密钥KeyId，对应[GetPlayInfo](https://www.volcengine.com/docs/4/2918) 接口返回的PlayInfoList项中的 PlayAuthId | | playAuth | string | 否 | - | 私有加密播放的加密密钥，对应[GetPlayInfo](https://www.volcengine.com/docs/4/2918) 接口返回的PlayInfoList项中的 PlayAuth | | streamType | "mp4" \| "hls" \| "dash" \| "rtm" \| "flv" | 否 | \- | 视频格式。取值如下：\ |||||- `mp4` |\ |||||- `hls` |\ |||||- `dash` |\ |||||- `flv` | |\ ||||| :::tip|\ |||||如果 `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`：否 | |\ ||||| :::tip|\ |||||受限于浏览器策略，自动播放不一定能成功，取决于浏览器环境、用户行为、浏览器配置等。详情请参考[自动播放](https://www.volcengine.com/docs/4/68693#%E8%87%AA%E5%8A%A8%E6%92%AD%E6%94%BE)。 |||||| | poster | string \| [IPoster](#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; } | 否 | \- | 多语言词典。可设置每个语种的词典，例如：
```javascript
{ zh: { PIP: '画中画' }, en: { PIP: 'pip' }}
``` |\ ||||| :::tip|\ |||||了解更多，请参见[默认词典](https://www.volcengine.com/docs/6469/127529)。 |||||| | pip | boolean \| [IPIPConfig](#ipipconfig) | 否 | PC: {position: 'controlsRight', index: 2.5, showIcon: true}; mobile：false | 画中画配置。 |\ ||||| :::tip|\ |||||画中画功能由浏览器提供。如果浏览器不支持，即使传入此配置也不会显示画中画按钮。 |||||| | fullscreen | [IFullscreenConfig](#ifullscreenconfig) | 否 |

{position: 'controlsRight', index: 0, rotateFullscreen: false, useCssFullscreen: false, target: null, switchCallback: null, disable: false, needBackIcon: false }

| 全屏配置。 | | alwaysShowDefinition | boolean | 否 | false | 是否总是显示清晰度切换控件，即只有单个清晰度时也显示清晰度切换控件。 | | definitionText | string | 否 | HD | `url` 参数对应视频的清晰度文案。 |\ ||||| :::tip|\ |||||仅 `alwaysShowDefinition` 为 `true` 时有效。 |||||| | definitionTextKey | string | 否 | \- | `url` 参数对应视频的清晰度文案的多语言 key，对应参数 `languages` 中的文案。 |\ ||||| :::tip|\ |||||仅 `alwaysShowDefinition` 为 `true` 时有效，优先级高于 `definitionText`。 |||||| | codec | [ICodecType](1248901#icodectype) | 否 | \- | 视频编码格式。 |\ ||||| :::tip|\ |||||- 在已知视频编码方式的情况下推荐传入，以便日志分析。 |\ |||||- 在 `useSoftDecoding` 参数为 `true`（开启 H.265 兼容降级模式）时，建议传入，可提升软解初始效率。 |||||| | region | [TRegionType](1248901#tregiontype) | 否 | cn | 点播服务所在区域，影响服务接口的请求域名 | | userRegion | [TRegionType](1248901#tregiontype) | 否 | cn | 用户所在区域，影响日志请求的上报服务及动态依赖拉取的域名 | | pluginPublicPath | string | 否 | https://lf-unpkg.volccdn.com/obj/vcloudfe/sdk/@volcengine/veplayer/${version}/plugin | 插件加载的路径。您可从 [SDK 离线包](https://www.volcengine.com/docs/4/67077#%E5%BC%95%E5%85%A5%E4%BE%9D%E8%B5%96)中获取插件，然后将插件文件放置于应用服务器上，再在初始化播放器时指定插件地址。 | | startTime | number | 否 | 0 | 起播时间，单位为秒。 | | playsinline | boolean | 否 | true | 是否启用内联播放模式。`playsinline` 属性是 HTML5 视频标签的一个属性，用于指定视频是否应在页面文档内播放。\ |||||- `true`：启用内联播放模式，表示视频将在页面文档内播放。 |\ |||||- `false`：禁用内联播放模式。
| |\ ||||| :::tip|\ |||||此参数仅在在移动端生效。此参数取值为 `true` 时，会在初始化 `video` 或 `audio` 对象的时候，将 `playsinline`、`webkit-playsinline`、`x5-playsinline` 三个属性设置为 `true`，请参考 [New Policies for iOS](https://webkit.org/blog/6784/new-video-policies-for-ios/) 了解内联播放模式相关知识。iOS 上内联播放模式的支持情况如下： |\ |||||- iOS 10 及以上系统 Safari 浏览器支持配置内联播放模式。 |\ |||||- iOS 10 以下系统 Safari 浏览器不支持配置内联播放模式，默认播放即进入系统全屏。 |||||| | videoAttributes | Partial | 否 | 无 | `video` 标签扩展属性。播放器初始化时会设置在 `videoElement` 或 `audioElement` 对象上。请参考 [HTMLMediaElement](https://developer.mozilla.org/en-US/docs/Web/API/HTMLMediaElement#properties) 查看支持的属性。 | | fluid | boolean | 否 | false | 是否启用流式布局。启用流式布局后，播放器会根据屏幕宽度进行自适应调整，以确保在不同屏幕尺寸上都能呈现良好的显示效果。取值如下：\ |||||- `true`：启用流式布局 |\ |||||- `false`：停用流式布局 | |\ ||||| :::tip|\ |||||启用流式布局时，播放器的宽高比与 `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](https://developer.mozilla.org/en-US/docs/Web/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](#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](1248901#imobileconfig) | 否 | - | 移动端交互插件配置。 | | start | [IStartConfig](1248901#istartconfig) | 否 | - | 播放器中间切换暂停/播放的按钮插件配置 | | enableHlsMSE | boolean | 否 | - | 是否开启 HLS 视频的 MSE 模式。仅移动端生效。默认情况下，在移动端使用原生 `video` 播放 HLS 视频。开启后，将采用 MSE 方式播放 HLS 视频，实现更好的兼容性、能控制缓存、节省流量。 | | useHlsPluginForSafari | boolean | 否 | true | 在 PC Safari 上是否 HLS 插件播放视频。取值如下：\ |||||- `true`：使用 HLS 插件。SDK 会自动加载 HLS 插件。 |\ |||||- `false`：不使用 HLS 插件。 | | | enableMp4MSE | boolean | 否 | false | 是否开启 MP4 视频的 MSE 模式。开启后，将采用 MSE 方式播放 MP4，实现精确的 Seek 加载、视频的无缝切换、流量节省等功能。 | | playList | [Stream](#stream)[] | 否 | - | 播放地址列表。 | | defaultDefinition | string | 否 | playList第一项 | 默认清晰度。仅当 `playList` 有值时生效。 | | plugins | any[] | 否 | - | 插件，可自行选择安装的插件，支持[西瓜播放器插件](https://h5player.bytedance.com/plugins/)。 | | ignores | string[] | 否 | [] | 用于禁用插件。VePlayer 内置了一些常用的功能插件。如需禁用某一内置插件，可传入插件名称（不区分大小写）。 | | umdUrlMap | Record | 否 | \- | UMD 依赖备用地址。用于依赖的 CDN 发生网络错误时的降级备用地址。支持的依赖如下：
\ |||||- `hls`：非加密 HLS 播放。 |\ |||||- `flv`：FLV 播放。 |\ |||||- `XGVideo`：软解播放。 |\ |||||- `hlsEncrypt`：加密 HLS 播放。 |\ |||||- `dash`：DASH 播放。 |\ |||||- `mp4Encrypt`：加密 MP4 播放。 |\ |||||- `danmujs`：弹幕。 |\ |||||- `danmuMask`：蒙版弹幕。 |\ |||||- `subtitle`：外挂字幕。 | | | unionId | string | 否 | - | 唯一 ID，用于[私有加密方案](https://www.volcengine.com/docs/4/106524)。 | | useSoftDecoding | boolean | 否 | false | 是否启用软解。取值如下：
\ |||||- `true`：启用。 |\ |||||- `false`：不启用。 | |\ ||||| :::tip|\ |||||- 移动端浏览器不支持 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类型](https://www.volcengine.com/docs/4/177191)，其他云厂商或者业务服务器存储的地址不支持。 | | urlExpireDiff | number | 否 | 60 | 判断视频播放地址过期的阈值。单位为秒。如设置为 500，则 SDK 会在地址过期前 500 秒时就触发过期事件 `Events.MEDIA_EXPIRED`，为您更新地址留足缓冲时间。 | | urlCheckExpireInterval | number | 否 | 400 | 视频播放地址过期检测的时间间隔。单位为毫秒。播放器以这个时间间隔轮询地将播放器所在的客户端时间与过期时间戳进行比较，以判断地址是否过期。 | | debug | boolean | 否 | false | 是否开启日志打印。 | | sdkErrorPlugin | [ISdkErrorConfig](#isdkerrorconfig) | 否 | - | 播放器报错信息。支持配置播放异常时显示的异常文案、图片以及是否提供刷新按钮等。 | | DanmuPlugin | boolean \| [IDanmuConfig](#idanmuconfig) | 否 | - | 弹幕及面板配置。支持配置弹幕文字大小、透明度、展示区域等参数。 | | DefinitionDemotePlugin | [IDefinitionDemotePlugin](#idefinitiondemoteplugin) | 否 | - | 清晰度降级配置。 | | EncryptHlsPlugin | boolean \| Partial<[IEncryptHlsPluginConfig](#iencrypthlspluginconfig)\> | 否 | - | HLS 加密播放配置。 | | vodLogOpts | Partial<[IVodLogOptsConfig](#ivodlogoptsconfig)\> | 否 | - | 质量日志上报配置。 | | autoBitrateOpts | [IAutoBitrateOpts](#iautobitrateopts) | 否 | - | 多码率自适应播放配置。 | | adaptRange | IAdaptRange | 否 | - | 动态 Buffer 配置。 | | Subtitle | [ISubtitleConfig](#isubtitleconfig) | 否 | - | 外挂字幕配置。 | | MemoryPlay | boolean \| [IMemoryPlayConfig](#imemoryplayconfig) | 否 | - | 记忆播放配置。 | | music | [IMusicConfig](#imusicconfig) | 否 | - | 音乐播放器配置。 | | AutoplayPlugin | [IAutoplayPluginConfig](#iautoplaypluginconfig) | 否 | - | 自动播放配置。 | | playListPlugin | [IPlayListConfig](#iplaylistconfig) | 否 | - | 播放列表配置。 | | dynamicwatermark | [IWatermarkConfig](#iwatermarkconfig) | 否 | - | 动态水印配置。 | | thumbnail | [IThumbnailConfig](#ithumbnailconfig) | 否 | - | 进度条预览缩略图配置。 | | progressDot | [IDot](#idot)[] | 否 | - | 进度条标记配置 | | mode | number | 否 | `0` | 移动端下倍速、清晰度等选择弹窗的样式\ |||||- `0`: 从页面底部弹出 |\ |||||- `1`: 从播放器容器内部右侧弹出 |\ |||||- `2`: 覆盖播放器整个容器的方式弹出 | | | seekedStatus | "pause" \| "play" \| "auto" | 否 | `play` | seek操作结束之后播放器的状态，如果取值为auto，则维持原播放状态, 默认是seek之后直接播放\ |||||- `play`: 播放 |\ |||||- `pause`: 暂停 |\ |||||- `auto`: 保持操作前的状态 | | | onMediaExpired | () =\> Promise<[SourceConfig](1248901#sourceconfig)\> | 否 | \- | 播放源过期的回调函数。可用来更新播放源数据。 | | onTokenExpired | () =\> Promise<[IPlayAuthTokenConfig](#iplayauthtokenconfig)\> | 否 | \- | 临时播放 Token 过期时的回调函数，可用来更新临时播放 Token。 | ## IPlayAuthTokenConfig Vid 播放配置。 | 配置项 | 类型 | 必选 | 默认值 | 描述 | | :-- | :-- |:-- | :-- | :-- | | playAuthToken | string | 是 | - | 应用服务端生成的临时播放凭证。 | | defaultDefinition | string | 否 | - | 默认清晰度。对应 [GetPlayInfo](https://www.volcengine.com/docs/4/2918) 接口返回的 `Definition`。为空时默认为接口返回的最高清晰度。 | | playDomain | string | 否 | `https://vod.volcengineapi.com` | 获取播放地址的请求域名。 | | needPoster | boolean | 否 | false | 是否使用您在视频点播控制台上设置的封面图。取值如下：
\ |||||- `false`：否。 |\ |||||- `true`：是。 | |\ ||||| :::tip|\ |||||请确保您已在视频点播控制台中生成和设置封面图，详见[封面图和封面候选](https://www.volcengine.com/docs/4/5335)。 |||||| | needThumbs | boolean | 否 | false | 是否使用您在视频点播控制台上生成的雪碧图。取值如下：
\ |||||- `false`：否。 |\ |||||- `true`：是。 | |\ ||||| :::tip|\ |||||请确保您已通过视频点播媒体处理服务生成雪碧图，详见[雪碧图](https://www.volcengine.com/docs/4/1171758)。 |||||| | needBarrageMask | boolean | 否 | false | 是否使用您在视频点播控制台上生成的蒙版弹幕。取值如下：
\ |||||- `false`：否。 |\ |||||- `true`：是。 | |\ ||||| :::tip|\ |||||请确保您已通过视频点播媒体处理服务生成蒙版弹幕。 |||||| | needDefinitionList | boolean | 否 | true | 是否需要获取展示多个清晰度。 | | keyToken | string | 否 | - | 用于 HLS 标准加密播放的 keyToken。 | | reqParams | Record | 否 | - | 可携带aid等透传参数，如:
{aid: 1234}，以playAuthToken下发的参数的优先级最高。
具体可传参数见[签发 PlayAuthToken](https://www.volcengine.com/docs/4/65659) | | definitionMap | Record | 否 | - | 定义清晰度的映射。 | | retryCount | number | 否 | 1 | 点播服务发生 502 错误时的重试次数。 | | autoDemoteDefinition | string | 否 | - | 清晰度自动降级开启时的自动档位，对应[GetPlayInfo](https://www.volcengine.com/docs/4/2918)返回的Definition字段 | | autoDemoteDefinitionTextKey | string | 否 | - | 开启清晰度自动降级（`isNeedAutoDemote` 为 `true`）时的自动档位对应的多语言文案 key，取值对应 `languages` 字段中各语种的 `key`。 | | urlQueryParams | Record | 否 | - | 视频地址请求时携带的额外query参数 | | getDrmAuthToken | (playAuthIds: string, vid: string, unionInfo: string) =\> Promise | 否 | \- | 获取 `PrivateDrmAuthToken` 的异步回调，回调入参为：\ |||||- `playAuthIds`: 视频的密钥 ID，对应 [GetPlayInfo](https://www.volcengine.com/docs/4/2918) 接口返回的 `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 | 是否优先使用[网页画中画](https://developer.mozilla.org/en-US/docs/Web/API/DocumentPictureInPicture)。 |\ ||||| :::tip|\ |||||仅浏览器支持 `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 度实现横屏效果。 | |\ ||||| :::tip|\ |||||- 该参数的优先级高于 `useCssFullscreen` 参数。 |\ |||||- 该参数一般用于移动端。 |||||| | useScreenOrientation | boolean | 否 | false | 旋转全屏后，锁定屏幕方向。适应于移动端设备全屏观看横屏视频 | | lockOrientationType | string | 否 | landscape | 旋转全屏后，锁定屏幕方向类型，默认是横屏，可选值见[orientation](https://developer.mozilla.org/en-US/docs/Web/API/ScreenOrientation/lock#orientation) | | target | HTMLElement | 否 | `null` | 自定义全屏功能的 `dom`。默认是播放器根节点。该参数必须是 `player.root` 的父辈节点，适用于解决全屏时和 `player.root` 同级的 `dom`需要显示的场景。 | | disable | boolean | 否 | false | 是否禁用全屏按钮。\ |||||- `true`：禁用。不渲染全屏按钮。 |\ |||||- `false`：不禁用。 | | | needBackIcon | boolean | 否 | false | 全屏的时候是否显示右上角返回按钮。取值如下：
\ |||||- `false`：不显示右上角返回按钮。 |\ |||||- `true`：显示右上角返回按钮。 | |\ ||||| :::tip|\ |||||此参数一般用于移动端。 |||||| | 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](#url) | 是 | - | 视频播放地址。 | | definition | string | 否 | - | 清晰度 key | | mapDefinition | string | 否 | - | 映射清晰度 key | | definitionTextKey | string | 否 | - | 多语言词典中对应的 key。比如设置 `definitionTextKey: HD_TEXT_KEY` 以及 `languages: {zh: {HD_TEXT_KEY: '高清'}}`，则清晰度切换选项显示 “高清”。不设置则显示 `definition` 的值。 | | codec | [ICodecType](1248901#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类型](https://www.volcengine.com/docs/4/177191)，其他云厂商或者业务服务器存储的地址不支持。 | | kid | string | 否 | - | 视频为加密视频时的密钥KeyId，对应[GetPlayInfo](https://www.volcengine.com/docs/4/2918) 接口返回的PlayInfoList项中的 PlayAuthId | | secretKey | string | 否 | - | 私有加密播放的加密密钥，对应[GetPlayInfo](https://www.volcengine.com/docs/4/2918) 接口返回的PlayInfoList项中的 PlayAuth | | drmType | [EDRMTYPE](1248901#edrmtype) | 否 | - | 视频为加密视频时的加密类型 | ## IVolume 音量配置。 | 配置项 | 类型 | 必选 | 默认值 | 描述 | | :-- | :-- |:-- | :-- | :-- | | position | [POSITIONS](1248901#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 | 否 | ture | 报错时是否展示刷新按钮。 | | retryLoopNum | number | 否 | 1 | 报错后重试次数。 | | errorTipsText | [TipsTextConfig](#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](#danmuitem)[] | 否 | - | 弹幕列表。 | | maskConfig | [IMaskConfig](1248901#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 | 是 | - | 清晰度映射文案。 | | defaultDefinition | string | 否 | 列表第一个 | 默认清晰度。 | | preloadTime | number | 否 | 50 | 预加载时间，单位为毫秒。 | ## IEncryptHlsPluginConfig HLS 加密播放配置。 | 配置项 | 类型 | 必选 | 默认值 | 描述 | | :-- | :-- |:-- | :-- | :-- | | playDomain | string | 否 | https://vod.volcengineapi.com | 获取播放地址的请求域名。 | | playAuthToken | string | 否 | - | 播放地址获取token，由服务端生成下发，详见[播放临时安全凭证（PlayAuthToken）](https://www.volcengine.com/docs/4/67350#%E4%B8%B4%E6%97%B6%E5%AE%89%E5%85%A8%E5%87%AD%E8%AF%81%E6%9C%BA%E5%88%B6%E8%AF%B4%E6%98%8E) | | keyToken | string | 是 | - | 密钥获取token，由服务端生成下发，详见[签发 Hls 标准加密AuthToken](https://www.volcengine.com/docs/4/65659#%E7%AD%BE%E5%8F%91-hls-%E6%A0%87%E5%87%86%E5%8A%A0%E5%AF%86-authtoken%EF%BC%88sha1hlsdrmauthtoken%EF%BC%89) | ## IVodLogOptsConfig 质量日志上报配置。 | 配置项 | 类型 | 必选 | 默认值 | 描述 | | :-- | :-- |:-- | :-- | :-- | | line_app_id | number | 是 | - | 视频点播应用 ID。您可在视频[点播控制台 > 点播SDK > 应用管理](https://console.volcengine.com/vod/region:vod+cn-north-1/sdk/app/)页面获取应用 ID（App ID）。 | | line_user_id | string \| number | 是 | - | 用于识别单一用户的 ID，可在[QoE指标](https://www.volcengine.com/docs/4/75736#qoe-%E6%8C%87%E6%A0%87%E8%AF%B4%E6%98%8E)中用于用户维度的筛选，也可以用于[单点追查](https://www.volcengine.com/docs/4/106093) 查找单用户的播放日志
用户 ID 对应于单点追查功能的查询条件中的设备 ID 维度。如不设置用户 ID，VePlayer 将根据用户浏览器随机生成一个值，该值会在浏览器端缓存。 | | tag | string | 否 | 普通视频 | 业务标签。对应于质量平台上的业务类型维度，其作用是区分业务中的不同场景，以便进行多维度分析。举例来说，假设您的应用中包含短视频和长视频两个场景，则可分别将 `tag` 设为 `short` 和 `long`。这样一来，您就能够在[质量平台](https://www.volcengine.com/docs/4/120175)上通过业务标签维度查询或过滤不同场景的数据。 | | subtag | string | 否 | - | 自定义子标签。对应于质量平台上的自定义标签维度，与 `tag` 配合使用，可用于区分同一业务类型下更为细分的音视频类型，比如加密视频、非加密视频、音频等。 | | codec_type | "h264" \| "h265" | 否 | unknown | 视频编码类型，取值如下\ |||||- `h264`：H.264 |\ |||||- `h265`：H.265 | | | channel | "cn" \| "va" \| "sg" | 否 | cn | 日志上报渠道，可选值：cn(国内) 、sg(新加坡) | | trackerConfig | Record | 否 | - | 日志上报额外配置 | ## 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](#isubtitleitem)[] | 否 | - | 字幕列表。 | | isDefaultOpen | boolean | 否 | true | 是否默认打开字幕。 | | isShowIcon | boolean | 否 | true | 是否显示图标。 | | mode | "external" \| "native" | 否 | external | 字幕渲染模式，取值如下：\ |||||- `"external"`：外挂字幕 |\ |||||- `"native"`：原生字幕 | | | style | [ISubtitleStyle](#isubtitlestyle) | 否 | - | 字幕样式。 | ## ISubTitleItem 字幕项。 | 配置项 | 类型 | 必选 | 默认值 | 描述 | | :-- | :-- |:-- | :-- | :-- | | language | string \| number | 否 | - | 字幕语言。 | | id | string \| number | 否 | - | 字幕 ID。 | | isDefault | boolean | 否 | false | 是否为默认选择的字幕。 | | text | string | 否 | - | 字幕名称。 | | url | string | 否 | - | 外挂字幕 URL 地址。 | | list | [IListItem](#ilistitem)[] | 否 | 无 | 字幕内容列表。非 `url` 形式时使用。 | ## IListItem 字幕内容项。 | 配置项 | 类型 | 必选 | 默认值 | 描述 | | :-- | :-- |:-- | :-- | :-- | | start | number | 是 | - | 开始时间，单位为秒。 | | end | number | 是 | - | 结束时间，单位为秒。 | | list | [ITextItem](#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 | 否 | \- | 获取最后一次播放时间函数 | ## IMusicConfig 音乐播放模式配置。 | 配置项 | 类型 | 必选 | 默认值 | 描述 | | :-- | :-- |:-- | :-- | :-- | | offline | boolean | 否 | false | 是否启用离线下载播放。 | | abCycle | [IABCycle](#iabcycle) \| null | 否 | null | AB 循环播放配置。 | | timeScale | number | 否 | 15 | 快进快退时间跨度，单位为秒。 | | mode | [PlayModeType](1248901#playmodetype) | 否 | order | 循环模式。 | | list | [IMusicListItem](1248901#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](#iplaylistitem)[] | 是 | [] | 播放列表数据。 | | mode | [EPlayMode](1248901#eplaymode) | 否 | order | 循环模式，取值如下：
\ |||||- `order`: 不循环播放，即列表中最后一个视频播放完成后就停止播放。 |\ |||||- `loop`: 列表循环，即列表中最后一个视频播放完成后将自动开始重新播放列表中的第一个视频。 | | | defaultIndex | number | 否 | order | 默认起始的播放次序。 | | isItemClickHide | boolean | 否 | true | 列表点击之后是否隐藏。 | | toggleMode | [TOGGLE_MODES](1248901#toggle-modes) | 否 | click | 列表行为触发模式。 | | isShowIcon | boolean | 否 | true | 是否显示播放列表按钮。 | ## IPlayListItem 播放列表项配置，支持 DirectUrl 和 Vid + playAuthToken 两种播放模式。 | 配置项 | 类型 | 必选 | 默认值 | 描述 | | :-- | :-- |:-- | :-- | :-- | | url | string | 否 | \- | 视频地址。 |\ ||||| :::tip|\ |||||`playAuthToken` 为空时，此参数必传。 |||||| | playAuthToken | string | 否 | \- | 播放临时安全凭证，由业务的 AppServer 签发。 |\ ||||| :::tip|\ |||||`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 `