# Video YOLO Player - 使用说明

版本: 2.0.0  
构建时间: 2026-03-06 12:00:00

## 概述

Video YOLO Player 是一个模块化的视频播放器，支持 YOLO 对象检测叠加显示。采用三步工作流程：

1. **视频分析** - 提取视频元数据
2. **对象预扫描** - 使用 YOLO 预处理视频
3. **播放** - 播放视频并显示检测结果

## 文件结构

```
video_yolo_player/
├── video_probe.py                  # 视频元数据提取工具
├── video_yolo_object_prescan.py    # YOLO 对象预扫描工具
├── video_yolo_player.py            # 主播放器
├── yolov8n.pt                      # YOLO 模型文件
└── README.md                       # 本文档
```

## 安装依赖

```bash
pip install opencv-python ultralytics numpy
```

确保已安装 `ffprobe` 和 `ffplay`（通常随 FFmpeg 安装）：
- macOS: `brew install ffmpeg`
- Linux: `sudo apt-get install ffmpeg`
- Windows: 从 https://ffmpeg.org 下载

## 使用流程

### 1. 提取视频元数据

```bash
python3 video_probe.py <video_path>
```

**输出**: `<video_name>.probe.json`

**示例**:
```bash
python3 video_probe.py my_video.mp4
```

**生成文件**: `my_video.probe.json`

包含信息：
- 视频格式、编码器
- 分辨率、帧率
- 时长、比特率
- 音频流、字幕流信息

### 2. 预扫描视频（可选但推荐）

```bash
python3 video_yolo_object_prescan.py <video_path> <yolo_model> [--save-interval SECONDS]
```

**输出**: `<video_name>.yolo.json`

**参数**:
- `--save-interval SECONDS`: 自动保存间隔（默认: 30 秒）
  - 范围: 5-300 秒
  - 推荐值:
    - 短视频 (< 5 分钟): 15 秒
    - 中等视频 (5-15 分钟): 30 秒（默认）
    - 长视频 (15-30 分钟): 60 秒
    - 超长视频 (> 30 分钟): 120 秒

**示例**:
```bash
# 默认 30 秒自动保存
python3 video_yolo_object_prescan.py my_video.mp4 yolov8n.pt

```

**生成文件**: `my_video.yolo.json`

包含信息:
- 每帧的检测结果
- 对象类别、 置信度
- 边界框坐标
- 自动保存次数和- 状态跟踪 (in_progress/interrupted/completed)

- 最后保存时间

**处理时间**: 取决于视频长度和硬件（约 0.05-0.1 秒/帧）
- 自动保存会增加少量开销（静默保存）

- 自动保存可以防止意外断电导致数据丢失

- 断点续传功能可以在中断后继续处理

### 3. 播放视频

```bash
python3 video_yolo_player.py <video_path> <yolo_model>
```

**示例**:
```bash
python3 video_yolo_player.py my_video.mp4 yolov8n.pt
```

## 播放器控制

### 键盘快捷键

| 按键 | 功能 |
|------|------|
| `y` / `Y` | 切换实时 YOLO 检测（蓝色框） |
| `p` / `P` | 切换预扫描 YOLO 数据（绿色框） |
| `i` / `I` | 显示视频探测信息 |
| `Space` | 暂停/继续 |
| `s` / `S` | 切换声音 |
| `b` / `B` | 切换状态栏 |
| `h` / `H` | 隐藏当前窗口 |
| `1` | 切换原始视频窗口 |
| `2` | 切换 YOLO 检测窗口 |
| `3` | 切换命令窗口 |
| `←` | 后退 5 秒 |
| `→` | 前进 5 秒 |
| `Shift+←` | 后退 30 秒 |
| `Shift+→` | 前进 30 秒 |
| `q` / `ESC` | 退出 |

### 命令输入

在命令窗口中输入以下命令并按 Enter：

| 命令 | 说明 | 示例 |
|------|------|------|
| `<帧号>` | 跳转到指定帧 | `1234` |
| `<时间码>` | 跳转到指定时间 | `00:01:30` |
| `<时间码.帧>` | 跳转到精确时间 | `00:01:30.15` |
| `+<秒数>` | 前进指定秒数 | `+10` |
| `-<秒数>` | 后退指定秒数 | `-5` |
| `i` | 显示视频探测信息 | `i` |

## 窗口布局

```
┌─────────────────┐  ┌─────────────────┐
│  1: Original    │  │  2: YOLO        │
│     Video       │  │    Detection    │
│                 │  │                 │
└─────────────────┘  └─────────────────┘
┌──────────────────────────────────────┐
│         3: Command Window            │
│  [Build Info]                        │
│  Examples: 123 | 00:01:30 | +10 | i  │
│  > _                                 │
└──────────────────────────────────────┘
```

- **窗口 1**: 原始视频
- **窗口 2**: YOLO 检测叠加（可显示实时和预扫描结果）
- **窗口 3**: 命令输入和状态显示

## 检测模式

### Live YOLO（实时检测）

- 按 `y` 激活
- **蓝色**边界框
- 实时计算，需要 GPU/CPU 性能
- 适合测试和调试

### Pre-scanned YOLO（预扫描）

- 按 `p` 激活
- **绿色**边界框
- 从 `.yolo.json` 加载，无性能开销
- 适合流畅播放和详细分析

### 双模式叠加

可以同时激活 `y` 和 `p`，对比实时检测和预扫描结果：
- 绿色框：预扫描结果
- 蓝色框：实时检测结果

## JSON 文件格式

### .probe.json 结构

```json
{
  "video_path": "/path/to/video.mp4",
  "probed_at": "2026-03-06T12:00:00",
  "format": {
    "format_name": "mov,mp4,m4a,3gp,3g2,mj2",
    "duration": 120.5,
    "size": 52428800,
    "bit_rate": 3473408
  },
  "video_stream": {
    "codec_name": "h264",
    "width": 1920,
    "height": 1080,
    "r_frame_rate": "30/1"
  },
  "audio_streams": [...]
}
```

### .yolo.json 结构

```json
{
  "metadata": {
    "video_path": "/path/to/video.mp4",
    "model_path": "/path/to/yolov8n.pt",
    "width": 1920,
    "height": 1080,
    "fps": 30.0,
    "total_frames": 3615,
    "total_duration": 120.5,
    "processed_at": "2026-03-06T12:00:00",
    "processing_time": 180.5,
    "total_detections": 7230
  },
  "frames": {
    "1": {
      "frame_number": 1,
      "time_seconds": 0.033,
      "time_formatted": "00:00:00",
      "detections": [
        {
          "class_id": 0,
          "class_name": "person",
          "confidence": 0.89,
          "x1": 100.5,
          "y1": 200.3,
          "x2": 300.7,
          "y2": 600.9
        }
      ]
    }
  }
}
```

## 性能优化建议

1. **预扫描优先**: 使用 `video_yolo_object_prescan.py` 预处理，播放时零性能开销
2. **GPU 加速**: 确保 YOLO 模型使用 GPU（自动检测）
3. **小模型**: `yolov8n.pt` 最快，`yolov8s/m/l/x.pt` 更准确但更慢
4. **分辨率**: 高分辨率视频需要更多处理时间

## 故障排除

### ffprobe 未找到

```bash
# macOS
brew install ffmpeg

# Linux
sudo apt-get install ffmpeg

# 验证安装
ffprobe -version
```

### YOLO 模型加载失败

```bash
# 下载 YOLOv8 模型
wget https://github.com/ultralytics/assets/releases/download/v0.0.0/yolov8n.pt
```

### 视频无法打开

检查文件路径和权限：
```bash
ls -la /path/to/video.mp4
```

### 性能问题

- 使用预扫描模式 (`p`) 代替实时检测 (`y`)
- 降低视频分辨率
- 使用更小的 YOLO 模型

## 完整示例

```bash
# 1. 分析视频
python3 video_probe.py /path/to/video.mp4

# 2. 预扫描对象
python3 video_yolo_object_prescan.py /path/to/video.mp4 yolov8n.pt

# 3. 播放视频
python3 video_yolo_player.py /path/to/video.mp4 yolov8n.pt

# 播放时：
# - 按 p 激活预扫描数据（绿色框）
# - 按 y 激活实时检测（蓝色框）
# - 按 i 查看视频信息
# - 输入 00:01:30 跳转到 1分30秒
```

## 更新日志

### v2.0.0 (2026-03-06)

**重大架构重构**:
- ✅ 模块化设计：分离 probe、prescan、player
- ✅ 移除 .txt 支持，统一使用 JSON
- ✅ 新增 y/Y 命令：实时 YOLO 检测（蓝色）
- ✅ 新增 p/P 命令：预扫描数据（绿色）
- ✅ 新增 i/I 命令：查看视频探测信息
- ✅ 延迟加载 YOLO 模型（仅在需要时加载）
- ✅ 改进焦点模式：输入命令时禁用单键快捷键
- ✅ 自动屏幕分辨率检测和窗口布局

### v1.0.0 (2026-03-06)

- 初始版本
- 基本视频播放和 YOLO 检测
- .txt 格式支持

## 许可证

MIT License

## 作者

Video YOLO Player Team

## 贡献

欢迎提交 Issue 和 Pull Request！