视频传输协议

上位机可通过socket与RK3588多模态盒子建立视频传输通道，可参照开发包中的[Android示例代码](https://www.yuque.com/iflyaiui/zzoolv/xk9rpv "Android示例代码")实现摄像头视频预览。

## 视频传输协议

### 概述

上位机可以通过socket连接盒子来获取到实时图像帧数据，以及人脸检测结果信息。

**设备IP**：如果盒子为动态ip，可通过[发送串口](https://aiui-doc.xf-yun.com/project-1/doc-367/ "发送串口")指令来获取ip。
**指定端口**：9090

### 消息格式

消息格式与串口协议类似，唯一不同点为消息数据长度位从2个字节扩充到4个字节。

<table border="0" class="docutils" style="width: 100%;">
<colgroup>
<col width="5%" />
<col width="10%" />
<col width="15%" />
</colgroup>
<tbody valign="top">
<tr class="row-odd">
<td><b>字节</b></td>
<td><b>值</b></td>
<td><b>含义说明</b></td>
</tr>
<tr class="row-even">
<td>0</td>
<td>0xA5</td>
<td>同步头</td>
</tr>
<tr class="row-odd">
<td>1</td>
<td>0x01</td>
<td>用户ID</td>
</tr>
<tr class="row-even">
<td>2</td>
<td>0xXX</td>
<td>消息类型</td>
</tr>
<tr class="row-odd">
<td>3~6</td>
<td>0xXXXXXXXX</td>
<td>消息数据长度</td>
</tr>
<tr class="row-even">
<td>7~8</td>
<td>0xXXXX</td>
<td>消息ID</td>
</tr>
<tr class="row-odd">
<td>9~n</td>
<td>消息数据</td>
<td>消息数据</td>
</tr>
<tr class="row-even">
<td>n+1</td>
<td>0xXX</td>
<td>内部校验码</td>
</tr>
</tbody>
</table>

### 通信规则

*   半双工通信，进行一问一答式通信；
*   语音模组主要负责下发消息，上位机主要负责接收消息及回复确认消息；
*   建立socket连接之后，盒子会首先下发图像帧格式消息，上位机获取到图像格式方可进行图像绘制；
*   若语音模组未收到上位机的确认消息，会在超时500ms之后再发送最新的图像数据，无重发规则；

### 通信格式

通信格式定义了图像格式消息、人脸检测消息、图像帧消息、确认消息。下面将分类详述：

<table border="0" class="docutils" style="width: 100%;">
<colgroup>
<col width="10%" />
<col width="8%" />
<col width="6%" />
<col width="8%" />
<col width="8%" />
<col width="8%" />
<col width="6%" />
<col width="6%" />
<col width="6%" />
<col width="6%" />
<col width="6%" />
<col width="6%" />
<col width="6%" />
<col width="6%" />
<col width="6%" />
<col width="6%" />
</colgroup>
<tbody valign="top">
<tr class="row-odd">
<td><b>分类</b></td>
<td><b>同步头</b></td>
<td><b>用户ID</b></td>
<td><b>消息类型</b></td>
<td><b>消息长度</b></td>
<td><b>消息ID</b></td>
<td colspan="9"><b>消息数据</b></td>
<td><b>校验码</b></td>
</tr>
<tr class="row-even">
<td><b>字节</b></td>
<td>0</td>
<td>1</td>
<td>2</td>
<td>3~6</td>
<td>7~8</td>
<td colspan="9">9~n</td>
<td>n+1</td>
</tr>
<tr class="row-odd">
<td><strong>图像格式</strong></td>
<td>0xA5</td>
<td>0x01</td>
<td>0x07</td>
<td>见下文解释</td>
<td>见下文解释</td>
<td colspan="9">图像格式json</td>
<td>0x00</td>
</tr>
<tr class="row-even">
<td><b>字节</b></td>
<td>0</td>
<td>1</td>
<td>2</td>
<td>3~6</td>
<td>7~8</td>
<td colspan="9">9~n</td>
<td>n+1</td>
</tr>
<tr class="row-odd">
<td><strong>图像帧数据</strong></td>
<td>0xA5</td>
<td>0x01</td>
<td>0x08</td>
<td>见下文解释</td>
<td>见下文解释</td>
<td colspan="9">图像二进制</td>
<td>0x00</td>
</tr>
<tr class="row-even">
<td><b>字节</b></td>
<td>0</td>
<td>1</td>
<td>2</td>
<td>3~6</td>
<td>7~8</td>
<td colspan="2">9</td>
<td colspan="1">10</td>
<td colspan="3">11</td>
<td colspan="3">12</td>
<td>13</td>
</tr>
<tr class="row-odd">
<td><strong>单人版本人脸检测信息</strong></td>
<td>0xA5</td>
<td>0x01</td>
<td>0x09</td>
<td>见下文解释</td>
<td>见下文解释</td>
<td colspan="9">人脸信息json</td>
<td>0x00</td>
</tr>
<tr class="row-even">
<td><b>字节</b></td>
<td>0</td>
<td>1</td>
<td>2</td>
<td>3~6</td>
<td>7~8</td>
<td colspan="2">9</td>
<td colspan="1">10</td>
<td colspan="3">11</td>
<td colspan="3">12</td>
<td>13</td>
</tr>
<tr class="row-odd">
<td><strong>多人版本人脸检测信息</strong></td>
<td>0xA5</td>
<td>0x01</td>
<td>0x0b</td>
<td>见下文解释</td>
<td>见下文解释</td>
<td colspan="9">人脸信息json</td>
<td>0x00</td>
</tr>
<tr class="row-even">
<td><b>字节</b></td>
<td>0</td>
<td>1</td>
<td>2</td>
<td>3~6</td>
<td>7~8</td>
<td colspan="2">9</td>
<td colspan="1">10</td>
<td colspan="3">11</td>
<td colspan="3">12</td>
<td>13</td>
</tr>
<tr class="row-odd">
<td><strong>确认消息</strong></td>
<td>0xA5</td>
<td>0x01</td>
<td>0xff</td>
<td>同上</td>
<td>同上</td>
<td colspan="2">0xA5</td>
<td colspan="1">0x00</td>
<td colspan="3">0x00</td>
<td colspan="3">0x00</td>
<td>0x00</td>
</tr>
</tbody>
</table>
#### 消息长度：

数据格式中3-6字节为消息数据长度，消息长度编码为小端模式，即第3字节存储低字节，第6字节存储高字节。如确认消息中消息数据有4字节，则消息长度为4，编码到3-6字节就是0x04 0x00 0x00 0x00
　　
#### 消息ID：

数据格式中7-8字节为消息ID，与消息长度类似，也是小端模式编码。可以使用消息ID过滤因超时重发导致的重复消息。两字节长度的消息ID取值0-65535，所以在实际使用中需要循环使用，具体实现可以参考Android平台上的源码实现。
　　
#### 校检码：

数据格式中每种数据类型的最后一个字节都是校检码，由于图像帧数据较大，校验位固定为0x00
　　
#### 编码格式：

消息中字符串类型的数据编码格式为UTF-8。
图像帧数据为bgr格式的二进制数据
#### 确认消息
    
确认消息是一个特殊的消息类型，它是对其他类型消息的确认，它的消息ID与其要确认的消息的ID相同。
如一个图像帧消息的消息ID为0x9527，那对应的确认消息的消息ID也应该是0x9527。

### 图像格式消息
图像格式的数据为json字符串，包含图像的宽、高、格式信息。

```
{
    "format":0,    // 0:bgr  1:jpeg
    "width":500,
    "height":500
}
```
<div style="display: flex; align-items: center; background-color: #fff3cd; border-left: 6px solid #ffc107; border-radius: 4px; padding: 12px 16px; gap: 8px;">
    <div style="width: 30px; height: 30px; flex-shrink: 0;">
        <svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round">
            <path d="M12 9v2m0 4h.01m-6.938 4h13.856c1.54 0 2.502-1.667 1.732-3L13.732 4c-.77-1.333-2.694-1.333-3.464 0L3.34 16c-.77 1.333.192 3 1.732 3z"/>
        </svg>
    </div>
    <div style="flex: 1; line-height: 1.6;">
	<h3 style="margin: 0 0 6px 0; font-weight: 600;">注意：</h3>
        <p style="margin: 0; font-size: 0.95rem;">图像格式仅在建立socket连接时下发一次</p>
    </div>
</div>

### 图像二进制消息
根据图像格式消息获取图像对应的解析格式，默认格式为`JPEG`压缩格式
#### JPEG格式
JPEG格式为有损压缩格式，上位机需对图像进行JPEG解压缩，获取原始位图后再进行屏幕渲染。
#### bgr格式
bgr图像数据为原始图像数据，图像数据传输对网络带宽要求较高，一帧图像的大小为个`width*height*3`字节，帧率最高25fps，色彩通道顺序为RGB RGB ...

### 单人版本人脸检测消息
人脸检测结果为json字符串，结果中数据仅作为参考使用。
无人脸时：
```
{
    "hasFace": false,       //有无人脸
    "wakeup": false,        //是否人脸唤醒
    "frameIndex": 0         //图像帧id
}
```

有人脸时：
```
{
    "hasFace": true,       //有无人脸
    "wakeup": true,        //是否人脸唤醒
    "frameIndex": 0,         //图像帧id
    "faceInfo":{
        "x": 10,                //人脸左上角x坐标
        "y": 10,                //人脸左上角y坐标
        "w": 100,               //人脸宽度
        "h": 100,               // 人脸高度
        "faceIndex":101,        //人脸跟随id
        "headPitch": -0.2,       //头姿上下偏转角
        "headYaw":-0.2,         //头姿左右偏转角
        "mouthOcc":false        //true:嘴部遮挡 false:嘴部无遮挡
	}

}
```

### 多人版本人脸检测消息
人脸检测结果为json字符串，结果中数据仅作为参考使用。
无人脸时：
```
{
    "list":[
        {
            "hasFace": false,       //有无人脸
            "wakeup": false,        //是否人脸唤醒
            "frameIndex": 0         //图像帧id
        }
    ]
}

```

有人脸时：
```
{
    "list":[
        {
            "hasFace": true,       //有无人脸
            "wakeup": true,        //是否人脸唤醒
            "frameIndex": 0,         //图像帧id
            "body":{
                  "x": 10,                //人体左上角x坐标
                  "y": 10,                //人体左上角y坐标
                  "w": 100,               //人体宽度
                  "h": 100,               //人体高度
                  "bodyIndex":0           //人体跟踪id，同人脸跟踪id
            },
            "faceInfo":{
                  "x": 10,                //人脸左上角x坐标
                  "y": 10,                //人脸左上角y坐标
                  "w": 100,               //人脸宽度
                  "h": 100,               // 人脸高度
                  "faceIndex":101,        //人脸跟随id
                  "headPitch": -0.2,       //头姿上下偏转角
                  "headYaw":-0.2,         //头姿左右偏转角
                  "mouthOcc":false        //true:嘴部遮挡 false:嘴部无遮挡
            },
			"identityInfo": {
				"identity":0,  // 注册到人脸库中的id
				"extInfo":"xxxx",  // 注册时添加的人脸信息
				"status":0,  // 识别状态：0：识别成功，14001：正在识别；14002：图像质量低；14003：未注册人脸
			}
        }
    ]
}
```
## 常见问题

**Q:图像卡顿，1秒仅收到2帧图像数据**
**A:** 语音模组未收到确认消息，延迟500ms下后才发出第二帧数据
**Q:图像传输对带宽的要求**
**A:** 如果传输格式为JPEG压缩格式，使用百兆带宽即可。