接口说明

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

播放器配置

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

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

var player = new VePlayer(options);

options

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

fullscreen

全屏相关配置。

DanmuConfig

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

DanmuItem

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

DefinitionDemotePlugin

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

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

playListItem

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

• 主备流降级
• 清晰度降级

SdkErrorConfig

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

RtmConfig

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

FlvConfig

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

HlsConfig

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

LiveInfoPanel

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

TimeShiftPlugin

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

liveLogger

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

方法

本节为您介绍 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_CHANGE，isFullscreen 为 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, isFullscreen 为 false。

类型

(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;

播放器属性

状态属性

事件

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

SDK 事件

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

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

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

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

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

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

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

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

播放器媒体事件

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

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

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

播放器扩展事件

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

{ url: string }

{ isFullScreen: boolean }

{ isCssFullScreen: boolean }

{ isPip: boolean }

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

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

{ data }

{ 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
}

错误码

错误码信息如下所示。