Motion video
生成 10–30 秒的动态图形短片，全部通过真实代码实现：Swift 音频合成引擎编写乐谱，Swift CoreGraphics/CoreImage 渲染引擎在同一节拍网格上绘制每一帧（支持亚帧运动模糊、真实高斯模糊、磨砂玻璃、胶片颗粒效果），AVFoundation 编码为 H.264 + AAC。此技能文件夹中包含所有必需内容；仅依赖 macOS 和 Xcode 命令行工具。
标准是“动态设计师的作品集”，而非演示：每个画面都与音乐节拍对齐，屏幕上的内容没有装饰性噪音，每个声称都为真。
文件夹结构
engine/—audio_core.swift+audio_main.swift（乐谱引擎），video_core.swift+video_main.swift（渲染引擎）。每个项目请勿编辑此处；项目代码应放入项目文件夹。scripts/mv.sh— 构建并运行：audio，stills <beats>，video [out]。levels.py、sheet.py、probe.swift由它调用。- 完整的示例项目位于配套技能
app-3d-video（template/：score.swift、scenes.swift、project.env，以及 SceneKit 层s3d.swift）。对于纯 2D 视频，请复制其project.env和score.swift，然后根据references/engine-api.md编写全新的scenes.swift。 examples/scores/energetic-128bpm.swift— 高能量发布乐谱（包含鼓点断奏、填充、中断）。references/motion-direction.md— 根据基调调整节奏、缓动、转场、布局、叙事模式及审查清单。编写场景前请阅读此文档。references/score-guide.md— 速度/调性/编配方法，匹配品牌声音的调性，响度目标。编写乐谱前请阅读此文档。references/engine-api.md— 每个绘图/音频函数及其签名。编写代码时阅读。
工作流程
1. 简报（限定为确实能改变结果的问题）
确定：目的与受众、时长、画面比例（默认 1080×1920 竖屏；通过 W/H 可设为 1920×1080 或 1080×1350）、基调、屏幕文案的语言。如果用户不在意，使用默认值：15 秒、竖屏、英文文案、基调与产品领域匹配。如果请求的内容在符合基调所需速度的情况下无法塞入给定时长，请提出并询问放弃哪个——时长还是内容——而不是强行压缩。（例如，一个健康类应用想要平静的节奏和15 秒的时长；答案是删减场景，而非加快速度。）
2. 调研事实
屏幕上的所有内容必须可溯源：
- 已发布的内容：自最近几个版本号更新以来的
git log、CHANGELOG、发布说明。 - 准确的产品文案：阅读代码以获取通知标题/正文、按钮标签、Siri/意图对话框字符串、代码片段标题、新手引导文本。直接引用它们；不要将其改写为承诺。
- 标记任何示意性内容（示例名称、计数、时间），并在交付时告知用户。
- 保持故事内部一致：如果场景 1 在 9:41 记录了 Metformin，场景 2 就不能询问上次服用 Metformin 的时间并回答“13 小时前”——请使用另一种药物。
3. 资产
收集真实的品牌资产：应用图标（最大 PNG）、Logo、品牌颜色（设计符号/资源目录）、产品已使用的官方徽章（例如“Works with Apple Health”），以及产品自身的声音（通知/声音 Logo 的 WAV 文件）。将一次性声音素材转换为合成器可用的格式：afconvert -f WAVE -d LEF32@48000 -c 1 in.wav assets/name.wav；如果仓库中有 sharp/resvg，则使用它们将 SVG 转换为 PNG，或使用 qlmanage -t -s 1024。
优先使用包含一套数据集的矢量 UI 重建（一张壁纸、一个时钟时间、一组姓名），而非原始截图。不同来源（不同时间、设备、数据、框架）的截图并排展示会显得奇怪；观看者会立刻注意到。如果确实需要使用截图，请在单次会话中捕获它们：xcrun simctl status_bar booted override --time 9:41 …，之后清除覆盖状态，并且绝不捕获其他恰好打开的应用。
4. 在节拍网格上规划
时长 = 小节数 × 4 × 60 / BPM，因此需一起选择 BPM 和小节数（15 秒 = 96 BPM 下 6 小节，128 BPM 下 8 小节）。在项目中编写 plan.md：一个表格，包含 小节 → 场景 → 每个节拍上的画面揭示（文字浮现、卡片落下、勾选弹出、转场）。每小节一个想法；重要时刻（Logo、关键功能、结束卡）位于强拍上。参见 references/motion-direction.md 中的基调预设和模式。
5. 项目文件夹
在 ~/Movies/MotionVideo/<slug>/ 中工作（可持久保留以供后续修改）：
mkdir -p ~/Movies/MotionVideo/<slug> && cp ~/.claude/skills/app-3d-video/template/{project.env,score.swift} ~/Movies/MotionVideo/<slug>/
编辑 project.env（BPM、DURATION、W、H、FPS），将品牌资产放入 assets/，然后重写 score.swift 并编写 scenes.swift。在 scenes.swift 顶部重新分配调色板变量（INK、TEAL、MINT、GREEN、GLOW、PAPER、DARKTEXT、ORANGE、DARK_MID、LIGHT_GLOW_A/B）以匹配品牌。
6. 先编写乐谱
编写 score.swift（配方参见 references/score-guide.md），然后运行 mv.sh <dir> audio。您无法听到它——请阅读电平输出：RMS 在基调的目标范围内，无削波，段落对比符合预期（安静的引子、高音补强的升起、任何中断处的凹陷）。视频会读取 music.wav 以用于音频响应元素，因此请在渲染静帧之前渲染音频。
7. 场景，然后静帧审查——至少两轮
编写 scenes.swift，定义 func render(_ t: Double, frame: Int)，然后运行：
~/.claude/skills/motion-video/scripts/mv.sh <dir> stills 0.5,2,4.25,6,8.5,10,13,16,20,22.5
打开 <dir>/sheet.png 并依据 references/motion-direction.md 中的清单进行检查（弹性超调处的重叠、裁剪的降部、过小的文本、混乱的淡入淡出、不一致的 UI、空白空间）。还需选取转场中间的节拍点，而不仅仅是静止状态。修复并重新渲染静态帧，直到某一轮检查结果干净无问题。静帧渲染速度约为 0.1 秒/帧，因此可以自由迭代。
8. 最终渲染与验证
mv.sh <dir> video <dir>/out.mp4 — 在 SUB=5 运动模糊下，渲染速度约为 0.3–0.5 秒/帧（15 秒 @ 60 fps ≈ 5–8 分钟），因此请在后台运行。探针会打印时长和轨道信息；此外，提取几帧（.build/probe out.mp4 <dir> 2,5,9,12）并进行查看。
9. 交付
复制到 ~/Downloads/<Product>_<Topic>_<duration>s[_vN].mp4，使用 SendUserFile 发送，并汇报：逐节拍的叙事（以秒为单位）、哪些资产和字符串是真实的、哪些是示意性的、您仅通过测量来判断音频，以及为用户提供一个简短的检查清单（调高音量收听、在手机上检查可读性、品牌/徽章使用情况）。修订时保留先前版本（v1/）。
修订
大多数反馈对应一个调节旋钮：更慢/更平静 → 降低 BPM + 减少场景 + 阻尼弹簧（k≈5, w≈6）+ 更长的揭示（0.9–1 节拍）+ 使用焦点变焦/光圈转场而非甩切；更高能量 → 使用高能量乐谱、带超调的弹簧、甩切、鼓点上的闪光效果；“我不理解功能 X” → 在一个设备上展示完整的因果链（请求 → 响应 → 结果），使用产品真实的响应文案，并以价值而非功能名称作为标题。