animation-review

这段内容是审核时保存的快照。外部来源才是完整且最新的版本。

---
name: animation-review
description: Review web animations by recording the browser and sending video to Gemini for frame-level analysis
---

# Animation Review

Review animations and interactions by recording the browser and sending the video to Gemini for structured analysis.

## Prerequisites

- `ffmpeg` installed (`brew install ffmpeg`)
- `playwright` Python package with Chromium (`pip install playwright && playwright install chromium`)
- `google-genai` Python package (`pip install google-genai`)
- `GEMINI_API_KEY` environment variable set
- For manual recording only: macOS Screen Recording permission granted to terminal app

## How Gemini fits in

Gemini is the **eyes** — it watches the recording and describes what it sees with precision. You are the **hands** — you translate those observations into code changes with full codebase context.

**Treat all Gemini analysis as observational evidence, not authoritative diagnosis.** Gemini cannot see the code. When it suggests root causes or implementation fixes, treat these as hypotheses from an external observer who can see the symptoms but not the source. Its frame-level descriptions of *what happens visually* are reliable. Its theories about *why* are informed guesses that you should verify against the actual code.

This applies across all modes, but especially to `diagnose` (where Gemini hypothesizes about bugs) and `inspire` (where Gemini decomposes effects without knowing your tech stack).

### Interpreting timestamps and durations

Gemini can only observe what's in the sampled frames. Its temporal precision depends on the analysis FPS:

| Mode | FPS | Frame interval | What this means |
|------|-----|---------------|-----------------|
| **check** | 5 | 200ms | A "300ms animation" could be anywhere from 200-400ms (1-2 frames). Timestamps are ±200ms. Good enough for "does it happen" but not for timing accuracy. |
| **review** | 12 | 83ms | A "300ms animation" is ~3-4 frames. Easing character is visible. Durations are accurate within ~80ms — enough to judge "too fast" vs "too slow". |
| **diagnose/inspire** | 24 | 42ms | A "300ms animation" is ~7 frames. Easing curves, stagger offsets, and glitch moments are precisely observable. Durations are accurate within ~40ms. |

When Gemini reports a duration like "~400ms with ease-out", consider the mode's precision. At 5fps that could really be 200-600ms. At 24fps it's likely 360-440ms. The system prompt tells Gemini to report in frame counts alongside milliseconds so you can judge precision yourself.

If you're debugging a timing issue and Gemini's temporal precision isn't sufficient, re-run at a higher mode. A `check` that reveals "something's off with the timing" can be followed up with a `diagnose` for frame-precise detail. You can also escalate just a specific time range — see "Escalating a region" below.

## Workflow

### 1. Determine source and mode

There are two entry points — figure out which applies:

**User provides a video file.** The user has a screen recording (.mov, .mp4, .webm) — either of their own UI or a reference they want to recreate. Skip straight to step 3 (Analyze). No recording step needed. User-provided videos are typically 30-60fps, which is more than enough for any analysis mode — Gemini downsamples to the mode's FPS automatically.

**Agent captures from the browser.** The animation is running in a local dev server and needs to be recorded. Proceed to step 2 (Record), then step 3 (Analyze).

Choose the analysis mode based on what question you're trying to answer:

| Mode | FPS | Model | Question | When to use |
|------|-----|-------|----------|-------------|
| **check** | 5 | Flash | "Does it work?" | First pass — verify the animation fires, completes, and doesn't visually break. Early development, after wiring up a new animation, smoke testing. |
| **review** | 12 | Flash | "How does it feel?" | Design and polish — evaluate easing, timing, choreography, and overall quality. Use when the animation work