Motion Showreel

Motion Showreel

把一个想法做成一支以图形、文字或界面动画为主的短视频，交付 MP4 和能重建的源码。

原理：页面暴露确定性的 render(t)，脚本逐帧截图，再用 ffmpeg 合成 MP4。配乐和音效在代码里合成，和画面共用一张时间表 timeline.js，所以卡点可以精确到帧。

好片子从哪来：变化密度、运动质感、一个记忆点、音画关系，这四项通常决定观感。但具体怎么动、动多少，由风格和内容决定，不是每支片子都要多机位、弹簧和满屏音效。全局只守几条底线（见「底线」），其余都是给模型的起点，不是天花板。

适用范围

时长：最适合 5–60 秒。纯音乐驱动、没有旁白的片子可以做到 2 分钟左右（比如 mixed-media-era 那种年代回顾）；超过 60 秒时按段落分别制作、分别检查，开工前跟用户说清楚渲染和审片的成本。需要旁白讲解的视频不在本 Skill 范围内。

Opus 的长处和默认坑

• 长处：一个文件里能混用 Canvas、SVG/DOM、WebGL、Three.js，甚至每段换一种媒介；运动可以用公式精确计算（闭式弹簧、节拍网格、子帧运动模糊）；声音和画面读同一张时间表；能长时间自主「渲静帧 → 看图 → 修改」；审美判断力强，一句「全力以赴」就可能出很惊艳的东西。
• 默认坑：没有约束时，画面会落到深色背景、居中大字、所有元素一起淡入、紫蓝渐变加发光、机位不动；配乐会落到 A 小调四踩、每个重拍 impact + crash、钟声落版，几支片子听起来像同一首歌。所以要先找对标（画面和声音都要）、写清风格和禁止清单。但约束也不能写死：这个 Skill 的风格库和手法库都是起点，主题需要时随时改造、混搭或自定义。
• 做不好的：写实人物、复杂的手部 / 布料 / 毛发、需要真实物理精度的东西、照片级产品（除非用户提供模型或图片）。遇到这些就风格化处理，或者换成绿幕人物 + 代码场景的分工。

工作流

0 环境检查（一次）
1 一次问清 ──────── 能从请求里推断的就不问
2 brief.md ──────── 对标 → 用途 + 风格 → Reel Read → 节拍网格 + 分镜 + 禁止清单
3 风格帧 ────────── 🛑 唯一的停顿点：已定风格 → 1 个方向 3 张帧；未定风格 → 3 个方向各 1 张帧
4 制作 ──────────── timeline → 逐镜头 → 静帧自检 → 确定性检查 → 小样 → 正片
5 声音（可选）────── 代码合成 / 用户曲子 / 无声
6 验收 ──────────── 技术检查（程序判定，必须全过）+ 审片（看图列问题，交给用户终审）
7 交付

工作目录：在用户当前目录下建 <slug>/，所有文件都放在里面：brief.md、index.html、motion.js、timeline.js、score.mjs 或 score.tone.js（按 scaffold 的 --audio 选择）、build.sh、fonts/、assets/、audio/、qa/、out/。

第 0 步：环境

第一次使用时运行 sh <skill>/scripts/setup.sh：它会安装 Playwright 和 Chromium，再跑 check-env.mjs。需要 Node 18+ 和 ffmpeg；缺了就告诉用户怎么装，不要替用户装系统软件。工具自带测试：cd <skill>/scripts && npm test。

第 1 步：一次问清

用一条消息问，最多 5 个问题，请求里已经回答过的就跳过。用户说「你看着办」，就全部用默认值，并在 brief 里注明。

• 用户给了参考视频：先跑 inspect.mjs sheet <ref> --cells 30 看全貌，inspect.mjs grid <ref> --strips 量出剪点和它们落的节拍网格（BPM 候选、每段占几步、每个转场的连续帧），inspect.mjs heat <ref> 看每段里哪里在动、动多大面积。把量到的数写进 brief 的对标一栏。只学结构和手法，不搬素材。
• 用户给了曲子：先跑 audio.mjs beats <track> --out <slug>/audio/beats.json。
• 画面里要出现的产品、品牌或技术名词，不确定的先查证。

放手模式：用户说「全力以赴」「你随意」「给我惊喜」，或者只给了一个主题、没有其他要求时，进入放手模式：只守底线和技术管线，风格、结构、手法都由你自己判断，可以完全不用风格库里的风格。仍然要写 brief（这是让你自己的创意可控、可复现的方式），仍然在第 3 步给 3 个方向。

第 2 步：brief.md

先找对标：动笔前为这支片子（这个主题 + 这种用途）挑 1–2 个对标作品，可以是电影片头、广告、游戏、动效作品、设计流派。在 brief 里写下「学什么」（构图、节奏、镜头语法、配色逻辑、配乐结构）和「不学什么」（角色、具体镜头、旋律、logo、字体文件）。对标比任何规则都更能拉高上限。

再想三个候选结构：比如一段旅程、一次前后对比、一次倒数、一个变成另一个、一个不切镜头的长镜头。各用两三行写下来，选一个并写明理由。第一个冒出来的想法往往是这个风格的陈词滥调。

用途和风格分开选：

• 用途（拍什么、按什么结构讲）看 references/formats.md，只读对应的那一节。
• 风格（长什么样、怎么动、什么声音）先看 references/styles/INDEX.md，再只读选中的 1–2 个风格文件。风格可以直接用、改造（替换其中一两条规则）、混搭（一主一辅，或者按段落切换媒介），也可以按 styles/_template.md 自定义。风格规则保持不变，故事、镜头和结构从用户的主题来，不要沿用别的片子。每个风格文件都有「辨识信号」和「最俗的版本」两节：按主题挑 2–3 个信号（至少一个不在俗套里），在 brief 里写明翻掉了俗套的哪几条，或者为什么保留。用户选了风格，要的是一眼认出这个风格，两三个信号就够了。
• 再按需翻 references/craft.md（手法库）。

按 references/brief-template.md 写 brief，核心是：

Reel Read:
  format: [用途，formats.md 里的类型]
  benchmark: [对标作品 · 学什么 · 不学什么]
  structure: [三个候选结构 → 选中哪个、为什么]
  style: [styles/ 里的风格（含改造点），或者混搭方案，或者自定义规则]
  signals: [挑了哪 2–3 个辨识信号、为什么；翻掉了俗套的哪几条]
  takeaway: [观众记住的一句话或一个画面]
  hook: [前 1 秒发生什么]
  signature: [记忆点：第几秒、什么手法]
  palette / type / motion / camera / texture: [按所选风格写出具体值]
  sound: [无声 / 合成（声音对标、律动、和声、配器、曲线，见 sound.md 第 2 节）/ 用户曲子（BPM、drop）]
  forbidden: [这支片子的禁止清单]

接着在 brief 里写节拍网格 + 分镜表：先定 BPM 和小节数，每个镜头一行，写明 拍号区间 | 画面（含原文文字）| 运动 | 镜头 | 声音 | 转场。

用户只说了一句「全力以赴」，也要把它翻译成上面这份具体约束，否则结果就是抽卡。

第 3 步：风格帧（🛑 唯一停顿点）

建项目：sh <skill>/scripts/scaffold.sh <slug> [--audio synth|tone|layer|none]（默认 synth = 第 1 档合成；只拷贝选中的那份 score，build.sh 的 AUDIO= 也随之设好）。starter 只用来验证管线能跑通，画面和文案都要换掉。先写 timeline.js。

A. 用户已经定了风格（或者给了明确的参考）：

1. 用真代码搭出 hook 帧、记忆点帧、结尾帧，配色、字体、文案都用最终的。
2. render.mjs <slug> --still 0.6,7.2,14.5 --sheet，自己先看一遍，明显的问题修完再给用户。记忆点靠运动的话，另出一段 2–3 秒的小样（--start --duration）。
3. 把 Reel Read 摘要、分镜概要、风格帧发给用户，问「方向对吗？」。

B. 用户没定风格（包括放手模式）：给 3 个拉开差距的方向，规则见 styles/INDEX.md：

• A 贴合主题 / 品牌，B 换一种画面语言（来自另一个分组），C 大胆（自定义、混搭或结构上很大胆，至少一个方向不是库里现成的）。
• 每个方向写一段迷你 Reel Read（风格、对标、记忆点、配乐方向，3–5 行），并用真代码渲一张最能代表它的关键帧。三个方向的页面放在同一个项目里，用 ?dir=a|b|c 切换。B、C 只为这一张关键帧服务，不必做成能播的整片。
• render.mjs <slug> --directions a,b,c --at 14.5,2,0 一次渲出三张并拼成带标签的 qa/directions.png，发给用户，问「选哪个，或者怎么混合？」。

两种情况都真的等用户回复，再进入制作。用户事先说过不用确认的，就自己选一个、写明理由，自查后继续；交付时把没选的方向一起给用户（B 情况附上 qa/directions.png，A 情况各写一句另外两个可能的方向），让用户回来还能换。

第 4 步：制作

制作前先读 references/stack.md（页面契约、确定性、各技术的坑）。要现成写法时查 references/recipes.md。

1. 时间点全部写进 timeline.js，页面和 score.mjs 都从这里 import。镜头表写进 SHOTS（验收时按镜头报运动），刻意的停留写进 HOLDS（比如落版 [[b(36), DUR]]），要留呼吸的重拍写进 DROPS，验收工具会读它们。转场要对拍时，用 revealOn(拍点, 转场时长, 揭开点) 倒推起点，让新画面露出来的那一帧落在拍上。
2. 逐个镜头做。每个镜头渲开头、中段、结尾 3 张静帧；快速动作用 inspect.mjs strip 看连续帧。
3. 跑确定性检查 render.mjs <slug> --determinism，不通过就先修。
4. 片长 30 秒以上或渲染慢的，先出低清小样：--size 960x540 --out out/proxy.mp4。
5. 出正片：先在 build.sh 顶部按 brief 设好 FPS、SIZE、AUDIO、LOOP，再 sh <slug>/build.sh。它会构建配乐，先跑确定性检查（不过不出片），再渲染，接着跑文字框景检查（只出审片材料，不挡构建），最后带着同一份规格跑技术检查（时长取 timeline.js 的 DUR）。--subframes、--dpr、--grain 作为参数加在后面，按风格需要加。这些参数都会成倍增加耗时，开渲前先报预计时间。

硬规则：

• 画面只由 t 决定：不用 Math.random、Date.now、rAF、定时器、CSS 动画，帧和帧之间不保存状态。
• 字体和素材全部加载完，再设置 READY = true；字体放进项目自托管。
• 布局从 stageSize() 返回的宽高推导，不写死像素。

第 5 步：声音（可选）

看 references/sound.md。声音方向（对标、律动、和声、配器、曲线）在第 2 步的 brief 里就定好，这一步按它来写；按风格选一档：

• 构建：audio.mjs build <slug>/score.mjs 或 score.tone.js，都会输出 −14 LUFS 的 audio/music.wav。
• 用户曲子：先跑 audio.mjs beats（有 librosa 时自动使用），对齐 timeline，再在 score 里 S.load() 进来叠音效。
• 无声：跳过这一步。

你听不到声音，所以每次 build 之后都要跑 audio.mjs check，看数值和图。timeline.js 里写了 DROPS 时，它还会量出每个重拍前那半拍的凹陷和重拍的抬升，没有呼吸就给 WARN。