You need to enable JavaScript to run this app.
最新活动
产品
解决方案
定价
生态与合作
支持与服务
开发者
了解我们
导航

接口说明

最近更新时间2023.08.22 18:08:51

首次发布时间2022.07.25 11:28:38

本文为您介绍火山引擎视频云播放器(VePlayer)SDK 的配置、方法、事件与错误码。

播放器配置

在实例化 VePlayer 时,您可以对播放器的功能参数进行配置。支持的配置项包括但不限于:

  • 拉流地址和协议
  • 播放器语言
  • 软/硬件解码
  • 弹幕、面板与尺寸
  • 循环及播放控制
  • 清晰度自动降级
  • 直播时移
var player = new VePlayer(options);

options

VePlayer 类可配置的参数如下表所示。

名称类型默认值描述

isLive

Boolean

false

是否是直播场景。

  • true:直播播放;
  • false:点播播放。

id

String

播放器容器 ID,VePlayer 将被插入在该容器中。
idroot 至少传入 1 个。

root

HTMLElement

播放器容器,VePlayer 将被插入在该容器中。
idroot 至少传入 1 个。如果同时传入,则优先将播放器插入 root 容器中。

url

String

直播拉流地址。您可手动拼接或使用地址生成器生成拉流地址,详细说明请参见生成直播地址
urlplayList 至少传入 1 个;如果同时传入,则 playList 中需要包含 url

streamType

String

直播拉流地址类型。支持的取值包括:

  • rtm
  • flv
  • mp4
  • hls

如果 url 中的拉流地址无后缀,则 streamType 必传。

playList

Array

拉流地址列表。详细说明请参见 playListItem

  • urlplayList 至少传入 1 个;
  • 如同时传入 url,则 playList 中需要包含 url
pluginsAny自定义插件。视频直播支持清晰度自动降级插件。详细信息可参见 DefinitionDemotePlugin

languages

Object

自定义播放器的多语言词典,可设置每个语种的词典,格式为 { [key: string]: Object; }
例如,{ zh: { PIP: '画中画' }, en: { PIP: 'pip' }}

说明

了解更多语言的词典,请参见默认字典

useSoftDecoding

Boolean

false

是否启用软解。

说明

  • 部分安卓浏览器中播放器被劫持,部分功能将不可见,可开启软解;
  • 移动端浏览器不支持 flv 格式,如果需要播放该格式的视频,可开启软解;
  • 部分浏览器不支持 H.265 编码格式,如果需要播放该编码格式的视频,请开启软解;
  • 软解播放的解码操作依赖设备 CPU,播放高码率、高分辨率的视频时,对 CPU 占用率非常高。
enableH265DegradeBooleanFALSE是否开启 H.265 兼容模式。开启后,如果浏览器不支持 H.265 硬解,自动降级为 H.265 软解。
codec"h264" | "h265""h264"视频的实际编码格式。在使用 enableH265Degrade 开启 H.265 兼容降级模式时,建议传入该参数。
enableHlsMSEBooleanfalse开启时,优先使用 Media Source Extensions API 播放流媒体。
sdkErrorPluginObject播放器报错信息,支持自定义异常情况下的文案、图片以及是否提供刷新按钮等选项。详细说明请参见 SdkErrorConfig

rtm

Object

超低延时直播(RTM)配置,配置 RTM 拉流参数,详细说明请参见 RtmConfig

说明

传入的 url 为 RTM 拉流地址时,该配置生效;否则,配置不生效。

flv

Object

FLV 拉流格式配置,详细说明请参见 FlvConfig

说明

传入的 url 为 FLV 拉流地址时,该配置生效;否则,配置不生效。

hls

Object

HLS 拉流格式配置,详细说明请参见 HlsConfig

说明

传入的 url 为 HLS 拉流地址时,该配置生效;否则,配置不生效。

DanmuPluginObject弹幕及面板配置,支持配置弹幕文字大小、透明度、展示区域等参数,详细说明请参见 Danmuconfig
DefinitionDemotePluginObject清晰度自动降级配置,详细说明请参见 DefinitionDemotePlugin
widthString|Number100%相对于播放器容器的宽度
heightString|Number100%相对于播放器容器的高度
volumeNumber0.6默认音量,取值范围 0 ~ 1

autoplay

Boolean

true

是否自动播放。

  • true:自动播放;
  • false:点击播放。

autoplayMuted

Boolean

true

是否静音自动播放,该属性仅在 autoplay 为 true 时生效。

  • true:开启静音播放;
  • false:关闭静音播放。

loop

Boolean

false

是否开启循环播放。

  • true:开启;
  • false:关闭。
posterString设置封面图
defaultPlaybackRateNumber1默认起播倍速,参考值包括 0.50.7511.52

pip

Boolean

true

是否显示画中画。

  • true:显示;
  • false:不显示。
fullscreenObject全屏相关配置,详细说明请参见 fullscreen

lang

String

zh

播放器语言选择列表。支持自定义,默认语言类型包括:

  • zh
  • en
  • jp
  • zh-hk

liveInfoPanel

Object

直播信息展示面板,目前支持展示 hls 和 flv 格式的直播信息,详细说明请参见 LiveInfoPanel

说明

使用直播信息展示面板,需要先引入 LiveInfoPanel 插件:plugins: [window.VePlayer.LiveInfoPanel]

timeShiftPluginObject直播时移配置。参数说明请参见 TimeShiftPlugin;接入方法请参见功能接入
liveLoggerObject直播日志配置。详细说明请参见 liveLogger;接入方法请参见功能接入

playsinline

Boolean

true

是否启用内联播放模式。

  • true:启用
  • false:停用

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

说明

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

fluid

Boolean

false

是否启用流式布局。

  • true:启用
  • false:停用

说明

启用流式布局时:

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

fitVideoSize

String

fixed

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

  • fixed:保持容器宽度和高度,不做适配
  • fixWidth:保持容器宽度,适配高度
  • fixHeight:保持容器高度,适配宽度
  • auto:根据视频宽度和高度,适配容器宽度和高度

videoFillMode

String

auto

video 画面填充模式,可选项有:

  • fillWidth:填充宽度,高度溢出则裁剪高度
  • fillHeight:填充高度,宽度溢出则裁剪宽度
  • fill:拉伸视频以填充容器
  • contain:保持宽高比,缩放至一边填满容器,另一边将添加“黑边”
  • auto:使用浏览器默认画面填充模式

marginControls

Boolean

false

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

  • true:开启
  • false:关闭
x5-video-player-typeStringh5启用微信同层播放,设置值为 H5。

x5-video-player-fullscreen

Boolean

false

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

  • true:启用
  • false:停用

x5-video-orientation

String

landscape|portrait

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

  • landscape:横屏
  • portrait:竖屏
  • landscape|portrait:跟随手机自动旋转

fullscreen

全屏相关配置。

名称类型默认值描述

rotateFullscreen

Boolean

false

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

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

useCssFullscreen

Boolean

false

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

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

needBackIcon

Boolean

false

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

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

DanmuConfig

弹幕配置参数如下表所示。

参数类型默认值描述

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:字体大小为 14px;
  • 50:字体大小为 16px;
  • 100:字体大小为 20px。

active

Boolean

false

是否开启弹幕

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

usePanel

Boolean

true

是否展示弹幕设置面板

  • true:展示;
  • false:不展示。
danmuItemsArray弹幕列表,详细信息请参见 DanmuItem

DanmuItem

弹幕列表参数如下表所示。

参数类型默认值描述
idString弹幕唯一 ID
txtString弹幕文案
startNumber弹幕出现时间,单位为 ms
durationNumber弹幕持续显示时间,单位为 ms
styleObject弹幕样式。例如,style : { color: '#ff9500', fontSize: '20px', padding: '2px 11px'}

DefinitionDemotePlugin

配置清晰度自动降级前,需要先引入 DefinitionDemotePlugin 插件。plugins: [window.VePlayer.DefinitionDemotePlugin]

清晰度自动降级参数如下表所示。

参数类型默认值描述
oftenWaitingCountNumber3频繁等待的次数阈值。等待时间超过 OftenWaitingTime 的次数大于该值,即频繁等待
oftenWaitingTimeNumber5000频繁等待的时间阈值,单位为 ms。等待时间超过该值的次数大于 OftenWaitingCount,即频繁等待
longWaitingTimeNumber5000等待超时的时间阈值,单位为 ms。等待超过该值,即为等待超时
isNeedAutoDemoteBooleanfalse是否自动触发降级
demotePriorityArray['uhd', 'hd', 'sd', 'ld', 'ao']降级顺序,按照数组顺序依次降级,数组中的元素与 playList 中的 definition 相对应

playListItem

拉流地址列表,可配置多线路和多清晰度,参数说明如下表所示。接入实例可参考:

参数类型默认值描述

streamType

String

直播拉流地址类型。支持的取值包括:

  • rtm
  • flv
  • mp4
  • hls

如果 playList 中的拉流地址无后缀,则 streamType 必传。

urlString直播拉流地址。您可通过手动拼接或地址生成器生成,详细说明请参见生成直播地址
definitionString清晰度标识,例如,'uhd'、'hd'、'sd'、'ld'、'ao'

definitionTextKey

String

definition

多语言词典中对应的标识。缺省情况,显示 definition 的值。
例如,将 definitionTextKey 设置为 ‘HD_TEXT_KEY’,并将 languages 设置为 { zh: { HD_TEXT_KEY: '高清' }},则清晰度切换选项将显示为“高清”。

lineIdString线路唯一 ID

lineTextKey

String

多语言词典中对应的 Key。
例如,将 lineTextKey 设置为 ‘LINE_ONE’,并将 languages 设置为 { zh: { LINE_ONE: '线路一' }},则清晰度切换选项显示为“线路一”。

backUrlListArray降级拉流地址。当 sdkErrorPlugin.isNeedDemoteBacktrue 时,如果主流发生错误,可自动降级到此拉流地址

SdkErrorConfig

播放器报错信息配置,参数说明如下表所示。

参数类型默认值描述

errorImg

Boolean

true

报错时是否显示提示图片

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

errorTips

Boolean

true

报错时是否展示报错文案。
默认报错文案是“播放发生错误,点击刷新试试吧”,可通过配置 languages 中的 errorTips,进行自定义。
例如,将 languages 设置为 { zh: { errorTips: '播放出错' }}

isNeedRefreshButton

Boolean

true

报错时是否显示“刷新”按钮。

  • true:显示;
  • false:不显示。
retryLoopNumNumber1报错后重试次数

isNeedDemoteBack

Boolean

false

播放发生错误时是否进行降级。

  • false:不降级。提示 errorTipsText 字段配置的报错信息;
  • true:降级。播放时发生错误,自动切换至 backUrlList 字段配置的备用拉流地址进行播放。

RtmConfig

超低延时直播 RTM 配置,参数说明如下所示。

参数类型默认值描述
loadTimeoutNumber5000RTM 拉流请求超时等待时间,单位 ms
retryDelayNumber1000RTM 拉流请求失败时重试时间间隔,单位 ms
retryCountNumber0RTM 拉流请求失败时的重试次数

backupURL

String

RTM 起播建联失败时降级到 flv 或 hls 的拉流地址。

  • 指定 backupURL,播放器默认开启失败降级;
  • 不指定 backupURL,播放失败会发送 error 报错。

backupStreamType

String

备用拉流地址的协议类型,需要与 backupURL 同时配置,支持以下取值。

  • flv
  • hls

FlvConfig

FLV 格式流相关配置,参数说明如下所示。

说明

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

参数类型默认值描述
loadTimeoutNumber10000FLV 格式拉流网络请求超时等待时间,单位 ms。
retryDelayNumber1000FLV 格式拉流网络请求失败重试时间间隔,单位 ms。

retryCount

Number

0

FLV 格式拉流网络请求失败时的重试次数。

说明

retryCount 参数仅在网络错误时生效;发生其他错误时 retryCount 配置不生效,例如,解码失败时播放器不会根据 retryCount 配置的值进行重试。

HlsConfig

HLS 格式流相关配置,参数说明如下所示。

说明

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

参数类型默认值描述
loadTimeoutNumber10000HLS 格式拉流网络请求超时等待时间,单位 ms。
retryDelayNumber1000HLS 格式拉流网络请求失败时重试时间间隔,单位 ms。

retryCount

Number

0

HLS 格式拉流网络请求失败时的重试次数。

说明

retryCount 参数仅在网络错误时生效;发生其他错误时 retryCount 配置不生效,例如,解码失败时播放器不会根据 retryCount 配置的值进行重试。

LiveInfoPanel

视频详细数据面板配置,显示后可以在播放视窗中查看当前直播视频的格式、码率、帧率等信息,参数说明如下表所示。

参数类型默认值描述

visible

Boolean

true

是否显示视频详细信息面板

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

showH265Info

Boolean

false

是否显示 H.265 软解的解码效率、解码消耗等信息。

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

说明

useSoftDecodingtrue,且浏览器支持软解时,showH265Info 可以取 true

TimeShiftPlugin

直播时移参数配置,参数说明如下表所示。

参数类型默认值描述
livingStartTimeNumber当前时间直播开始时间,Unix 时间戳,单位为 s,需要传入浏览器本地时间
maxMoveTimeNumber604800最大时移时间,单位为 s,取值范围为 [6,604800]

liveLogger

直播日志配置,参数说明如下表所示。

参数类型默认值描述
appIdString应用 ID,可登录控制台查询

enable

Boolean

true

是否开启日志上传。

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

方法

本节为您介绍 VePlayer 的方法和调用示例。

on()

监听拉流相关的事件。

类型

(action: string, func: (...args: any[]) => void) => void

参数

  • action:类型为 string
  • func:类型为 (...args: any[]) => void

示例

veplayer.on('player_create_finish', () => {
    console.log('播放器创建完成')
})

once()

监听事件,事件处理函数只执行一次。

类型

(action: string, func: (...args: any[]) => void) => void

参数

  • action:类型为 string
  • func:类型为 (...args: any[]) => void

示例

veplayer.once('player_create_finish', () => {
    console.log('播放器创建完成')
})

off()

解绑事件监听。

类型

(action: string, func: (...args: any[]) => void) => void

参数

  • action:类型为 string
  • func:类型为 (...args: any[]) => void

示例

veplayer.off('player_create_finish')

destroy()

销毁当前实例。

类型

() => Promise<void>

示例

veplayer.destroy()

player.play()

播放视频。

类型

() => Promise<void>

示例

veplayer.player.play()
// 或者
veplayer.player.play().then(() => {
    // 播放成功
}).catch(() => {
    // 播放失败,一般发生于未经用户交互时的自动播放
})

player.pause()

暂停播放。

示例

veplayer.player.pause()

player.retry()

刷新。

示例

veplayer.player.retry()

switchURL()

切换地址。

类型

(src: string) => void

示例

veplayer.switchURL('url');

player.resetState()

重置当前实例状态,暂停视频并且将当前实例状态设置为起播之前的状态,累计播放时长的计算结果会清空,播放器容器 DOM 上的类名会重置为起播之前的状态。

示例

veplayer.player.resetState();

player.reset()

调用 player.resetState() 重置实例状态、注销所有已经注册的组件,并且将当前实例的配置恢复为默认值。

示例

veplayer.player.reset();

player.setConfig()

更新配置信息,如果新的配置列表中包含内置插件的配置项,则会调用内置插件的 setConfig 对其进行更新。

类型

(config: Config) => void

示例

veplayer.player.setConfig({url: '另一个url'})

player.focus()

播放器获取焦点,调用该 API,veplayer.player.isActive 将会变为 true,会触发 Events.veplayer.player_FOCUS 事件。

类型

(config?: { autoHide?: boolean, delay?: number }) => void

参数

  • autoHide :是否需要自动隐藏,默认为 true,即经过 delay 时长之后,会自动调用 veplayer.player.blur()

  • delay :自动隐藏延迟时长,单位 ms,当 autoHide: false 的时候,忽略该配置项,默认取 veplayer.player.config.inactive

示例

veplayer.player.focus()

player.blur()

播放器失去焦点,调用该 API,veplayer.player.isActive 将会变为 false,会触发 Events.PLAYER_BLUR 事件。

类型

(config?: { ignorePaused?: boolean }) => void

参数

ignorePaused :是否忽略暂停状态,默认值是 true,默认暂停的时候不取消焦点状态。

示例

veplayer.player.blur()

player.canPlayType()

检测当前浏览器是否能播放指定类型的视频,实现的代码示例如下:

类型

(mimeType?: string) => boolean

示例

const mimeType = 'video/mp4; codecs="avc1.64001E, mp4a.40.5"'
veplayer.player.canPlayType(mimeType);

player.getBufferedRange()

返回 currentTime 所处的缓冲时间范围,start 表示缓冲起始时间,end 表示缓存截止时间。

类型

(timeRanges?: TimeRanges) => [number, number]

参数
timeRanges时间范围

示例

const [start, end] = veplayer.player.getBufferedRange();

player.checkBuffer()

验证某个时间点是否在当前缓冲区间内。

类型

(time: number) => boolean

示例

const flag = veplayer.player.checkBuffer(10);

player.getFullscreen()

全屏。如果该接口调用的时候处于网页全屏状态会自动退出网页全屏,下发事件 Events.FULLSCREEN_CHANGE

类型

(el?: HTMlElement) => Promise<void>

参数
el:全屏作用的 DOM 节点,如果不传默认是 veplayer.player.root,必须是 veplayer.player.root 的父辈节点。

示例

// 监听全屏变化
veplayer.player.on(Events.FULLSCREEN_CHANGE, (isFullscreen) => {
	if (isFullscreen) {
		// 全屏
	} else {
		// 退出全屏
	}
})
// 播放器进入全屏状态
veplayer.player.getFullscreen()

player.exitFullscreen()

退出全屏。该接口调用会下发事件 Events.FULLSCREEN_CHANGEisFullscreen 为 false。

类型

(el?: HTMlElement) => Promise<void>

参数
el:全屏作用的 DOM 节点,默认不传会获取 getFullscreen 作用的节点,必须是 veplayer.player.root 的父辈节点。

示例

veplayer.player.exitFullscreen()

player.getCssFullscreen()

播放器进入网页全屏,利用 CSS 模拟实现全屏效果。如果该接口调用的时候处于全屏状态,会自动退出全屏,下发事件 Events.CSS_FULLSCREEN_CHANGE

类型

(el?: HTMlElement) => Promise<void>

参数
el:全屏作用的 DOM 节点,传入参数须是播放器容器 veplayer.player.root 的父辈节点,默认为播放器容器 veplayer.player.root

示例

// 监听网页全屏变化
veplayer.player.on(Events.CSS_FULLSCREEN_CHANGE, (isFullscreen) => {
	if (isFullscreen) {
		// 网页全屏
	} else {
		// 退出网页全屏
	}
})
veplayer.player.getCssFullscreen()

player.exitCssFullscreen()

退出网页全屏状态。调用该接口会下发事件 Events.CSS_FULLSCREEN_CHANGE, isFullscreenfalse

类型

(el?: HTMlElement) => Promise<void>

参数
el:全屏作用的 DOM 节点,默认不传会获取 getCssFullscreen 作用的节点,且必须是 veplayer.player.root 的父辈节点。

示例

veplayer.player.exitCssFullscreen()

player.addClass()

增加类名,给播放器容器 veplayer.player.root 添加 CSS 类名。

类型

(className: string) => void

示例

veplayer.player.addClass('className')

player.removeClass()

移除类名,给播放器容器 veplayer.player.root 移除 CSS 类名。

类型

(className: string) => void

示例

veplayer.player.removeClass('className')

player.hasClass()

判定类名,判断播放器容器 veplayer.player.root 是否存在 CSS 类名。

类型

(className: string) => boolean

示例

const flag = veplayer.player.hasClass('className')

player.setAttribute()

设置属性,给播放器容器 veplayer.player.root 设置属性。

类型

(key: string, value: any) => void

示例

veplayer.player.setAttribute('key', 'value')

player.getPlugin()

在当前播放器获取插件的实例。

示例

const pluginInstance = veplayer.player.getPlugin('pluginName')

player.registerPlugin()

在当前播放器上注册某个插件。

类型

(plugin: Function | {
	plugin: Function;
	options: object;
}, config?: {
	[propName: string]: any;
}) => PluginInstance

参数

  • plugin: 插件构造函数。
  • config:可选参数,config 插件配置列表。

示例

const pluginInstance = veplayer.player.registerPlugin(MyPlugin)

player.unRegisterPlugin()

在当前播放器上销毁或者注销某个插件。

类型

(plugin: { pluginName: string } | string, removedFromConfig?: boolean) => void

参数

  • plugin:插件实例或者插件名称。
  • removedFromConfig:注销实例的同时,是否同时将其从 veplayer.player.config.plugins 中移除,默认 false

示例

const pluginInstance = veplayer.player.unRegisterPlugin(pluginName)

属性

属性大部分为只读类型,部分属性支持写入。以外层容器 DOM 对象root 为例,该属性是只读类型,能通过 get 方式获取容器设置,不能通过 set 方式设置容器。而视频音量 volume 属性是可读可写类型,不仅支持“对象通过 get 方式获取音量,还支持通过 set 方式设置音量。

const veplayer = new VePlayer({
    id: 'video',
    width: 800,
    height: 500,
    url: 'xx.flv'
  });

  // 获取外层容器 DOM
  const root = veplayer.player.root;

  // 获取视频音量
  const curVolume = veplayer.player.volume;
  // 设置音量
  veplayer.player.volume = 0.1;

播放器属性

参数类型读写类型描述
configObject只读当前播放器的配置对象。
rootHTMLElement只读播放器外层容器 DOM 对象。
videoObject只读媒体对象,通常是 videoElement/audioElement 。

autoplay

Boolean

可读可写

设置/获取是否自动播放。

  • true:自动播放
  • false:手动播放
bufferedTimeRange只读获取当前已缓冲的时间范围。
playedTimeRange只读获取已经播放的音频/视频的时间范围。
crossOriginString可读可写设置/获取是否跨域 crossorigin
currentSrcString可读可写设置/获取当前视频的播放地址。
cumulateTimeNumber只读获取视频累计播放时长,单位为 s。
volumeNumber可读可写设置/获取视频的音量,取值范围为 0-1。

muted

Boolean

可读可写

设置/获取视频静音状态。

  • true:静音
  • false:非静音

defaultMuted

Boolean

只读

是否默认静音,只在初始化的时候生效。

  • true:静音
  • false:非静音
errorMediaError | String只读媒体错误对象
srcString可读可写设置/获取当前视频的地址,设置时为切换当前播放的视频源。
langString可读可写设置/获取当前语言。
controlPlugin可读可写播放器控制栏插件对象,具体针对控制栏的说明,可参见 拉流 SDK 内置插件说明。
innerContainerHTMLElement只读内置容器 DOM 对象,该属性只有在画面和控制栏互不重叠情况下存在,即当配置 config.marginControls 参数配置为 true 的时候存在。

状态属性

参数类型读写类型描述

state

String

只读

播放器当前所处的状态,其状态枚举值、枚举名称和说明如下:

  • 0:ERROR,播放出现错误
  • 1:INITIAL,初始化
  • 2:READY,配置/事件/插件等均已经初始化/绑定/实例化完成
  • 3:ATTACHING,进入媒体对象挂载阶段
  • 4:ATTACHED,媒体对象已经挂载到了 DOM 中
  • 5:NOTALLOW,播放被阻止
  • 6:RUNNING,已经成功起播进入播放流程
  • 7:ENDED,播放结束
  • 8:DESTROYED,播放器实例处于已被销毁
endedBoolean只读当前视频是否播放结束。
pausedBoolean只读当前视频是否处于暂停状态。

networkState

String

只读

视频的网络状态,其状态枚举值、枚举名称和说明如下:

  • 0:NETWORK_EMPTY,目前还没有数据,readyState 的值是 HAVE_NOTHING
  • 1:NETWORK_IDLE,HTMLMediaElement 处于活动状态并已选择资源,但未使用网络
  • 2:NETWORK_LOADING,浏览器正在下载 HTMLMediaElement 数据
  • 3:NETWORK_NO_SOURCE,未找到 HTMLMediaElement src。

readyState

String

只读

视频的就绪状态,其状态枚举值、枚举名称和说明如下:

  • 0:HAVE_NOTHING,没有关于媒体资源的可用信息
  • 1:HAVE_METADATA,已检索到足够多的媒体资源来初始化元数据, 快进/快退不会引发异常
  • 2:HAVE_CURRENT_DATA,当前播放位置的数据可用,但不足以播放下一帧
  • 3:HAVE_FUTURE_DATA,当前播放位置以及未来至少一小段时间的数据是可用的(至少有两帧以上的数据)
  • 4:HAVE_ENOUGH_DATA,有足够的数据可用,并且下载速率足够,媒体可以不间断地播放到最后
isFullscreenBoolean只读播放器是否处于全屏状态。
isCssfullScreenBoolean只读播放器是否处于网页全屏状态。
isSeekingBoolean只读是否处于快进/快退状态。
isActiveBoolean只读是否处于焦点状态,处于焦点状态会显示控制栏。

事件

VePlayer 是基于事件驱动的逻辑模型,其在关键逻辑处理或状态变化时会触发相应事件。您可根据业务需要监听事件并执行自定义回调。

说明

您可调用以下方法进行事件相关操作:

  • on():监听指定事件。
  • once():一次性监听指定事件。
  • off():解绑事件监听。

SDK 事件

SDK 事件指 VePlayer 视频直播播放器配置相关的事件。

事件名回调参数描述
PLAYER_CREATED_FINISHplayer_create_finishundefined播放器完成创建
PLAYER_REBUILDplayer_rebuildundefined播放器重建

DANMU_CHANGE

danmu_change

{
  active: boolean; // 是否激活
  external: object; // 弹幕配置信息
}

弹幕配置发生变化

CANCEL_UNMUTEcancel_unmuteundefined取消静音
REFRESH_CLICKrefresh_clickundefined触发刷新

PLAY_BACKUP_CHANGE

play_backup_change

{
  currentUrl: string; // 当前播放地址
  nextUrl: string; // 降级后播放地址
  retryTimes: number; // 降级次数
}

报错时触发降级

PLAY_BACKUP_CHANGE_FINISHplay_backup_change_finishundefined报错时触发所有降级结束
PLAY_ERROR_BUTTON_CLICKplay_error_button_clickundefined报错时触发重试

PlAY_URL_CHANGE

play_url_change

{
  url: string; // 改变后播放地址
  from: string; // 改变前播放地址
}

拉流地址改变

SHOW_PLAY_ERRORshow_play_errorundefined展示报错
LONG_WAITINGlong_waitingundefined长时间等待
OFTEN_WAITINGoften_waitingundefined频繁等待

DEFINITION_DEMOTE

definition_demote

{
  currentDef: string; // 改变前清晰度
  willChangeDef: string; // 降级后清晰度
}

清晰度降级

LINE_CHANGE

line_change

{
  from: string \| number; // 切换前 lineId
  to: string \| number; // 切换后 lineId
}

线路切换

ERRORerrorError报错信息,监听返回格式为 Error,其中 message 为错误信息,errorCode错误码

监听报错信息事件代码示例

veplayer.on('error', (error) => {
  // error 处理
})

播放器媒体事件

播放器媒体事件指浏览器 video 原生触发的事件。

事件名枚举值回调参数含义
LOAD_STARTloadstartundefined视频内容开始加载
LOADED_DATAloadeddataundefined视频起播数据加载完成
PLAYplayundefined播放
PAUSEpauseundefined暂停
ENDEDendedundefined结束
AUTOPLAY_PREVENTEDautoplay_was_preventedundefined自动播放失败
PLAYINGplayingundefined恢复播放(包括暂停后恢复播放或卡顿后恢复播放)
SEEKINGseekingundefinedseek 播放
SEEKEDseekedundefinedseek 完成
TIME_UPDATEtimeupdateundefined播放时间改变
WAITINGwaitingundefined等待加载数据
CANPLAYcanplayundefined视频缓冲足够数据,可以播放
CANPLAY_THROUGHcanplaythroughundefined视频可以流畅播放
VOLUME_CHANGEvolumechangeundefined音量发生变化

监听音量变化事件代码示例

veplayer.on('volumechange', () => {
  const muted = veplayer.muted // 是否静音 Boolean
  const volume = veplayer.volume  // 音量 0-1
})

播放器扩展事件

播放器扩展事件指播放器在媒体事件之外扩展的事件。

事件名枚举值回调参数含义
READYreadyundefined播放器完成实例化
COMPLETEcompleteundefined播放器创建 video 完成,可以开始播放

URL_CHANGE

urlchange

{ url: string }

播放资源发生变化,player.src='xxx'

PLAYER_FOCUSfocusundefined播放器聚焦
PLAYER_BLURblurundefined播放器失焦

FULLSCREEN_CHANGE

fullscreen_change

{ isFullScreen: boolean }

全屏状态切换

CSS_FULLSCREEN_CHANGE

cssFullscreen_change

{ isCssFullScreen: boolean }

样式全屏状态切换

MINI_STATE_CHANGE

mini_state_change

{ isPip: boolean }

画中画播放模式切换

DESTROYdestroyundefined播放器销毁
REPLAYreplayundefined播放器重新播放
RETRYretryundefined重试

DEFINITION_CHANGE

definition_change

{
   from: { url: string; definition: string};
   to: { url: string; definition: string};
}

清晰度发生变化

VIDEO_RESIZE

video_resize

{
     videoScale: number;
     vWidth: number;
     vHeight: number;
     cWidth: number;
     cHeight: number;
}

播放器容器尺寸发生变化

PIP_CHANGEpip_changeboolean画中画状态切换
ROTATErotateundefined播放器被旋转

SHORTCUT

shortcut

{ data }

播放器内置快捷键事件触发

SEI_PARSEDSEI_PARSEDundefinedSEI 信息解析

USER_ACTION

user_action

{ data }

内置插件用户行为触发,所有内置插件用户行为交互都会下发该事件,可用于用户行为埋点

监听全屏状态变化事件代码示例

veplayer.on('fullscreen_change', (isFullscreen) => {
  if (isFullscreen) {
    // 全屏 TODO
  } else {
    // 退出全屏 TODO
  }
})

错误

错误对象

const error = {
  errorType: string, // 错误类型
  errorCode: number, // 错误码
  message: string, // 错误信息
  mediaError?: { // video.error
    code: number,
    message?: string
  },
  originError?: {},  // 原始错误对象
  readyState: number,  // mediaElement readyState
  networkState: number,// mediaElement networkState
  currentTime: number, // 当前播放到的时间点
  duration: number, // 视频时长
  ended: boolean,
  src: any,
  url?: string, // network error的时候有,请求出现问题的url
  httpCode?: number // network error的时候有,请求返回的是httpCode
}

错误码

错误码信息如下所示。

错误码
错误码含义
建议处理方式
5101(v1.5.1 及以上版本)获取数据过程被中止。可能的原因有网络中断或浏览器发生异常请先检查浏览器的网络请求是否正常,再尝试重新播放
5102(v1.5.1 及以上版本)网络发生错误,无法成功获取媒体文件请先检查浏览器的网络请求是否正常,再尝试重新播放

5103

(v1.5.1 及以上版本)浏览器在解码媒体资源时发生错误。可能的原因有视频数据异常或解码器解码失败

  1. 请检查原始视频是否正常;
  2. 重新进行转码和播放;
  3. 如果未排除,请联系技术支持。

5104

(v1.5.1 及以上版本)因视频格式不支持、服务器或网络的问题造成视频无法加载

  1. 检查浏览器视频数据请求是否正常;
  2. 检查浏览器和页面环境是否支持要播放的视频格式;
  3. 如果未排除,请联系技术支持。
1(v1.5.0 及以下版本)获取数据过程被中止。可能的原因有网络中断或浏览器发生异常请先检查浏览器的网络请求是否正常,再尝试重新播放
2(v1.5.0 及以下版本)网络发生错误,无法成功获取媒体文件请先检查浏览器的网络请求是否正常,再尝试重新播放

3

(v1.5.0 及以下版本)浏览器在解码媒体资源时发生错误。可能的原因有视频数据异常或解码器解码失败

  1. 请检查原始视频是否正常;
  2. 重新进行转码和播放;
  3. 如果未排除,请联系技术支持。

4

(v1.5.0 及以下版本)因视频格式不支持、服务器或网络的问题造成视频无法加载

  1. 检查浏览器视频数据请求是否正常;
  2. 检查浏览器和页面环境是否支持要播放的视频格式;
  3. 如果未排除,请联系技术支持。
1100处理和解析 HLS 格式的视频流时发生了错误请检查 M3U8 文件封装格式是否符合 HLS 标准
2100网络错误请检查请求播放地址,是否返回 403(过期或者权限验证失败)
2101网络请求超时请检查播放地址是否合法
3100FLV 解封装出错,可能原因包括文件损坏、不完整或者不符合 FLV 文件格式规范等请联系技术支持
3200TS 解封装出错,可能原因包括文件损坏、不完整或者不符合 TS 文件格式规范等请联系技术支持
5200MSE addSourceBuffer 出错请联系技术支持
5201MSE appendBuffer 出错请联系技术支持
5202MSE 其他错误请联系技术支持
8100参数错误请检查参数是否合法
8200其他错误请联系技术支持