mcpField
V
video-understand

video-understand

github.com/calesthio创意与媒体72.7k1.4k 次安装今天更新
代码仓库

关于 video-understand

video-understand 是用于本地分析视频的技能，可提取关键帧并选择性转录语音。它使用 ffmpeg 和 Whisper，输出结构化 JSON，无需 API 密钥。

主要功能

  1. 01按场景、关键帧或间隔提取画面
  2. 02可选的 Whisper 转录
  3. 03设置帧数上限和模型大小
  4. 04将 JSON 输出到终端或文件

适用场景

  1. 01查看视频中的关键时刻
  2. 02在本地转录视频音频
  3. 03按固定间隔抽取画面

安装

复制下面的命令，在终端中运行。

$npx skills add https://github.com/calesthio/openmontage --skill video-understand

安装后在 Claude Code 中输入/video-understand确认已加载。

附带文件references/output-format.mdscripts/understand_video.py

详细介绍

video-understand

使用 ffmpeg 提取帧，并使用 Whisper 转录，在本地理解视频内容。完全离线，无需 API 密钥。

Prerequisites

  • ffmpeg + ffprobe（必需）：brew install ffmpeg
  • openai-whisper（可选，用于转录）：pip install openai-whisper

Commands

# Scene detection + transcribe (default)
python3 skills/video-understand/scripts/understand_video.py video.mp4

# Keyframe extraction
python3 skills/video-understand/scripts/understand_video.py video.mp4 -m keyframe

# Regular interval extraction
python3 skills/video-understand/scripts/understand_video.py video.mp4 -m interval

# Limit frames extracted
python3 skills/video-understand/scripts/understand_video.py video.mp4 --max-frames 10

# Use a larger Whisper model
python3 skills/video-understand/scripts/understand_video.py video.mp4 --whisper-model small

# Frames only, skip transcription
python3 skills/video-understand/scripts/understand_video.py video.mp4 --no-transcribe

# Quiet mode (JSON only, no progress)
python3 skills/video-understand/scripts/understand_video.py video.mp4 -q

# Output to file
python3 skills/video-understand/scripts/understand_video.py video.mp4 -o result.json

CLI 选项

标志说明
video输入视频文件（位置参数，必需）
-m, --mode提取模式：scene（默认）、keyframe、interval
--max-frames保留的最大帧数（默认：20）
--whisper-modelWhisper 模型大小：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": "Hello and welcome..."}
  ],
  "text": "Full transcript...",
  "note": "Use the Read tool to view frame images for visual understanding."
}

使用 Read 工具打开帧图像路径，直观检查提取出的帧。

参考资料

  • references/output-format.md -- 完整的 JSON 输出架构文档

评论

支持 Markdown