video_probe/README.md

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                       # 本文档

安装依赖

pip install opencv-python ultralytics numpy

确保已安装 ffprobe 和 ffplay（通常随 FFmpeg 安装）：

• macOS: brew install ffmpeg
• Linux: sudo apt-get install ffmpeg
• Windows: 从 https://ffmpeg.org 下载

使用流程

1. 提取视频元数据

python3 video_probe.py <video_path>

输出: <video_name>.probe.json

示例:

python3 video_probe.py my_video.mp4

生成文件: my_video.probe.json

包含信息：

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

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

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 秒

示例:

# 默认 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. 播放视频

python3 video_yolo_player.py <video_path> <yolo_model>

示例:

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 结构

{
  "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 结构

{
  "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 未找到

# macOS
brew install ffmpeg

# Linux
sudo apt-get install ffmpeg

# 验证安装
ffprobe -version

YOLO 模型加载失败

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

视频无法打开

检查文件路径和权限：

ls -la /path/to/video.mp4

性能问题

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

完整示例

# 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！