理解视频内容
使用 FFmpeg 进行帧提取并结合 Whisper 进行转录,在本地理解视频内容。完全离线运行,无需任何 API 密钥。
前置条件
ffmpeg+ffprobe(必需):brew install ffmpegopenai-whisper(可选,用于转录):pip install openai-whisper
命令
# 场景检测 + 转录(默认)
python3 skills/video-understand/scripts/understand_video.py video.mp4
# 关键帧提取
python3 skills/video-understand/scripts/understand_video.py video.mp4 -m keyframe
# 固定间隔提取
python3 skills/video-understand/scripts/understand_video.py video.mp4 -m interval
# 限制提取帧数
python3 skills/video-understand/scripts/understand_video.py video.mp4 --max-frames 10
# 使用更大的 Whisper 模型
python3 skills/video-understand/scripts/understand_video.py video.mp4 --whisper-model small
# 仅提取帧,跳过转录
python3 skills/video-understand/scripts/understand_video.py video.mp4 --no-transcribe
# 安静模式(仅输出 JSON,无进度信息)
python3 skills/video-understand/scripts/understand_video.py video.mp4 -q
# 输出到文件
python3 skills/video-understand/scripts/understand_video.py video.mp4 -o result.json
CLI 选项
| 标志 | 描述 |
|---|---|
video | 输入的视频文件(位置参数,必需) |
-m, --mode | 提取模式:scene(默认)、keyframe、interval |
--max-frames | 保留的最大帧数(默认:20) |
--whisper-model | Whisper 模型大小:tiny、base、small、medium、large(默认:base) |
--no-transcribe | 跳过音频转录,仅提取帧 |
-o, --output | 将结果 JSON 写入文件,而非标准输出 |
-q, --quiet | 隐藏进度信息,仅输出 JSON |
提取模式
| 模式 | 工作原理 | 最佳用途 |
|---|---|---|
scene | 通过 ffmpeg select='gt(scene,0.3)' 检测场景变化 | 大多数视频,内容频繁变化 |
keyframe | 提取 I 帧(编码器关键帧) | 具有自然关键帧放置的编码视频 |
interval | 基于视频时长和最大帧数均匀分布采样 | 固定采样,结果可预测 |
如果 scene 模式未检测到任何场景变化,则会自动回退至 interval 模式。
输出
脚本将 JSON 输出到标准输出(或使用 -o 参数输出到文件)。完整的模式定义请参阅 references/output-format.md。
{
"video": "video.mp4",
"duration": 18.076,
"resolution": {"width": 1224, "height": 1080},
"mode": "scene",
"frames": [
{"path": "/abs/path/frame_0001.jpg", "timestamp": 0.0, "timestamp_formatted": "00:00"}
],
"frame_count": 12,
"transcript": [
{"start": 0.0, "end": 2.5, "text": "欢迎来到..."}
],
"text": "完整转录文本...",
"note": "请使用读取工具查看帧图片以进行视觉理解。"
}
请使用读取工具查看帧图片的路径,以视觉检查提取的帧。
参考
references/output-format.md— 完整的 JSON 输出模式文档