You need to enable JavaScript to run this app.
导航

配置

最近更新时间2023.12.22 18:29:13

首次发布时间2023.10.09 22:02:45

LiveVePlayerOptions

配置项类型是否必选默认值说明
rtmRtm-为播放器设置 RTM 拉流配置。
flvFlv-为播放器设置 FLV 拉流配置。FLV 格式流相关配置仅适用于支持 MSE 播放的 PC 端浏览器和安卓端浏览器。

hls

Hls

-

为播放器设置 HLS 拉流配置。HLS 格式流相关配置仅适用于支持 MSE 播放的 PC 端浏览器和安卓端浏览器。

说明

  • PC 端该配置默认生效;
  • 移动端仅在 enableMSE 设置为 true 且支持 MSE 的浏览器中生效。
infoPanelInfoPanelConfig-为播放器设置直播信息展示面板配置,支持设置是否显示面板和信息刷新时间间隔。当前直播信息面板支持展示 HLS 和 FLV 格式的直播信息,如果是软解播放,会额外显示软解相关信息。
timeShiftTimeShiftConfig-为播放器设置直播时移配置,接入方法请参见功能接入
loggerLoggerConfig-日志上报配置,支持设置开启/关闭开始日志上报并设置日志参数,接入方法请参见功能接入
ignoresstring[]为播放器禁用内置插件列表,接入方法请参见插件说明
iconsany为播放器替换插件图标,接入方法请参见插件说明
idstring'veplayer'指定播放器容器 ID,VePlayer 将被插入在该容器中。id 和 el 需至少传入 1 个。如果同时传入,则优先将播放器插入 id 容器中。
elHTMLElement指定播放器容器元素,VePlayer 将被插入在该容器中。id 和 el 需至少传入 1 个。如果同时传入,则优先将播放器插入 id 容器中。
widthstring | number'100%'设置播放器宽度,传入 number 类型参数则播放器内部默认添加单位px,传入 string 类型参数则直接赋值给播放器容器 width 样式属性。
heightstring | number'100%'设置播放器高度,传入 number 类型参数则播放器内部默认添加单位px,传入 string 类型参数则直接赋值给播放器容器 height 样式属性。
urlstring为播放器配置直播拉流地址。您可手动拼接或使用地址生成器生成拉流地址,生成方法请参见生成直播地址。url 和 playList 需至少传入 1 个。
playlistSource[]为播放器配置直播拉流地址列表。url 和 playlist 需至少传入 1 个。
defaultSourcestring当存在多个直播线路时,为播放器设置默认直播线路,不传则默认列表第一个。
defaultDefinitionstring为播放器设置默认直播清晰度,不传则默认列表第一个。
fallbackUrlsstring[]为播放器设置备路拉流地址,支持设置多个备路拉流地址,在 maxFallbackRound 大于 0 时有效。当您使用配置的直播拉流地址拉流失败时,会在直播地址和备路直播地址之间循环拉流,直到拉流成功。
maxFallbackRoundnumber0为播放器设置拉流失败时循环拉流的最大次数。

decodeType

DecodeType

'hardware'

为播放器设置解码方式。

说明

开启软解后,播放器会使用浏览器的软件解码器来解码视频流。软解模式具有较高的兼容性,适用于各种设备和浏览器,但依赖设备 CPU,在高分辨率或高码率视频播放时会出现卡顿或延迟。建议在以下场景开启软解:

  1. 部分安卓浏览器中播放器被劫持,部分功能将不可见,可开启软解;
  2. 移动端浏览器不支持 flv 格式,如果需要播放该格式的视频,可开启软解;
  3. 部分浏览器不支持 H.265 编码格式,如果需要播放该编码格式的视频,请开启软解。
codecCodec'h264'为播放器设置视频的实际编码格式。如果您在degradation 设置了 soft-first 属性(即硬解不支持时降级软解),建议您传入该参数,省去探测实际编码格式的操作。
degradationboolean | Degradation'soft-first'为播放器设置是否开启 H.265 兼容模式。在 H.265 兼容模式下,播放器会优先使用硬解来解码 H.265 直播流。如果设备或浏览器不支持 H.265 硬解,则自动降级为 H.265 软解。
posterstring为播放器设置封面图 URL。
langstring-为播放器设置初始显示语言,语言包不存在的情况下默认显示 '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' } }} ,格式请参考默认词典
autoplayboolean | { muted?: boolean; }{ muted: true }为播放器设置是否自动播放, muted 设置为 true 为静音自动播放。
volumenumber0.6为播放器设置默认音量,取值范围 [0,1]。

pip

boolean

false

为播放器设置是否显示画中画功能按钮。

  • true:显示;
  • false:不显示。

fullscreen

boolean | Fullscreen

-

为播放器设置是否显示全屏功能按钮,并进行全屏功能设置。

  • true:显示;
  • false:不显示。
errorErrorConfig-为播放器设置报错信息,支持配置播放异常时,播放器显示的异常文案、图片,以及是否提供刷新按钮等。
definitionDefinitionConfig-为播放器设置清晰度的相关配置。

controls

boolean | { [propName: string]: any; }

true

为播放器设置是否显示控制栏。

  • true: 显示;
  • false: 不显示
listTypeListType'bottom'为播放器设置清晰度选择线路选择时的选择面板样式,仅在移动端有效。

playsinline

boolean

true

为播放器设置是否启用内联播放模式。playsinline 属性是 HTML5 视频标签的一个属性,用于指定视频是否应在页面文档内播放。

  • true:启用,表示视频将在页面文档内播放;
  • false:停用,默认浏览器播放行为。

该配置项只在移动端生效,当取值为 true 的时候,会在初始化 video 或 audio 对象的时候,将 playsinline、webkit-playsinline、x5-playsinline 三个属性设置为 true,请参考 New Policies for iOS 了解内联模式相关知识。

说明

  • iOS 10 及以上系统 Safari 浏览器支持配置内联播放模式;
  • iOS 10 以下系统 Safari 浏览器不支持配置内联播放模式 ,默认播放即进入系统全屏。
videoAttributes{ [propName: string]: any; }为播放器设置 video 标签扩展属性,初始化时会设置在 videoElement 或 audioElement 对象上,请参考 HTMLMediaElement 查看其支持的属性配置。

fluid

boolean

false

为播放器设置是否启用流式布局,启用流式布局后播放器会根据屏幕的宽度进行调整,保持在不同屏幕尺寸上都有良好的显示效果。

  • true:启用
  • false:停用

说明

启用流式布局时:

  • 如果 widthheightNumber 类型,则按照其数值计算播放器宽高比;
  • 如果 widthheight 不是 Number 类型,默认使用 16:9 比例。

fitVideoSize

"fixWidth" | "fixHeight" | "fixed"

'fixed'

为播放器设置尺寸适配方式,在视频资源初始化之后,根据获取到的 videoWidth 和 videoHeight 值对播放器容器宽高比例进行调整,可选项有:

  • fixed: 保持容器宽/高,不做适配;
  • fixWidth: 保持容器宽度,适配高度;
  • fixHeight: 保持容器高度,适配宽度。

videoFillMode

"auto" | "fillHeight" | "fillWidth" | "fill" | "cover"

'auto'

为播放器设置视频画面填充模式,可选项有:

  • fillwidth: 填充宽度,高度溢出则裁剪高度;
  • fillHeight: 填充高度,宽度溢出则裁剪宽度;
  • fill: 拉伸视频以填充容器;
  • cover: 保持其宽高比的同时填充元素的整个内容框;
  • auto: 使用浏览器默认的视频画面填充模式。

marginControls

boolean

false

是否开启画面和控制栏分离模式。设置为开启时,控制栏将会常驻,与视频画面不重叠。

  • true:开启
  • false:关闭
'x5-video-player-type'string启用微信同层播放。

'x5-video-player-fullscreen'

boolean

是否启用微信全屏播放模式。

  • true:启用
  • false:停用

'x5-video-orientation'

"landscape" | "portrait" | "landscape|portrait"

微信横竖屏控制,支持如下取值:

  • landscape:横屏
  • portrait:竖屏
  • landscape|portrait:跟随手机自动旋转
pluginsany[]自定义插件列表。

Rtm

配置项类型是否必选默认值说明
enableFallbackbooleantrue当前环境不支持播放 RTM 或者 RTM 拉流播放失败时是否进行降级。

fallbackUrl

string

配置 RTM 拉流失败降级地址,可配置 FLV 拉流地址或 HLS 的拉流地址。enableFallbacktrue 时生效。

  • 指定 fallbackUrl:当前环境不支持播放 RTM 或 RTM 拉流建联失败时,降级到 fallbackUrl 拉流地址。
  • 未指定 fallbackUrl:当前环境不支持播放 RTM 或 RTM 拉流建联失败时,根据当前 RTM 地址降级到对应的 FLV 或者 HLS 地址。
loadTimeoutnumber5000播放器发起 RTM 拉流请求的超时时间,单位为 ms,超过该时间仍未收到服务器响应,则认为网络请求失败。
retryCountnumber0播放器发起 RTM 拉流请求失败时重新尝试建联的最大次数,取值为 0 时表示关闭播放器重试。
retryDelaynumber1000播放器发起 RTM 拉流请求失败时与再次尝试建联的时间间隔,单位为 ms。

enableRTMAutoTranscode

boolean

false

播放器发起 RTM 拉流请求时,是否开启自动转码。

  • true:开启
  • false:关闭

说明

如有使用 RTM 拉流自动转码的需求,请先创建工单联系技术支持进行配置。

Flv

配置项类型是否必选默认值说明
retryCountnumber0播放器发起 FLV 拉流请求失败时重新尝试建联的最大次数,取值为 0 时表示关闭播放器重试。
retryDelaynumber1000播放器发起 FLV 拉流请求失败时与再次尝试建联的时间间隔,单位为 ms。
loadTimeoutnumber10000播放器发起 FLV 拉流请求的超时时间,单位为 ms,超过该时间仍未收到服务器响应,则认为网络请求失败。

enableLowLatency

boolean

false

播放器发起 FLV 拉流请求时,是否开启低延时。例如,当您开启低延时且推流端 GOP 设置为 2s 的情况下,FLV 拉流平均端到端延时约为 2s。

  • true:开启
  • false:关闭

Hls

配置项类型是否必选默认值说明
loadTimeoutnumber10000播放器发起 HLS 拉流请求的超时时间,单位为 ms,超过该时间仍未收到服务器响应,则认为网络请求失败。
retryCountnumber0播放器发起 HLS 拉流请求失败时重新尝试建联的最大次数,取值为 0 时表示关闭播放器重试。
retryDelaynumber1000播放器发起 HLS 拉流请求失败时与再次尝试建联的时间间隔,单位为 ms。

enableMSE

boolean

false

为播放器设置在移动端进行 HLS 拉流时,是否优先使用Media Source Extensions API 播放流媒体。

  • false:不使用
  • true:优先使用

InfoPanel

配置项类型是否必选默认值说明
visiblebooleanfalse是否显示直播信息展示面板。
intervalnumber500渲染间隔 (ms)。

TimeShiftConfig

配置项类型是否必选默认值说明
liveStartTimenumberDate.now() / 1000直播开始时间,Unix 时间戳,单位为 s,需要传入浏览器本地时间。
maxShiftOffsetnumber604800最大时移时间,单位为 s,取值范围为 [6,604800]。

LoggerConfig

配置项类型是否必选默认值说明
enablebooleantrue是否开启日志上报。
appIdstring应用 ID,登录视频直播控制台 > SDK 管理查询。
appNamestring应用名称。

userId

string

用于识别单一用户的 ID,如不设置,会随机生成一个用户 ID 存在浏览器缓存中。

说明

建议您使用与业务相关的用户 ID,以便在发生播放错误时快速定位排查问题。

deviceId

string

用于识别用户设备的 ID,如不设置,会随机生成一个用户 ID 存在浏览器缓存中。

说明

建议您使用与业务相关的用户设备 ID,以便在发生播放错误时快速定位排查问题。

showUserIdInErrorPanelbooleantrue报错时是否在报错面板显示当前用户id信息。

Source

配置项类型是否必选默认值说明
namestring线路标识(唯一值)。
textstring | Record<string, string>线路展示名称。可设置多语言 {text: {'zh-cn': '线路一', 'en': 'LineOne'}}
definitions(string | Definition)[]该线路下清晰度列表。

Definition

配置项类型是否必选默认值说明
urlstring播放地址。
definitionstring清晰度标识(唯一值)。
textstring | Record<string, string>清晰度展示名称。可设置多语言 {text: {'zh-cn': '高清', 'en': 'HD'}}
fallbackUrlsstring[]为当前清晰度地址设置备路拉流地址,支持设置多个备路拉流地址。当前清晰度地址拉流失败时,会在当前清晰度地址和备路直播地址之间循环拉流,直到拉流成功。

Fullscreen

配置项类型是否必选默认值说明

rotateFullscreen

boolean

false

切换全屏时,是否旋转为横屏播放,通常在移动端使用。如果开启横屏播放,切换全屏时,将在竖屏状态下把播放器旋转 90 度,实现横屏效果。该配置优先级高于 useCssFullscreen。

  • true:使用旋转横屏;
  • false:不使用旋转横屏。

useCssFullscreen

boolean

false

是否使用页面全屏代替系统全屏功能。

  • true:页面全屏;
  • false:系统全屏。

needBackIcon

boolean

false

全屏的时候是否显示右上角返回按钮,通常在移动端开启。

  • true:显示;
  • false:不显示。

ErrorConfig

配置项类型是否必选默认值说明
showErrorImgbooleantrue是否展示报错图片。
showErrorTipbooleantrue是否展示报错提示。
showRefreshbooleantrue是否展示刷新按钮。
errorTipsTextstring | Record<string, string>自定义报错显示。
extraTips{ label: string | Record<Lang, string>; value: string | Record<Lang, string>; }[]更多提示信息。

DefinitionConfig

配置项类型是否必选默认值说明
longWaitingTimenumber5000等待超时的时间阈值,单位为 ms。等待超过该值,会抛出 DEFINITION_FALLBACK 事件,如果 needFallbacktrue 则会提示清晰度降级。
needFallbackbooleanfalse是否开启清晰度降级。
demotePrioritystring[]['uhd', 'hd', 'sd', 'ld', 'ao']降级顺序,按照数组顺序依次降级,数组中的元素与 playlist 中的 definition 相对应。

DecodeType

类型: enum

解码方式。

属性说明
Software'software'软解
Hardware'hardware'硬解

Codec

类型: enum

视频的实际编码格式。如果您在degradation 设置了 SoftFirst 属性(即硬解不支持降级软解),建议您传入该参数,省去探测实际编码格式的操作。

属性说明
H265'h265'H.265 编码格式
H264'h264'H.264 编码格式

Degradation

类型: enum

是否开启 H.265 兼容模式。在 H.265 兼容模式下,播放器会优先使用硬解来解码 H.265 直播流。如果设备或浏览器不支持 H.265 硬解,则自动降级为 H.265 软解。

属性说明
SoftFirst'soft-first'硬解不支持降级到软解

ListType

类型: enum

清晰度选择线路选择时的选择面板样式,仅在移动端有效。

属性说明
Bottom'bottom'底部抽屉
Fullscreen'fullscreen'右侧抽屉,常用于全屏时展示
Inner'inner'窗口蒙层展示