You need to enable JavaScript to run this app.
导航
视频直播
  • 文档首页
    • /
  • 视频直播

配置

最近更新时间：2024.03.18 20:23:33

首次发布时间：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是无为播放器替换插件图标，接入方法请参见插件说明。
drmDrm否-商业 DRM 播放配置。
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 时有效。当您使用配置的直播拉流地址拉流失败时，会在直播地址和备路直播地址之间循环拉流，直到拉流成功。
maxFallbackRoundnumber否0为播放器设置拉流失败时循环拉流的最大次数。

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 为静音自动播放。
volumenumber否0.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：停用

说明

启用流式布局时：

  • 如果 width 和 height 是 Number 类型，则按照其数值计算播放器宽高比；
  • 如果 width 和 height 不是 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[]否无自定义插件列表。

closeVideoClick

boolean

否

false

是否关闭 PC 端单击播放区域切换播放/暂停的能力，开启时，点击播放器区域可实现播放或暂停。

  • true: 关闭；
  • false: 开启。

closeVideoDblclick

boolean

否

false

PC 端时表示是否关闭双击播放器进入全屏的能力，移动端时表示是否关闭双击切换播放/暂停的能力。

  • true: 关闭；
  • false: 开启。

Rtm

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

fallbackUrl

string

否

无

配置 RTM 拉流失败降级地址，可配置 FLV 拉流地址或 HLS 的拉流地址。enableFallback 为 true 时生效。

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

enableRTMAutoTranscode

boolean

否

false

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

  • true：开启
  • false：关闭

说明

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

Flv

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

enableLowLatency

boolean

否

false

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

  • true：开启
  • false：关闭

Hls

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

enableMSE

boolean

否

false

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

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

InfoPanel

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

TimeShiftConfig

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

LoggerConfig

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

userId

string

否

无

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

说明

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

deviceId

string

否

无

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

说明

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

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

Drm

配置项类型是否必选默认值说明
fairplayFairplayDrm否-使用 FairPlay 加密时的 DRM 配置。

FairplayDrm

配置项类型是否必选默认值说明
getDrmConfig(config: { url: string;}) => Promise<FairplayDrmConfig>否-获取 DRM 配置的方法，用于更新 DRM 配置。

FairplayDrmConfig

配置项类型是否必选默认值说明
serverCertificatePathstring否无获取 FairPlay 证书的请求地址。
serverProcessSPCPathstring否无获取 DRM 授权许可的请求地址。

Source

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

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

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

DefinitionConfig

配置项类型是否必选默认值说明
longWaitingTimenumber否5000等待超时的时间阈值，单位为 ms。等待超过该值，会抛出 DEFINITION_FALLBACK 事件，如果 needFallback 为 true 则会提示清晰度降级。
needFallbackboolean否false是否开启清晰度降级。
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'窗口蒙层展示