Communitygithub.com

motion-match

将参考视频、GIF 或屏幕录制中的动画精确测量并重建到用户自己的设计中,或与用户的设计进行逐帧对比验证。

motion-match 是什么?

motion-match 是一个面向开发者与 AI 代理的专业动画匹配与重建技能。它可以将“让这个动起来像那个”的模糊需求量化为精确数值:包括每一剪辑点、每个运动元素的开始时间、持续时间、缓动函数、过冲量、移动距离、旋转角度和形状变化。用户只需提供参考视频(或 GIF、屏幕录制),该技能就能自动分解帧序列、测量运动参数、拟合缓动曲线,并输出可直接用于 CSS、Web Animations API、Framer Motion、GSAP、Remotion、SwiftUI、After Effects 等工具的代码片段。随后,它还会生成与参考帧逐帧对比的报告,确保时间误差控制在 ±0.08 秒以内。 该技能还提供三种模式:**导演模式**——从静态图像出发,为 UI 入场、演示等场景设计全套动态,并内置多种风格预设(冷静、中立、活泼);**故事模式**——为短视频、解说动画等提供更复杂的动态编排;**剪辑模式**——将用户生成的视频素材(如 AI 生成的片段、UGC 视频)剪辑成带字幕和动态图形的广告。脚本基于 NiazMorshed2007/reanimate 和 rossark0/rossark-motion-skill 的方法改编(均为 MIT 许可),所有测量与分析流程均由本技能自有脚本完成,不上传任何数据至外部。

兼容平台✓Claude Code~Codex CLI✓Cursor
npx skills add https://github.com/stazdev/motion-match/tree/HEAD/skills/motion-match

在你喜欢的 AI 中提问

打开一个已预加载此 Agent Skill 的新对话。

文档

Motion match:测量任意动画,重建它,证明它与原版运动一致

将“让这个动起来像那个”转化为数字:每一剪辑点,以及每个运动元素的起始、持续时间、缓动、过冲、位移、旋转和形状变化。将运动重建到用户所使用的任何工具中(CSS、Web Animations API、Framer Motion、GSAP、Remotion、SwiftUI、After Effects),然后逐帧比较,直到时间匹配到 ±0.08 秒以内。没有参考运动,只有静态图片?使用导演模式(见下文)处理 UI 入场,使用故事模式处理演示短片和解释性视频:Claude 设计运动、构建它,然后用相同的脚本测量其自身的渲染结果,这样“流畅”就不是空口无凭,而是经过验证的。需要将视频片段(UGC、AI 生成、实拍)剪辑成广告?使用剪辑模式:相同的测量、导演规则和审阅流程,应用于视频素材。 方法改编自 NiazMorshed2007/reanimate 和 rossark0/rossark-motion-skill(均为 MIT 许可);脚本均为自有。

<skill> 是本技能的文件夹。所有工作放在当前文件夹下的 ./motion-match/<name>/ 目录中: ref/(参考分解)、ours/(我们的渲染分解)、compare-N/(每轮对比结果)、spec.md。

设置(首次使用)

需要 ffmpeg/ffprobe 在 PATH 中,以及装有 numpy 和 Pillow 的 Python 3。

  • 检查:python3 -c "import numpy, PIL"。如果失败,寻找一个已安装这些库的 Python(现有项目的 venv),否则询问用户一次,然后:python3 -m venv ~/.motion-match/venv && ~/.motion-match/venv/bin/pip install numpy pillow,并在后续命令中使用 ~/.motion-match/venv/bin/python 作为 python。每个脚本运行时都加上 -I 参数。
  • 导演模式和故事模式还需要无头渲染页面:pip install playwright && python -m playwright install chromium(询问用户一次)。如果无法安装,则改为屏幕录制页面,并说明时间精度会稍差。
  • 无需其他安装;不会上传任何内容。

0. 范围界定(在测量前将其写入 spec.md 顶部)

  • 目标: 用户明确指出的文件 + 时间范围(+ 裁剪,如“前 3 秒”、“仅按钮部分”)。
  • 保真度: 运动忠实(默认):顺序、时间(±0.08 秒)、缓动族、过冲量、相对于元素尺寸的位移、错位。用户自己的艺术设计、颜色、字体和文字。像素忠实仅在用户明确要求且仅用于私人练习时适用:他人的设计、Logo、角色和音乐属于他们;绝不要帮助发布其副本。
  • 目标平台: 运动将要集成到的工具或代码(如果不明确则询问一次:它将决定输出格式)。
  • 获取参考: 用户提供的文件,或他们制作的屏幕录制(网站和应用程序:录制交互过程;本技能基于帧工作,而非网站的代码)。仅当用户要求下载特定视频时,才从 YouTube 或某个网站下载,并放入其专属文件夹;将其视为私有参考材料。

1. 分解

python -I <skill>/scripts/ref_frames.py REF.mp4 --out motion-match/<name>/ref [--start S --end E --crop x:y:w:h] → 以源帧率生成每一帧,sheets/timing_NN.png(每一帧:时间、缓动、跟随动作)和 sheets/poses.png(每秒 2 帧:发生了什么)。读取每张 sheet。GIF 同理。

2. 测量

  • 剪辑与片段: python -I <skill>/scripts/motion_compare.py motion-match/<name>/ref motion-match/<name>/ref --out motion-match/<name>/self --no-align 列出参考中的剪辑点(场景变化)和运动及其时间。始终静止的参考(没有剪辑点)将被视为一个整体。
  • 精确颜色: python -I <skill>/scripts/track_motion.py <ref>/frames --sample X,Y --at T(使用全尺寸帧的像素坐标,而非联系 sheet 的坐标)。
  • 每个运动元素: track_motion.py <ref>/frames --name btn --colors HEX,HEX --tol 35 --region x,y,w,h [--save-masks] (或 --not-bg HEX 表示“除了背景以外的所有内容”)。对于有发光或复杂背景的参考,务必提供 --region 和该元素独有的颜色;检查打印出的可见帧范围是否合理。记录每帧的位置(cx cy)、尺寸(w h)、挤压(aspect)、边缘、淡入/放大(presence)、颜色和旋转(angle)。
  • 每次运动: python -I <skill>/scripts/fit_easing.py <ref>/track_btn.json --prop cy --from A --to B (每次运动一个窗口,切勿跨越剪辑点)→ 起始、结束、持续时间(毫秒和帧数)、缓动族、过冲量、稳定时间,以及可直接粘贴用于 CSS、WAAPI、Framer Motion、GSAP 和 Remotion 的代码行。 误差 ≤ 0.03 表示拟合良好;“没有单个缓动能拟合”意味着需要拆分窗口,或者这是一个关键帧链。
  • 微小运动(如 2% 的挤压、5 像素的浮动)不会在 sheet 上显示,但会在跟踪数值中体现:务必读取这些数值。
  • 淡入的微小文本靠近活动曲线的噪声:改用 track_motion 进行测量。

用哪些数值测量哪种运动

运动类型测量用属性备注
移动、滑动、浮动cx、cy每个轴单独拟合
缩放、放大、挤压w、h、aspect
淡入淡出presence(配合 --colors)
旋转、旋转动画angle(度,顺时针为正,可超过 360 度)基于轮廓;圆形返回 None:在圆形上标记一个点作为独立元素跟踪其 cx/cy。具有 n 重对称性的形状(正方形:4)每帧需要 < 180/n 度,因此快速旋转需要高帧率源。区域内其他相同颜色的形状会干扰:缩小 --region
变形(形状 → 形状)--save-masks,然后 shape_compare.py见下文
3D 翻转 / 卡片翻转w(像余弦一样缩小)+ presence;在半幅点颜色翻转背面是独立元素
路径运动(弧线、曲线)cx 和 cy 两者,若沿路径旋转则加上 angle分别拟合每个轴;路径形状显示在 sheet 上
裁剪 / 蒙版揭示、擦除x1 或 y1(领先边缘)、w/h
线条绘制presence
文字拆分(逐词/逐字)跟踪第一个和最后一个词;错位量等于它们的起始时间差 ÷(总元素数 − 1)
计数器、图表条条:h/y0;数字:参考 sheet(目测)

变形。 track_motion.py ... --name blob --save-masks 保存每一帧的轮廓(居中、缩放至等面积)。然后:

  • python -I <skill>/scripts/shape_compare.py <ref>/track_blob_masks.npz --from A --to B 将 morph 系列(0 = 起始形状,1 = 结束形状)添加到 track_blob.json 中。fit_easing.py ... --prop morph 随后给出其起始、结束和持续时间。变形进度遵循面积,因此其时间可靠,但缓动名称并非可直接粘贴的值:从规格说明书中获取缓动,或者从可跟踪的参数(w、aspect、angle)获取。
  • 我们的 vs 参考:shape_compare.py REF_masks.npz --vs OURS_masks.npz --from A --to B [--rotate] → 形状路径:参考中的每个中间形状是否也出现在我们的动画中,不论其时间(通过:平均差 ≤ 10%,最差 ≤ 整个变形过程的 25%)。然后 fit_easing.py REF_TRACK --prop morph --vs OUR_TRACK 检查时间。--rotate 可在变形同时发生旋转时忽略转向(通过 angle 检查)。

3. 编写运动规格说明(spec.md;每一行都成为一个检查点)

| # | 元素 | 属性 | 从 → 到 | 起始时间 s | 持续时间 s(帧数) | 缓动 | 过冲量 | 错位 / 备注 | 数据来源 |
| 1 | card | translateY | 40 → 0 px | 0.20 | 0.60 (18) | easeOutCubic / cubic-bezier(.33,1,.68,1) | 0% | +0.08 s 每张卡片 | track + fit_easing |
| 2 | icon | rotate | 0 → 180 deg | 0.40 | 0.30 (9) | easeOutCubic | 0% | — | track angle + fit_easing |
| 3 | blob | morph | 正方形 → 圆形 | 0.50 | 0.40 (12) | easeInOutCubic | — | 形状路径 PASS | shape_compare |
| c | — | 剪辑点 | — | 1.77, 2.33 | — | — | — | — | motion_compare self |

行中的“?”表示尚未读取该帧。同时注明不运动的元素。在任务较大时,先向用户展示规格说明书,然后再开始构建。

4. 构建

在用户选择的工具中,使用他们的设计。从规格说明书中复制时间,从针对该工具的拟合器输出中复制缓动。当布局不同时,根据元素或帧的相对距离映射位移。关键帧链:使用平滑、无过冲的插值;如果参考有过冲并稳定下来,则使用弹簧。

  • 旋转: 明确设置 transform-origin(测量枢轴点:其 cx, cy 保持不变的点)。
  • 变形: SVG 路径在两端需要相同数量和类型的命令(或使用 flubber / GSAP MorphSVG);UI 布局变形(按钮 → 卡片、缩略图 → 页面)使用 FLIP 或共享元素过渡(Framer layoutId、View Transitions API);圆角 / 尺寸变形使用纯 CSS。
  • 3D: 父元素设置 perspective: 800–1200 px、backface-visibility: hidden,两个面作为独立层。

5. 比较与修正(2-5 轮)

  1. 在同一窗口以相同帧率渲染或屏幕录制我们的动画(以录制参考的相同方式录制网页)。
  2. ref_frames.py OURS.mp4 --out motion-match/<name>/ours --like motion-match/<name>/ref/frames.json (相同的窗口、裁剪、帧率和帧尺寸)。
  3. motion_compare.py motion-match/<name>/ref motion-match/<name>/ours --out motion-match/<name>/compare-N → 偏移、每个剪辑点和运动(起始/结束/持续时间/峰值误差)、±0.08 秒内通过,activity.png(两条曲线)和 sheets/compare_NN.png(参考 | 我们的 | 差异)。每轮都读取 sheet。
  4. 针对 spec 中的每一行:以相同方式跟踪我们的动画,然后 fit_easing.py REF_TRACK --prop P --from A --to B --vs OUR_TRACK → 每次运动的时间通过/失败、位移和缓动族匹配。变形行:同时执行 shape_compare.py --vs。
  5. 修复证据指向的最小问题,重新渲染,重复。5 轮后,报告所有仍然失败的问题及其数值和原因。绝不要偷偷放宽容差。
症状常见原因修复方法
所有元素偏移一个固定值起始延迟或触发延迟调整第一个延迟
我们的动画更短且提前结束缓动过强(expo vs cubic)使用拟合出的贝塞尔曲线
参考有过冲,我们没有spring/back 与普通缓动back.out / 一个根据测量到的过冲量调整的弹簧
我们的动画中某次运动提前停止缺少次要运动(漂移、推进)查看该窗口内的 sheet
我们的动画中多出一段运动或剪辑有些东西在参考中是静止的,但在我们的动画里动了移除或延迟它
元素编号跳变跟踪捕获到了另一个元素缩小 --region,使用该元素独有的颜色
旋转位移正确,但 cx/cy 中有抖动transform-origin 错误将枢轴点移到测量到的静止点
变形时间通过,但形状路径失败路径插值方式不同(点顺序、起始点)重新排序路径点 / 匹配命令;使用变形库

6. 报告

保真度;匹配了哪些内容,哪些是用户自己的;最后一次对比表格(剪辑点和运动及其误差,通过/失败);每个元素的行;activity.png 和对比 sheet 的路径;所有剩余差异及其数值和原因;以及哪些检查是测量出来的(由脚本生成)和哪些是目测出来的(通过查看 sheet)。

导演模式:输入静态图像,为其设计运动

当用户提供图像(UI 截图、线框图、海报、产品照片)且没有参考运动,或要求 Claude 选择运动时使用。工作同样放在 ./motion-match/<name>/ 下(ours/、spec.md、check-N/)。对于视频片段而不是 UI 入场,请按照下面故事模式中的步骤操作。

  1. 读取图像。 列出每个元素(背景、导航、标题、正文、图片、行动号召按钮、卡片、图标)及其像素位置盒子、角色和重要程度排名:一个视觉焦点,然后是支持元素,最后是装饰性元素。注意阅读顺序、分组(一行卡片、一个列表)、情绪(冷静/高档、中性/产品、活泼)以及任何暗示特殊运动的元素(切换图标、图表、Logo 标记、曲线路径、可翻转卡片)。
  2. 根据情绪选择个性,除非用户指定了。当用户要求提供选项时,构建所有三种。
个性入场方式持续时间缓动位移错位时间过冲量
冷静淡入 + 上升400–600 mseaseOutQuart / cubic-bezier(.25,1,.5,1)8–16 px60–80 ms无
中性淡入 + 上升,或缩放 .97→1250–400 mseaseOutCubic / cubic-bezier(.33,1,.68,1)12–24 px40–60 ms无
活泼上升 + 缩放 .9→1弹簧弹簧(stiffness 300–400, damping 20–26)16–32 px50–70 ms3–8%
  1. 根据角色选择特殊运动(词汇表;数值为起始点,根据个性缩放):
运动类型何时使用默认值
变形图标切换(菜单 ↔ 关闭、播放 ↔ 暂停)、按钮展开为卡片或面板、形状 Logo300–500 ms easeInOutCubic;布局变形通过 FLIP/共享元素
旋转切换/箭头图标、刷新、倾斜入场图标 90–180° 在 200–300 ms easeOutCubic 内;入场 −6…−10° → 0 使用个性缓动;加载器 360° 线性 0.8–1.2 s 循环
3D 翻转 / 倾斜双面卡片、定价切换、悬停深度翻转 rotateY 180° 在 500–700 ms easeInOutCubic 内;悬停倾斜 ≤ 8°
路径运动某物在运动(飞机、沿线路径的点、光标)easeInOutSine,沿路径转向,0.8–1.6 s
裁剪 / 蒙版揭示英雄图片、大标题内嵌或圆形裁剪,500–800 ms easeOutQuart
文字拆分仅主标题词间间隔 40–60 ms,字母间 15–30 ms;整行 ≤ 1 s
线条绘制图标、签名、图表、下划线stroke-dashoffset,600–1000 ms easeInOutCubic
计数器 / 图表增长数字、条、圆环数字 800–1200 ms easeOutExpo;条从基线增长,错位 40–60 ms
视差 / 深度分层英雄滚动场景层速度 0.2–0.6 滚动速度;支持滚动时间线时使用
  1. 编排规则:

    • 顺序:背景/容器 → 焦点 → 标题 → 支持元素 → 行动号召按钮。装饰性元素(导航)最后,或作为快速 150 ms 淡入最先出现(如果它构成页面框架)。
    • 尺寸决定持续时间(图标取低值,英雄图片取高值)。
    • 错位:组内元素依次出现。组间错位 = 元素持续时间 + 50–100 ms。
    • 相同形状的元素运动方向相同。不同形状的元素可以有不同的运动方向。
    • 目标:没有两个活动的元素在同一时间以相同方式运动。
  2. 在导演模式下构建和对比:遵循与上述 1-3 步骤相同的“分解→测量→规格→构建→对比”流程,但参考是给定的静态图像。

省略了故事模式和剪辑模式的详细描述,以减少字数。

相关技能