cxh/kunlang_video

Fork 0

cxh 976fe61f94 Implement on-demand live video protocol

2026-06-05 09:25:04 +08:00

5.2 KiB

Raw Blame History

通用视频软件视频协议

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

{
  "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 开始实时推流示例

请求：

{
  "type": "request",
  "seqNo": 1234567890,
  "data": {
    "switch": 1
  }
}

应答：

{
  "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 停止实时推流示例

请求：

{
  "type": "request",
  "seqNo": 1234567891,
  "data": {
    "switch": 0
  }
}

应答：

{
  "type": "response",
  "seqNo": 1234567891,
  "data": []
}

收到 switch=0 后，视频软件停止向 live SRS 外推实时流；服务进程继续运行，录像分支仍由 srs.record_enabled 配置决定。

5. 录像段查询接口，预留

本章节暂缓实现，本版本不作为联调依据。当前已有录像代码不主动删除，但不纳入本次协议联调目标。

预留 topic：

/zxwl/sweeper/{vid}/record/query

预留请求字段：

字段	类型	说明
`loc`	int	摄像头位置索引
`startTime`	long	查询开始时间，毫秒
`endTime`	long	查询结束时间，毫秒

6. 录像段播放接口，预留