video-understand 是一个用于在本地理解视频内容的工具,结合 ffmpeg 抽帧与 Whisper 语音转写,完全离线运行,无需 API 密钥。
用途
该工具用于理解视频内容:从视频中抽取画面帧,并可选择对音频进行语音转写,最终以 JSON 形式输出视频的基本信息、帧列表与转写文本。适合需要在本地、无外部 API 依赖的情况下分析视频画面与语音的场景。
主要能力
- 使用 ffmpeg 进行帧提取,使用 Whisper 进行语音转写,全程离线,无需 API 密钥。
- 提供三种抽帧模式:
- scene(默认):通过 ffmpeg
select='gt(scene,0.3)'检测场景变化,适合大多数内容多变的视频。 - keyframe:提取 I 帧(编码关键帧),适合具有自然关键帧分布的编码视频。
- interval:根据视频时长与最大帧数均匀间隔抽帧,适合固定采样、输出可预测的场景。
- 若 scene 模式未检测到场景变化,会自动回退到 interval 模式。
- scene(默认):通过 ffmpeg
- 输出 JSON,包含视频文件名、时长、分辨率、抽帧模式、帧列表(路径、时间戳、格式化时间戳)、帧数量、转写片段(起止时间与文本)以及完整转写文本。
- 可通过 Read 工具查看抽取出的帧图像路径,进行视觉理解。
使用方式
前置依赖:
- ffmpeg + ffprobe(必需):
brew install ffmpeg - openai-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 |
输出示例:
{
"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": "Hello and welcome..."}
],
"text": "Full transcript...",
"note": "Use the Read tool to view frame images for visual understanding."
}
完整 JSON 输出结构可参考 references/output-format.md。
适用场景
- 需要在本地、无网络或不允许调用外部 API 的环境中分析视频画面与语音内容。
- 需要按场景变化、关键帧或固定间隔抽取视频帧,并获取带时间戳的帧列表。
- 需要将视频语音转写为带时间区间的文本,用于后续检索或理解。
限制
- 需要预先安装 ffmpeg 与 ffprobe;转写功能需要额外安装 openai-whisper。
- 转写质量与速度受所选 Whisper 模型大小影响。
- 抽帧数量受
--max-frames限制(默认 20)。 - 资料未提供关于收费、价格、支持平台、处理时长或效果保证的信息。