motion-video-workflowBLOCK

From the repository's own README, as read at the audited commit. Badges and raw HTML are left out.

const t = say('4万');        // → 22.59,数字就在这一帧砸出来
say('收藏', 2);              // 第 2 次说「收藏」的时刻
sayEnd('抄作业');            // 最后一个字的时刻

The instruction file, verbatim from the audited commit — this is the text the model reads, and the surface the audit's instruction layer examines. Quoted here so you can judge it without cloning anything.

---
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. **背景音乐**(只在用户没给音乐时问):
   - 「我自己找音乐(推荐)」:说明效果最好,节奏清楚、带鼓点的纯音乐最合适,拿到后再开工。
   - 「自动合成配乐」:说明是代码合成的极简电子乐,没有版权问题,但效果不如真人挑的音乐,之后可以随时替换后重新混音,画面不用重做。
   - 「配音里已经带了音乐」:用户自己混好了配乐,就走第 1 步的「配音自带配乐」,不再另加音乐。

后面各步只做选中的比例:只出 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 里用 **Claude Opus 5.5** 运行(也兼容 Codex 等支持 SKILL.md 的 agent),所有工作都在用户电脑本地完成。每期要现场写上千行动画代码、做视觉判断,模型越弱,画面越简单、bug 越多;发现当前不是 Opus 时,开场提醒用户一句,用户坚持就照常做。模板就在本 skill 目录的 `motion-kit/` 里。
1. 问清或自定一个项目目录(默认 `~/Movies/<片名>/源码`),把 skill 目录下的 `motion-kit/` 整个复制过去,后续都在这个项目目录里操作。不要直接改 skill 目录里的模板。
2. 在项目目录运行 `bash tools/setup.sh`。它会安装 Python 依赖、Playwright 的 Chromium、下载听写模型,并检查 ffmpeg 和中文字体。缺什么按提示装(需要用户确认的安装命令先问用户)。**从上一期复制了模型也要跑**:模板里不带中文字体,跳过 setup 会缺 `a/fonts/NotoSansSC.ttf`,中文变成宋体(预览会报「缺中文字体」)。
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 步。交付时提醒用户:换成自己挑的音乐效果更好,替换后重跑混音和合成即可。
0. **配音自带配乐时**(用户已经混好音乐):不跑 `mix.sh`,直接把配音响度统一成混音,结尾留出定版:`ffmpeg -i vo -af "aformat=channel_layouts=stereo,aresample=48000,apad=pad_dur=0.8,afade=t=out:st=配音时长-0.8:d=1.6,loudnorm=I=-14:TP=-1.0:LRA=11" -ar 48000 mix.wav`。听写用同一个配音转 16k(`ffmpeg -i vo -ac 1 -ar 16000 vo16k.wav`,带轻配乐也能听准),拍点直接 `python3 tools/beats.py vo`,然后跳到第 3 步。
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 个候选方案的缩略图。效果图要和成片一致,含标题带、装饰带、配色,中间放一个关键画面。用户选定后再开工,后面确认单1里的效果图项就不用重复做。
- 用户选「不要」:直接按推荐方向做,交付时说明用了哪个方向。

| 类型 | 叙事结构 | 主要组件(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 这些强调类组件);mascot(产品有吉祥物 / IP 形象时用 Char 让角色弹出、从边缘探出、呼吸浮动,SoftShot 做柔光渐变镜头底);product-ui 里的 CallScreen(AI 打电话、代谈这类场景的通话界面);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`,不要靠肉眼估。

**重建产品界面先对照真实截图**(用户反馈):要用代码重建某个产品的界面(客户端、App、后台)时,先去它的官网首屏、产品页、下载页或发布视频里找官方的真实界面截图,抓下来后照着校准配色(取色)、布局、字号和文案,不要凭印象画。讲 Claude Code 时默认用桌面客户端(Code 页)的界面,不用终端,除非口播明确说的是终端。

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

**抠图**:白底素材按亮度阈值加羽化处理。官方白底 / 纯色底的角色动画(比如 logo 变形成吉祥物)用 `python3 tools/key_video.py 视频 a/目录 [--scale] [--from] [--to]` 抠成透明 PNG 序列,角色身上的白色不会被抠掉,字母 o 这类封闭孔洞也会抠干净,再挑单帧当静态角色图。复杂背景用 rembg(可以 pip 安装)。

**提到的真实内容一律用官方素材**(用户反馈):口播里出现的产品、公司、人物、界面,包括只提一句的竞品,画面里都要用官方真实素材,比如 logo、应用图标、IP 形象、官网截图、发布视频截帧,不能用代码画的占位图代替。实在找不到才按真实样式重建,并在交付时说明哪些是重建的。

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

## 4. 分镜(写进项目目录的 分镜.md)
分镜表按口播逐句写,每行包括:时间、口播、画面与动效、用到的组件、转场(到下一镜怎么接:硬切,或者哪种运镜转场、前后衔接的是哪两个元素)。**组件一栏要标明「现成」还是「新写」**:组件包能表达的用现成的;表达不了或效果不够,才新写,并在这一栏写一句为什么要新写。分镜表的写法参考 `examples/muse/分镜与制作记录.md`。

**硬规则**(来自用户反馈):
- **一个画面只讲一个信息。** 一屏信息太多时,用镜头运动依次展示(camKeys 逐个推近),不要把所有东西同时摆出来。
- **关键信息出现后至少停留 0.9–1.2 秒**,不能刚推近就切走。转场只

BLOCKgrade D · trust 69/100 Do not install this without reading the findings. The audit found something that could harm you or your machine.

What the source does

Filesystem

none-observed

Network

declared (4 observation(s))

Shell

none-observed

Dependencies

pinned

Secrets in source

none-found

Findings (6)

command -v ffmpeg >/dev/null || echo "!! 缺 ffmpeg:macOS 用 brew install ffmpeg,Ubuntu 用 sudo apt install ffmpeg"

if command -v fc-list >/dev/null; then fc-list | grep -qi "Noto Sans CJK" || echo "!! 缺中文字体 Noto Sans CJK SC(标题的超粗字重靠它):macOS 用 brew install --cask font-noto-sans-cjk-sc,Ubuntu 用 sudo apt install font

os.makedirs('fr', exist_ok=True); [os.remove('fr/' + f) for f in os.listdir('fr')]

docs/showcase/reel.gif

docs/showcase/transitions-30s.mp4

system use found in code, not declared in the description

Gates applied: no_behavioural_pass.