Communitygithub.com

Claude Eye:影格動畫分析工具

將螢幕錄影或 UI 動畫逐幀分析,找出時間差錯誤(如元素淡入不同步、過渡延遲、閃爍或卡頓)。使用 ffmpeg 擷取影格,再透過 Claude 的視覺能力閱讀每個影格(無需 API 金鑰),最後建立時間戳記時間軸與不同步報告。

Claude Eye:影格動畫分析工具 是什麼?

Claude Eye 是一項專為開發者設計的 AI 工具技能,用於分析 UI 動畫或網頁過渡效果的影格,以找出細微的時間差錯誤。它支援 mp4、mov、webm、gif 等常見影片格式,並可在 Claude Code、Cursor 等平台上使用。工作流程分為三步驟:首先透過 ffmpeg 以指定的 FPS 擷取影格,並產生對應時間戳記的清單;接著,Claude 依序閱讀每個影格,記錄每個動畫元素(如標題、按鈕、圖片)的透明度、狀態(隱藏、過渡中、可見、淡出)以及其他變化(如位移、縮放);最後,工具會自動產出含時間軸表格、元素時間表、不同步事件與觀察報告的 markdown 文件,並搭配 JSON 格式的分析資料。為了節省上下文成本,建議將影格數量控制在 40 幀以內,並可透過粗掃與精掃兩階段策略鎖定問題區間。此工具不僅處理透明度,也適用於版面位移、元件閃爍、載入器異常旋轉等畫面問題,最終由使用者解讀並提出修正建議。

相容平台✓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。如果找不到 ffmpeg,請告知使用者,並根據其作業系統提供安裝指令(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(--fps 1 或 2)粗掃整個影片,找出有變化的區段。然後對該區段使用較高 fps(--start/--end,--fps 10–15)重新擷取,並輸出到另一個 --out 目錄。最後產出細掃報告。
  • 如果使用者提到特定時間點(例如「大約 3 秒處」、「標題出現的時候」),直接針對該區間進行高 fps 擷取。

預設 960 px 寬度足以判斷透明度與位置。只有在元素非常小時才使用較大的 --width。

3. 檢視影格並記錄觀察結果

使用讀取工具依序檢視影格。對每個影格,記錄所有正在動畫或可能動畫的可見文字/UI 元素:標題、副標題、按鈕、圖片、高亮區塊、覆蓋層等。

跨影格保持選擇器名稱一致: 首次看到一個元素時,為它選一個描述性的 kebab-case 名稱(例如 hero-title、subtitle、cta-button),並在後續所有影格中重複使用完全相同名稱。時間軸會根據名稱合併影格,因此 hero-title 在某個影格中出現,而 subtitle 在下個影格中出現,會被視為兩個不同元素,導致分析失敗。一旦元素出現或已知存在,就將其納入並記錄為 0%。這樣可以清楚顯示「隱藏 → 淡入」的過渡點。

對於每個元素,請估算:

  • opacity_percent(0–100)。根據背景以及後續影格中元素的完全可見外觀來判斷。部分揭露(如剪裁路徑或遮罩揭露 40%)也計為 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 中的時間戳記提供影格參考答案。

相關技能