kunlang_video/docs/视频协议.md

# 通用视频软件视频协议

本文档定义通用视频软件与平台之间的视频相关 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 |