whaojie797-design/video-reverse-engineering

video-reverse-engineering

validate
License: MIT
version

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

逆向拆解一个视频究竟是如何制作的。给 agent 一个视频 URL；返回一份镜头清单、可直接粘贴使用的 AI 图像/视频提示词，以及一份完整的复刻指南——基于真实提取的帧，而非模型的想象。

为什么需要它

让 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 "" -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。