Motion2Code — 把动效设计视频重建为可编辑的 SVG + GSAP 代码

技能简介

Motion2Code 是一个教编程 Agent「看视频写动画」的技能：把一段动效设计视频，重建成干净、可编辑的代码——内联 SVG 图形 + 一条 GSAP 时间线，能逐帧 seek、无缝循环，并且必须与源视频逐帧并排比对通过。如果源素材是网站或应用的屏幕录制，它还会再进一步，直接重建出可交互的真实站点（GSAP ScrollTrigger）。技能适配 Claude Code、Codex、Cursor、Copilot、Gemini 等主流 Agent，附带 6 个已重建的示例作品（动态字体、匹配剪辑、节日海报、天气雷达、贴纸作品集、播客播放器），每个 10~15 秒、24~60 KB。

核心能力

• 视频研究的自动化：study_video.py 每 0.25 秒抽帧并按时间命名，识别转场前后帧，输出联系表、调色板与源视频的循环评分。
• 调色板提取：palette.py 直接打印视频或图片里每种平涂色的十六进制值与占画比例。
• 逐帧差分校验：frame_diff.py 在指定时间点（或整段区间）生成「源视频 | 代码渲染」并排图与差分散点，列出最差的五个时刻。
• 页面契约检查：check_anim.py 校验页面契约、脚本白名单、禁止内嵌位图与视频；带 --runtime 时还会无头打开页面，检查控制台错误、网络请求、循环接缝、seek 是否确定性、是否自动播放。
• 逐帧渲染导出：render_anim.py 通过 anim.seek 逐帧渲染成 mp4、GIF 封面或 PNG，尺寸任意。
• 并排证明片：side_by_side.py 把源片与渲染结果叠成一条带标注的对比视频，横竖屏皆可。
• 统一动画契约：页面必须暴露 window.anim = { tl, duration, seek(t), play(from), pause() }，seek(t) 必须是 t 的纯函数；?t=6.5 定格、?external=1 等待外部驱动、无参数则自动循环。
• 硬性约束：只使用给定源视频、绝不重新生成或内嵌其画面、文字照抄源提示（即使拼错）、颜色从源采样、GSAP 时间线是唯一时钟、循环必须在代码里闭合（frame(duration) 等于 frame(0)）。

安装配置

1. 通用方式（支持 skills 标准）：npx skills add lovisdotio/motion2code。
2. Claude Code：仓库内置 .claude-plugin/ 插件与市场清单，可直接作为插件安装。
3. Codex：把 skills/motion2code 复制到 ~/.agents/skills/；Cursor：复制到 ~/.cursor/skills/ 并加载 adapters/cursor/ 里的规则；Copilot：gh skill install lovisdotio/motion2code motion2code；Gemini CLI：gemini extensions install https://github.com/lovisdotio/motion2code。
4. 依赖：Python 3.9+、ffmpeg；会开浏览器的脚本需要 Playwright（pip install playwright && python -m playwright install chromium）。

使用步骤

1. 用自然语言下指令：「把 clip.mp4 重建成可循环的 SVG + GSAP 动画」，或「把这个应用录屏变成一个真实站点」。
2. 需要完整需求说明时，填 prompts/convert-video-prompt.md 里的模板。
3. Agent 先用 study_video.py 研究视频，再写页面与时间线。
4. 跑 frame_diff.py 定位差异最大的时刻，逐个修到与源片对齐。
5. 跑 check_anim.py --runtime 确认契约与运行时行为，再 render_anim.py 出片。
6. 用 side_by_side.py 生成对比证明片，作为交付验收。

适用场景

• 动效还原交付：设计师给了参考视频，需要可维护的代码而不是录屏。
• 营销页/落地页动画：把宣传片的动效落到真实网页上。
• 产品演示复现：把屏幕录制变成可交互的原型站点。
• 动画教学：逐帧比对本身就是理解动效节奏的最好方式。
• 性能优化：用 20~60 KB 的 SVG 动画替代几百 KB 的视频素材。

适用人群

• 前端工程师与动效开发者
• 需要把设计稿落地的创意开发者
• 做营销页、作品集的独立开发者
• 使用 Claude Code / Codex 的视觉向工程师

工作原理

技能把「还原动效」拆成研究、构建、验证三段闭环：研究阶段用脚本把视频拆成结构化事实（帧、转场、调色板、循环点），构建阶段要求产出单文件自包含页面（内联 SVG、GSAP 3、必要时 flubber 与 Google Fonts），验证阶段用差分与运行时检查把「看起来像」变成「逐帧对得上」。因为页面必须暴露确定的 seek(t)，渲染才能逐帧驱动并输出可对比的证明片，从而让 Agent 有一个可自动判定成败的标准，而不是靠自我感觉。

官方链接

• GitHub：https://github.com/lovisdotio/motion2code
• 在线示例：https://fal-motion-in-code.vercel.app
• 协议：MIT