配置项 | 类型 | 是否必选 | 默认值 | 说明 |
---|---|---|---|---|
rtm | Rtm | 否 | - | 为播放器设置 RTM 拉流配置。 |
flv | 否 | - | 为播放器设置 FLV 拉流配置。 说明 FLV 拉流格式流相关配置适用于支持 MSE 播放的 PC 端浏览器、安卓端浏览器和支持 MMS API 的 iOS 浏览器。 | |
hls | 否 | - | 为播放器设置 HLS 拉流配置。 说明
| |
infoPanel | InfoPanelConfig | 否 | - | 为播放器设置直播信息展示面板配置,支持设置是否显示面板和信息刷新时间间隔。当前直播信息面板支持展示 HLS 和 FLV 格式的直播信息,如果是软解播放,会额外显示软解相关信息。 |
timeShift | TimeShiftConfig | 否 | - | 为播放器设置直播时移配置,接入方法请参见功能接入。 |
logger | LoggerConfig | 否 | - | 日志上报配置,支持设置开启/关闭开始日志上报并设置日志参数,接入方法请参见功能接入。 |
ignores | string[] | 否 | 无 | 为播放器禁用内置插件列表,接入方法请参见插件说明。 |
icons | any | 是 | 无 | 为播放器替换插件图标,接入方法请参见插件说明。 |
drm | Drm | 否 | - | 商业 DRM 播放配置。 |
id | string | 否 | 'veplayer' | 指定播放器容器 ID,VePlayer 将被插入在该容器中。id 和 el 需至少传入 1 个。如果同时传入,则优先将播放器插入 id 容器中。 |
el | HTMLElement | 否 | 无 | 指定播放器容器元素,VePlayer 将被插入在该容器中。id 和 el 需至少传入 1 个。如果同时传入,则优先将播放器插入 id 容器中。 |
width | string | number | 否 | '100%' | 设置播放器宽度,传入 number 类型参数则播放器内部默认添加单位px,传入 string 类型参数则直接赋值给播放器容器 width 样式属性。 |
height | string | number | 否 | '100%' | 设置播放器高度,传入 number 类型参数则播放器内部默认添加单位px,传入 string 类型参数则直接赋值给播放器容器 height 样式属性。 |
url | string | 否 | 无 | 为播放器配置直播拉流地址。您可手动拼接或使用地址生成器生成拉流地址,生成方法请参见生成直播地址。url 和 playList 需至少传入 1 个。 |
playlist | Source[] | 否 | 无 | 为播放器配置直播拉流地址列表。url 和 playlist 需至少传入 1 个。 |
defaultSource | string | 否 | 无 | 当存在多个直播线路时,为播放器设置默认直播线路,不传则默认列表第一个。 |
defaultDefinition | string | 否 | 无 | 为播放器设置默认直播清晰度,不传则默认列表第一个。 |
fallbackUrls | string[] | 否 | 无 | 为播放器设置备路拉流地址,支持设置多个备路拉流地址,在 maxFallbackRound 大于 0 时有效。当您使用配置的直播拉流地址拉流失败时,会在直播地址和备路直播地址之间循环拉流,直到拉流成功。 |
maxFallbackRound | number | 否 | 0 | 为播放器设置拉流失败时循环拉流的最大次数。 |
decodeType | 否 |
| 为播放器设置解码方式。 说明 开启软解后,播放器会使用浏览器的软件解码器来解码视频流。软解模式具有较高的兼容性,适用于各种设备和浏览器,但依赖设备 CPU,在高分辨率或高码率视频播放时会出现卡顿或延迟。建议在以下场景开启软解:
| |
codec | Codec | 否 | 'h264' | 为播放器设置视频的实际编码格式。如果您在degradation 设置了 soft-first 属性(即硬解不支持时降级软解),建议您传入该参数,省去探测实际编码格式的操作。 |
degradation | boolean | Degradation | 否 | 'soft-first' | 为播放器设置是否开启 H.265 兼容模式。在 H.265 兼容模式下,播放器会优先使用硬解来解码 H.265 直播流。如果设备或浏览器不支持 H.265 硬解,则自动降级为 H.265 软解。 |
poster | string | 否 | 无 | 为播放器设置封面图 URL。 |
lang | string | 否 | - | 为播放器设置初始显示语言,语言包不存在的情况下默认显示 'en' 语言包 。默认值为 document.documentElement.getAttribute('lang') || navigator.language || 'zh-cn' |
i18n | { texts: Record<Lang, Record<string, string>>; } | 否 | 无 | 为播放器设置自定义的多语言词典,可设置每个语种的词典,格式为 { texts: { [key: string]: Object; } }。 例如,{ texts: { 'zh-cn': { PIP: '画中画' }, en: { PIP: 'pip' } }} ,格式请参考默认词典。 |
autoplay | boolean | { muted?: boolean; } | 否 | { muted: true } | 为播放器设置是否自动播放, muted 设置为 true 为静音自动播放。 |
volume | number | 否 | 0.6 | 为播放器设置默认音量,取值范围 [0,1]。 |
pip | boolean | 否 |
| 为播放器设置是否显示画中画功能按钮。
|
fullscreen | boolean | Fullscreen | 否 | - | 为播放器设置是否显示全屏功能按钮,并进行全屏功能设置。
|
error | ErrorConfig | 否 | - | 为播放器设置报错信息,支持配置播放异常时,播放器显示的异常文案、图片,以及是否提供刷新按钮等。 |
definition | DefinitionConfig | 否 | - | 为播放器设置清晰度的相关配置。 |
controls | boolean | { [propName: string]: any; } | 否 |
| 为播放器设置是否显示控制栏。
|
listType | ListType | 否 | 'bottom' | 为播放器设置清晰度选择或线路选择时的选择面板样式,仅在移动端有效。 |
playsinline | boolean | 否 |
| 为播放器设置是否启用内联播放模式。playsinline 属性是 HTML5 视频标签的一个属性,用于指定视频是否应在页面文档内播放。
说明
|
videoAttributes | { [propName: string]: any; } | 否 | 无 | 为播放器设置 video 标签扩展属性,初始化时会设置在 videoElement 或 audioElement 对象上,请参考 HTMLMediaElement 查看其支持的属性配置。 |
fluid | boolean | 否 |
| 为播放器设置是否启用流式布局,启用流式布局后播放器会根据屏幕的宽度进行调整,保持在不同屏幕尺寸上都有良好的显示效果。
说明 启用流式布局时:
|
fitVideoSize | "fixWidth" | "fixHeight" | "fixed" | 否 |
| 为播放器设置尺寸适配方式,在视频资源初始化之后,根据获取到的 videoWidth 和 videoHeight 值对播放器容器宽高比例进行调整,可选项有:
|
videoFillMode | "auto" | "fillHeight" | "fillWidth" | "fill" | "cover" | 否 |
| 为播放器设置视频画面填充模式,可选项有:
|
marginControls | boolean | 否 |
| 是否开启画面和控制栏分离模式。设置为开启时,控制栏将会常驻,与视频画面不重叠。
|
'x5-video-player-type' | string | 否 | 无 | 启用微信同层播放。 |
'x5-video-player-fullscreen' | boolean | 否 | 无 | 是否启用微信全屏播放模式。
|
'x5-video-orientation' | "landscape" | "portrait" | "landscape|portrait" | 否 | 无 | 微信横竖屏控制,支持如下取值:
|
plugins | any[] | 否 | 无 | 自定义插件列表。 |
closeVideoClick | boolean | 否 |
| 是否关闭 PC 端单击播放区域切换播放/暂停的能力,开启时,点击播放器区域可实现播放或暂停。
|
closeVideoDblclick | boolean | 否 |
| PC 端时表示是否关闭双击播放器进入全屏的能力;移动端时表示是否关闭双击切换播放/暂停的能力。
|
配置项 | 类型 | 是否必选 | 默认值 | 说明 |
---|---|---|---|---|
enableFallback | boolean | 否 | true | 当前环境不支持播放 RTM 或者 RTM 拉流播放失败时是否进行降级。 |
fallbackUrl | string | 否 | 无 | 配置 RTM 拉流失败降级地址,可配置 FLV 拉流地址或 HLS 的拉流地址。
|
loadTimeout | number | 否 | 5000 | 播放器发起 RTM 拉流请求的超时时间,单位为 ms,超过该时间仍未收到服务器响应,则认为网络请求失败。 |
retryCount | number | 否 | 0 | 播放器发起 RTM 拉流请求失败时重新尝试建联的最大次数,取值为 0 时表示关闭播放器重试。 |
retryDelay | number | 否 | 1000 | 播放器发起 RTM 拉流请求失败时与再次尝试建联的时间间隔,单位为 ms。 |
enableRTMAutoTranscode | boolean | 否 |
| 播放器发起 RTM 拉流请求时,是否开启自动转码。
说明 如有使用 RTM 拉流自动转码的需求,请先创建工单联系技术支持进行配置。 |
networkEvaluateInterval | number | 否 | 1000 | 指定进行网络评估的最近时间长度,单位为毫秒,默认为 1000,表示对最近 1000 毫秒内的网络情况进行评估。 |
seamlesslyReload | boolean | 否 |
| 暂停后重新拉流的处理方式是否为无缝替换。
说明 Safari 浏览器在进行 RTM 拉流时不支持使用此配置。 |
disconnectTime | number | 否 | - | 暂停播放后的断联时间,单位为秒,默认不断联。 说明 Safari 浏览器在进行 RTM 拉流时,如果出现断联,重新拉流时会出现短暂黑屏或加载情况。 |
配置项 | 类型 | 是否必选 | 默认值 | 说明 |
---|---|---|---|---|
retryCount | number | 否 | 0 | 播放器发起 FLV 拉流请求失败时重新尝试建联的最大次数,取值为 0 时表示关闭播放器重试。 |
retryDelay | number | 否 | 1000 | 播放器发起 FLV 拉流请求失败时与再次尝试建联的时间间隔,单位为 ms。 |
loadTimeout | number | 否 | 10000 | 播放器发起 FLV 拉流请求的超时时间,单位为 ms,超过该时间仍未收到服务器响应,则认为网络请求失败。 |
enableLowLatency | boolean | 否 |
| 播放器发起 FLV 拉流请求时,是否开启低延时。例如,当您开启低延时且推流端 GOP 设置为 2s 的情况下,FLV 拉流平均端到端延时约为 2s。
说明 低延迟 FLV 拉流仅在 PC 端浏览器中生效。 |
lowLatency | LowLatency | 否 | - | 低延时的详细配置。 |
abr | Abr | 否 | - | 为播放器设置 FLV 拉流时的 自适应码率(ABR)配置。 |
maxReaderInterval | number | 否 | 5000 | 设置无数据返回最大时长,单位为毫秒,默认值为 5000,超过最大时长将被判断为断流,并触发 ended 事件。 |
disconnectTime | number | 否 | 0 | 暂停播放后的断联时间,单位为秒,默认值为 0,表示暂停播放后立即断联。 |
seamlesslyReload | boolean | 否 |
| 暂停后重新拉流的处理方式是否为无缝替换。
|
配置项 | 类型 | 是否必选 | 默认值 | 说明 |
---|---|---|---|---|
enableFrameChasing | boolean | 否 |
| FLV 低延时模式下,是否开启倍速追帧。
|
配置项 | 类型 | 是否必选 | 默认值 | 说明 |
---|---|---|---|---|
enable | boolean | 否 |
| 是否开启 FLV 拉流时的自适应码率(ABR)功能,默认为开启。
|
debug | boolean | 否 |
| 是否开始调试模式,默认为关闭。
|
bitrate | number | 否 | - | 当前拉流地址 URL 对应的码率。 |
urls | { [bitrate: number]: string; } | 否 | - | 自适应码率流信息。 |
配置项 | 类型 | 是否必选 | 默认值 | 说明 |
---|---|---|---|---|
loadTimeout | number | 否 | 10000 | 播放器发起 HLS 拉流请求的超时时间,单位为 ms,超过该时间仍未收到服务器响应,则认为网络请求失败。 |
retryCount | number | 否 | 0 | 播放器发起 HLS 拉流请求失败时重新尝试建联的最大次数,取值为 0 时表示关闭播放器重试。 |
retryDelay | number | 否 | 1000 | 播放器发起 HLS 拉流请求失败时与再次尝试建联的时间间隔,单位为 ms。 |
enableMSE | boolean | 否 |
| 为播放器设置在移动端进行 HLS 拉流时,是否优先使用Media Source Extensions API 播放流媒体。
|
配置项 | 类型 | 是否必选 | 默认值 | 说明 |
---|---|---|---|---|
visible | boolean | 否 | false | 是否显示直播信息展示面板。 |
interval | number | 否 | 500 | 渲染间隔 (ms)。 |
配置项 | 类型 | 是否必选 | 默认值 | 说明 |
---|---|---|---|---|
liveStartTime | number | 否 | Date.now() / 1000 | 直播开始时间,Unix 时间戳,单位为 s,需要传入浏览器本地时间。 |
maxShiftOffset | number | 否 | 604800 | 最大时移时间,单位为 s,取值范围为 [6,604800]。 |
配置项 | 类型 | 是否必选 | 默认值 | 说明 |
---|---|---|---|---|
enable | boolean | 否 | true | 是否开启日志上报。 |
appId | string | 否 | 无 | 应用 ID,登录视频直播控制台 > SDK 管理查询。 |
appName | string | 否 | 无 | 应用名称。 |
userId | string | 否 | 无 | 用于识别单一用户的 ID,如不设置,会随机生成一个用户 ID 存在浏览器缓存中。 说明 建议您使用与业务相关的用户 ID,以便在发生播放错误时快速定位排查问题。 |
deviceId | string | 否 | 无 | 用于识别用户设备的 ID,如不设置,会随机生成一个用户 ID 存在浏览器缓存中。 说明 建议您使用与业务相关的用户设备 ID,以便在发生播放错误时快速定位排查问题。 |
showUserIdInErrorPanel | boolean | 否 | true | 报错时是否在报错面板显示当前用户 ID 信息。 |
配置项 | 类型 | 是否必选 | 默认值 | 说明 |
---|---|---|---|---|
fairplay | FairplayDrm | 否 | - | FairPlay DRM 配置。 |
配置项 | 类型 | 是否必选 | 默认值 | 说明 |
---|---|---|---|---|
getDrmConfig | (config: { url: string;}) => Promise<FairplayDrmConfig> | 否 | - | 获取 DRM 配置的方法,用于更新 DRM 配置。 |
配置项 | 类型 | 是否必选 | 默认值 | 说明 |
---|---|---|---|---|
serverCertificatePath | string | 否 | - | 获取证书的请求地址。 |
serverProcessSPCPath | string | 否 | - | 获取内容密钥许可证的请求地址。 |
配置项 | 类型 | 是否必选 | 默认值 | 说明 |
---|---|---|---|---|
name | string | 否 | 无 | 线路标识(唯一值)。 |
text | string | Record<string, string> | 否 | 无 | 线路展示名称。可设置多语言 {text: {'zh-cn': '线路一', 'en': 'LineOne'}} 。 |
definitions | (string | ExposedDefinition)[] | 是 | 无 | 该线路下清晰度列表。 |
配置项 | 类型 | 是否必选 | 默认值 | 说明 |
---|---|---|---|---|
url | string | 是 | 无 | 播放地址。 |
definition | string | 是 | 无 | 清晰度标识(唯一值)。 |
text | string | Record<string, string> | 否 | 无 | 清晰度展示名称。可设置多语言 {text: {'zh-cn': '高清', 'en': 'HD'}} 。 |
fallbackUrls | string[] | 否 | 无 | 为当前清晰度地址设置备路拉流地址,支持设置多个备路拉流地址。当前清晰度地址拉流失败时,会在当前清晰度地址和备路直播地址之间循环拉流,直到拉流成功。 |
配置项 | 类型 | 是否必选 | 默认值 | 说明 |
---|---|---|---|---|
rotateFullscreen | boolean | 否 |
| 切换全屏时,是否旋转为横屏播放,通常在移动端使用。如果开启横屏播放,切换全屏时,将在竖屏状态下把播放器旋转 90 度,实现横屏效果。该配置优先级低于 useCssFullscreen。
|
useCssFullscreen | boolean | 否 |
| 是否使用页面全屏代替系统全屏功能。
|
needBackIcon | boolean | 否 |
| 全屏的时候是否显示右上角返回按钮,通常在移动端开启。
|
配置项 | 类型 | 是否必选 | 默认值 | 说明 |
---|---|---|---|---|
showErrorImg | boolean | 否 | true | 是否展示报错图片。 |
showErrorTip | boolean | 否 | true | 是否展示报错提示。 |
showRefresh | boolean | 否 | true | 是否展示刷新按钮。 |
errorTipsText | string | Record<string, string> | 否 | 无 | 自定义报错显示。 |
extraTips | { label: string | Record<Lang, string>; value: string | Record<Lang, string>; }[] | 否 | 无 | 更多提示信息。 |
配置项 | 类型 | 是否必选 | 默认值 | 说明 |
---|---|---|---|---|
longWaitingTime | number | 否 | 5000 | 等待超时的时间阈值,单位为 ms。等待超过该值,会抛出 DEFINITION_FALLBACK 事件,如果 needFallback 为 true 则会提示清晰度降级。 |
needFallback | boolean | 否 | false | 是否开启清晰度降级。 |
demotePriority | string[] | 否 | ['uhd', 'hd', 'sd', 'ld', 'ao'] | 降级顺序,按照数组顺序依次降级,数组中的元素与 playlist 中的 definition 相对应。 |
在 RTM 拉流场景下,获取到的网络情况。
配置项 | 类型 | 是否必选 | 默认值 | 说明 |
---|---|---|---|---|
speed | number | 否 | - | 最近一次网络评估周期内的下载速度, 单位为 bps。 |
avgSpeed | number | 否 | - | 最近 5 次网络评估周期内下载速度平均值,单位为 bps。 |
lostRate | number | 否 | - | 最近一次网络评估周期内的网络丢包率。 |
avgLostRate | number | 否 | - | 最近 5 次网络评估周期内的网络丢包率平均值。 |
RTM 直播流播放信息。
配置项 | 类型 | 是否必选 | 默认值 | 说明 |
---|---|---|---|---|
video | { codec: string; payloadType: string; sdpFmtpLine: string; bytesReceived: number; firCount: number; pliCount: number; frameHeight: number; frameWidth: number; framesDecoded: number; framesDropped: number; framesPerSecond: number; framesReceived: number; jitter: number; jitterBufferDelay: number; keyFramesDecoded: number; nackCount: number; packetsLost: number; packetsReceived: number; } | 否 | - | 视频信息。 |
audio | { codec: string; payloadType: string; sdpFmtpLine: string; audioLevel: number; bytesReceived: number; jitter: number; jitterBufferDelay: number; packetsLost: number; packetsReceived: number; totalSamplesDuration: number; totalSamplesReceived: number; } | 否 | - | 音频信息。 |
FLV 直播流播放信息。
配置项 | 类型 | 是否必选 | 默认值 | 说明 |
---|---|---|---|---|
avgSpeed | number | 是 | - | 平均下载速度。 |
bitrate | number | 是 | - | 码率。 |
bufferEnd | number | 是 | - | 剩余缓冲时间。 |
currentTime | number | 是 | - | 当前播放时间。 |
downloadSpeed | number | 是 | - | 当前下载速度。 |
encodeType | string | 是 | - | 编码方式。 |
fps | number | 是 | - | 帧率。 |
height | number | 是 | - | 视频高度。 |
totalReceivedByte | number | 是 | - | 总共收到的字节数。 |
totalReceivedCost | number | 是 | - | 接收所有字节消耗时长。 |
width | number | 是 | - | 视频宽度。 |
类型:enum
解码方式。
属性 | 值 | 说明 |
---|---|---|
Software | 'software' | 软解。 |
Hardware | 'hardware' | 硬解。 |
类型:enum
视频的实际编码格式。如果您在 degradation 设置了 SoftFirst 属性(即硬解不支持降级软解),建议您传入该参数,省去探测实际编码格式的操作。
属性 | 值 | 说明 |
---|---|---|
H265 | 'h265' | H.265 编码格式。 |
H264 | 'h264' | H.264 编码格式。 |
类型:enum
是否开启 H.265 兼容模式。在 H.265 兼容模式下,播放器会优先使用硬解来解码 H.265 直播流。如果设备或浏览器不支持 H.265 硬解,则自动降级为 H.265 软解。
属性 | 值 | 说明 |
---|---|---|
SoftFirst | 'soft-first' | 硬解不支持时,优先降级到软解。 |
类型:enum
清晰度选择或线路选择时的选择面板样式,仅在移动端有效。
属性 | 值 | 说明 |
---|---|---|
Bottom | 'bottom' | 底部抽屉。 |
Fullscreen | 'fullscreen' | 右侧抽屉,常用于全屏时展示。 |
Inner | 'inner' | 窗口蒙层展示。 |