video-reverse-engineering

视频逆向拆解与复刻 —— 给 AI Agent 用的 Skill。丢一个视频链接进去，得到分镜脚本、可直接用的 AI 生图/生视频提示词、以及一份完整复刻指南。

Reverse-engineer how a video was actually made. Give an agent a video URL; get back a shot list, ready-to-paste AI image/video prompts, and a full replication guide — grounded in real extracted frames, not in the model's imagination.

---

为什么需要它

让 Agent "分析一下这个视频",十次有九次拿回来的是内容摘要——它讲了什么、观点是什么。但如果你的目的是照着拍一条,内容摘要一点用都没有。

更糟的是,大多数 Agent 根本没看过画面,就开始输出"镜头 1:一个咖啡店的空镜,氛围温馨"这种谁都写得出来的废话。没有时间码、没有景别、没有运镜、没有色调,拿去生图生不出东西,拿去实拍也不知道怎么拍。

	Before(直接问 Agent)	After(装上这个 Skill)
分析依据	凭标题和简介脑补	场景检测算法抽出的真实关键帧,逐张看过
时间码	没有,或者是估的	从 timestamps.txt 取,精确到秒
镜头描述	"一个温馨的空镜"	景别/角度/运镜/构图/光线/调色/转场,术语表统一用词
能不能直接用	不能	制图 Prompt 可直接粘进 Midjourney / 即梦 / 可灵
复刻路径	没有	AI 生成 + 实拍两条路径都给,含后期与平台适配
编造风险	高	明确禁止:没看到画面就不许写镜头内容

---

它怎么工作

视频 URL
   ↓  scripts/extract_shots.sh
下载 → 场景检测抽帧 → 抽字幕 → 抽音频 → 读元数据
   ↓
frames/shot_0001.jpg ... + timestamps.txt(精确时间码)
   ↓  宿主逐张读图,对照 references/shot_glossary.md 的术语
逐镜头视觉分析(景别/角度/运镜/构图/光线/调色/主体/文字/转场)
   ↓  + 节奏结构与音频分析
   ↓  对照 references/output_templates.md
┌──────────────┬──────────────────┬──────────────┐
│ A. 分镜脚本   │ B. 制图提示词      │ C. 复刻指南   │
│ 逐镜头表格    │ 中文说明+英文Prompt │ AI路径+实拍路径│
└──────────────┴──────────────────┴──────────────┘

关键设计:抽帧和逐帧分析这两步不能跳过。即使用户只要分镜脚本,也必须先真的把帧抽出来看过——这是所有产出的地基。素材抓不到时有三级降级方案(要用户发文件 → 找现成拆解文章辅助 → 只用标题简介并如实告知分析会打折),但底线是绝不在没看到画面的情况下编造镜头。

---

安装

三个宿主分别装,选你在用的那个:

Codex

git clone https://github.com/whaojie797-design/video-reverse-engineering.git ~/.codex/skills/video-reverse-engineering

Claude Code

git clone https://github.com/whaojie797-design/video-reverse-engineering.git ~/.claude/skills/video-reverse-engineering

Cursor

git clone https://github.com/whaojie797-design/video-reverse-engineering.git ~/.cursor/skills/video-reverse-engineering

装完不需要额外注册,宿主会自己扫 skills 目录读 SKILL.md 的 frontmatter。

运行依赖

这个 Skill 会真的下载视频、真的抽帧,所以必须先装两个外部工具:

工具	macOS	Linux	Windows
ffmpeg / ffprobe	brew install ffmpeg	apt install ffmpeg	winget install Gyan.FFmpeg
yt-dlp	pip install yt-dlp --break-system-packages	同左	pip install yt-dlp

另外宿主需要具备读图能力(多模态)。如果宿主看不了图片,这个 Skill 给不出可信的镜头分析。

脚本启动时会自检依赖,缺哪个直接告诉你怎么装:

❌ 缺少 ffmpeg。安装方式：macOS `brew install ffmpeg` / Linux `apt install ffmpeg` / Windows `winget install Gyan.FFmpeg`

---

用法

装好之后,直接把链接丢给 Agent 就行,不用喊 Skill 名字:

https://www.bilibili.com/video/BVxxxxxxxx  这个是怎么拍的?

Skill 的 description 写明了触发条件——只发一个链接、什么都不说,只要意图是理解或复刻制作方法(而不是要内容摘要),也会触发。

也可以手动跑抽帧脚本:

bash scripts/extract_shots.sh -u "<视频URL或本地文件>" -o ./analysis

# 参数
#  -t  场景检测阈值,默认 0.28。漏镜头就调低到 0.15~0.2
#  -i  按固定间隔补抽帧(秒)。慢速推拉摇移不触发场景切换时用
#  -s  下载最大高度,默认 1080

产出:

analysis/
├── frames/shot_0001.jpg ...   关键帧(含开场首帧)
├── frames/timestamps.txt      每帧精确时间码,按行号对应文件序号
├── frames_interval/           等间隔补帧(仅当用了 -i)
├── audio/audio.mp3            完整音轨,判断配乐/卡点
├── subs/                      平台字幕(比听写靠谱)
└── meta/                      分辨率/帧率/时长/场景检测日志

---

仓库结构

.
├── SKILL.md                          Skill 主文件(六步工作流)
├── scripts/extract_shots.sh          素材抓取:下载/抽帧/抽字幕/抽音频
├── references/shot_glossary.md       镜头语言术语速查(99 行,7 大类中英对照)
├── references/output_templates.md    三份交付物模板 + 完整跑通范例(157 行)
└── tools/validate_skill.py           打包规范校验(CI 用)

shot_glossary.md 覆盖景别 / 拍摄角度 / 运镜 / 转场 / 光线 / 构图 / 调色风格七大类,强制统一用词——既保证描述专业,也让术语能直接喂给生图工具。

output_templates.md 不只给模板,还附了一个从头到尾跑通的完整范例,产出时照着同等详细程度写,防止越写越水。

---

质量校验

tools/validate_skill.py 会检查这个包是否符合 Agent Skill 开放规范,CI 每次 push 都跑:

==============================================================
skill validation: video-reverse-engineering
==============================================================
  PASS  frontmatter keys are all recognised: name, description
  PASS  name = video-reverse-engineering (25 chars)
  PASS  description = 367 chars (limit 1024)
  PASS  referenced file exists: references/output_templates.md
  PASS  referenced file exists: references/shot_glossary.md
  PASS  referenced file exists: scripts/extract_shots.sh
  PASS  no host-specific coupling terms in skill body or scripts
  PASS  bash -n passes: scripts/extract_shots.sh
  PASS  scripts/extract_shots.sh handles ffmpeg fps flag compatibly

RESULT: PASS (9 checks)

校验内容:frontmatter 只用标准字段(非标准字段会被严格宿主拒载)、name 命名规范且 ≤64 字符、description ≤1024 字符、SKILL.md 引用的每个文件都真实存在、不写死任何特定宿主的产品名或内部工具名、shell 语法通过 bash -n、ffmpeg 参数无过期用法。

CI 还会用 ffmpeg 合成一段带三次硬切的测试视频,真跑一遍 extract_shots.sh,断言抽出 ≥3 帧、时间码和音轨都非空。

本地跑:

python tools/validate_skill.py

---

局限性

说清楚比藏着好:

• 必须有 ffmpeg + yt-dlp,没有就跑不起来。这不是纯文本 Skill。
• 平台有登录墙/地区限制/反爬时下载会失败。降级方案能兜底,但分析质量确实会下降,Skill 会如实告诉你,不会假装看过。
• 场景检测不是万能的。慢速推拉摇移不触发切换判定,需要用 -i 补抽帧交叉参考;转场花哨的片子也可能误切。阈值 -t 要根据片子调。
• 运镜是推断出来的。关键帧是静态图,运镜靠前后帧位置变化 + 时长 + 音频节奏推断,不是逐帧光流分析,复杂运镜可能判错。
• 依赖宿主的读图能力。宿主不支持多模态,这个 Skill 没有意义。
• 长视频成本高。超过 3 分钟建议只拆关键片段(广告/短视频的黄金开场几秒分析价值远高于中后段)。

版权提示

拆解分析本身不受影响,但如果原视频里有真人清晰面部、可识别品牌商标、或有版权的原创音乐,直接照搬做二次传播会有肖像权/商标/音乐版权风险。Skill 会在复刻指南里提醒,并建议 AI 路径用虚构人物、实拍路径找自己的演员场地、音乐换成曲风相似的可商用曲库。

License

MIT — 见 LICENSE。