视频理解

视频理解 是做什么的？

构建一次共享的证据层。将观察结果保留在源时间中，将编辑决策留给下游技能。

本技能是 /video-cut、/video-to-shorts、 /video-add-captions、/video-add-content-cards 和 /video-add-graphic-motion 的前置条件。 请先运行本技能，以便这些下游技能使用相同的经过验证的证据和时间线。

依赖项

需要 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 毫秒的间隔，以便字幕和衍生品不会静默地丢失文本。

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。

契约

• 创建或验证 project.json 时，请阅读 project-schema.md。
• 在映射源时间和节目时间时，请阅读 timeline-schema.md。
• 在编写语义理解之前，请阅读 understanding-schema.md。
• 使用 understanding.example.json 作为简洁示例。

所有持久的机器文件都位于 work/understand/ 中。将 work/cache/ 视为可丢弃的。