设备端与应用端信令交互说明

最近更新时间:2024-05-11 11:20:22

我的收藏

概述

底层应用端和设备端 P2P 传输通道建立后,将基于该通道实现 P2P 消息发送和音视频传输功能。下面将详细描述设备端与应用端的信令交互流程,分为音视频传输(设备推音视频流给应用端)、对讲音视频传输(应用端推音视频流给设备端,适用于语音对讲或音视频对讲)、接收信令(应用端发送消息给设备)、发送信令(设备发送信息给应用端)。
说明:
提及参数为内部参数,请勿使用。

音视频传输

请求方法 get
请求路径 / ipc.flv

基本请求参数

_crypto

类型:可选
可见性:外部参数
描述:加密开关,值为 on 或 off,无此参数或不为 off 则默认开启加密。
示例:
_crypto=off

action

类型:必选
可见性:外部参数
描述:本次拉流请求的类型,有 live 直播,playback 回放,download 下载。
示例:
action=live

channel

类型:必选
可见性:外部参数
描述:本次拉流请求的通道号,单摄像头为0,多摄像头设备指的是第几个摄像头,nvr 设备指的是第几路数据,均从0开始计数。
示例:
channel=0

user_args

类型:可选
可见性:外部参数
描述:用户自定义参数,不宜过长,建议控制在1KB 以内,内容和格式不限,但不得出现非法 URL 字符。
示例:
user_args=this_is_user_args%E4%BD%A0%E5%A5%BD

requester

类型:可选(后续开发建议作为必选参数)
可见性:外部参数
描述:发起拉流请求的角色,不宜过长,建议控制在64字节以内。目前有这几种:app-android,app-ios,wxmp-android,wxmp-ios,server-voip,如有必要可扩展版本号等额外信息,例如:app-android-xiaomi,wxmp-ios-p2p-player-version123。
示例:
requester=app-android

直播请求

用于观看摄像头实时音视频内容
直播请求参数 action = live

附加请求参数

quality
类型:必选
可见性:外部参数
描述:本次拉流请求的视频质量,有低中高三种,分别是:standard,high,super。
示例:
quality=standard

请求示例

http://ipc.p2p.com/ipc.flv?action=live&channel=0&quality=high&_token=123456789&_peername=xxxxxxxx&requester=app-android&req_id=xxxxxxxx&user_args=this_is_user_args%E4%BD%A0%E5%A5%BD

回放请求

用于回放摄像头SD 卡内录像
回放请求参数 action = playback

附加请求参数

start_time
类型:必选
可见性:外部参数
描述:请求回放的开始时间,UNIX 秒级时间戳, 与 end_time 间隔建议在5秒以上,间隔过小可能导致索引错误。
示例:
start_time=123456789
end_time
类型:必选
可见性:外部参数
描述:请求回放的结束时间,UNIX 秒级时间戳, 与 start_time 间隔建议在5秒以上,间隔过小可能导致索引错误。
示例:
end_time=123456789

请求示例

http://ipc.p2p.com/ipc.flv?action=playback&channel=0&start_time=1633060850&end_time=1633060880&_token=123456789&_peername=xxxxxxxx

下载请求

用于下载 SD 卡内文件,配合“查询文件列表”信令使用。
回放请求参数 action = download

附加请求参数

file_name
类型:必选
可见性:外部参数
描述:下载的文件名,若包含文件路径请进行 URL 编码处理。
示例:
file_name=test_file.mp4
offset
类型:必选
可见性:外部参数
描述:下载文件的起始位置,用户可借助此参数开发断点续传功能。
示例:
offset=0

请求示例

http://ipc.p2p.com/ipc.flv?action=download&channel=0&file_name=test_file.mp4&offset=0&_crypto=off&_peername=xxxxxxxx

对讲音视频传输

请求方法 post
请求路径 / voice

请求参数

基本请求参数

请参考“音视频传输 - 基本请求参数”中除 action,channel 的其余参数。

附加请求参数

channel
类型:摄像头类设备可选,NVR 类设备必选。
可见性:外部参数
描述:本次对讲请求的通道号,对于摄像头类设备此参数暂未使用,可省略;对于 NVR 类设备指的是第几路,从0开始计数。
示例:
channel=0

请求示例

http://ipc.p2p.com/voice?channel=0&_token=123456789&_peername=xxxxxxxx

接收信令

请求方法 post
请求路径 / command
默认开启加密,不可关闭。

请求参数

action

类型:必选
可见性:外部参数
描述:inner_define为内部信令,请勿使用;user_define为外部信令即用户自定义信令。
示例:
action=inner_define
action=user_define

channel

类型:摄像头类设备可选,NVR 类设备必选。
可见性:外部参数
描述:本次对讲请求的通道号,对于摄像头类设备此参数暂未使用,可省略;对于 NVR 类设备指的是第几路,从0开始计数。
示例:
channel=0

cmd

类型:必选
可见性:外部参数
描述:消息类型
示例:
cmd=my_message

内部信令

本地录像回放相关信令

按起止时间查询录像
请求参数:
描述
cmd
get_record_index
信令类型
start_time
UNIX 时间戳
查询录像的开始时间,单位为秒,与 end_time 间隔建议在5秒以上,间隔过小可能导致索引错误
end_time
UNIX 时间戳
查询录像的结束时间,单位为秒,与 start_time 间隔建议在5秒以上,间隔过小可能导致索引错误
type
枚举
表示录像的类型,是一个整数,由用户自己定义具体含义,目前暂不支持
返回值:
json 格式的录像索引列表,基本格式如下:
{
"video_list": [
{
"type": 0,
"start_time": "<unix时间戳>",
"end_time": "<unix时间戳>"
},
{
"type": 0,
"start_time": "<unix时间戳>",
"end_time": "<unix时间戳>"
}
]
}
请求示例:
http://ipc.p2p.com/command?_token=123456789&_peername=xxxxxxxx&action=inner_define&cmd=get_record_index&start_time=000&end_time=111
按月查询录像
请求参数:
描述
cmd
get_month_record
信令类型
time
时间
6位整数,前4位表示年,后两位表示月
返回值:
json 格式,其中video_list的值转换为一个32位的整数,从低位到高位每一比特代表月份的第几天是否有录像;例如:8320(0010000010000000)表示8号和14号有录像。
{"video_list":"123456"}
请求示例:
http://ipc.p2p.com/command?_token=123456789&_peername=xxxxxxxx&action=inner_define&cmd=get_month_record&time=202401
回放暂停
请求参数:
描述
cmd
playback_pause
信令类型
返回值:
json 格式,<code>为信令执行结果返回值,0正常,其他异常。
{"status":"<code>"}
请求示例:
http://ipc.p2p.com/command?_token=123456789&_peername=xxxxxxxx&action=inner_define&cmd=playback_seek&progress=123456
回放继续
请求参数:
描述
cmd
playback_resume
信令类型
返回值:
json 格式,<code>为信令执行结果返回值,0正常,其他异常。
{"status":"<code>"}
请求示例:
http://ipc.p2p.com/command?_token=123456789&_peername=xxxxxxxx&action=inner_define&cmd=playback_resume
设置播放位置
请求参数:
描述
cmd
playback_seek
信令类型
progress
整数
毫秒单位的时间戳,表示在当前文件内希望跳转播放的位置
返回值:
json 格式,<code>为信令执行结果返回值,0正常,其他异常。
{"status":"<code>"}
请求示例:
http://ipc.p2p.com/command?_token=123456789&_peername=xxxxxxxx&action=inner_define&cmd=playback_seek&progress=123456
获取播放位置
请求参数:
描述
cmd
playback_progress
信令类型
返回值:
json 格式,<code>为信令执行结果返回值,0正常,其他异常;<timestamp>当前播放进度,单位毫秒。
{
"status":"<code>",
"progress":"<timestamp>"
}
请求示例:
http://ipc.p2p.com/command?_token=123456789&_peername=xxxxxxxx&action=inner_define&cmd=playback_progress
设置快进
请求参数:
描述
cmd
playback_ff
信令类型
value
整数
0表示正常播放
1表示只播放I帧
2表示从相邻的两个I帧中取一个I帧播放
3表示从相邻的三个I帧中取一个I帧播放
以此类推
返回值:
json 格式,<code>为信令执行结果返回值,0正常,其他异常。
{"status":"<code>"}
请求示例:
http://ipc.p2p.com/command?_token=123456789&_peername=xxxxxxxx&action=inner_define&cmd=playback_ff&value=1
设置快退
请求参数:
描述
cmd
playback_rewind
信令类型
start_time
时间戳
单位毫秒,表示倒放的结束时间
end_time
时间戳
单位毫秒,表示倒放的开始时间
返回值:
json 格式,<code>为信令执行结果返回值,0正常,其他异常。
{"status":"<code>"}
请求示例:
http://ipc.p2p.com/command?_token=123456789&_peername=xxxxxxxx&action=inner_define&cmd=playback_rewind&start_time=100&end_time=200
设置倍速
请求参数:
描述
cmd
playback_speed
信令类型
speed
整数
单位毫秒,表示帧间隔,以视频为准进行同步,假设视频的正常帧率为25fps,即帧间隔是50ms,数值小于正常帧间隔则为快放。例如:设置为10则相当于5倍速快放;数值大于正常帧间隔则为慢放,例如设置为100则相当于0.5倍速慢放
返回值:
json 格式,<code>为信令执行结果返回值,0正常,其他异常。
{"status":"<code>"}
请求示例:
http://ipc.p2p.com/command?_token=123456789&_peername=xxxxxxxx&action=inner_define&cmd=playback_speed&speed=50

TWeCall及语音对讲相关信令

挂断
说明:由 client 端发送给设备端,用于接听以后,表示主动挂断。
请求参数:
描述
cmd
call_hang_up
信令类型
返回值:
json 格式,<code>为信令执行结果返回值,0正常,其他异常。
{"status":"<code>"}
请求示例:
http://ipc.p2p.com/command?_token=123456789&_peername=xxxxxxxx&action=inner_define&cmd=call_hang_up
拒接
说明:由 client 端发送给设备端,用于接听以前,表示拒接。
请求参数:
描述
cmd
call_reject
信令类型
返回值:
json 格式,<code>为信令执行结果返回值,0正常,其他异常。
{"status":"<code>"}
请求示例:

http://ipc.p2p.com/command?_token=123456789&_peername=xxxxxxxx&action=inner_define&cmd=call_reject
取消
说明:由 client 端发送给设备端,用于接听以前,表示主动取消呼叫。
请求参数:
描述
cmd
call_cancel
信令类型
返回值:
json 格式,<code>为信令执行结果返回值,0正常,其他异常。
{"status":"<code>"}
请求示例:
http://ipc.p2p.com/command?_token=123456789&_peername=xxxxxxxx&action=inner_define&cmd=call_cancel
占线
说明:由 client 端发送给设备端,用于接听以后,表示有其他设备正在通话。
请求参数:
描述
cmd
call_busy
信令类型
返回值:
json 格式,<code>为信令执行结果返回值,0正常,其他异常。
{"status":"<code>"}
请求示例:
http://ipc.p2p.com/command?_token=123456789&_peername=xxxxxxxx&action=inner_define&cmd=call_busy
无应答
说明:由 client 端发送给设备端,用于接听以前,表示呼叫超时无人接听。
请求参数:
描述
cmd
call_timeout
信令类型
返回值:
json 格式,<code>为信令执行结果返回值,0正常,其他异常。
{"status":"<code>"}
请求示例:
http://ipc.p2p.com/command?_token=123456789&_peername=xxxxxxxx&action=inner_define&cmd=call_timeout

其他信令

查询设备状态
请求参数:
描述
cmd
get_device_st
信令类型
type
live / voice / playback
必选,询问设备是否接受直播、对讲、回放请求
quality
standard / high / super
type 为 live 时必选,询问设备是否支持低中高图像质量的直播请求
返回值:
json 格式,status状态码,0接受连接请求,其他值拒绝连接请求;appConnectNum当前已连接到设备的 APP 或小程序数;maxConnectNum设备端支持的最大连接数。
[
{
"status":"code",
"appConnectNum":"2",
"maxConnectNum": "3"
}
]
请求示例:
http://ipc.p2p.com/command?_token=123456789&_peername=xxxxxxxx&action=inner_define&cmd=get_device_st&type=live&quality=standard
查询文件列表
请求参数:
描述
cmd
get_file_list
信令类型
返回值:
json 格式,file_type文件类型;file_name文件名;file_size文件大小;start_time开始时间;end_time结束时间;extra_info扩展信息,可用于携带哈希值或其他自定义文件信息。
{
"file_list": [
{
"file_type": "video",
"file_name": "1234.mp4",
"file_size": "1024000",
"start_time": "2024-01-23_12-34-00",
"end_time": "2024-01-23_12-34-59",
"extra_info": {
"md5": "abvdefg"
}
},
{
"file_type": "picture",
"file_name": "abcd.jpg",
"file_size": "10240",
"start_time": "2024-01-23_12-34-56",
"end_time": "2024-01-23_12-34-56"
}
]
}
请求示例:
http://ipc.p2p.com/command?_token=123456789&_peername=xxxxxxxx&action=inner_define&cmd=get_file_list
查询NVR下设备名称
请求参数:
描述
cmd
get_nvr_list
信令类型
返回值:
json 格式,DeviceName设备名;Channel位于几通道;Online是否在线。
[
{
"DeviceName": "name1",
"Channel": "1",
"Online": "0"
},
{
"DeviceName": "name2",
"Channel": "2",
"Online": "1"
}
]
请求示例:
http://ipc.p2p.com/command?_token=123456789&_peername=xxxxxxxx&action=inner_define&cmd=get_nvr_list

外部信令

即用户自定义信令
请求参数:
描述
cmd
信令内容
用户自定义信令,不宜过长,建议控制在1KB 以内,内容和格式不限,但不得出现非法 URL 字符
返回值:
格式不限,类型不限,不宜过长,建议控制在1KB 以内。
请求示例:
自定义信令进行云台控制示例:
http://ipc.p2p.com/command?_token=123456789&_peername=xxxxxxxx&action=user_define&cmd=ptz_left_speed_1
http://ipc.p2p.com/command?_token=123456789&_peername=xxxxxxxx&action=user_define&cmd=ptz_right_speed_1
自定义信令传输少量二进制数据:
http://ipc.p2p.com/command?_token=123456789&_peername=xxxxxxxx&action=user_define&cmd=36D7F336FCEC9E57318ECA0323BA94970296A776CE028D19F5CA5AC44E92952B4CE77642354CBAE7036F4DA954317462C61A1BC033DAC882FAAB9EDCBFEE47DA

发送信令

请求方法 post
请求路径 / feedback
默认开启加密,不可关闭。
消息在 http 报文正文中发送,采用 json 格式。

请求参数

描述
product_id
设备三元组信息
供对方识别设备、消息管理等场景使用
device_name
设备三元组信息
供对方识别设备、消息管理等场景使用

请求示例

http://127.0.0.1:34567/ipc.p2p.com/forward/xxxxxxxxxxxxx/proxy.sample.server/feedback?_token=123456789&product_id=xxxxxxxx&device_name=xxxxxxxx

用户自定义信令

用户自定义消息格式采用 json 格式,不得含有iv_private_cmd字段,其余内容不限,长度不宜过大,建议控制在16KB 以内。
示例:
发送
{
"my_message":"hello world"
}
接收
{
"status":"<code>"
}
<code>为返回值,0正常,其他异常。

内部信令

内部消息使用以下 json 格式
发送
{"iv_private_cmd":"<cmd>"}
接收
{"status":"<code>"}

挂断

说明:由设备端发送给 client 端,用于接听以后,表示主动挂断。
{"iv_private_cmd":"call_hang_up"}
响应:
{"status":"<code>"}
<code>为返回值,0正常,其他异常。

取消

说明:由设备端发送给 client 端,用于接听以前,表示主动取消呼叫。
{"iv_private_cmd":"call_cancel"}
响应:
{"status":"<code>"}
<code>为返回值,0正常,其他异常。

其他信令

设备端主动停止接收对端发送的音视频数据

说明:由设备端发送给 client 端,用于双向对讲的情景。
{"iv_private_cmd":"recv_stop"}
响应:
{"status":"<code>"}
<code>为返回值,0正常,其他异常。