mcpField
V
video-understand

video-understand

github.com/whitetowerai创意与媒体1785 次安装3 周前更新
代码仓库

关于 video-understand

video-understand 是用于视频分析的技能，在编辑前建立经过验证的证据层。它生成源时间轴上的转录、指标和事实观察，供后续视频技能使用，不规定剪辑决策。

主要功能

  1. 01初始化视频项目和时间轴
  2. 02使用 faster-whisper 转录音频
  3. 03分析客观指标与语义候选项
  4. 04验证源时间轴证据
  5. 05为后续技能生成审阅材料

适用场景

  1. 01在剪辑前整理源视频
  2. 02生成转录文本和审阅材料
  3. 03为字幕或剪辑技能提供已验证证据

安装

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

$npx skills add https://github.com/whitetowerai/cut-as-code --skill video-understand

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

包含的文件

除 SKILL.md 外，安装时一起下载的参考资料和脚本。

examples/
understanding.example.json
reference/
project-schema.md
timeline-schema.md
understanding-schema.md
scripts/
analyze.py
build_render_plan.py
build_timeline.py
check_protocol_extensions.py
init_project.py
probe.py
projectlib.py
render_project.py
transcribe.py
validate.py
tests/
test_editor_protocol.py
test_render_project.py

详细介绍

视频理解

只需构建一次共享证据层。观察结果使用源时间，并将编辑决策留给下游技能。

此技能是 /video-cut、/video-to-shorts、 /video-add-captions、/video-add-content-cards 和 /video-add-motion-graphics 的前置条件。先运行此技能，让这些技能使用相同的已验证证据和时间线。

依赖项

转录需要 ffmpeg/ffprobe、Python 和 faster-whisper。处理媒体前请检查这些依赖项。

工作流

  1. 从原始源初始化项目：

    python scripts/init_project.py path/to/source.mp4 path/to/my-video-project

    这会创建 input/、review/00-video-understanding/、final/、精简的面向机器的 work/ 目录树、身份时间线、project.json、媒体信息以及 START-HERE.md。它不会为未选择的编辑操作创建文件夹。

  2. 仅当源需要显式刷新元数据时，才再次探测：

    python scripts/probe.py input/original-video.mp4 work/understand/media.json

  3. 提取 16 kHz 单声道音频并进行转录：

    ffmpeg -y -i input/original-video.mp4 -ac 1 -ar 16000 work/cache/audio16k.wav
python scripts/transcribe.py work/cache/audio16k.wav work/understand/transcript medium `
  --lang auto --cache-dir work/cache/faster-whisper

    对于语言未知或混合语言的语音，请使用 --lang auto。切勿根据用户提示词的语言推断语音语言。仅当音频本身或用户提供的明确元数据能够确定语言时，才传入 --lang zh 之类的固定语言。将模型下载内容保存在项目本地的 work/cache/faster-whisper/ 缓存中。Faster-whisper 偶尔可能会生成起止时间相同的单点计时词语；共享时间线映射器会将其保留为 1 ms 的时间间隔，避免字幕及衍生内容悄然丢失文本。

  4. 生成客观指标和语义候选项：

    python scripts/analyze.py work/understand/transcript.json work/understand/analysis.json

  5. 阅读源、转录文本和分析结果。编写 work/understand/understanding.json，其中包含事实摘要、源时间范围、置信度和转录证据。不要规定剪辑、卡片或视觉风格。

  6. 在下游使用前进行验证：

    python scripts/validate.py understanding work/understand/understanding.json work/understand/transcript.json

  7. 仅在 review/00-video-understanding/ 下创建以下有用的审核产物： video-summary.md、transcript.srt 和 contact-sheet.jpg。核实元数据、 时间戳、证据引用和可见帧。请勿使用 PNG 或临时命名的文件替代协议规定的名称。

  8. 只有在审核产物和语义证据验证通过后，才将理解操作的 check.status 标记为 pass。 操作生命周期的 status 与检查结果彼此独立； 切勿将 verified 写入 check.status。

约定

所有持久化机器文件都位于 work/understand/。请将 work/cache/ 视为可丢弃内容。

评论

支持 Markdown