mblode/reverse-engineer-animation

Reverse Engineer Animation

Measure motion that already exists in a recording, then reproduce it. This is the forensic counterpart to the ui-animation skill (which prescribes how motion should be designed).

Reference files

| File | Read when | |------|-----------| | references/measurement-guide.md | Deciding what to measure, eye vs script, reading metrics.json, choosing an ROI | | references/curve-fitting.md | Reading fit_curves.py output, spring vs bezier, judging fit error, asymmetric open/close | | references/code-output.md | Emitting code for CSS, Motion/Framer Motion, SwiftUI, React Native, or UIKit | | references/choreography.md | Multi-element / multi-phase motion: staggers, blur-before-move, per-edge settling |

Dependencies

• ffmpeg — frame extraction (brew install ffmpeg). Required for step 1.
• Python: pip install opencv-python numpy scipy — tracking + curve fitting (steps 4).

Extraction degrades gracefully: with only ffmpeg you can still extract frames and reason visually. Tracking and fitting need the Python packages.

Workflow

Copy and track this checklist:

Reverse-engineer progress:
- [ ] Step 1: Extract frames + contact sheet
- [ ] Step 2: Vision pass — identify element, effects, phases
- [ ] Step 3: Decide precision (eye-only vs scripted)
- [ ] Step 4: Track motion and fit curves (if escalating)
- [ ] Step 5: Annotate choreography (delays, asymmetry)
- [ ] Step 6: Emit code for the target(s)
- [ ] Step 7: Validate against the recording

Step 1: Extract frames

Run python3 scripts/extract_frames.py <video> <outdir> (add --fps N for very slow clips). On a multi-second recording, trim to just the transition with --start SECONDS --duration SECONDS — extracting the whole clip floods the contact sheet and dilutes tracking. Open the generated contact_sheet.png first — it shows the whole window at once.

Step 2: Vision pass

View the contact sheet and name, in order:

• The element(s) that move.
• Every effect present — translate, scale (often anisotropic), opacity, blur, corner radius, shadow, color. Use the property checklist in references/measurement-guide.md.
• The phases — e.g. backdrop blurs in, element tucks under the notch, over-stretches, then settles per-edge. Note which property leads and which lags.

Step 3: Decide precision

• Simple fade or linear slide → read timing off the contact sheet and skip to step 5.
• Elastic, springy, or multi-property motion → escalate to step 4. Eyeballing a spring is unreliable.

Step 4: Track and fit

Run python3 scripts/track_motion.py <outdir> → metrics.json. Pass --bbox X,Y,W,H to isolate one element when several move (one bbox per element). Then run python3 scripts/fit_curves.py <outdir>/metrics.json → spring params, cubic-bezier, and a fit error per property. Read references/curve-fitting.md to interpret the numbers and pick the model. High error on both models means multi-phase motion — split the timeline and fit each segment.

Step 5: Annotate choreography

Load references/choreography.md. Build the timing-offset table (when each property starts and settles) — those lead/lag gaps and the over-stretch carry more of the feel than any single curve.

Step 6: Emit code

Substitute the fitted parameters into the templates in references/code-output.md for the requested target. Keep movement on transform/opacity. Emit two transitions when open and close differ. Produce the consolidated handoff motion spec (timing table + curves + snippet) from references/code-output.md so the result can be implemented without the video.

Step 7: Validate

See Validation below.

Asymmetric open/close

Open and close are almost never mirror images — open tends to be slower and springier, close faster and flatter. Measure each direction separately (record or trim two clips and run the pipeline on each). Report two curves; never reuse the open curve reversed.

Anti-patterns

• Fitting one global curve to multi-phase motion — split into phases and compose keyframes.
• Tracking only position and ignoring blur/opacity — those usually lead the move and are where the polish lives.
• Assuming symmetric open/close — measure both directions.
• Reporting spring params without checking the fit error — a bad fit gives confident-looking but wrong numbers.
• Emitting code that animates layout props (width, height, top, left) — reproduce the motion on transform/opacity (defer to ui-animation rules).
• Re-reading a script to reconstruct its logic instead of running it — the scripts are the canonical, deterministic path.

Validation

• Re-derive: play the emitted animation, screen-record it, run it back through extract_frames.py, and compare contact sheets side-by-side with the original.
• Slow to 0.1x in DevTools to confirm phase order (lead/lag) and the over-stretch survive.
• Confirm the emitted code only animates transform, opacity, and filter.
• Sanity-check fitted spring overshoot/zeta against what you saw — a clear bounce must not fit as a flat ease.

Related skills

• ui-animation — turn the extracted spec into production-grade, interruptible motion and apply its easing defaults and anti-pattern rules.