210 lines
5.2 KiB
Markdown
210 lines
5.2 KiB
Markdown
# 通用视频软件视频协议
|
||
|
||
本文档定义通用视频软件与平台之间的视频相关 MQTT 协议。
|
||
|
||
本版本仅将实时视频心跳和实时播放地址获取作为联调依据。录像查询、录像播放章节为预留章节，暂缓实现，本版本不作为联调依据。
|
||
|
||
## 1. MQTT 连接
|
||
|
||
连接参数由软件运行目录下的 `config.json` 提供：
|
||
|
||
| 字段 | 说明 |
|
||
| --- | --- |
|
||
| `mqtt_server.address` | MQTT 服务器地址 |
|
||
| `mqtt_server.port` | MQTT 服务器端口 |
|
||
| `mqtt_server.client_id` | MQTT client id |
|
||
| `mqtt_server.username` | MQTT 用户名 |
|
||
| `mqtt_server.password` | MQTT 密码 |
|
||
| `mqtt_server.veh_id` | 设备/车辆唯一编号，协议 topic 中记为 `{vid}` |
|
||
| `mqtt_server.topic_profile` | topic 配置，默认 `protocol`，可切换为 `legacy` |
|
||
|
||
## 2. MQTT Topic
|
||
|
||
默认 `topic_profile=protocol` 时使用协议主题：
|
||
|
||
| 用途 | Topic |
|
||
| --- | --- |
|
||
| 实时视频状态上报 | `/zxwl/sweeper/{vid}/video/status` |
|
||
| 实时播放地址获取 | `/zxwl/sweeper/{vid}/video/query` |
|
||
| 录像段查询，预留 | `/zxwl/sweeper/{vid}/record/query` |
|
||
| 录像段播放，预留 | `/zxwl/sweeper/{vid}/record/play` |
|
||
|
||
兼容 `topic_profile=legacy` 时使用旧主题：
|
||
|
||
| 用途 | Topic |
|
||
| --- | --- |
|
||
| 实时视频状态上报 | `/kun/vehicle/video/status/{vid}` |
|
||
| 实时播放地址获取 | `/kun/vehicle/video/request/{vid}` |
|
||
| 录像段查询，预留 | `/kun/vehicle/video/record/query/{vid}` |
|
||
| 录像段播放，预留 | `/kun/vehicle/video/record/play/{vid}` |
|
||
|
||
## 3. 实时视频状态上报
|
||
|
||
### 3.1 数据协议
|
||
|
||
| 项目 | 内容 |
|
||
| --- | --- |
|
||
| 协议 | MQTT + JSON |
|
||
| 发送方 | 视频软件 |
|
||
| 接收方 | 平台 |
|
||
| 上报频率 | 默认 1s 一次，由 `mqtt_server.mqtt_heart_threshold` 配置 |
|
||
| 默认 topic | `/zxwl/sweeper/{vid}/video/status` |
|
||
|
||
### 3.2 消息内容
|
||
|
||
| 字段 | 类型 | 说明 |
|
||
| --- | --- | --- |
|
||
| `timestamp` | long | 上报时间戳，13 位毫秒 |
|
||
| `status` | int | `0`：未推流或全部异常；`1`：全部实时通道正常；`2`：部分实时通道异常 |
|
||
| `channels` | array | 各通道实时推流状态 |
|
||
|
||
`channels` 对象结构：
|
||
|
||
| 字段 | 类型 | 说明 |
|
||
| --- | --- | --- |
|
||
| `loc` | int | 摄像头位置索引，0-7 |
|
||
| `running` | bool | 当前实时推流是否正常 |
|
||
| `reason` | string/null | 不正常时的原因；正常时为 `null` |
|
||
|
||
服务启动默认不向 live SRS 外推实时流。未收到 `switch=1` 前，心跳中通道 `running=false`，`reason` 表示实时推流未开启。
|
||
|
||
### 3.3 示例
|
||
|
||
```json
|
||
{
|
||
"timestamp": 1744247201000,
|
||
"status": 0,
|
||
"channels": [
|
||
{
|
||
"loc": 0,
|
||
"running": false,
|
||
"reason": "Live stream not requested"
|
||
}
|
||
]
|
||
}
|
||
```
|
||
|
||
## 4. 实时播放地址获取
|
||
|
||
### 4.1 数据协议
|
||
|
||
| 项目 | 内容 |
|
||
| --- | --- |
|
||
| 协议 | MQTT + JSON |
|
||
| 请求方 | 平台 |
|
||
| 应答方 | 视频软件 |
|
||
| 默认 topic | `/zxwl/sweeper/{vid}/video/query` |
|
||
|
||
请求和应答使用同一个 topic，通过 `type` 和 `seqNo` 区分。
|
||
|
||
### 4.2 请求内容
|
||
|
||
| 字段 | 类型 | 说明 |
|
||
| --- | --- | --- |
|
||
| `type` | string | 固定为 `request` |
|
||
| `seqNo` | long/string | 应答流水号，请求和应答保持一致 |
|
||
| `data` | object | 请求内容 |
|
||
|
||
`data` 对象结构：
|
||
|
||
| 字段 | 类型 | 说明 |
|
||
| --- | --- | --- |
|
||
| `switch` | int | `1`：开始向服务器推实时视频并返回播放 URL；`0`：停止向服务器推实时视频，避免持续消耗外网流量 |
|
||
|
||
### 4.3 开始实时推流示例
|
||
|
||
请求：
|
||
|
||
```json
|
||
{
|
||
"type": "request",
|
||
"seqNo": 1234567890,
|
||
"data": {
|
||
"switch": 1
|
||
}
|
||
}
|
||
```
|
||
|
||
应答：
|
||
|
||
```json
|
||
{
|
||
"type": "response",
|
||
"seqNo": 1234567890,
|
||
"data": [
|
||
{
|
||
"loc": 0,
|
||
"url": "http://36.153.162.171:11985/rtc/v1/whep/?app=camera&stream=AHD1_main&vhost=live&eip=36.153.162.171:8000"
|
||
}
|
||
]
|
||
}
|
||
```
|
||
|
||
说明：
|
||
|
||
- URL 使用当前 `srs.live_playback_profile` 生成。
|
||
- 公网 profile 必须带 `eip=36.153.162.171:8000`。
|
||
- `stream` 使用 `AHD*_main`，不带 `.flv`。
|
||
- 切换实时推流状态时允许视频管线短暂重启。
|
||
|
||
### 4.4 停止实时推流示例
|
||
|
||
请求：
|
||
|
||
```json
|
||
{
|
||
"type": "request",
|
||
"seqNo": 1234567891,
|
||
"data": {
|
||
"switch": 0
|
||
}
|
||
}
|
||
```
|
||
|
||
应答：
|
||
|
||
```json
|
||
{
|
||
"type": "response",
|
||
"seqNo": 1234567891,
|
||
"data": []
|
||
}
|
||
```
|
||
|
||
收到 `switch=0` 后，视频软件停止向 live SRS 外推实时流；服务进程继续运行，录像分支仍由 `srs.record_enabled` 配置决定。
|
||
|
||
## 5. 录像段查询接口，预留
|
||
|
||
本章节暂缓实现，本版本不作为联调依据。当前已有录像代码不主动删除，但不纳入本次协议联调目标。
|
||
|
||
预留 topic：
|
||
|
||
```text
|
||
/zxwl/sweeper/{vid}/record/query
|
||
```
|
||
|
||
预留请求字段：
|
||
|
||
| 字段 | 类型 | 说明 |
|
||
| --- | --- | --- |
|
||
| `loc` | int | 摄像头位置索引 |
|
||
| `startTime` | long | 查询开始时间，毫秒 |
|
||
| `endTime` | long | 查询结束时间，毫秒 |
|
||
|
||
## 6. 录像段播放接口，预留
|
||
|
||
本章节暂缓实现，本版本不作为联调依据。当前已有录像代码不主动删除，但不纳入本次协议联调目标。
|
||
|
||
预留 topic：
|
||
|
||
```text
|
||
/zxwl/sweeper/{vid}/record/play
|
||
```
|
||
|
||
预留请求字段：
|
||
|
||
| 字段 | 类型 | 说明 |
|
||
| --- | --- | --- |
|
||
| `loc` | int | 摄像头位置索引 |
|
||
| `segmentId` | string | 录像段 ID |
|