Communitygithub.com

Claude Eye:逐帧动画分析

将屏幕录像转换为带时间戳的帧,利用 Claude 自身的视觉能力逐帧分析 UI/Web 动画中的时序错误(如淡入淡出不同步、过渡错位、闪烁或卡顿),并生成带时间轴和不同步报告的详细分析。

Claude Eye:逐帧动画分析 是什么?

Claude Eye 是一个专为 AI 代理(如 Claude Code、Cursor)设计的技能,用于精确分析屏幕录像中 CSS/JS 动画的时序问题。它利用 ffmpeg 从视频(.mp4、.mov、.webm、.gif)中提取帧,无需额外 API 密钥,仅依赖 Claude 本身的视觉能力。该技能通过逐帧记录每个 UI 元素的透明度、状态(隐藏/过渡中/可见/过渡出)和运动信息,构建精确到毫秒的时间线,并自动检测元素间超过 40% 透明度差异的不同步事件。它支持分阶段分析:先低帧率粗扫定位问题区域,再高帧率细查,以控制上下文消耗。最终生成包含帧透明度表、元素时序、过渡点和修复建议的报告,并指导用户定位源文件中对应的 CSS transition、@keyframes 或 framer-motion/GSAP 配置,给出精确的修复方案。计时精度可达单帧(±1/fps 秒),还可用于分析布局偏移、闪烁、加载旋转器异常等非透明度相关问题。

兼容平台✓Claude Code~Codex CLI~Cursor
npx skills add https://github.com/AbbasMalikzada/claude-eye-skill/tree/HEAD/claude-eye

在你喜欢的 AI 中提问

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

文档

Claude Eye:逐帧动画分析 是做什么的?

你无法观看视频,但你可以阅读图像。这项技能将视频转换为一组带时间戳的帧,让你查看每一帧并记录每个动画元素的行为,然后将这些观察结果转化为一个时间线,精确显示何时出现不同步。CSS/JS 动画中的时序错误通常偏差 100-300 毫秒,人眼难以察觉,但在帧表格中却一目了然。

脚本位于此文件旁的 scripts/ 目录中。它们只需要 Node 18+ 和 ffmpeg/ffprobe,无需 npm install。下面,<skill> 表示此技能的目录。

1. 检查先决条件

运行 ffmpeg -version。如果缺失,告知用户并给出其操作系统的安装命令(Windows:winget install Gyan.FFmpeg 或 choco install ffmpeg;macOS:brew install ffmpeg;Linux:sudo apt install ffmpeg)。之后他们需要打开一个新的终端。未经询问不要自行安装。

2. 提取帧

node <skill>/scripts/extract_frames.mjs <video> --fps 5 --out ./claude-eye-output [--start S] [--end S] [--width 960]

这将写入 frames/frame_NNNN.png 以及一个 manifest.json,其中将每个帧编号映射到其时间戳。始终从 manifest 获取时间戳,不要自行计算。

合理安排图像读取预算。 你读取的每一帧都会消耗上下文,因此每次遍历应控制在约 40 帧或更少:

  • 短视频(约 8 秒以下): 全程 5 fps 即可。
  • 较长的视频,或不知道问题所在: 先进行粗扫(整个视频 --fps 1 或 2)以找到元素移动的位置。然后仅对该时间段使用更高 fps(--start/--end,--fps 10-15)重新提取到单独的 --out 目录中。报告精细分析的结果。
  • 如果用户指定了某个时刻(“大约 3 秒处”、“标题出现时”),直接提取该时间段。

默认的 960 px 宽度足以判断透明度和位置。仅当元素非常小时才使用更大的 --width。

3. 查看帧并记录观察结果

使用读取工具按顺序读取帧。对于每一帧,记下所有正在动画化或可能动画化的可见文本/UI 元素:标题、副标题、按钮、图片、高亮跨度、覆盖层等。

跨帧保持选择器名称稳定: 首次看到某个元素时,为其选择一个描述性的 kebab-case 名称(hero-title、subtitle、cta-button),并在后续每个帧中精确复用该名称。时间线通过名称连接帧,因此一个帧中的 hero-title 和下一个帧中的 title 会被视为两个不同的元素,分析将失败。一旦某个元素出现或已知存在,即使其透明度为 0% 也应包含它。这样可以使“隐藏 → 过渡进入”的节点可见。

对于每个元素,估算:

  • opacity_percent(0-100)。根据背景以及该元素在后续帧中完全可见的外观进行判断。同时计算部分揭示:例如一个 40% 揭示的 clip-path 或 mask 擦除计为 40。
  • state:其中之一为 hidden(≤10%)、transitioning-in(上升)、visible(≥90%)、transitioning-out(下降)。与相邻帧比较以区分“进入”和“退出”。
  • 可选项:has_gradient、has_blur 和 notes,用于记录移动(如 "translateY 约为最终位置上方 20px")、缩放、模糊程度或颜色变化。移动和缩放与透明度同等重要,因此在看到时将它们记录在 notes 中。

将所有内容写入 <out>/frames.json:

[
  {
    "frame": 1,
    "elements": [
      { "selector": "hero-title", "opacity_percent": 0, "state": "hidden" },
      { "selector": "subtitle", "opacity_percent": 0, "state": "hidden" }
    ],
    "overall_state": "pre-animation",
    "observation": "空白英雄区域;尚未渲染任何内容。"
  }
]

frame 必须与 manifest 中的帧编号匹配。时间戳将从 manifest 中填入。对于较长的运行,请分块写入文件,而不是将 40 帧保存在内存中。

压缩视频中的透明度是近似值。帧间 ±10% 的差异属于噪点;跨越多个帧的模式才是信号。

4. 生成报告

node <skill>/scripts/build_report.mjs ./claude-eye-output --context "动画的预期行为"

这会产生 report.md(摘要、透明度时间线表格、每个元素的时序、过渡点、不同步事件、观察结果)和 analysis.json。不同步是指某些元素完全可见而其他元素仍在过渡中的帧,其透明度差值超过 40 点。使用 --spread N 可以更严格或更宽松地设置此阈值。

5. 解读:这是你增值的地方

脚本找到了(何时)发生问题。你的工作是说明(为什么)以及(要更改什么):

  1. 用具体发现替换 report.md 中的 <!-- RECOMMENDATIONS --> 部分。阅读元素时序表:例如,“subtitle 比 hero-title 晚 200 毫秒开始,并在 400 毫秒后达到完全不透明度,这表明持续时间和延迟都较长。”使用帧间距(1/fps)将帧间隔转换为毫秒。
  2. 如果用户的源代码可用,请找到这些元素的 CSS/JS(transition、animation、@keyframes、transition-delay、framer-motion/GSAP 配置),并指出解释观察到的时序的确切行。提出具体的修复方案。
  3. 提及你的计时精度(±1 帧 = ±1/fps 秒)。如果结论依赖于小于一个帧的间隔,请在声称之前以更高的 fps 重新提取该时间段。

然后在聊天中给用户一个简短总结:哪些内容在动画化、关键时序、每个不同步事件及其时间戳和可能的原因以及修复方案。同时包含 report.md 的路径。

不仅仅是透明度

报告流程主要围绕透明度/可见性构建,但相同的帧读取方法也适用于其他问题,例如布局偏移、元素跳动、闪烁(一帧的错误状态)、不应旋转的加载器或看起来线性的缓动。对于这些问题,仍然提取帧并读取它们。你可以跳过 build_report.mjs,直接使用来自 manifest 的帧引用时间戳给出答案。

相关技能