Video-Shotcraft 深度技术分析报告

Repo: Vincentwei1021/video-shotcraft Stars: 7,064 语言: TypeScript License: Apache-2.0

本报告面向两类读者：AI/视频创作爱好者（第 1–3 节）与开发者（第 4–7 节），可按需跳跃阅读。

一、项目是什么

video-shotcraft 是目前 GitHub 上 stars 最高的 Claude Code / Codex AI 视频制作技能——它将编码 Agent 变成一个影视级产品宣传片制作工作室。用户只需描述产品并说"用 video-shotcraft 做个宣传片"，Agent 便会自主完成：

从 152 张镜头配方卡（shot recipe cards）中选片
驱动 Remotion（React 式视频引擎）渲染
采集真实页面截图并做 2.5D 运镜
完成声音设计（BGM + SFX）
导出成品视频（MP4）及剪映工程文件

核心指标：152 张镜头卡 · 221 个 TSX demo 实现 · 209 个动效样片 · 149 个 SFX · 5 首 BGM · 10 个镜头分类 · 1 套完整生产模板（36.2 秒，1920×1080，30fps）

二、技术定位与竞品差异

2.1 定位

这不是一个"AI 视频生成器"（不调用 Stable Diffusion / Sora 类模型），而是一个结构化镜头语言系统 + Remotion 代码生成器。它的本质是：

镜头词汇化：将 152 种动效运动语法封装为"镜头卡"，每张卡含用途、能量、时长、参数表、demo 源码、已知坑
Agent 可执行：SKILL.md 是给 Claude Code / Codex 的指令文件，定义何时读哪张卡、如何组合
确定性渲染：所有动画必须可复现，禁用 Math.random() / Date.now()，用 mulberry32 哈希种子保证帧级一致性

2.2 竞品对比

维度	video-shotcraft	Runway/Pika	传统 AE 模板
交互方式	对话 + Agent 自动	纯文本/图片	手动
输入	产品描述 / URL	图片/文字	工程文件
运动语法	152 种配方卡	扩散模型采样	手动关键帧
可复现性	确定性（种子固定）	概率性	确定
真实感	真实页面截图 + 2.5D 运镜	AI 生成	素材依赖
声音设计	内置 SFX/BGM 库	无/弱	手动

差异化优势：真实产品截图 + 结构化镜头语言 + 全自动 Agent 执行链路，三者结合在开源社区几乎没有直接竞品。

三、创作流程与能力边界

3.1 三种创作模式

用户可选择三种制作路径：

① 模板路线：直接使用 Ink Press 完整模板（36.2s），换产品截图 + 文案即可，最快路径

② 自主自由创作：Agent 从产品理解 → 视觉方向 → 镜头映射 → 分镜 → 渲染全程自主推进，无需用户逐阶段确认

③ 共同创作：Agent 提出方案，由用户在"产品简报 → 视觉方向 → 镜头映射 → 分镜"四个节点确认后继续

3.2 生产管线（自主自由创作）

阶段0: 产品理解（只读检查：定位/功能/视觉tokens/数据风险）
阶段1: 视觉方向 → HTML styleframe（截图验证）
阶段2: 功能→镜头映射（扫描152卡，选卡+demo）
阶段3: 分镜表 + 帧级时间轴
阶段4: 最终素材采集（PageCam三件套：全页2x截图+元素cutout+layout.json）
阶段5: 逐镜头实现（读卡→读demo→copy组件→npx remotion still自检）
阶段6: 声音设计（SFX钉帧表+BGM混音）
阶段7: 独立终检（subagent审查+双版本渲染：带BGM/无BGM）

3.3 能力边界

✅ 强项：Web/桌面产品宣传片、2.5D 页面运镜、BGM 卡点剪辑、声音设计、真实截图质感

⚠️ 局限：非复刻场景手搓 UI 质量有限；人物实拍场景不适合；渲染需本地 Node.js 环境（无 SaaS）

四、架构解析

4.1 核心目录结构

video-shotcraft/
├── SKILL.md                    # Agent 入口指令文件
├── package.json                # 仓库级 vitest（仅测试 helpers）
├── references/
│   ├── pipeline.md             # 8阶段制作流水线
│   ├── guided-free-creation.md  # 共同创作指南
│   ├── aesthetic-rules.md       # 187行审美判例（17条规则）
│   ├── music-beat-sync.md      # BGM节奏分析+卡点方法论
│   ├── sound-design.md         # 声音设计词汇表+对齐技巧
│   ├── final-review.md         # 终检清单
│   ├── jianying-export.md      # 剪映工程导出指南
│   └── shots/                  # 152张镜头配方卡（10个分类）
│       ├── ui-entrance/        # UI入场（52卡）
│       ├── typography/          # 字体动画（18卡）
│       ├── transition/         # 转场（20卡）
│       ├── interaction/        # 交互演示（15卡）
│       ├── effects/            # 特效（12卡）
│       ├── opening/            # 开场（10卡）
│       ├── outro/              # 收尾（8卡）
│       ├── rhythm/             # 节奏镜头（8卡）
│       ├── camera/             # 相机运动（9卡）
│       └── data/               # 数据可视化（8卡）
├── demos/                     # 221个 TSX demo 实现（按卡分组）
├── assets/
│   ├── lib/                   # 8个核心可复用 Remotion 组件
│   │   ├── PageCam.tsx        # 2.5D 页面相机（核心组件）
│   │   ├── ClipCard.tsx       # 外部视频素材包装
│   │   ├── FlashCut.tsx       # 闪切效果
│   │   ├── Caption.tsx        # 字幕
│   │   ├── DigitRoll.tsx      # 数字滚动
│   │   ├── VerticalTicker.tsx # 无限滚动墙
│   │   ├── FlatPanel.tsx      # 3D 面板
│   │   └── helpers/           # 纯函数（camera/motion/rand/shake）
│   ├── scripts/
│   │   └── capture-template.mjs # PageCam 三件套采集脚本
│   └── audio/
│       ├── bgm/               # 5 首 BGM
│       └── sfx/               # 149 SFX（16类：transition/impact/riser/camera/ui/text/paper/film/light/data/scifi/mech/glass/fluid/crowd/counter）
├── template/                  # 完整可渲染生产模板（Ink Press）
│   ├── package.json           # Remotion 4.0.484 + React 19.2.7 + TS 6.0.3
│   ├── remotion.config.ts
│   └── src/
│       └── index.ts           # Root Composition
├── gallery/                   # 静态 HTML 画廊（209样片）
│   ├── index.html             # 主页
│   ├── library.html           # 镜头卡库（搜索+过滤）
│   └── showcase.html          # 作品展示
└── jianying-export/          # 剪映工程导出（Python）
    ├── mac_draft.py
    ├── windows_draft.py
    └── smoke_test.py

4.2 关键文件详解

SKILL.md — Agent 的"大脑"

SKILL.md 定义了 Agent 如何理解用户意图并路由到不同制作路径。核心逻辑：

模式判断（最早执行）：用户是否已选模板/自主创作/共同创作？是否点名了具体镜头卡？
例外处理：用户点名 Ink Press → 直接进模板路线；点名具体卡名 → 解析 gallery/api/library.json 校验并定位 demo
交付收尾（成片后自动执行）：推荐 @ 作者、邀请提交作品展示页、可导出剪映工程

与 Remotion 官方 skill 的区别：Remotion 官方 skill 偏向"通用 Remotion 提示"，video-shotcraft 是完整的产品宣传片专项技能，含 152 张已调校的镜头卡、完整生产管线、和剪映导出。

PageCam.tsx — 2.5D 页面相机的工程实现

这是整个项目的核心技术组件。它实现"从产品真实截图出发做 3D 运镜"：

// 相机关键帧类型
type CamKey = {
  frame: number;
  cx: number;        // 页面空间中心 x
  cy: number;        // 页面空间中心 y
  zoom: number;      // 缩放（1 = 1 CSS px → 1 输出 px）
  rotX?: number;     // X轴旋转（度数）
  rotY?: number;     // Y轴旋转
  rotZ?: number;     // Z轴平面旋转
  persp?: number;    // 透视强度（越小越强）
};

核心工作机制：

接收全页纹理（2x 分辨率截图）+ layout.json 坐标
在关键帧之间做 lerp 插值
children 按页面 CSS px 定位（与 layout.json 共坐标系）
3D 文字发糊的解法（见 aesthetic-rules Q2）：CSS zoom 替代 transform scale，让 Chromium 按放大后尺寸栅格化

镜头卡结构 — 配方而非模板

每张镜头卡是参数化运动语法，不是固定动画。典型结构：

---
name: row-embed
一句话: 内容行像卡片一样从空中降下、rotateX收平、嵌入瞬间底边亮一道强调色的缝
适用: 结构化数据长进页面的详情页/列表镜头
时长: 约2s（12–68f）
能量: 中
---

## 意图
[设计意图说明]

## 动效核心
- 飞行姿态: perspective(900px) translateY(-120*air) rotateX(16*air)
- 强调色缝: 底边2px，Easing.out cubic

## 参数表
| 参数 | 典型值 | 调节手感 |
[参数表格]

## 声音
[音效选择建议]

## 已知坑
[踩过的坑及规避方法]

## 参考实现
demos/ui-entrance/row-embed/RowEmbed.tsx

这种"配方卡"设计让同一运动语法可以适配不同产品，只需改截图和参数即可。

Pipeline.md — 8 阶段生产流水线

最值得学习的工程实践：

方向性问题不进逐镜头阶段：styleframe（HTML 静态页面截图验证）锁定视觉方向后才开始写代码
素材采集在分镜放行后：避免"采了不用"的浪费
静帧自检贯穿全程：每镜头完成即 npx remotion still 截图，肉眼检查后才继续
独立 subagent 终检：制作 Agent 和审查 Agent 分离，避免确认偏差

Aesthetic-rules.md — 187 条判例式审美规则

核心规则体系（分类编号）：

R(节奏): hold 满 1s、宁慢勿快、卡点约束 ≤3 处
Q(质感·运镜): 真实截图优先、3D 下文字用 CSS zoom、高光不群发
S(声音): 电影系词汇而非游戏音、禁用 sfx/ui/ 合成反馈音
C(文案): 画面锁定后按帧重写文案
P(流程): 不把首检交给用户、参考素材逐帧拆解

五、代码质量与工程实践

5.1 测试体系

npm test            # vitest（仅 assets/lib/helpers 纯函数：mulberry32/velocityAt/lagged/dampedSettle/handheld）
smoke-render-demos.py  # demo TSX 首帧渲染冒烟测试
pr-checks.yml         # CI: tsc 严格编译 + vitest + 冒烟渲染

测试覆盖率聚焦于确定性纯函数（helpers 层），UI 组件依赖 Remotion 自身测试 + 手动冒烟验证。这是合理的工程取舍——Remotion 组件的时间轴动画难以单元测试。

5.2 TypeScript 使用

严格模式：tsc --noEmit 是 CI 强制检查项
React 19 + TypeScript 6：前沿依赖栈
典型问题捕获：MoClaw 博文的真实案例显示，TypeScript 在渲染前就捕获了两处重复 transform 声明（行 710 和 865），避免了运行时错误

5.3 渲染工程

关键发现：

并发陷阱：4x 并发渲染会在 MP4 中产生切片伪影，解决方案：--concurrency=1（代价：渲染时间 2.5×）
headless Linux：chrome-headless-shell 替代 chrome，--browser-executable 指向无头浏览器
CDN 阻断：remotion.media 不可达时需 --browser-executable 绕过

六、License 与合规

资产	License	备注
项目整体	Apache-2.0	可商用，需保留 License 声明
Remotion 渲染引擎	Remotion License	个人/小团队免费；公司可能需付费（购买前需核实）
音频（BGM + SFX）	见 `assets/audio/ATTRIBUTION.md`	Mixkit License（免费商用免署名）、incompetech（CC-BY 需署名）
Kenney 音包	CC0	本项目已弃用（判例："太像游戏"）

开发者合规建议：

商用前确认 Remotion License 当前条款
BGM 使用 Mixkit 曲目或保留 ATTRIBUTION.md 记录
sfx/ui/ 目录需逐个试听，剔除合成反馈音

七、开发者上手指南

7.1 快速开始

# 方式1：Agent 安装
npx skills add Vincentwei1021/video-shotcraft

# 方式2：手动安装
git clone https://github.com/Vincentwei1021/video-shotcraft
ln -s /path/video-shotcraft ~/.claude/skills/video-shotcraft

# 渲染生产模板
cd video-shotcraft/template
npm install
npx remotion render src/index.ts AiflPromo out/promo.mp4

# 本地画廊
cd video-shotcraft/gallery
bash fetch-media.sh   # 拉取样片 mp4
python3 -m http.server 4178

7.2 开发自己的镜头

浏览 https://vincentwei1021.github.io/video-shotcraft/library.html 选镜头
复制卡名（如 row-embed）
读 references/shots/ui-entrance/row-embed.md 全文
按"参考实现"定位：demos/ui-entrance/row-embed/RowEmbed.tsx
copy demo 到你的 Remotion 项目并适配

7.3 添加新镜头卡

写 references/shots/<category>/new-shot.md（frontmatter + 意图 + 参数表 + 已知坑）
写 demos/<category>/new-shot/Demo.tsx（Remotion TSX 实现）
添加 gallery/api/library.json 条目（含卡名、分类、style-key）
跑 smoke-render-demos.py 验证 demo 首帧
更新 SKILL.md 的"何时读哪个文件"表

7.4 CI/CD

GitHub Actions pr-checks.yml 在每个 PR 自动执行：

tsc --noEmit（TypeScript 严格编译）
npm test（vitest）
smoke-render-demos.py（demo 首帧渲染）

总结

video-shotcraft 是目前最系统化的 AI Agent 视频制作技能，其核心价值不在于某个单点创新，而在于：

镜头词汇化：152 种运动语法封装为可组合的配方卡
全链路自动化：从产品描述到成片的 8 阶段生产管线
工程化审美：187 条判例式规则 + 独立终检机制
真实截图 + 2.5D 运镜：真实产品质感是它与 AI 生成视频的本质区别

适用场景：Web/桌面 SaaS 产品宣传片、App 演示视频、Launch 视频 不适用：人物实拍、自然风景、纯创意动画

技术栈：TypeScript · React 19 · Remotion 4 · Node.js · Python（剪映导出）

分析时间：2026-09-02 | 数据来源：GitHub + 本地仓库分析 + Web 搜索