视频元数据分析器

基于 Python + uv 的命令行工具，用于递归扫描一个或多个目录中的视频文件，调用 ffprobe 提取结构化元数据，并调用 ffmpeg 记录运行环境能力，最终输出：

• report.json：完整元数据与汇总统计
• files.csv：逐文件明细
• report.html：可直接打开的离线可视化报告

当前能力

• 输入一个或多个目录，递归发现常见视频文件
• 提取视频时长、大小、编码、分辨率、帧率、音频编码等字段
• 单个视频探测失败时不中断整次扫描，会单独记录错误清单
• 汇总时长分布、大小分布、视频编码分布、分辨率分布
• 时长分布、大小分布会根据当前目录样本范围自动调整分桶粒度，避免结果全部挤在默认大桶里
• 可以基于已有 report.json 重新计算 summary，并重建 report.html / files.csv，无需再次扫描视频文件
• 生成适合人工查看的 HTML 报告，以及适合后续二次处理的 JSON / CSV

依赖要求

• Python 3.11+
• uv
• ffprobe
• ffmpeg

要求 ffprobe 与 ffmpeg 已经在系统 PATH 中，或者在运行时通过参数显式指定。

初始化

uv sync --dev

运行方式

最直接的方式：

uv run video-metadata-analyzer D:\Videos E:\Archive --output-dir .\reports\latest

如果你更习惯模块方式：

uv run python -m video_metadata_analyzer D:\Videos --output-dir .\reports\latest

如果 ffprobe / ffmpeg 不在 PATH 中，可以显式指定：

uv run video-metadata-analyzer D:\Videos `
  --ffprobe-bin C:\ffmpeg\bin\ffprobe.exe `
  --ffmpeg-bin C:\ffmpeg\bin\ffmpeg.exe `
  --output-dir .\reports\latest

如果你已经有一份旧的 report.json，只想在新版本逻辑下重算汇总并重建报告，不想重新扫描视频文件：

uv run video-metadata-analyzer --report-json .\reports\latest\report.json

默认会直接在该 report.json 所在目录重写：

• report.json
• files.csv
• report.html

如果你希望把重建后的结果写到新目录：

uv run video-metadata-analyzer `
  --report-json .\reports\latest\report.json `
  --output-dir .\reports\rebuilt

输出内容

生成目录内默认包含以下文件：

• report.json
• files.csv
• report.html

其中：

• report.json 包含 summary、成功文件列表 files，以及失败文件列表 failures
• files.csv 同时输出成功和失败结果，带 status、error_type、error_message 字段
• report.html 是离线静态页面，可以直接双击打开查看，并显示错误清单面板
• 当使用 --report-json 时，会从 files / failures 重新计算 summary，再生成新的 report.json、files.csv、report.html

开发与测试

运行测试：

uv run pytest -q

查看命令帮助：

uv run video-metadata-analyzer --help

第一版边界

当前版本优先保证“扫描、提取、汇总、可视化”这条主链路可用，暂时没有做这些增强项：

• 损坏视频的深度解码验证
• 更复杂的前端交互图表
• 增量扫描与数据库缓存