BodyBalanceEvaluation/document/视频推流和录制规则说明.md

# 视频推流和录制规则说明

## 概述

本文档详细说明了身体平衡评估系统的视频推流和录制功能规则，包括足部监视视频推流、深度相机视频推流、多路视频同步录制以及数据库存储规范。

## 功能架构

### 1. 视频推流功能

#### 1.1 推流类型
- **足部监视视频推流**: 来自普通摄像头的足部监测画面
- **深度相机视频推流**: 来自FemtoBolt深度相机的身体姿态画面

#### 1.2 推流技术规范
- **传输协议**: WebSocket
- **推流格式**: Base64编码的JPEG图像帧
- **推流频率**: 30 FPS
- **线程模式**: 独立线程处理，避免阻塞主程序
- **目标端**: 前端Web页面实时显示

#### 1.3 推流实现方式
```python
# 足部监视视频推流线程
def _camera_streaming_thread(self):
    # 从摄像头获取帧 → 编码 → WebSocket推送

# 深度相机视频推流线程  
def _femtobolt_streaming_thread(self):
    # 从FemtoBolt获取帧 → 编码 → WebSocket推送
```

### 2. 视频录制功能

#### 2.1 录制类型
根据`detection_sessions`表结构，系统需要同步录制三种视频：

1. **足部检测视频** (`normal_video_path`)
   - 数据源: 普通摄像头
   - 文件名: `feet.mp4`
   - 内容: 足部监测画面

2. **深度相机视频** (`femtobolt_video_path`)
   - 数据源: FemtoBolt深度相机
   - 文件名: `body.mp4`
   - 内容: 身体姿态深度画面

3. **屏幕录制视频** (`screen_video_path`)
   - 数据源: 前端界面录制
   - 文件名: `screen.mp4`
   - 内容: 完整的检测界面录制

#### 2.2 存储路径规范
```
基础路径: data/patients/{患者ID}/{sessionID}/
├── feet.mp4          # 足部检测视频
├── body.mp4          # 深度相机视频
└── screen.mp4        # 屏幕录制视频
```

#### 2.3 录制参数规范
- **视频编码**: H.264 (mp4v)
- **分辨率**: 
  - 足部视频: 1280x720
  - 深度相机视频: 1920x1080 (根据FemtoBolt配置)
  - 屏幕录制: 根据前端界面尺寸
- **帧率**: 30 FPS
- **音频**: 不录制音频

## 核心方法设计

### 3.1 录制控制方法

#### 3.1.1 start_recording方法
```python
def start_recording(self, session_id: str, patient_id: str) -> Dict[str, bool]:
    """
    同步启动三个视频录制功能
    
    Args:
        session_id: 检测会话ID
        patient_id: 患者ID
        
    Returns:
        Dict: 各录制任务的启动状态
        {
            'feet_recording': bool,
            'body_recording': bool, 
            'screen_recording': bool,
            'session_updated': bool
        }
    """
```

**功能流程**:
1. 创建录制目录: `data/patients/{patient_id}/{session_id}/`
2. 初始化三个VideoWriter对象
3. 启动三个录制线程
4. 更新`detection_sessions`表的视频路径字段
5. 返回启动状态

#### 3.1.2 stop_recording方法
```python
def stop_recording(self, session_id: str) -> Dict[str, Any]:
    """
    同步停止所有视频录制
    
    Args:
        session_id: 检测会话ID
        
    Returns:
        Dict: 录制结果信息
        {
            'status': 'success'|'failed',
            'video_files': {
                'feet_video': str,
                'body_video': str,
                'screen_video': str
            },
            'file_sizes': Dict[str, int],
            'duration': int
        }
    """
```

**功能流程**:
1. 停止所有录制线程
2. 释放VideoWriter资源
3. 检查录制文件完整性
4. 更新`detection_sessions`表的结束时间和持续时间
5. 返回录制结果

### 3.2 推流控制方法

#### 3.2.1 start_streaming方法
```python
def start_streaming(self) -> Dict[str, bool]:
    """
    启动视频推流
    
    Returns:
        Dict: 推流启动状态
        {
            'camera_streaming': bool,
            'femtobolt_streaming': bool
        }
    """
```

#### 3.2.2 stop_streaming方法
```python
def stop_streaming(self) -> bool:
    """
    停止所有视频推流
    
    Returns:
        bool: 停止操作是否成功
    """
```

## 数据库集成规范

### 4.1 detection_sessions表字段映射

| 字段名 | 数据类型 | 说明 | 录制对应 |
|--------|----------|------|----------|
| `normal_video_path` | TEXT | 足部检测视频路径 | `feet.mp4` |
| `femtobolt_video_path` | TEXT | 深度相机视频路径 | `body.mp4` |
| `screen_video_path` | TEXT | 屏幕录制视频路径 | `screen.mp4` |
| `start_time` | TIMESTAMP | 检测开始时间 | 录制开始时间 |
| `end_time` | TIMESTAMP | 检测结束时间 | 录制结束时间 |
| `duration` | INTEGER | 检测持续时间(秒) | 录制持续时间 |
| `status` | TEXT | 会话状态 | recording/completed |

### 4.2 数据库操作时机

#### 4.2.1 录制开始时
```sql
UPDATE detection_sessions SET 
    normal_video_path = 'data/patients/{patient_id}/{session_id}/feet.mp4',
    femtobolt_video_path = 'data/patients/{patient_id}/{session_id}/body.mp4',
    screen_video_path = 'data/patients/{patient_id}/{session_id}/screen.mp4',
    start_time = CURRENT_TIMESTAMP,
    status = 'recording'
WHERE id = '{session_id}'
```

#### 4.2.2 录制结束时
```sql
UPDATE detection_sessions SET 
    end_time = CURRENT_TIMESTAMP,
    duration = CAST((julianday(CURRENT_TIMESTAMP) - julianday(start_time)) * 86400 AS INTEGER),
    status = 'completed'
WHERE id = '{session_id}'
```

## 线程管理规范

### 5.1 推流线程
- **线程名称**: `camera_streaming_thread`, `femtobolt_streaming_thread`
- **线程类型**: daemon线程
- **生命周期**: 与推流状态同步
- **异常处理**: 线程内部捕获异常，记录日志，不影响主程序

### 5.2 录制线程
- **线程名称**: `feet_recording_thread`, `body_recording_thread`, `screen_recording_thread`
- **线程类型**: 非daemon线程，确保录制完整性
- **同步机制**: 使用threading.Event控制启停
- **资源管理**: 确保VideoWriter正确释放

## 错误处理和异常情况

### 6.1 设备异常处理
- 摄像头断开: 停止对应推流/录制，记录错误日志
- FemtoBolt设备异常: 降级到普通摄像头模式
- 存储空间不足: 停止录制，保存已录制内容

### 6.2 网络异常处理
- WebSocket连接断开: 自动重连机制
- 推流延迟过高: 降低推流质量或帧率

### 6.3 文件系统异常
- 目录创建失败: 使用备用路径
- 文件写入失败: 记录错误，尝试恢复
- 磁盘空间监控: 预警机制

## 性能优化策略

### 7.1 内存管理
- 帧缓冲区大小限制
- 及时释放图像数据
- 内存使用监控

### 7.2 CPU优化
- 多线程并行处理
- 图像编码优化
- 帧率自适应调整

### 7.3 存储优化
- 视频压缩参数调优
- 分段录制避免大文件
- 异步写入机制

## 配置参数

### 8.1 推流配置
```python
STREAMING_CONFIG = {
    'fps': 30,
    'quality': 80,  # JPEG质量
    'max_frame_buffer': 10,
    'reconnect_interval': 5  # 秒
}
```

### 8.2 录制配置
```python
RECORDING_CONFIG = {
    'fps': 30,
    'codec': 'mp4v',
    'max_file_size': 1024 * 1024 * 1024,  # 1GB
    'segment_duration': 600  # 10分钟分段
}
```

## 测试验证

### 9.1 功能测试
- [ ] 单独推流测试
- [ ] 同步录制测试
- [ ] 数据库更新测试
- [ ] 异常恢复测试

### 9.2 性能测试
- [ ] 长时间录制稳定性
- [ ] 多路并发性能
- [ ] 内存泄漏检测
- [ ] 存储空间使用

### 9.3 兼容性测试
- [ ] 不同设备组合
- [ ] 不同分辨率支持
- [ ] 浏览器兼容性

## 部署注意事项

1. **依赖库**: 确保OpenCV、WebSocket库版本兼容
2. **权限设置**: 摄像头访问权限、文件写入权限
3. **防火墙**: WebSocket端口开放
4. **存储规划**: 预估存储空间需求
5. **备份策略**: 重要录制文件的备份机制

---

*本文档版本: 1.0*  
*最后更新: 2025年08月03日*  
*维护人员: 系统开发团队*