HOOKS 接入#

H5Player 基于 webpack/tapable 实现了播放过程的钩子函数，为接入方提供了在播放过程的介入可行性

注：目前提供的 hook 都是同步的

1. 接口汇总#

hooks 名称	回调定义	描述
afterPlayerInit	SyncHook([player, renderConfig])	播放器初始化后触发，目前只对直通实例生效。
afterRendererInit	SyncHook([renderer, decoder])	渲染，解码器初始化完毕
afterControl	SyncHook([object])	解码器操作结果回调，直通生效
afterLoaded	SyncHook([player])	播放器获取到媒体流地址后触发，此时并没有开始播放视频或者监听对讲。对直通播放器，回放播放器，监听对讲实例均生效。
afterReady	SyncHook([player])	播放器已准备好开始播放，支持直通、回放。
afterBufferChange	SyncHook([object])	播放器缓存量改变，仅插件使用
onAcceptFrameData	SyncHook([decoder, param])	接收到视频帧报警信息，常用于 SDK 插件开发
beforePlay	SyncHook([player, preventExecution])	播放器播放通知 (play) 前触发。直通在调用 load 会自动播放，因此只有回放生效
beginPlay	SyncHook([])	开始播放；目前直通生效
afterPlay	SyncHook([player])	播放器获取到播放通知 (play) 后触发，回放生效。
beforePause	SyncHook([player, preventExecution])	播放器获取到暂停通知 (pause) 前触发，回放生效。
afterPause	SyncHook([player])	播放器获取到暂停通知 (pause) 后触发，回放生效。
afterSeek	SyncHook([timeData])	播放器设置时间 currentTime 后，完成进度跳转 seek 后触发，仅回放生效。
beforeStop	SyncHook([player, preventExecution])	视频停止前回调，回放生效。
afterStop	SyncHook([player, timeData])	播放器停止后触发。
beforeDestory	SyncHook([player, preventExecution])	视频销毁前回调。
afterDestory	SyncHook([player, timeData])	销毁后回调
onPlayEnded	SyncHook([player])	回放播放完成
onError	SyncHook([ErrorType, SubErrorType, ErrorDescription, ErrorInfo])	错误回调，能监听回放，直通中产生的各种错误
startReconnect	SyncHook([player])	直通断线后，开始重连的 hook.
reconnectSuccess	SyncHook([player])	直通断线后，重连成功的 hook.
afterListenTalkAutoClose	SyncHook([player])	监听对讲时，设备端主动断开后触发。只用于监听对讲。
playerStatusToggle	SyncHook([playersStatus])	回放通道播放状态变更。与播放器状态需要区分，播放状态是指在播放过程中，通道是有流的播放状态或无流的空闲状态；可配合 placeholder 插件实现自定义无视频时遮罩
startLoading	SyncHook([deviceInfo])	用于判断当前是否有通道开始缓冲，通常用于网络不佳的情况
stopLoading	SyncHook([deviceInfo])	用于判断当前是否有通道结束缓冲，可开始播放。通常用于网络不佳的情况。
onLoading	SyncHook([loadingList, done])	用于回调 loading 时的百分比信息和网速信息，直通和回放通用。
loadingTimeout	SyncHook([deviceInfo])	用于判断缓冲超时 (20s)。在 1.3.9 中，超时时长和 seek 超时时长保持一致。
onTimeChange	SyncHook([timeData])	回放播放过程中主动推送时间。推送频率可在 config 中配置，默认 500ms。如果业务层需要时间轴平滑移动，可将频率 设置低些，特别是服务器回放的小文件。
onChannelRender	SyncHook([frame, chanPlayer])	给出当前播放器渲染帧的设备信息或 AI 信息

2. API 接口#

2.1. afterPlayerInit#

描述

播放器初始化后触发，目前只对直通实例生效

示例

• player.hooks.afterPlayerInit.tap('after init', callback(player, config));

注：player 即播放实例

回调参数

参数	描述
player	播放器实例
config	渲染用参数

2.2. afterRendererInit#

描述

渲染，解码器初始化完毕

示例

• player.hooks.afterRendererInit.tap('renderer init', callback(renderer, decoder));

回调参数

参数	描述
renderer	渲染器
decoder	解码器

2.3. afterControl#

描述

解码器操作结果回调，直通生效

示例

• player.hooks.afterControl.tap('afterControl', callback({type, status, utc}));

回调参数

参数	描述
type	播放器操作类型
status	操作状态，0：失败；1：成功
utc	视频时间戳

2.4. afterLoaded#

描述

播放器获取到媒体流地址后触发，此时并没有开始播放视频或者监听对讲。对直通播放器，回放播放器，监听对讲实例均生效。

示例

• player.hooks.afterLoaded.tap('afterLoaded', callback(player));

回调参数

参数	描述
player	播放器实例

2.5. afterReady#

描述

播放器已准备好开始播放，支持直通、回放。

示例

• player.hooks.afterReady.tap('afterReady', callback(player));

回调参数

参数	描述
player	播放器实例

2.6. afterBufferChange#

描述

播放器缓存量改变，仅插件使用

示例

• player.hooks.afterBufferChange.tap('afterBufferChange', callback({ startTime, endTime, frameCount, session }));

回调参数

参数	描述
startTime	缓冲开始时间
endTime	缓冲结束时间
frameCount	缓冲视频帧数
session	session

2.7. onAcceptFrameData#

描述

接收到视频帧报警信息，常用于 SDK 插件开发

示例

• player.hooks.onAcceptFrameData.tap('onAcceptFrameData', callback(decoder, param));

回调参数

参数	描述
decoder	解码器
param	视频报警参数

2.8. beforePlay#

描述

播放器播放通知 (play) 前触发。直通在调用 load 会自动播放，因此只有回放生效。

示例

• player.hooks.beforePlay.tap('beforePlay', callback(player, preventExecution));

回调参数

参数	描述
player	播放器实例
preventExecution	function，阻断函数，可用于阻止 play 后续执行

2.9. beginPlay#

描述

开始播放；目前直通生效

示例

• player.hooks.beginPlay.tap('beginPlay', callback());

2.10. afterPlay#

描述

播放器获取到播放通知 (play) 后触发，回放生效。

示例

• player.hooks.afterPlay.tap('afterPlay', callback(player));

回调参数

参数	描述
player	播放器实例

2.11. beforePause#

描述

播放器获取到暂停通知 (pause) 前触发，回放生效。

示例

• player.hooks.beforePause.tap('beforePause', callback(player, preventExecution));

回调参数

参数	描述
player	播放器实例
preventExecution	function，阻断函数，可用于阻止 pause 后续执行

2.12. afterPause#

描述

播放器获取到暂停通知 (pause) 后触发，回放生效。

示例

• player.hooks.afterPause.tap('afterPause', callback(player));

回调参数

参数	描述
player	播放器实例

2.13. afterSeek#

描述

播放器设置时间 currentTime 后，完成进度跳转 seek 后触发，仅回放生效。

示例

• player.hooks.afterSeek.tap('after seek', callback(timeData));

回调参数

参数	类型	描述
timeData	Object	时间数据，参考 afterStop。

注：seek 失败场景下走 onError 回调

2.14. beforeStop#

描述

视频停止前回调，回放生效。

示例

• player.hooks.beforeStop.tap('beforeStop', callback(player, preventExecution));

回调参数

参数	描述
player	播放器实例
preventExecution	function，阻断函数，可用于阻止 stop 后续执行

2.15. afterStop#

描述

播放器停止后触发。

示例

• player.hooks.afterStop.tap('after stop', callback[player, timeData]);

回调参数

timeData 类型为 Object，监听对讲才有此参数，结构如下：

参数	描述
startTime	开始时间，客户端 utc 时间戳，单位 毫秒。如果未开始，该值为 null。
endTime	结束时间，客户端 utc 时间戳，单位 毫秒。
duration	播放时长，单位 毫秒。如果未开始，该值为 null。

2.16. beforeDestory#

描述

视频销毁前回调。

示例

• player.hooks.beforeDestory.tap('beforeDestory', callback(player, preventExecution));

回调参数

参数	描述
player	播放器实例
preventExecution	function，阻断函数，可用于阻止 destory 后续执行

2.17. afterDestory#

描述

销毁后回调

示例

• player.hooks.afterDestory.tap('afterDestory', callback(player, timeData));

回调参数

timeData 类型为 Object，直通才有此参数，参考 afterStop。

参数	描述
player	播放器实例
timeData	参考 afterStop

2.18. onPlayEnded#

描述

回放播放完成

示例

• player.hooks.onPlayEnded.tap('onPlayEnded', callback(player));

2.19. onError#

描述

错误回调，能监听回放，直通中产生的各种错误

示例

player.hooks.onError.tap('An error occurred', callback(errorType, subErrorType, errorDesription, errorInfo));

回调参数

参数名	类型	描述
errorType	String	错误类型
subErrorType	String	错误子类型
errorDescription	String	错误描述
errorInfo	Object	其余信息

详情参考 error-code.md

2.20. startReconnect#

描述

直通断线后，开始重连的 hook.

示例

• player.hooks.startReconnect.tap('start reconnecting', callback(player));

2.21. reconnectSuccess#

描述

直通断线后，重连成功的 hook.

示例

• player.hooks.reconnectSuccess.tap('start reconnecting', callback(player));

2.22. afterListenTalkAutoClose#

描述

监听对讲时，设备端主动断开后触发。只用于监听对讲。

示例

• intercomPlayer.hooks.afterListenTalkAutoClose.tap('auto close', callback(player));

回调参数

参数	描述
player	监听或对讲实例

2.23. playerStatusToggle#

描述

回放通道播放状态变更。与播放器状态需要区分，播放状态是指在播放过程中，通道是有流的播放状态或无流的空闲状态；可配合 placeholder 插件实现自定义无视频时遮罩

示例

• player.hooks.playerStatusToggle.tap('placeholder', callback(playersStatus));

回调参数

参数		数据类型	描述
playersStatus	Object[]	通道播放状态变化的集合
playerStatus:Object	devId	String	设备 Id
	channel	Number	通道号
	status	String	变化后的播放状态
	next	Function	需要占位的回调函数

2.24. startLoading#

描述

用于判断当前是否有通道开始缓冲，通常用于网络不佳的情况

示例

• player.hooks.startLoading.tap('start loading', callback(devideInfos));

回调参数

参数		数据类型	描述
deviceInfo		Object[]	设备通道列表
deviceInfo:Object	devId	String	设备 Id
	channel	Number	通道号

2.25. stopLoading#

描述

用于判断当前是否有通道结束缓冲，可开始播放。通常用于网络不佳的情况。

示例

• player.hooks.stopLoading.tap('start loading', callback(devideInfos));

回调参数

参数		数据类型	描述
deviceInfo		Object[]	设备通道列表
deviceInfo:Object	devId	String	设备 Id
	channel	Number	通道号

2.26. onLoading#

描述

用于回调 loading 时的百分比信息和网速信息，直通和回放通用。

示例

• player.hooks.loadingTimeout.tap('on loading', callback(loadingList, done));

回调参数

参数		数据类型	描述
loadingList		Object[]	loading 中的设备通道信息列表
	devId	string	设备号
	channel	number	通道号
	percent	number	进度百分比，0-100
	network	number	网速信息，单位 KB/s
done		boolean	是否完成加载结束 loading

2.27. loadingTimeout#

描述

用于判断缓冲超时 (20s)。在 1.3.9 中，超时时长和 seek 超时时长保持一致。

示例

• player.hooks.loadingTimeout.tap('loading timeout', callback(devideInfos));

回调参数

参数		数据类型	描述
deviceInfo		Object[]	设备通道列表
deviceInfo:Object	devId	String	设备 Id
	channel	Number	通道号

2.28. onTimeChange#

描述

回放播放过程中主动推送时间。推送频率可在 config 中配置，默认 500ms。

如果业务层需要时间轴平滑移动，可将频率 设置低些，特别是服务器回放的小文件。

示例

• player.hooks.onTimeChange.tap('time change', callback(timeData));

回调参数

参数		数据类型	描述
timeData		Object
	dateTime	String	根据传入配置的时区格式化好的时间字符串，如 "2022-12-28 16:17:34"。该格式可在全局配置 config 中配置, 默认"YYYY-MM-DD HH:mm:ss"
	utc	Number	utc 时间，单位秒，int。
	ms	Number	utc 秒之后的 毫秒数，取值 0-999.

2.29. onChannelRender#

描述

给出当前播放器渲染帧的设备信息或 AI 信息

示例

• player.hooks.onChannelRender.tap('onChannelRender', callback(frame, chanPlayer))

回调参数

参数	数据类型	描述
frame	object	携带 AI 或设备信息的帧数据
chanPlayers	object	当前渲染该数据帧的通道播放器