mcpField
V
video-understand

video-understand

github.com/heygen-com创意与媒体5261.1k 次安装15 周前更新
代码仓库

关于 video-understand

video-understand 是用于本地分析视频内容的技能，可提取场景帧或关键帧，并可选用 Whisper 转录音频。处理过程离线运行，无需 API 密钥。

主要功能

  1. 01场景变化检测与取帧
  2. 02关键帧或定时取帧
  3. 03可选 Whisper 音频转录
  4. 04以 JSON 输出结果

适用场景

  1. 01离线查看视频代表性画面
  2. 02提取视频帧供视觉检查
  3. 03生成视频转录与元数据

安装

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

$npx skills add https://github.com/heygen-com/skills --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