从一堆视频素材到剪辑执行包：我做了一个 Codex Skill

我做了一个 Codex Skill：把一堆视频素材整理成剪辑执行包

这两天做了一个小工具，准确说是一个 Codex Skill。仓库在这里：

https://github.com/kh464/ai-edit-package

起因也挺日常。最近在帮一位朋友整理视频剪辑作品，翻素材、挑镜头、想节奏，做着做着就想起以前在社团里专门负责视频内容的那段时间。那时候最耗人的往往不是剪辑软件本身，而是开始剪之前那一大摊准备工作。

它的名字现在叫 planning-video-edits，仓库名叫 ai-edit-package。名字有点长，但事情其实很简单：给它一堆视频素材，它先帮你整理素材，再生成一套可以继续剪辑的文件。

不是那种“建议你开头有冲击力，中间加强节奏，结尾升华主题”的建议。

我想要的是更落地一点的东西，比如：

asset_table.csv
asset_table.json
timeline.csv
shotlist.md
voiceover.srt
edit_plan.md
publish_checklist.md

这些文件不酷，但有用。剪辑真正开始的时候，往往缺的不是灵感，而是第一版结构。

起因

因为以前做过社团视频，我对这个流程还算熟。一个活动拍完，素材可能有几十个文件：开场、采访、空镜、观众反应、舞台、花絮。真正开始剪之前，要先把素材大致看一遍，心里知道哪些能当主线，哪些只能当补画面。

我之前也试过让 AI 帮忙做视频剪辑规划。结果经常是这样：

开头用一个强画面抓住观众，中间用快节奏镜头推进，最后用一个情绪镜头收束。

这句话没什么错，但也没法直接用。

剪辑师真正要处理的是很具体的问题：

IMG_0321.mp4 里面到底是什么？
哪个素材适合开头？
哪些只是过渡镜头？
这段应该放 2 秒还是 5 秒？
旁白从哪里开始，哪里停？
最后发 Reels、抖音、B 站，画幅和字幕安全区怎么处理？

如果 AI 只是在聊天窗口里给一段建议，我还是要自己回到文件夹里，从头看素材、记笔记、搭时间线。那它省下来的时间其实不多。

所以这个 Skill 的目标很明确：先别急着写漂亮文案，先把素材变成结构化文件。

第一步：先分析素材

视频文件不像文本文件。文件名通常没什么信息，尤其是手机素材，十几个 IMG_XXXX.mp4 排在一起，谁也不知道哪个是关键镜头。

于是我写了第一个脚本：

python scripts/analyze_footage.py path/to/footage --config config/default.yaml

它做的事比较朴素：

扫描素材目录
用 ffprobe 读取视频信息
记录时长、分辨率、帧率、横竖屏、有无音频
用 ffmpeg 抽几张代表帧
输出素材表和摘要

生成出来的东西大概是：

asset_table.csv
asset_table.json
analysis_summary.md
frames/<clip-name>/frame_###.jpg

这里我纠结过一个问题：每个视频到底抽多少帧？

一开始很容易写死，比如每个视频抽 6 张。但后来想想不对。20 秒的视频抽 6 张可能够，15 分钟的视频抽 6 张基本就是猜。长视频里可能换了好几个地点，光线也变了，人也变了，只看几张图很容易误判。

所以我把抽帧策略放到了配置文件里：

frame_sampling:
  preset: balanced
  presets:
    fast:
      min_frames_per_clip: 4
      max_frames_per_clip: 12
      interval_seconds: 45
    balanced:
      min_frames_per_clip: 6
      max_frames_per_clip: 24
      interval_seconds: 20
    deep:
      min_frames_per_clip: 10
      max_frames_per_clip: 48
      interval_seconds: 10

素材很多时用 fast，普通项目用 balanced，长视频或活动素材用 deep。这个设计不复杂，但我觉得很必要。视频素材的长度差异太大，固定抽帧数迟早会翻车。

第二步：生成剪辑执行包

分析素材只是第一步。知道“我有哪些素材”之后，还得知道“我怎么开始剪”。

所以又有了第二个脚本：

python scripts/build_edit_package.py output/footage-analysis --config config/default.yaml --target-duration 45 --platform reels

它会读取 asset_table.json，生成一套初始剪辑包：

timeline.csv
edit_plan.md
shotlist.md
voiceover.srt
publish_checklist.md
package_manifest.json

其中最关键的是 timeline.csv。

它不是最终时间线，也不是自动剪辑结果。它更像一张“剪辑草稿表”。每一行有：

时间线位置
镜头时长
来源文件
建议 source in / source out
这个镜头承担什么作用
旁白占位
声音提示
剪辑备注

这样一来，后面让 Codex 精修时，它不是在空白处发挥，而是在一张已经有结构的表上改。

voiceover.srt 也是同理。先给出时间轴和占位旁白，后面再改中文文案。哪怕第一版很粗，也比空白文件好。

我刻意没让脚本“理解画面”

这里有个取舍。

脚本现在不会因为文件名里有 sunset 就说“这是一个情绪化落日镜头”。它也不会凭空判断“这个镜头适合做结尾”。这些判断应该在看过抽帧之后做。

我让脚本只做确定性工作：

读取元数据
抽帧
生成表格
分配时间线
写出 CSV、Markdown、SRT

创意判断交给 Codex 或剪辑师。

这个边界对我来说挺重要。AI 可以参与判断，但基础文件生成最好稳定一点。否则它一本正经地编镜头内容，看起来很聪明，实际会误导人。

示例：一个 45 秒旅行短片

仓库里放了一个示例：

examples/travel-reel/

它模拟了 6 个旅行素材：

机场到达
火车窗外城市
街边食物特写
市场穿行
屋顶落日
夜晚霓虹路口

目标是做一个 45 秒竖屏 travel reel。

运行：

python scripts/build_edit_package.py examples/travel-reel/asset_table.json --output examples/travel-reel/edit-package --target-duration 45 --platform reels

会生成：

edit-package/
  edit_plan.md
  package_manifest.json
  publish_checklist.md
  shotlist.md
  timeline.csv
  voiceover.srt

然后可以继续让 Codex 改：

Use $planning-video-edits to refine examples/travel-reel/edit-package for a 45-second energetic city travel reel. Use the analysis summary, improve the shot order, rewrite voiceover.srt in Chinese, and mark which clips are opener/detail/ending.

这个流程没有宣传成“一键大片”。我也不太喜欢这么说。

它更像是把剪辑前面那段枯燥工作先铺好：整理素材、搭第一版时间线、写旁白占位、列发布检查项。剪辑师还是要判断，但不用从零开始。

项目结构

现在目录大概长这样：

ai-edit-package/
  SKILL.md
  README.md
  README.zh-CN.md
  agents/
    openai.yaml
  config/
    default.yaml
  scripts/
    analyze_footage.py
    build_edit_package.py
  tests/
    test_analyze_footage.py
    test_build_edit_package.py
  examples/
    travel-reel/
      asset_table.json
      analysis_summary.md
      WORKFLOW.md
      edit-package/
        timeline.csv
        edit_plan.md
        shotlist.md
        voiceover.srt
        publish_checklist.md

SKILL.md 是给 Codex 看的工作流说明。

scripts/ 是真正干活的地方。

examples/ 是给人看的。开源项目如果没有示例，读者很难判断这个东西到底能不能用。

测试里发现的一个小坑

项目里现在有一些单元测试：

python -m unittest tests.test_analyze_footage tests.test_build_edit_package -v

覆盖了抽帧数量、时间戳、视频文件查找、时间线分配、SRT 时间格式、剪辑包生成等。

有个小坑是在 Windows 上发现的。

我用 PowerShell 写了一个临时 asset_table.json，脚本读取时报：

Unexpected UTF-8 BOM

原因是有些 Windows 写文件方式会带 UTF-8 BOM。最后在读取 JSON 时改成：

encoding="utf-8-sig"

问题就没了。

这事很小，但挺典型。工具一旦准备给别人用，就不能只在自己顺手的环境里跑通。

现在还没做的东西

这个项目目前还没有直接导出 Premiere、Resolve、剪映草稿，也没有真正自动剪视频。

我一开始想过直接做 EDL、FCPXML 或剪映草稿，但后来先放下了。剪辑软件的导入格式细节不少，第一步就冲进去，容易把项目拖到兼容性泥潭里。

所以现在先做最通用的组合：

CSV + Markdown + SRT

这些文件简单、透明。人能看，AI 能改，后面也能再转换成其他格式。

后面可能会继续做

我现在比较想继续做几件事。

第一是场景变化抽帧。现在主要按时间间隔抽帧，够用但不够聪明。长视频里如果能根据画面变化抽帧，代表性会好很多。

第二是示例 Demo。现在仓库里有示例数据和输出文件，但如果有几张截图，展示从素材到 timeline 的过程，读起来会更直观。

第三是导出到剪辑软件。Resolve CSV、EDL、FCPXML、剪映草稿都可以考虑，但我会放到后面。

还有一个方向是模板。旅行、产品、活动、课程、口播，它们的时间线结构不一样。以后可以把这些结构做成配置。

最后

做完这个 Skill 后，我更确定一件事：AI 做视频剪辑，不应该只停在“给建议”。

对剪辑来说，真正有用的是把一堆模糊素材变成可以修改的文件。第一版可以粗，但要有结构。

这个项目现在就是在做这件事：

看素材
整理表格
搭第一版 timeline
写旁白占位
列发布检查项

如果你也经常面对一堆素材，不知道从哪里开始剪，可以试一下：