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.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. 增加画面旋转、镜头遮蔽、画面镜像功能 |
SMBCloudSDK_WebPlayer_Openapi@2.0.11 | 1. 适配商云开放平台接口,并调整部分对外开放的功能说明 |
tums-player是基于TP-LINK平台封装的视频播放组件,使用过程中不必学习专业的业务概念,更不用调用繁琐的接口,能够以极简的嵌入方式,快速在应用中集成视频功能。
覆盖的平台包含:H5/web
浏览器支持:
创建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', // 协议类型relay
url: 'https://xxx/requestRelayUrl?token=xxx' // 取流地址
pluginPath: '/static', // 当sdk资源不在根路径下时,需配置pluginPath
appKey: '', // 从商云平台获取的鉴权信息
appSecret: '' // 从商云平台获取的鉴权信息
});
// 回放必填字段
var player = new TumsPlayer('video-container', {
type: 'relay', // 协议类型relay
url: 'https://xxx/requestRelayUrl?token=xxx' // 取流地址
pluginPath: '/static', // 当sdk资源不在根路径下时,需配置pluginPath
appKey: '', // 从商云平台获取的鉴权信息
appSecret: '' // 从商云平台获取的鉴权信息
userId: '', // searchVideo接口返回的用户id
startTime: '' // 回放开始时间戳,默认今天0点
});
</script>
方法调用
示例:
xxxxxxxxxx
player.start(); // 开始播放(autoplay为false时可调用此方法)
player.pause(); // 暂停
player.play(); // 继续播放
player.destroy().then(() => {
// do something
}); // 销毁
player.on('ready', (evt) => {
console.log(evt.detail);
}); // 事件监听
前置说明:
播放器基本通过实例对象进行操作,需要首先调用构造函数,传递必要参数,然后再进行其他操作。
xxxxxxxxxx
let playerInstance = new window.TumsPlayer(node, options);
参数 | 说明 | 类型 | 可选值 | 默认值 |
---|---|---|---|---|
node | 播放器(canvas)画布外层容器 可为元素id或实际元素对象 | String/HTMLElement | -- | -- |
options | SDK参数,具体见后文说明 | Object | -- | -- |
参数 | 说明 | 类型 | 可选值 | 默认值 | 是否必选 |
---|---|---|---|---|---|
type | 视频流类型:传递relay即可 | String | rtsp/relay | rtsp | Y |
url | 取流地址:TP-LINK商用云平台通过提供的requestStreamUrl接口获取 | String | -- | -- | Y |
decoderType | 解码类型: (1) wasm:webAssembly软解; (2) webcodecs:webcodecsApi硬解,仅少数浏览器支持。 注:建议不传,由SDK内部自动判断即可 | String | wasm/webcodecs | -- | N |
pluginPath | sdk资源地址,默认是在根路径下。 比如sdk路径为/static/tums-player,则pluginPath值为/static。 | String | -- | '/' | N |
autoplay | 自动播放 | Boolean | true/false | false | N |
cover | 显示的画面是否覆盖父节点宽高,默认按画面原始比例显示 | Boolean | true/false | false | N |
streamType | 流类型: video:预览 sdvod:回放 | String | video/sdvod | video | N |
screenshotEnable | 截图使能 | Boolean | true/false | true | N |
volume | 音量 | Number | [1, 100] | 50 | N |
以下是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将会自动下载 | 无 |
方法 | 说明 | 参数 | 返回值 |
---|---|---|---|
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] | 无 |
方法 | 说明 | 参数 | 返回值 |
---|---|---|---|
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 |
options额外传递参数说明:
参数 | 说明 | 类型 | 可选值 | 默认值 | 是否必选 |
---|---|---|---|---|---|
resolution | 分辨率:VGA:子码流; HD:主码流 注:初始传入此值仅用于标记当前实例的分辨率,实际播放效果以url为准 | String | VGA/HD | '' | N |
xxxxxxxxxx
// 初始化player
const TumsPlayer = window['tums-player'].default;
player = new TumsPlayer(document.querySelector('#container'), {
type: 'relay', // 协议类型
url: 'https://xxxxxx', // requestStreamUrl获取的预览url
pluginPath: '/master', // 当sdk资源不在根路径下时,需配置pluginPath
streamType: 'video'
});
// 暂停/播放
const playOrSuspend = () => {
if (!player) return;
let isPlaying = player.isPlaying();
if (!isPlaying) {
if (player.isInit) {
player.start();
} else {
player.play();
}
} else {
player.pause();
}
}
需要设备支持鱼眼才可正常运行。
注:为避免操作问题,请提前获取设备能力集(详情见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.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信息判断设置成功或者失败 |
xxxxxxxxxx
// 获取
player
.getLensMaskValue()
.then(({ result = {} }) => {
result.enabled; // 遮蔽状态,true为遮蔽中,false为未遮蔽
});
// 设置(示例为开启遮蔽)
player
.getImageSwitch(true)
.then(() => {
// 设置成功,实际画面需要0.5-2s进行响应
})
.catch((errData) => {
// 设置失败,包括网络错误以及接口调用报错
// 具体错误见errData.error_code
});
xxxxxxxxxx
// 获取
player
.getImageSwitch()
.then(({ result = {} }) => {
result.flip; // 镜像状态,枚举值见方法说明
result.rotate; // 旋转状态,枚举值见方法说明
});
// 设置(示例为左右镜像)
player
.saveImageSwitch({ flip_type: 1 })
.then(() => {
// 设置成功,实际画面需要0.5-2s进行响应
})
.catch((errData) => {
// 设置失败,包括网络错误以及接口调用报错
// 具体错误见errData.error_code
});
xxxxxxxxxx
// 获取
player
.getImageSwitch()
.then(({ result = {} }) => {
result.flip; // 镜像状态,枚举值见方法说明
result.rotate; // 旋转状态,枚举值见方法说明
});
// 设置(示例为顺时针旋转90)
player
.saveImageSwitch({ rotate_type: 1 })
.then(() => {
// 设置成功,实际画面需要0.5-2s进行响应
})
.catch((errData) => {
// 设置失败,包括网络错误以及接口调用报错
// 具体错误见errData.error_code
});
options额外传递参数说明:
参数 | 说明 | 类型 | 可选值 | 默认值 | 是否必选 |
---|---|---|---|---|---|
parentQrCode | nvr设备二维码 | String | - | - | ipc通过nvr接入时需传递 |
qrCode | ipc设备二维码 | String | - | - | 直连ipc需传递 |
channelId | ipc通道号 | Number | - | 1 | Y |
options鉴权相关参数说明:
参数 | 说明 | 类型 | 可选值 | 默认值 | 是否必选 |
---|---|---|---|---|---|
appKey | ak信息 | String | -- | '' | Y |
appSecret | sk信息 | String | -- | '' | Y |
ak/sk为鉴权所需参数,如果想要使用能力集,设备控制功能,则必须传递,具体值可在商云中获取。
方法说明:
方法 | 说明 | 参数 | 返回值 |
---|---|---|---|
getModuleSpec | 获取设备能力集,目前包含镜像、镜头遮蔽和鱼眼模式,画面旋转默认全部ipc均支持。 | 无 | Promise 失败时返回相关error_code信息 成功时返回data data.lensMaskEnable:镜头遮蔽使能 data.flipEnable:画面镜像使能 data.rotateEnable:画面旋转使能 data.fishEveEnable:鱼眼模式使能 |
options额外传递参数说明:
参数 | 说明 | 类型 | 可选值 | 默认值 | 是否必选 |
---|---|---|---|---|---|
userId | searchVideo接口返回的用户id,回放必穿 | Number | -- | -- | Y |
startTime | 回放开始时间戳(见表后注1) | Number | -- | 当天00:00 | N |
endTime | 回放结束时间戳 | Number | -- | -- | N |
eventType | 回放事件类型 | Number[] | 见表后注2 | [1, 2] | N |
scale | 回放倍速 | Number | [0.0625, 0.125, 0.25, 0.5, 1, 2, 4, 8, 16] | 1 | N |
注1:时间戳指从1970年1月1日开始所经过的毫秒数。(即13位时间戳)
注2:事件类型定义,需要区分直连IPC和NVR通道。
直连IPC(取值范围见6.2): 数组包含指定事件类型即可。eg: [1, 2, 3] 表示同时回放定时、移动侦测和遮挡侦测类型。
NVR通道: 目前仅支持:1 定时类型,2 动检类型。传值[1]表示只回放定时类型,[2]表示只回放动检类型,[1, 2]表示同时回放两种类型。
方法 | 说明 | 参数 | 返回值 |
---|---|---|---|
setPlaybackConfig | 设置回放参数 | (options: Object) options参数内容如下 startTime、endTime、scale、eventType(可任意组合) | 无 |
getPlaybackTime | 获取当前回放时间戳 | 无 | timestamp:Number 13位时间戳 |
xxxxxxxxxx
// 初始化
const TumsPlayer = window['tums-player'].default;
player = new TumsPlayer(document.querySelector('#container'), {
type: 'relay', // 协议类型
url: 'https://xxxxx',
pluginPath: '/master', // 当sdk资源不在根路径下时,需配置pluginPath
streamType: 'sdvod',
userId: 55,
scale: 1,
startTime: 1705507200000,
eventType: [1, 2]
});
// 暂停/播放
const playOrSuspend = () => {
if (!player) return;
let isPlaying = player.isPlaying();
if (!isPlaying) {
if (player.isInit) {
player.start();
} else {
player.play();
}
} else {
player.pause();
}
}
// 修改回放配置
const setPlaybackConfig = () => {
player.setPlaybackConfig({
startTim: xxx, // 回放开始时间设置
endTime: xxx, // 回放结束时间设置
scale: 2, // 回放倍率
eventType: [1, 2, 3] // 回放事件类型
});
}
// 获取当前回放时间
const getPlaybackTime = () => {
let timeStamp = player.getPlaybackTime(); // 13位时间戳
}
用户需注册TP-LINK商用云平台账号成为开发者。
该账号需要安全保存,因为后续所有的开发流程都需要基于此账号进行,更重要的是,后续添加的设备与购买的服务,都归属于该账号。该账号还将作为超级管理员,可以创建子账号,从而实现应用内权限 的分配与管理:
完成以上步骤后可通过相关协议文档获取到用于预览的视频流地址和鉴权token等信息。具体流程如下:
注:开放接口可以通过ak/sk的方式进行鉴权,具体使用说明可见商云“开发者”菜单。
requestStreamUrl请求和响应参数示例:
xxxxxxxxxx
{
"qrCode":"7D98AEE1EAF46E2E6",
"channelId":1,
"streamType":"video",// video: 预览,sdvod:回放
"resolution":2, // 0:流畅,2:高清
"clientType":"browser"
}
{
"result": {
"sdkStreamUrl": "https://smbcloud-openapi.tp-link.com.cn/vms/open/webServer/v1/requestRelayUrl?token=12089-e2FwcGxpY2F0aW9uSWQgPSAxODYwfQ-9428ea08997541178fe11e3b6f4eec28&devInfoId=21000002447&clientType=browser&streamType=video&resolution=2"
},
"error_code": 0
}
预览时清晰度默认为流畅,若要修改清晰度,需重新调用requestStreamUrl接口配置resolution,以获取新的播放地址
获取设备前的流程与预览一致,前端拿到设备信息(parentQrCode、qrCode、channelId)之后,可查询设备存储的录像并进行播放:
回放时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: xxxx // 跳转到指定时间开始回放
});
player.setPlaybackConfig({
startTime: xxxx,
scale: 0.5 // 配置可组合,跳转时间并开启1/2倍速播放
});
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 | 解码性能不足 | 解码过慢,可能是浏览器资源不足够解码器流畅运行 |
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 | 紧急呼救 |