motiscope

A motion-design tool for coding agents. Pure Python (standard library) + ffmpeg. No cloud, no npm, no accounts required. Ships as a Claude Code plugin, and as portable agent skills for Codex, Cursor, and anything that reads AGENTS.md.

"I want this animation on my site." — drop the clip, run /motiscope:analyze, then /motiscope:recreate gsap.

Demo — original → recreated

motiscope measured the motion of the tomato — a 4.45s clock, the wake-and-wave beats, and the easing curve of each. The banana is an original character built on that measured motion: an 11 KB animated SVG. The timing transfers; the artwork doesn't have to.

Original animation from SVGator's website-animation examples — all credit to the original creator. → full example · gallery

Ambient geometric loop — fifteen tiles, one beat

Fifteen tiles spin, scroll and ripple. motiscope measured a 0.75s master beat — burst peaks at 0.317 / 1.067 / 1.817s, agreeing to ±0.02s across three independent tiles — and an easing whose peak angular speed is 3.6× the mean, far sharper than a stock ease-in-out. The result is 14 KB of animated SVG with no JavaScript. Only the palette changed.

The whole-frame summary said linear. Per tile it isn't — the velocity drops to near zero and ramps again. That's the point: the report gives you the timing, you read the frames.

→ Live recreation · raw analysis + build script · original on SVGator

How it works

motiscope does the one thing a vision model can't do from a screenshot — measure time — and hands everything else to the model:

1. The numbers measure the WHEN. A dense per-frame motion-energy curve (native fps, effectively free) plus ffmpeg signal analysis (scdet, freezedetect, blackdetect, siti, signalstats) give the exact timing: durations, the per-segment easing curve (a real cubic-bezier fitted from the velocity profile), beat/segment boundaries, stagger timing, and loop period. A still has no time axis — so this is the part that can't be guessed. It's the moat.
2. The frames carry the WHAT. motiscope curates the keyframes that matter (chosen by the motion signal) and hands them to the model. Claude reads them with full vision to identify the elements and what kind of animation each is — fade, slide, scale, mask reveal, path draw, morph, 3D flip, text effect, whatever it sees. motiscope deliberately does not classify animation types — the model is better at that than any hand-coded taxonomy, so there's no fixed list to box you in.

So: measured timing + curated frames → the model recreates it. motiscope is a precise stopwatch and a smart frame-picker; the intelligence is Claude's.

Want the real mechanism? How it works walks through the motion-energy curve, why the hold threshold is anchored to the 75th percentile instead of the peak, and how easing is recovered by integrating speed — with figures drawn from real pipeline output, and ground-truth clips you can run yourself. Exact constants: docs/how-it-works.md.

The motions it reads & rebuilds

Staggered entrances, easing curves, holds, fades, loops — read off the energy curve and rebuilt as code. (These figures are animated SVGs — the same kind of motion motiscope recreates.)

Install

Claude Code — install the plugin; it bundles everything:

/plugin marketplace add github:KumarSashank/motiscope
/plugin install motiscope@motiscope

Codex, Cursor, or any other agent — install the CLI, then teach your agent:

git clone https://github.com/KumarSashank/motiscope.git ~/.motiscope
~/.motiscope/install.sh      # one symlink into ~/.local/bin, no sudo

motiscope install codex      # -> ~/.agents/skills/
motiscope install cursor     # -> ./.cursor/skills/ + rules
motiscope install agents     # -> a marked block in ./AGENTS.md
motiscope install list       # every target

Requires ffmpeg + ffprobe (and python3). Run motiscope doctor — or /motiscope:doctor in Claude Code — to check and, with your consent, install them. New here? See QUICKSTART.md. Full matrix and version caveats: PLATFORMS.md.

Usage

/motiscope:doctor                      # verify deps, scaffold config (first run)
/motiscope:analyze animations/hero.mp4 # analyze a recording -> animation spec
/motiscope:recreate gsap               # emit GSAP code (or css | framer | lottie)

Or just drop a recording into an animations/ folder in your project and run /motiscope:analyze — it will find it.

Local files only. Supported: .mp4 .mov .webm .mkv .m4v .avi .gif. To capture a web animation, screen-record it and save the file.

Commands

Outside Claude Code the same four workflows are skills named motiscope-analyze, motiscope-recreate, motiscope-rebuild-site, motiscope-doctor (Codex mentions them with $name, Cursor with /name), and the measurement runs as motiscope analyze ....

In Claude Code, GSAP output leans on the official GSAP skills (timeline / core / scrolltrigger / react / utils) for idiomatic results; elsewhere the workflow carries the equivalent guidance inline.

Controlling frames & token cost

Only the curated frames the model sees cost tokens (~300–400 each); the numeric analysis is free. Frame count tracks motion complexity, capped by a preset — it does not grow with video length (a 10s clip typically yields ~10 frames).

• Focus a section of a longer video: --start 0:12 --end 0:15 (timestamps come back in absolute source time).
• Sample fast content densely: --fps 20 lays a uniform backbone (a frame every ~50ms) across the window; near-identical frames still collapse unless --no-dedup.
• Auto-decompose (default for clips ≥8s with ≥2 motion beats): finds the beats, drills each motion segment densely, and skips holds — the budget follows the motion. Frames are allocated per beat by motion magnitude (a fast/intense beat gets more frames than a slow one). Force with --decompose / disable with --no-decompose.
• Loop detection: looping animations are detected (energy-curve autocorrelation) and reported with a period, so recreation can set repeat / yoyo.

Small elements register correctly: the primary motion signal is localized (built from the most-active regions), so a small button/card/icon moving on a large page is detected as real motion rather than washing out in a whole-frame average.

Output layout

Per-video working files land in a gitigno