视频元数据分析器

一个基于 Python + uv 的命令行工具，用于递归扫描一个或多个目录中的视频文件，调用 ffprobe 提取结构化元数据，并生成三类报告：

• report.json：完整元数据、失败列表与统计摘要
• files.csv：适合后续处理的明细表
• report.html：可直接打开的人类可读报告

当前能力

• 递归扫描一个或多个目录，自动发现常见视频文件
• 提取视频时长、大小、码率、分辨率、帧率、流数量等字段
• 单个视频探测失败时不中断整体扫描，会单独记录到失败列表
• 输出时长分布、大小分布、视频编码分布、分辨率分布
• 默认根据当前样本范围自动调整时长/大小分桶粒度
• 可用参数显式指定时长和大小分布的粒度，覆盖自动分桶
• 可以基于已有 report.json 重新计算 summary，并重建 report.html / files.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

粒度参数

默认情况下，时长分布和大小分布会根据样本范围自动选择合适的分桶粒度。

如果你希望固定粒度，可以使用：

• --duration-bucket-seconds：显式指定时长分布的分桶粒度，单位为秒
• --size-bucket-megabytes：显式指定大小分布的分桶粒度，单位为 MB

例如：

uv run video-metadata-analyzer D:\Videos `
  --duration-bucket-seconds 60 `
  --size-bucket-megabytes 100 `
  --output-dir .\reports\latest

上面的命令会把时长分布按 60 秒一桶、大小分布按 100 MB 一桶来统计。

基于旧报告重建

如果你已经有一份旧的 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

重建时同样可以指定新的粒度参数：

uv run video-metadata-analyzer `
  --report-json .\reports\latest\report.json `
  --duration-bucket-seconds 300

扫描阶段如果使用了显式粒度，这些设置会写入 report.json 的 summary_options。之后再次用 --report-json 重建时，如果不额外传参，会继承原先保存的粒度；如果只传其中一个参数，则只覆盖对应那一项。

输出结果说明

输出目录默认包含三个文件：

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

其中：

• report.json 包含 summary、成功文件列表 files、失败文件列表 failures，以及用于重建的 summary_options
• 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

当前边界

当前版本优先保证扫描、提取、统计、可视化和报告产出，暂时没有实现这些增强项：

• 损坏视频内容级校验
• 交互式前端筛选界面
• 增量扫描缓存或数据库