f3e2d2dca7
Core modules: - probe.rs: ffprobe execution logic - parser.rs: JSON parsing logic - output.rs: Output formatting - lib.rs: Library interface - main.rs: CLI entry point Features: - Extract video metadata using ffprobe - Parse video/audio/subtitle streams - Save to JSON file - Console summary output Documentation: - Added QUICKSTART.md - Added ENVIRONMENT_SETUP_REPORT.md
341 lines
7.9 KiB
Markdown
341 lines
7.9 KiB
Markdown
# 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！
|