tums-player 使用说明

tums-player 使用说明1. 简介2. 使用方法2.1 本地运行demo2.2 正式部署3. 代码示例——demo.html4. 使用说明4.1 options通用参数4.2 事件4.3 通用方法4.4 通用功能 - 录制4.5 功能使用说明 -- 预览4.5.1 预览4.5.1.1 示例 -- 预览4.5.2 鱼眼模式4.5.3 设备控制4.5.3.1 示例 -- 遮蔽4.5.3.2 示例 -- 镜像4.5.3.3 示例 -- 旋转4.5.4 设备能力集说明4.6 功能使用说明 -- 回放4.6.1 示例 -- 回放5. 接入TP-LINK商用云平台指南5.1 预览流程5.2 回放流程6. 附录6.1 错误码6.2 事件类型约束

版本备注
v1.0.01. 创建文档
2. 支持预览功能
V1.1.01. 增加商云接口调用流程
2. 增加回放功能相关参数和方法
V1.2.01. 增加语音对讲相关参数和方法
V1.3.01. 增加本地平台回放功能
V1.4.01. 增加鱼眼画面显示模式相关参数和方法
V1.5.01. 增加云台功能相关参数和方法
V1.5.11. 补充语音对讲详细参数说明
V2.0.01. 增加webcodecs解码方案及相关参数配置
V2.0.11. 增加画面旋转、镜头遮蔽、画面镜像功能
SMBCloudSDK_WebPlayer_Openapi@2.0.111. 适配商云开放平台接口,并调整部分对外开放的功能说明

1. 简介

tums-player是基于TP-LINK平台封装的视频播放组件,使用过程中不必学习专业的业务概念,更不用调用繁琐的接口,能够以极简的嵌入方式,快速在应用中集成视频功能。

覆盖的平台包含:H5/web

浏览器支持:

2. 使用方法

2.1 本地运行demo

  1. 下载tums-player-demo
  2. 解压代码
  3. 参考readme.html,启动demo

2.2 正式部署

  1. 下载tums-player
  2. 将压缩包移至服务器或前端项目后解压,需注意播放器资源路径要求为xxx/tums-player/
  3. 参照代码示例开发页面
  4. 运行服务器使用

3. 代码示例——demo.html

创建dom

引入sdk

初始化播放器

方法调用

示例:

4. 使用说明

前置说明:

播放器基本通过实例对象进行操作,需要首先调用构造函数,传递必要参数,然后再进行其他操作。

参数说明类型可选值默认值
node播放器(canvas)画布外层容器
可为元素id或实际元素对象
String/HTMLElement----
optionsSDK参数,具体见后文说明Object----

4.1 options通用参数

参数说明类型可选值默认值是否必选
type视频流类型:传递relay即可Stringrtsp/relayrtspY
url取流地址:TP-LINK商用云平台通过提供的requestStreamUrl接口获取String----Y
decoderType解码类型:
(1) wasm:webAssembly软解;
(2) webcodecs:webcodecsApi硬解,仅少数浏览器支持。
注:建议不传,由SDK内部自动判断即可
Stringwasm/webcodecs--N
pluginPathsdk资源地址,默认是在根路径下。
比如sdk路径为/static/tums-player,则pluginPath值为/static。
String--'/'N
autoplay自动播放Booleantrue/falsefalseN
cover显示的画面是否覆盖父节点宽高,默认按画面原始比例显示Booleantrue/falsefalseN
streamType流类型:
video:预览
sdvod:回放
Stringvideo/sdvodvideoN
screenshotEnable截图使能Booleantrue/falsetrueN
volume音量Number[1, 100]50N

4.2 事件

以下是SDK完整事件列表:

事件说明回调参数
ready当播放器实例化完成时触发event: {detail: player实例 }
play当媒介数据将要开始播放时触发event: {detail: player实例 }
pause当媒介数据暂停时触发event: {detail: player实例 }
stream开始推流时触发event: {detail: player实例 }
playing当媒介数据已开始播放时触发event: {detail: player实例 }
error发生错误时触发event: {detail: {code: 0, message: '', type: 'audio'/'video'}},code详见错误码列表, type默认为video
warning发生警告时触发event: {detail: {code: 0, message: ''}},code详见错误码列表
disconnected与服务器断开连接时触发event: { detail: { code: 0, reason: '' } }
ended当媒介数据播放结束时触发event: {detail: player实例 }
zoom当画面放大时触发event: {detail: {scale: 放大的倍率,见表后注1 } }
videoRecordFinished录制文件下载时触发,目前录制超过10min将会自动下载

4.3 通用方法

方法说明参数返回值
init播放器初始化同options
destroy播放器销毁Promise
start开始播放
stop停止播放
pause暂停播放
play继续播放
fullscreen全屏放大(controlEl: HtmlDomElement, forceRotate: Boolean)
controlEl: 全屏放大后在画面中插入的dom节点,可选
forceRotate: 是否强制横屏,默认为false
exitFullscreen退出全屏
screenshot视频截图(download: Boolean)
download: 是否自动下载截图,默认为true
base64格式图片数据,png格式
on监听事件,与事件列表对应(eventName: String, callback: Function)
off注销事件(eventName: String, callback: Function)
toggleZoomState切换电子放大状态(见注3)(state: Number)
state:
1,进入放大状态;
0,退出放大状态
setZoomScale设置放大倍率(scale: Number)
scale: 取值[1, 5],超过范围的值不生效
playAudio移动端需在用户操作页面触发touch等事件后,在事件回调中执行此方法开始播放音频
getVolume获取当前播放音量volume: Number
setVolume设置播放音量(volume: Number)
volume: 取值[0, 100]

4.4 通用功能 - 录制

方法说明参数返回值
startRecording开启预览录像。受浏览器内存限制,建议录像时间不超过10分钟(options: Object)
options参数内容如下
micStream: Boolean,是否录制麦克风声音,默认false
Promise
开始录像后resolve
stopRecording停止预览录像并下载录像文件(fileName: String, download: Boolean)
fileName: 文件名,最终下载文件名格式为${文件名}_${时间戳}.webm
download: 是否自动下载文件,默认true
Promise
返回录像文件blob类型数据
getRecordInfo获取预览录像信息recordInfo: Object
包含参数内容如下:
time: 录像时间,单位毫秒
size: 录像文件大小,单位kb

4.5 功能使用说明 -- 预览

4.5.1 预览

options额外传递参数说明:

参数说明类型可选值默认值是否必选
resolution分辨率:VGA:子码流;
HD:主码流
注:初始传入此值仅用于标记当前实例的分辨率,实际播放效果以url为准
StringVGA/HD''N
4.5.1.1 示例 -- 预览

4.5.2 鱼眼模式

需要设备支持鱼眼才可正常运行。

注:为避免操作问题,请提前获取设备能力集(详情见4.5.4),以确定预览设备支持鱼眼功能。

options额外传递参数说明:

参数说明类型可选值默认值是否必选
fishEyeDisplayMode鱼眼画面显示模式String'ORIGIN': 原图;
‘FISHEYE_360D’:顶装360度全景;
‘FISHEYE_180D’:顶装180度全景;
‘FISHEYE_WIN_PLANE_TOP_QUAD’:顶装四分屏;
‘FISHEYE_LONGITUDE’:壁装全景拉伸;
‘ORIGIN’N

方法说明:

方法说明参数返回值
setFishEyeDisplayMode设置鱼眼画面显示模式(mode: String)
枚举类型同options.fishEyeDisplayMode

4.5.3 设备控制

设备控制功能目前仅支持镜头遮蔽画面镜像画面旋转

注:为避免操作问题,请提前获取设备能力集(详情见4.5.4),以确定预览设备支持相关功能。 设备能力集所需的parentQrCode、qrCode、channelId也请按要求传递。

方法说明参数返回值
getLensMaskValue获取镜头遮蔽状态Promise
设备不支持时将返回error_code信息
设备支持时可从 result.enabled中取得具体状态
setLensMaskValue设置镜头遮蔽状态(maskStatus: Boolean)
true:遮蔽
false:不遮蔽
Promise
根据返回的error_code信息判断设置成功或者失败
getImageSwitch获取图像切换配置,目前可包含镜像和画面旋转Promise
失败时返回相关error_code信息
成功时可以通过result.flip和result.rotate分别取得镜像状态和旋转状态。
saveImageSwitch设置图像切换配置,目前可包含镜像和画面旋转(config: Object)
config.flip_type(Number): 镜像状态
取值:
0:关闭
1:左右
2:上下
3:中心
config.rotate_type(Number):旋转状态
0:关闭
1:顺时针旋转90
2:逆时针旋转90
3:逆时针旋转180
Promise
根据返回的error_code信息判断设置成功或者失败
4.5.3.1 示例 -- 遮蔽
4.5.3.2 示例 -- 镜像
4.5.3.3 示例 -- 旋转

4.5.4 设备能力集说明

options额外传递参数说明:

参数说明类型可选值默认值是否必选
parentQrCodenvr设备二维码String--ipc通过nvr接入时需传递
qrCodeipc设备二维码String--直连ipc需传递
channelIdipc通道号Number-1Y

options鉴权相关参数说明:

参数说明类型可选值默认值是否必选
appKeyak信息String--''Y
appSecretsk信息String--''Y

ak/sk为鉴权所需参数,如果想要使用能力集,设备控制功能,则必须传递,具体值可在商云中获取。

方法说明:

方法说明参数返回值
getModuleSpec获取设备能力集,目前包含镜像、镜头遮蔽和鱼眼模式,画面旋转默认全部ipc均支持。Promise
失败时返回相关error_code信息
成功时返回data
data.lensMaskEnable:镜头遮蔽使能
data.flipEnable:画面镜像使能
data.rotateEnable:画面旋转使能
data.fishEveEnable:鱼眼模式使能

 

4.6 功能使用说明 -- 回放

options额外传递参数说明:

参数说明类型可选值默认值是否必选
userIdsearchVideo接口返回的用户id,回放必穿Number----Y
startTime回放开始时间戳(见表后注1)Number--当天00:00N
endTime回放结束时间戳Number----N
eventType回放事件类型Number[]见表后注2[1, 2]N
scale回放倍速Number[0.0625, 0.125, 0.25, 0.5, 1, 2, 4, 8, 16]1N
方法说明参数返回值
setPlaybackConfig设置回放参数(options: Object)
options参数内容如下
startTime、endTime、scale、eventType(可任意组合)
getPlaybackTime获取当前回放时间戳timestamp:Number
13位时间戳
4.6.1 示例 -- 回放

5. 接入TP-LINK商用云平台指南

用户需注册TP-LINK商用云平台账号成为开发者。

该账号需要安全保存,因为后续所有的开发流程都需要基于此账号进行,更重要的是,后续添加的设备与购买的服务,都归属于该账号。该账号还将作为超级管理员,可以创建子账号,从而实现应用内权限 的分配与管理:

  1. 开通“开发者”平台服务(开发者菜单可在商云首页顶部菜单中找到)
  2. 选择所需套餐并创建自己所需要的应用
  3. 根据不同应用类型添加设备(项目型跟随项目添加即可,设备型需要在应用中单独添加)
  4. 开发者账号授权应用权限给子账户A
  5. 子账户A可以在 开发者 -> 我的应用 -> 应用管理 -> 密钥信息中获取鉴权所需要的信息

完成以上步骤后可通过相关协议文档获取到用于预览的视频流地址和鉴权token等信息。具体流程如下:

注:开放接口可以通过ak/sk的方式进行鉴权,具体使用说明可见商云“开发者”菜单。

5.1 预览流程

getDeviceListInProjectApplication(项目型)
或者
getDeviceListInDeviceApplication(设备型)
requestStreamUrl
获取设备列表
获取预览url
预览url传给sdk即可播放

requestStreamUrl请求和响应参数示例:

预览时清晰度默认为流畅,若要修改清晰度,需重新调用requestStreamUrl接口配置resolution,以获取新的播放地址

 

5.2 回放流程

获取设备前的流程与预览一致,前端拿到设备信息(parentQrCode、qrCode、channelId)之后,可查询设备存储的录像并进行播放:

getDeviceListInProjectApplication(项目型)
或者
getDeviceListInDeviceApplication(设备型)
searchYear
searchVideo
是, 继续查询录像
否, 查询完成
requestStreamUrl
获取设备列表
查询设备具有录像的日期(可选)
查询设备在某天所存储的录像片段
响应的录像片段长度 == endIdx - startIdx
记录userId, 显示录像时间轴
获取回放地址
回放url传给sdk即可播放

回放时sdk传参必填项如下:

回放常用功能示例:

6. 附录

6.1 错误码

code含义问题定位
1001请求中止一般为传参问题或设备异常
1002网络异常 
1003媒体资源解析错误 
1004不支持的媒体源 
1005媒体资源已加密 
1006媒体数据传输错误 
1007连接服务器失败 
1008不支持的解码类型 
1101商云服务器内部错误 
1102token过期或不存在 
1104设备ID无效 
1105达到带宽限制在线观看人数过多,需要在商云中开放持续播放专用通道服务
1106请求预览地址参数错误 
1107连接relay服务器失败 
1108取流失败 
1109暂不支持此视频流协议版本 
1110已达到拉流请求上限 
1111已长时间观看 
1112VIP窗口预览数达到上限 
1113VIP预览客户端数量达到上限 
1114分享时段结束 
1115权限不足 
1120多媒体数据加密状态发生变化 
1121设备正在通话中 
1122解绑设备 
1201设备不支持语音对讲 
1202用户拒绝提供信息 
1203浏览器不支持硬件设备 
1204无法发现指定的硬件设备 
1205无法打开麦克风请检测是否有接入音频输入设备,或者浏览器的麦克风权限是否打开
1206通话模式不支持 
1207音频设备正忙,无法发起通话 
1208浏览器获取麦克风权限被拒绝 
1301设备离线请检测商云中该设备的状态
1302设备被移除 
1303设备密码被修改 
1401未知错误请保留设备相关信息,所属项目及分组,并联系技术支持处理
1402操作超时 
1403网络异常 
1404服务器内部错误 
1405session过期或不存在 
1501回放配置失败 
2001分辨率过高导致视频卡顿帧率过低提示(可能设备配置的帧率本身就低)
2002网络不稳定导致视频卡顿帧率过低提示(可能设备配置的帧率本身就低)
2003解码性能不足解码过慢,可能是浏览器资源不足够解码器流畅运行

6.2 事件类型约束

eventType事件类型eventType事件类型
1定时2移动侦测
3遮挡侦测4越界侦测
5区域入侵6进入区域
7离开区域8徘徊侦测
9人员聚集10快速移动
11停车侦测12物品遗留
13物品拿取14音频异常
15虚焦侦测16场景变更
17人脸侦测18报警
19过线统计20登陆异常
21SD卡满22SD卡错误
23SD卡拔出24网线断开
25IP冲突26人形检测
27车辆侦测28物品遗漏拿取侦测
29移动侦测云存30迎宾播报
31视频留言32移动侦测人形加强
33移动侦测车辆加强34区域入侵人形加强
35区域入侵车辆加强36越界侦测人形加强
37越界侦测车辆加强38人脸比对
39人脸相册40进入区域人形加强
41进入区域车辆加强42离开区域人形加强
43离开区域车辆加强44客流量统计
45门铃呼叫46人员到访
47车位占用48哭声检测
49人形相册50紧急呼救