---
name: "motion-video-workflow"
description: "用户提供配音（背景音乐可选，没有就自动合成），要做口播动效视频（案例分享、AI资讯、AI知识讲解、教程）时使用：听写、抓素材、分镜、代码动效，按需出16:9或9:16成片，并出3:4和4:3封面。"
---

# 口播动效视频工作流（通用版）

用户提供**配音**；**背景音乐**可选，没有就自动合成。最终交付：
- 成片：16:9、9:16，或两种都出（开场时确认）
- 3:4 和 4:3 封面各一张（必出）

## 开场确认（拿到配音后先做，后面不再问）
用一次 AskUserQuestion 问完下面两项。用户在请求里已经说明的项直接跳过，不重复问；两项都说明了就不问。
1. **输出比例**：9:16 竖版 / 16:9 横版 / 两种都要。推荐项按用户的发布平台来定：抖音、小红书、视频号推荐 9:16；B 站、YouTube 推荐 16:9；不确定就推荐 9:16。
2. **背景音乐**（只在用户没给音乐时问）：
   - 「我自己找音乐（推荐）」：说明效果最好，节奏清楚、带鼓点的纯音乐最合适，拿到后再开工。
   - 「自动合成配乐」：说明是代码合成的极简电子乐，没有版权问题，但效果不如真人挑的音乐，之后可以随时替换后重新混音，画面不用重做。

后面各步只做选中的比例：只出 9:16 时跳过所有 16:9 的渲染和检查，动效只为竖版 1080×1080 内容窗设计；只出 16:9 时跳过第 7 步。

要求：
- 不加字幕，只做动效。
- 画面全部由代码生成：HTML、CSS 3D 和 Canvas 画出每一帧，再逐帧渲染。
- 每支片子按自己的内容重新设计，**不复用上一支的画面、配色和版式**。
- 复用的是这套流程、引擎和组件。

## 给用户看的输出规范（每条消息都遵守）
**模块化，不长篇大论。** 每条消息只用下面三种模块，按需组合：
1. **结论**：一到两句话，说做完了什么、结果是什么。
2. **要点**：最多 5 条短清单，或者一张小表格。内容多就用表格，不写成段落。
3. **需要你定**：有问题才出现，见下面的提问规则。

约束：
- 正文不超过 10 行（表格和图片不算）。超过就砍掉，或者合并成表格。
- 不复述用户已经知道的内容，不讲内部实现（代码、命令、组件名、文件结构），除非用户问。
- 能用图就不用字：效果图、关键帧、封面直接发图（SendUserFile），文字只写「看哪里」。
- 进度更新只写一行，比如「音频完成：配音 55.7 秒，配乐已合成」。
- 每个阶段结束都用同一个格式：结论 → 要点 → 需要你定（没有就写「下一步：……」）。

**提问一律是选择题。** 用 AskUserQuestion：
- 每题 2–4 个选项，**推荐项放第一个，标「（推荐）」**，每个选项用一句话说明选了会怎样。
- 能合并的问题一次问完，一次最多 4 题。不问能从口播或上下文推出来的事。
- 需要用户先看图再选时，先发图，再出选择题。
- 用户不在，或者说了「直接做」：全部按推荐走，交付时在「要点」里列出替他选了什么。
- **没有 AskUserQuestion 或 SendUserFile 的环境**（比如 Codex）：选择题改成编号选项列出，推荐项放第一个，让用户回编号；发图改成给出图片的完整路径。

## 0. 准备模板（motion-kit）
本 skill 推荐在 Claude Code 里运行（也兼容 Codex 等支持 SKILL.md 的 agent），所有工作都在用户电脑本地完成。模板就在本 skill 目录的 `motion-kit/` 里。
1. 问清或自定一个项目目录（默认 `~/Movies/<片名>/源码`），把 skill 目录下的 `motion-kit/` 整个复制过去，后续都在这个项目目录里操作。不要直接改 skill 目录里的模板。
2. 在项目目录运行 `bash tools/setup.sh`。它会安装 Python 依赖、Playwright 的 Chromium、下载听写模型，并检查 ffmpeg 和中文字体。缺什么按提示装（需要用户确认的安装命令先问用户）。
3. 先读 `README.md`，了解目录结构和组件清单。
4. `examples/muse/` 是第一支片（产品案例）的完整源码，只作参考，不能照套。
5. 用任务列表跟踪进度：音频、类型和风格、素材、分镜、确认单、搭建、预览、渲染、竖版、封面、交付。

## 1. 音频
0. **选了自动合成配乐时**：先单独听写配音（`ffmpeg -i vo -ac 1 -ar 16000 vo16k.wav` 后跑第 3 步），按口播的段落定冲击点，再运行 `python3 tools/make_bgm.py --dur 时长+0.2 --impacts 段落切换时刻 [--brk 痛点段起,止] [--end 收尾时刻]`。冲击点放在钩子结束、转入主体、高潮这些位置，吸附到拍点（120 BPM 拍长 0.5 秒）。痛点或「以前」段落适合用 `--brk`（去鼓加低通），结束时自动回归。脚本直接生成 `bgm.wav` 和精确的 `beats.js`，跳过第 4 步。交付时提醒用户：换成自己挑的音乐效果更好，替换后重跑混音和合成即可。
1. 运行 `bash tools/mix.sh vo bgm 时长`。它会：
   - 让音乐在有人声时自动压低，整体响度统一到 -14 LUFS，结尾淡出。
   - 导出混音 `mix.wav`，以及听写用的纯人声 `vo16k.wav`。
2. 时长定为配音时长加 0.5–1 秒，留给结尾定版。
3. 运行 `python3 tools/asr.py vo16k.wav`，得到 `asr.json`，里面有每个字的时间。只能用纯人声听写，混音后的音频听写不准。
4. 运行 `python3 tools/beats.py bgm`，生成 `beats.js`（拍点 BEATS、低频重拍 KICKS）。
5. 切点和关键词出现的时刻，都用 `snap(t)` 吸附到最近的拍点上。
6. 听写结果有错字时，按上下文校正，再整理成口播全文。

## 2. 判断类型，定风格（开工前只问一次）
根据口播内容判断片子属于下面哪一类，然后给用户 2–3 个视觉方向，用 AskUserQuestion 让用户选。每个方向写清：
- 名字，比如「深夜霓虹」「清爽白板」「杂志拼贴」
- 主色和辅色
- 背景类型
- 转场组合
- 竖版装饰带用哪个 preset

如果用户不在，就选最贴合内容的方向，并在交付时说明选了哪个。

**需求对齐之后，必须问一次要不要出效果图。** 类型、视觉方向、输出比例这些需求和用户对齐之后，用 AskUserQuestion 问用户：「要不要先做几张效果图给你确认？」推荐选「要」。
- 用户选「要」：先出效果图，包括推荐方案的 9:16 静帧，以及 2 个候选方案的缩略图。效果图要和成片一致，含标题带、装饰带、配色，中间放一个关键画面。用户选定后再开工，后面确认单①里的效果图项就不用重复做。
- 用户选「不要」：直接按推荐方向做，交付时说明用了哪个方向。

| 类型 | 叙事结构 | 主要组件（packs） | 素材 |
|---|---|---|---|
| 案例分享 | 先抛结果作钩子 → 事件经过 → 转折 → 结果 → 一句感悟 | product-ui：Phone、Notice；explainer：Pill、BigStat；web：WebShot、WebCrop | 产品 logo、IP 形象、真实界面（官网、发布视频截帧），界面按截图 1:1 重建 |
| AI 资讯 | 快讯开场 → 每条新闻占一屏 → 关键数字 → 影响或观点 → 收尾 | news：NewsCard、Ranking、Ticker、PostCard；explainer：BigStat | 公司 logo、官方公告截图、产品图。每条信息都用网页搜索核实来源和日期 |
| AI 知识讲解 | 抛出问题 → 用比喻画面类比 → 拆解原理 → 对比 → 举例 → 一句话总结 | explainer：KineticText、FlowChain、Layers、Compare、Timeline、BarChart、KeyWord | 主要靠代码画的图标和图示，少量真实 logo |
| 教程 | 先展示最终效果 → 每步一屏 → 常见坑 → 回顾清单 | tutorial：Win、Cursor、Spotlight、Callout、StepBadge、CodeBlock、Terminal；web：WebShot、WebMark、WebCrop | 工具的真实截图，用户提供或用浏览器截取 |

所有类型通用：vertical（只出 9:16 时的画布 VShot / vcam，以及 Stamp、Seal、Chars、StatBox、Toast、Keycap、Burst 这些强调类组件）；outro（片尾 FavButton、FollowCard、CommentPin，作者信息写在 `CONFIG.creator`）；web 里的 ClipPlayer（在卡片里播放视频素材）。

同一类型的不同片子，也要换比喻、换主视觉、换配色。`config.js` 里的 THEME 每次都要重新定。

## 3. 抓素材
**来源优先级**：
1. 官网（矢量 logo、IP 形象、3D 图标）
2. 官方发布视频截帧
3. Wikipedia、Wikimedia（注明作者和许可）
4. 实在没有，就用代码按真实样式重建

不要编造新闻、数据或引用。示意性的数据必须在画面里标「示意」。

**真实网页**：用 `python3 tools/capture.py URL 名称 [--sel 选择器 元素名]` 抓 2x 截图，包括首屏、整页长图、元素位置表 `名称_els.json`，还有指定元素的单独截图。Cookie 和登录这类浮层会自动关掉。按钮和标题的坐标查 `_els.json`，不要靠肉眼估。

**下载方法**：本地网络可用时直接用 `curl -L -o a/文件名 URL` 下载；视频截帧用 `ffmpeg -ss 时间 -i 视频 -frames:v 1 a/xx.jpg`。需要登录或动态加载的页面，用 Playwright 打开后截图或取资源地址。下载前告诉用户要下哪些文件、来自哪里。

**抠图**：白底素材按亮度阈值加羽化处理。复杂背景用 rembg（可以 pip 安装）。

**整理**：所有素材放进 `a/`，同时在 `a/来源.md` 记下每个素材的来源和许可。

## 4. 分镜（写进项目目录的 分镜.md）
分镜表按口播逐句写，每行包括：时间、口播、画面与动效、用到的组件。**组件一栏要标明「现成」还是「新写」**：组件包能表达的用现成的；表达不了或效果不够，才新写，并在这一栏写一句为什么要新写。分镜表的写法参考 `examples/muse/分镜与制作记录.md`。

**硬规则**（来自用户反馈）：
- **一个画面只讲一个信息。** 一屏信息太多时，用镜头运动依次展示（camKeys 逐个推近），不要把所有东西同时摆出来。
- **关键信息出现后至少停留 0.9–1.2 秒**，不能刚推近就切走。转场只放在信息之间。
- **手机竖屏观看下要看得清**：
  - 16:9 成片里，正文不小于 40px，关键词 100–200px。
  - 聊天和界面要推近到 2.4–2.8 倍再看。
  - 计时器、数字、标签都要往大里做。
- **关键词单独放大**：用 KeyWord、KineticText 的 `[[ ]]`，或者用镜头推近。
- **重复的信息直接删掉。**
- **品牌字标要对齐基线**，比如 `from` 和 logo 的对齐，要量好位置再摆。
- 不加字幕。口播里的关键词可以变成画面元素，但不能整句上屏。
- 转场 0.35–0.7 秒，切点吸附到拍点上；转场区间写进 MB，渲染时加运动模糊。
- 静止镜头加一点 `drift()`，重拍上加 `kickScale()`，画面不要完全不动。

## 4.5 确认单①（分镜写完、动效开工之前，必须等用户确认）
每一项都**先给一个推荐并说明理由，再给候选**。用户回「按推荐来」或逐项指定后才开始做动效。
- **顶部标题**（竖版装饰带）：1 个推荐加 2–4 个候选。
- **底部文案**：放哪个 logo、写哪句介绍，1 个推荐加 1–2 个替代；没有明确主体的片子写栏目名或留空。
- **装饰带和配色**（第 2 步已出过效果图并确认的，这项跳过）：用模板先出一张推荐方案的 9:16 静帧效果图（标题、装饰带、配色都是成片的样子，中间放一个关键画面），写明主色、辅色、背景色和理由；另附 2 个候选方案的缩略图。配色依据：有品牌跟品牌色；没品牌按题材定（资讯偏冷静的蓝黑，知识讲解偏清爽浅色，教程偏干净白底）。
- 附上分镜表，让用户知道每段放什么画面。
- **最后问一题：要不要先看全篇关键帧总览？**（选择题：「要，先看总览再做（推荐）」/「不用，直接做完」）。选择决定第 5 步怎么走，整个流程只问这一次。

第 2 步的类型和视觉方向可以并进这张确认单一起问，不必分两次。

## 5. 搭建与预览
1. 在 `config.js` 里设好主题、时长、预载素材、竖版装饰带文案和封面文案。
2. 在 `scenes.js`（篇幅长就拆成 s1.js、s2.js…，并在 html 里引入）里按分镜写 Scene。只出 9:16 时，每个镜头用 `VShot(名, t0, t1)` 直接在 1080×1080 内容窗的本地坐标里搭，镜头用 `vcam`，切入用 `vEnter`，不用再考虑 16:9 构图。
   - **时间点不要手抄数字**：页面里用 `say('4万')`（第一个字的时间）、`say('收藏', 2)`（第 2 次出现）、`sayEnd('抄作业')`（最后一个字的时间）。命令行可以用 `python3 tools/when.py 词…` 先查。听写有错字时，用没错的相邻字词来查。
   - 片尾的收藏、关注、评论区置顶，优先用 outro 包。
3. 组件统一用 `工厂(parent, …, {t0, t1}) → {upd(t)}` 的写法。镜头用 `camKeys` 加 `applyCam`。要对准某个元素，用 `rectOf('#id')` 或 `target` 参数取它的位置，不要猜坐标。
4. 每个画面都要考虑竖版：竖版只能看到 x 从 420 到 1500 的范围（`SAFE`）。放不下时，在 `VMODE` 分支里改坐标或改竖排；FlowChain 在竖版下会自动竖排；对比类内容用左右摇镜。
5. 预览：`python3 tools/preview.py 时间点列表`（生成的图用 Read 工具查看），竖版加 `--v`。拼成缩略图总览后逐一检查以下几点：
   - 文字是否被裁
   - 元素是否重叠
   - 字够不够大
   - 停留时间够不够
   - 有没有页面报错
**按确认单①最后一题的选择走：**
- **选了「先看总览」**：
  1. 先不做完整动画，每个镜头只搭出它的**关键画面**，也就是信息全部到位、版式和配色定稿的那一帧。入场和镜头运动可以先简单处理。
  2. 每个镜头取一帧（`preview.py` 抽帧），拼成**全篇关键帧总览图**，每格下面标时间和对应的口播。自查过第 5 条的检查项后发给用户。
  3. 选择题：「按这个做完（推荐）/ 改其中几个镜头 / 整体风格要调整」。用户确认后，再补全动画、转场、镜头运动，然后进入第 6 步渲染。渲染前不再发关键帧。
- **选了「直接做完」**：完整搭建 → 自查 → 直接渲染。过程中和交付时都不发关键帧总览。

## 6. 渲染与交付规格
1. 后台分段并行渲染（60fps，运动模糊最多 4 个子帧），只渲染开场确认时选中的比例，每个版本单独跑：
   - 16:9：`nohup bash tools/segs.sh 时长 > segs.log 2>&1 &`
   - 9:16：同一条命令加 `--v`
   - 机器核心多时可把并行数（第三个参数）调到 3–4。
2. 判断渲染是否完成，检查 `segs*/ALLDONE` 文件。**不要用 `pgrep -f` 去匹配命令行**，它会匹配到自己。
3. 合成成片：`bash tools/finish.sh mix.wav 输出.mp4 [--v] [CRF]`，编码为 HEVC（hvc1）加 AAC，CRF 默认 25。抖音上传无需压得太小，画质优先时可用 CRF 20–22。

## 7. 9:16 竖版
- 画面 1080×1920：上方 420px 是标题带，中间 1080×1080 是内容窗，下方 420px 是信息带加进度条。由 `shell/vframe.js` 生成。
- **只要出 9:16，顶部标题带就一定有标题，不能留空。** 用户给出口播稿，或者听写整理出口播全文之后，就按口播开头的钩子拟标题：1 个推荐加 2–4 个候选，在确认单①里确认。标题要和开头钩子说的是同一件事。
- `CONFIG.vertical` 里设置：
  - `preset`：night、tech、clean、paper 四选一，跟着当次风格走
  - `title`：两行标题，每行不超过 9 个字，`[[ ]]` 标出重点
  - `sub`：一句话说明
  - `tag`：栏目标签，比如「AI 资讯」「AI 知识」「教程」
  - `brand`：片子主体的标识，没有就不填
- 动效和 16:9 版完全一致，只是重新排版。

## 8. 封面
**成片做完后，3:4 竖版和 4:3 横版两张封面都要生成，缺一不可。** 即使这次只出了一种比例的成片，也照样出两张封面。
1. **先定标题，再做封面。** 给用户 6–10 个短标题选：
   - 走标题党方向，可以带悬念、数字或反差
   - 不加逗号，可以用感叹号或问号
   - 两行以内，每行不超过 6 个字
2. 用户定了标题后，写进 `CONFIG.cover`（title、kicker、hero）。
3. 运行 `python3 tools/cover_shot.py`，导出两倍分辨率的 3:4 和 4:3 两张封面，再转成 JPG。
4. 主图优先用真实素材。版式可以在 cover.html 里按当次风格调整。

## 9. 交付
1. 成果放在 `~/Movies/<片名>/`，分成四个文件夹：成片（16:9、9:16）、封面、素材（带来源清单）、源码（项目目录）。完成后告诉用户各文件的完整路径。
2. 在 `~/Movies/<片名>/` 里写一份 `<片名>_动效片.md`，包括：口播、分镜表、素材来源、修改记录。
3. **每期复盘**（交付消息的最后一个模块）：按三类列出建议，用多选题让用户勾选同意的，勾了的再更新进 skill：
   - **规则**：用户这次提的意见里，以后每期都适用的 → 补进第 4 步的硬规则。
   - **组件**：这期新写的组件里，以后还会用的 → 去掉写死的样式（颜色走主题变量），放进 `motion-kit/packs/`，并更新 README 的组件清单。
   - **引擎和工具**：这次碰到的 bug 或缺的功能 → 修进 `motion-kit/engine/` 或 `tools/`。
   skill 文件就在本 skill 所在目录（Claude Code 一般是 `~/.claude/skills/motion-video-workflow/`，Codex 一般是 `~/.agents/skills/motion-video-workflow/`），没经用户勾选不要改。