SuperAPI AI 工具集

video-understand

通用与其它

查看项目

更新于 11-08 16:06

技能介绍

video-understand 是一个用于在本地理解视频内容的工具,结合 ffmpeg 抽帧与 Whisper 语音转写,完全离线运行,无需 API 密钥。

用途

该工具用于理解视频内容:从视频中抽取画面帧,并可选择对音频进行语音转写,最终以 JSON 形式输出视频的基本信息、帧列表与转写文本。适合需要在本地、无外部 API 依赖的情况下分析视频画面与语音的场景。

主要能力

  • 使用 ffmpeg 进行帧提取,使用 Whisper 进行语音转写,全程离线,无需 API 密钥。
  • 提供三种抽帧模式:
    • scene(默认):通过 ffmpeg select='gt(scene,0.3)' 检测场景变化,适合大多数内容多变的视频。
    • keyframe:提取 I 帧(编码关键帧),适合具有自然关键帧分布的编码视频。
    • interval:根据视频时长与最大帧数均匀间隔抽帧,适合固定采样、输出可预测的场景。
    • 若 scene 模式未检测到场景变化,会自动回退到 interval 模式。
  • 输出 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)。
  • 资料未提供关于收费、价格、支持平台、处理时长或效果保证的信息。