tums-player 使用说明

tums-player 使用说明1. 简介2. 使用方法2.1 本地运行demo2.2 正式部署3. 代码示例——demo.html4. 使用说明4.1 参数4.2 事件4.3 方法5. 接入TP-LINK商用云平台指南5.1 预览流程5.2 回放流程6.接入TP-LINK TUMS平台指南7. 附录7.1 错误码7.2 事件类型约束

版本	备注
V1.0.0	1. 创建文档 2. 支持预览功能
V1.1.0	1. 增加商云接口调用流程 2. 增加回放功能相关参数和方法
V1.2.0	1. 增加语音对讲相关参数和方法
V1.3.0	1. 增加本地平台回放功能
V1.4.0	1. 增加鱼眼画面显示模式相关参数和方法
V1.5.0	1. 增加云台功能相关参数和方法
V1.5.1	1. 补充语音对讲详细参数说明
V2.0.0	1. 增加webcodecs解码方案及相关参数配置
V2.0.1	1. 增加画面旋转、镜头遮蔽、画面镜像功能

1. 简介

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

覆盖的平台包含：H5/web

浏览器支持：

Chrome 60+
FireFox 55+

2. 使用方法

2.1 本地运行demo

下载tums-player-demo
解压代码
参考readme.pdf，启动demo

2.2 正式部署

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

3. 代码示例——demo.html

创建dom


<html>
    <body>
        <div id="video-container"></div>
    </body>
</html>

引入sdk


xxxxxxxxxx
<!-- 假设sdk在/static/tums-player/路径下 -->
<script src="/static/tums-player/tums-player.umd.min.js"></script>

初始化播放器


x
<script>
    var TumsPlayer = window['tums-player'].default;
    var player = new TumsPlayer('video-container', {
        type: 'relay', // 协议类型，rtsp/relay
        url: 'https://xxx/requestRelayUrl?token=xxx' // 取流地址
        pluginPath: '/static' // 当sdk资源不在根路径下时，需配置pluginPath
    });
</script>
// 或
<script>
    var TumsPlayer = window['tums-player'].default;
    var player = new TumsPlayer('video-container');
    player.init({
        type: 'relay', // 协议类型，rtsp/relay
        url: 'https://xxx/requestRelayUrl?token=xxx' // 取流地址
    });
</script>
// 对接TUMS平台
<script>
    var TumsPlayer = window['tums-player'].default;
    var player = new TumsPlayer('video-container', {
        type: 'rtsp', // 协议类型，rtsp/relay
        url: 'rtsp://xxx' // 取流地址
        socket: 'wss://xxx/ws', // websocket地址
        pluginPath: '/static' // 当sdk资源不在根路径下时，需配置pluginPath
    });
</script>

对接TUMS平台，若websocket地址为IP或缺少TLS/SSL证书的域名，首次连接会出现失败的情况，需浏览器先主动访问https://xxx/ws (wss替换为https)，然后选择高级-继续前往对当前https地址进行授权

方法调用

示例：


xxxxxxxxxx
player.start(); // 开始播放(autoplay为false时可调用此方法)
player.pause(); // 暂停
player.play(); // 继续播放
player.destroy().then(() => {
    // do something
}); // 销毁
player.on('ready', (evt) => {
    console.log(evt.detail);
}); // 事件监听

4. 使用说明

4.1 参数

TumsPlayer类：


xxxxxxxxxx
TumsPlayer(node, options);

options说明：

参数	说明	类型	可选值	默认值	是否必选
type	视频流类型。目前取值有： rtsp（对接TP-LINK TUMS平台使用）； relay（对接TP-LINK商用云平台使用）	String	rtsp/relay	rtsp	Y
url	取流地址： TP-LINK TUMS平台使用提供的getPreviewUrl/getPlaybackUrl/getMultitransUrl接口获取； TP-LINK商用云平台通过提供的requestStreamUrl接口获取；	String	--	--	Y
socket	websocket连接地址，type为rtsp时必填	String	--	--	N
decoderType	解码类型，目前取值有wasm（webAssembly软解），webcodecs（webcodecs API硬解，仅少数浏览器支持）。未配置此参数会自动根据当前浏览器环境使用对应解码方式。配置此参数会判断当前浏览器是否支持，若不支持会出现报错。	String	wasm/webcodecs	--	N
pluginPath	sdk资源地址，默认是在根路径下。比如sdk路径为/static/tums-player，则pluginPath值为/static	String	--	‘/’	N
autoplay	自动播放	Boolean	--	true	N
resolution	分辨率，目前取值有VGA（子码流），HD（主码流），初始传入此值仅用于标记当前实例的分辨率，实际播放效果以url为准	String	VGA/HD	''	N
cover	显示的画面是否覆盖父节点宽高，默认按画面原始比例显示	Boolean	--	false	N
streamType	流类型，目前取值有video（预览），sdvod（回放，仅支持TP-LINK商用云平台）	String	video/sdvod	video	N
userId	searchVideo接口返回的用户id，type为relay且streamType为sdvod时必填	Number	--	--	N
startTime	回放开始时间戳（见注1）	Number	--	当天00:00	N
endTime	回放结束时间戳	Number	--	--	N
eventType	回放事件类型(仅支持TP-LINK商用云平台， TP-LINK TUMS平台需要在获取回放url时设置)	Number[]	见注2	[1, 2]	N
scale	回放倍速	Number	[0.0625, 0.125, 0.25, 0.5, 1, 2, 4, 8, 16]	1	N
talkEnable	语音对讲使能	Boolean	--	true	N
screenshotEnable	截图使能	Boolean	--	true	N
volume	音量	Number	[1, 100]	50	N
fishEyeDisplayMode	鱼眼画面显示模式	String	'ORIGIN': 原图； ‘FISHEYE_360D’：顶装360度全景； ‘FISHEYE_180D’：顶装180度全景； ‘FISHEYE_WIN_PLANE_T OP_QUAD’：顶装四分屏； ‘FISHEYE_LONGITUDE’：壁装全景拉伸；	‘ORIGIN’	N
authSessionId	鉴权Id(/tums/account/v1/login登录接口获取的sessionId，TP-LINK TUMS平台回放功能必选)	String	--	''	N
queryAddress	回放api访问前缀(TP-LINK TUMS平台回放功能必选)	String	--	''	N
videoSessionId	回放功能视频数据会话id(通过addPlaybackChn接口获取,TP-LINK TUMS平台回放功能必选)	String	--	''	N
videoDevId	设备id(TP-LINK TUMS平台回放功能必选)	String	--	''	N
storageDevId	回放数据存储设备id	String	--	''	N
useMultitrans	本地平台回放功能是否使用Multitrans协议	Boolean	--	false	N

对接TP-LINK商用云平台，使用云台功能需传递以下参数：

参数	说明	类型	可选值	默认值	是否必选
appKey	从商用云平台获取的开发者密钥ID (AK)	String	-	-	Y
appSecret	从商用云平台获取的开发者密钥（SK）	String	-	-	Y
proxyServer	商用云平台地址	String	-	'https://api-smbcloud.tplinkcloud.com.cn/'	N

使用镜头遮蔽、画面镜像、画面旋转时需要传递以下参数：

参数	说明	类型	可选值	默认值	是否必选
parentId	nvr设备id	String	-	-	ipc通过nvr接入时需传递
channel	ipc通道号	Number	-	-	ipc通过nvr接入时需传递
devId	ipc设备id	String	-	-	Y

注：

时间戳指从1970年1月1日开始所经过的毫秒数。
事件类型定义，需要区分直连IPC和NVR通道。
直连IPC（取值范围见6.2）：
数组包含指定事件类型即可。eg: [1, 2, 3] 表示同时回放定时、移动侦测和遮挡侦测类型。
NVR通道：
目前仅支持：1 定时类型，2 动检类型。传值[1, 0]表示只回放定时类型，[2, 0]表示只回放动检类型，[3, 0]表示同时回放两种类型。

4.2 事件

事件	说明	回调参数
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: 放大的倍率，见注3} }
videoRecordFinished	录制文件下载时触发，目前录制超过10min将会自动下载	无

注：

进入电子放大状态后，在画面中单击鼠标左键放大画面，右键缩小画面，也可使用滚轮操作；放大范围：[1, 5]，粒度为0.25。

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)	无
setResolution	设置分辨率	(url: String, resolution: String) url: 新分辨率对应视频流地址， resolution: VGA(子码流)、HD（主码流），可选	无
setPlaybackConfig	设置回放参数	(options: Object) options参数内容如下 startTime、endTime、scale、eventType（可任意组合）	无
getPlaybackTime	获取当前回放时间戳	无	timestamp：Number
toggleZoomState	切换电子放大状态（见注3）	(state: Number) state: 1，进入放大状态；0，退出放大状态	无
setZoomScale	设置放大倍率	(scale: Number) scale: 取值[1, 5]，超过范围的值不生效	无
startVoiceIntercom	开始语音对讲	(options: Object）详细内容见下方语音对讲参数说明	无
stopVoiceIntercom	结束语音对讲	无	无
playAudio	移动端需在用户操作页面触发touch等事件后，在事件回调中执行此方法开始播放音频	无	无
getVolume	获取当前播放音量	无	volume: Number
setVolume	设置播放音量	(volume: Number) volume: 取值[0, 100]	无
setFishEyeDisplayMode	设置鱼眼画面显示模式	(mode: String)	无
startRecording	开启预览录像。受浏览器内存限制，建议录像时间不超过1分钟	(options: Object) options参数内容如下 micStream: Boolean，是否录制麦克风声音，默认false	Promise 开始录像后resolve
stopRecording	停止预览录像并下载录像文件	(fileName: String, download: Boolean) fileName: 文件名，最终下载文件名格式为`${文件名}_${时间戳}.mp4` download: 是否自动下载文件，默认true	Promise 返回录像文件blob类型数据
getRecordInfo	获取预览录像信息	无	recordInfo: Object 包含参数内容如下： time: 录像时间，单位毫秒 size: 录像文件大小，单位kb
getLensMaskValue	获取镜头遮蔽状态	无	Promise 设备不支持时将返回error_code信息设备支持时可从 result.lens_mask.lens_mask_info.enabled中取得具体状态
setLensMaskValue	设置镜头遮蔽状态	(maskStatus: String) maskStatus: on/off	Promise 根据返回的error_code信息判断设置成功或者失败
getImageSwitch	获取图像切换配置，目前可包含镜像和画面旋转	无	Promise 失败时返回相关error_code信息成功时可以通过result.flip_type和result.rotate_type分别取得镜像状态和旋转状态。
saveImageSwitch	设置图像切换配置，目前可包含镜像和画面旋转	(config: Object) config.flip_type: 镜像状态取值： off：关闭 left_and_right：左右 up_and_down：上下 center：中心 config.rotate_type：旋转状态 off ：关闭 anticlockwise_180 ：逆时针旋转180 clockwise_90 ：顺时针旋转90 anticlockwise_90 ：逆时针旋转90	Promise 根据返回的error_code信息判断设置成功或者失败
getModuleSpec	获取设备能力集，目前包含镜像和镜头遮蔽，画面旋转默认全部ipc均支持	无	Promise 失败时返回相关error_code信息成功时返回data data. lensMaskEnable: 镜头遮蔽使能 data. flipEnable: 画面镜像使能 data.rotateEnable: 画面旋转使能

语音对讲参数说明

对接TP-LINK商用云平台：

参数	说明	类型	是否必选
url	通过requestStreamUrl接口获取的语音对接地址	String	是
mode	通话模式，取值： half_duplex：半双工模式 vad：VAD人声检测模式 aec：AEC全双工模式默认为aec（双向语音对讲）	String	否

示例：


xxxxxxxxxx
// 获取url流程
...
// player为播放器实例
player.startVoiceIntercom({
    url: 'https://xxx/requestRelayUrl?token=xxx'
});

对接TP-LINK TUMS平台（接口调用详见第6节）：

参数	说明	类型	是否必选
url	rtsp地址：使用getMultitransUrl接口获取的rtspUrl或使用requestBidirectionStream接口获取的参数拼接 `${protocol}://${serverUrl}:${port}/`	String	是
wssUrl	websocket地址：使用getMultitransUrl接口获取的wssUrl或使用requestBidirectionStream接口获取的参数拼接 `wss://${serverUrl}:${port}/ws/`	String	是
slpData	requestBidirectionStream接口响应的result数据（使用getMultitransUrl接口获取url时不需要传此参数）	String	否
mode	同上	String	否

示例：


xxxxxxxxxx
// 获取url流程
...
// player为播放器实例
player.startVoiceIntercom({
    url: 'rtsp://xxxx',
    wssUrl: 'wss://xxx/ws'
});

云台方法(仅对接TP-LINK商用云平台支持)

方法	说明	参数	参数详解	返回值
setPtzParams	云台的转动、调焦	(options: Object) options参数内容如下 id 、 direction 、 startOrNot、speed	id：设备索引，可通过getDeviceInRegionWithPermission等接口获取； direction：移动方向（ 0表示左上、1表示上、2表示右上、 3表示左、4表示持续水平转动、5表示右、 6表示左下、7表示下、8表示右下、 9表示缩小画面、10表示放大画面、 11表示聚焦近处、12表示聚焦远处）； startOrNot ：开始或停止移动（ 0表示停止，1表示开始）; speed：移动速度（浮点型字符串，0-1之间），默认值‘0.571’	Promise，设备不支持相关指令时将返回error_code信息
resetPtzDevicePosition	云台复位	(id: String)	id：设备索引，可通过getDeviceInRegionWithPermission等接口获取;	Promise，设备不支持相关指令时将返回error_code信息


xxxxxxxxxx
// mousedown 开始移动
player.setPtzParams({
    id: '574674137700770163',
    direction: 3,
    startOrNot: 1
}).then((response) => {
    // Do something
});
// mouseup 停止移动
player.setPtzParams({
    id: '574674137700770163',
    direction: 3,
    startOrNot: 0
});

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

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

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

设备添加到开发者账号下。
开发者账号授权设备权限给子账户A。
用户A通过子账户A的权限来操作设备

开发者后台通过账户登录TP-LINK商用云平台后，可通过相关协议文档获取到用于预览的视频流地址和鉴权token等信息。具体流程如下：

5.1 预览流程

开发者获取到AK/SK并计算出请求签名后，可参考以下请求流程获取预览链接：

requestStreamUrl请求和响应参数示例：


xxxxxxxxxx
{
    "clientType":"browser",
    "clientUUID":"8cb18a36-8cc4-143b-2214-641945094566",
    "devInfoId":"574674137700825011",
    "resolution":2, // 0：流畅，2：高清
    "streamType":"video", // video: 预览，sdvod：回放
    "cloudDomain":"smbcloud.tp-link.com.cn",
    "windowUUID":"c01984bd-0f28-8384-f66d-78f9325bf434"
}
{
    "result":{
        "sdkStreamUrl":"https://smbcloud.tp-link.com.cn/tums/relay/v1/sdk/requestRelayUrl?token=12931-e3NhbHQgPSAtMTQyMzI0MTM3O2NsaWVu-4f17ec1306694dc5a0390a06f4a56f22&devInfoId=574674137700825011&clientUUID=8cb18a36-8cc4-143b-2214-641945094566&clientType=browser&streamType=video" // url传入sdk即可播放
    },
    "error_code":0
}

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

5.2 回放流程

获取设备前的流程与预览一致，前端拿到设备ID之后，可查询设备存储的录像并进行播放：

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


xxxxxxxxxx
var player = new TumsPlayer('video-container', {
    type: 'relay',
    url: 'https://xxx/requestRelayUrl?token=xxx&&streamType=sdvod' // 取流地址
    streamType: 'sdvod',
    userId: '1', // searchVideo接口获取
});

回放常用功能示例：


xxxxxxxxxx
player.getPlaybackTime(); // 获取回放进度，更新时间轴可使用此方法
player.setPlaybackConfig({
    startTime: 'xxx' // 跳转到指定时间开始回放
});
player.setPlaybackConfig({
    startTime: 'xxx',
    scale: 0.5 // 配置可组合，跳转时间并开启1/2倍速播放
});

6.接入TP-LINK TUMS平台指南

回放/预览接口调用流程：

注1：

getStoragesById：传递devId获取设备数据存储位置，即存储设备id（storageDevId）。

注2：

addPlaybackChn：传递设备id、存储设备id、事件类型、回放起止时间、回放速率（目前传递'1/1'即可）获取回放通道标识，即sessionId。

注3：

getPlaybackUrl：传递addPlaybackChnsessionId、设备id、storageDevId，获取的获取回放url，准备传给sdk。

注4：

getMultitransUrl：传递devId可以直接获取到httpsPort与socket地址，若无httpsPort则使用默认值10180 ，wss地址拼接格式如下：ws://${host}:${httpsPort}/ws/，其中host是socket中的ip部分。

注5： getDeviceInRegionWithPermission接口可以根据预览权限进行设备列表查询，permissionList传[0]代表预览，传[1]代表回放。

7. 附录

7.1 错误码

code	含义
1001	请求中止
1002	网络异常
1003	媒体资源解析错误
1004	不支持的媒体源
1005	媒体资源已加密
1006	媒体数据传输错误
1007	连接服务器失败
1008	不支持的解码类型
1101	商云服务器内部错误
1102	token过期或不存在
1104	设备ID无效
1105	达到带宽限制
1106	请求预览地址参数错误
1107	连接relay服务器失败
1108	取流失败
1109	暂不支持此视频流协议版本
1110	已达到拉流请求上限
1111	已长时间观看
1112	VIP窗口预览数达到上限
1113	VIP预览客户端数量达到上限
1114	分享时段结束
1115	权限不足
1120	多媒体数据加密状态发生变化
1121	设备正在通话中
1122	解绑设备
1201	设备不支持语音对讲
1202	用户拒绝提供信息
1203	浏览器不支持硬件设备
1204	无法发现指定的硬件设备
1205	无法打开麦克风
1206	通话模式不支持
1207	音频设备正忙，无法发起通话
1208	浏览器获取麦克风权限被拒绝
1301	设备离线
1302	设备被移除
1303	设备密码被修改
1401	未知错误
1402	操作超时
1403	网络异常
1404	服务器内部错误
1405	session过期或不存在
1501	回放配置失败
2001	分辨率过高导致视频卡顿
2002	网络不稳定导致视频卡顿
2003	解码性能不足

7.2 事件类型约束

eventType	事件类型	eventType	事件类型
1	定时	2	移动侦测
3	遮挡侦测	4	越界侦测
5	区域入侵	6	进入区域
7	离开区域	8	徘徊侦测
9	人员聚集	10	快速移动
11	停车侦测	12	物品遗留
13	物品拿取	14	音频异常
15	虚焦侦测	16	场景变更
17	人脸侦测	18	报警
19	过线统计	20	登陆异常
21	SD卡满	22	SD卡错误
23	SD卡拔出	24	网线断开
25	IP冲突	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	紧急呼救