Skip to content
Back to search

motiscope

Recreate any web animation from a screen recording. A motion-design plugin: analyzes motion (timing, easing, stagger, loops) and rebuilds it as GSAP / CSS / Framer Motion / Lottie code.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/kumarsashank--motiscope/badge.svg)](/listings/kumarsashank--motiscope)

HTML

<a href="/listings/kumarsashank--motiscope"><img src="/api/listings/kumarsashank--motiscope/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

**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](QUICKSTART.md)**. Full matrix and version caveats: **[PLATFORMS.md](PLATFORMS.md)**.

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

.claude-plugin/marketplace.json · Manifest · 23 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. {
  2. "name": "motiscope",
  3. "description": "A motion-design plugin — turn a screen recording of an animation into working web animation code (GSAP / CSS / Framer Motion / Lottie).",
  4. "owner": {
  5. "name": "Kumar Sashank Ghanta",
  6. "email": "kumar@eonverse.in"
  7. },
  8. "plugins": [
  9. {
  10. "name": "motiscope",
  11. "description": "Analyze a screen recording of an animation and recreate it as GSAP / CSS / Framer Motion / Lottie code.",
  12. "author": {
  13. "name": "Kumar Sashank Ghanta"
  14. },
  15. "source": "./",
  16. "category": "productivity",
  17. "tags": ["animation", "motion-design", "gsap", "css", "framer-motion", "lottie", "ffmpeg"],
  18. "keywords": ["animation", "motion-design", "gsap", "css", "framer-motion", "lottie"],
  19. "license": "MIT",
  20. "homepage": "https://github.com/KumarSashank/motiscope"
  21. }
  22. ]
  23. }
README.md · README · 259 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. <p align="center">
  2. <img src="docs/hero.svg" alt="motiscope — motion-energy oscilloscope" width="100%">
  3. </p>
  4. <h1 align="center">motiscope</h1>
  5. <p align="center">
  6. <b>See the motion, recreate the animation.</b><br>
  7. Drop a screen recording of an animation — get working <b>GSAP / CSS / Framer Motion / Lottie</b> code.
  8. </p>
  9. <p align="center">
  10. <img alt="license MIT" src="https://img.shields.io/badge/license-MIT-6366f1">
  11. <img alt="version 1.0.0" src="https://img.shields.io/badge/version-1.0.0-818cf8">
  12. <img alt="works with Claude Code, Codex, Cursor" src="https://img.shields.io/badge/works%20with-Claude%20Code%20%C2%B7%20Codex%20%C2%B7%20Cursor-a78bfa">
  13. <img alt="deps ffmpeg" src="https://img.shields.io/badge/deps-ffmpeg-e879f9">
  14. <img alt="recreate targets" src="https://img.shields.io/badge/recreate-GSAP%20%C2%B7%20CSS%20%C2%B7%20Framer%20%C2%B7%20Lottie-22d3ee">
  15. </p>
  16. <p align="center">
  17. <a href="https://kumarsashank.github.io/motiscope/"><b>🔗 Live site</b></a> ·
  18. <a href="QUICKSTART.md">Quickstart</a> ·
  19. <a href="#install">Install</a> ·
  20. <a href="PLATFORMS.md">Platforms</a> ·
  21. <a href="#how-it-works">How it works</a>
  22. </p>
  23. ---
  24. A motion-design tool for coding agents. Pure Python (standard library) + `ffmpeg`.
  25. No cloud, no npm, no accounts required. Ships as a **Claude Code plugin**, and as
  26. **portable agent skills** for Codex, Cursor, and anything that reads `AGENTS.md`.
  27. > "I want this animation on my site." — drop the clip, run `/motiscope:analyze`,
  28. > then `/motiscope:recreate gsap`.
  29. ## Demo — original → recreated
  30. <p align="center">
  31. <img src="docs/examples/banana/compare.gif" width="100%" alt="Left: the original tomato animation. Right: the banana recreated with motiscope — both playing the same beats in sync.">
  32. </p>
  33. <p align="center"><sub><b>Left:</b> the original. &nbsp;<b>Right:</b> recreated with motiscope. &nbsp;<i>(one clip, so the beats stay in sync)</i></sub></p>
  34. motiscope measured the **motion** of the tomato — a 4.45s clock, the wake-and-wave beats,
  35. and the easing curve of each. The **banana is an original character** built on that
  36. measured motion: an 11 KB animated SVG. *The timing transfers; the artwork doesn't have to.*
  37. Original animation from [SVGator's website-animation examples](https://www.svgator.com/blog/website-animation-examples-and-effects/)
  38. — all credit to the original creator. → [full example](docs/examples/banana/) ·
  39. [gallery](https://kumarsashank.github.io/motiscope/gallery.html)
  40. ### Ambient geometric loop — fifteen tiles, one beat
  41. <p align="center">
  42. <img src="docs/examples/ambient/compare.gif" width="100%" alt="Left: the original ambient geometric loop. Right: the recreation — same tiles, same beat, new palette.">
  43. </p>
  44. <p align="center"><sub><b>Left:</b> the original. &nbsp;<b>Right:</b> recreated with motiscope.</sub></p>
  45. Fifteen tiles spin, scroll and ripple. motiscope measured a **0.75s master beat** — burst
  46. peaks at 0.317 / 1.067 / 1.817s, agreeing to ±0.02s across three independent tiles — and an
  47. easing whose peak angular speed is **3.6× the mean**, far sharper than a stock ease-in-out.
  48. The result is **14 KB** of animated SVG with no JavaScript. Only the palette changed.
  49. The whole-frame summary said `linear`. Per tile it isn't — the velocity drops to near zero
  50. and ramps again. *That's the point: the report gives you the timing, you read the frames.*
  51. → **[Live recreation](https://kumarsashank.github.io/motiscope/examples/ambient/)** ·
  52. [raw analysis + build script](docs/examples/ambient/) ·
  53. [original on SVGator](https://www.svgator.com/blog/website-animation-examples-and-effects/)
  54. ## How it works
  55. <p align="center"><img src="docs/pipeline.svg" alt="pipeline: video → frames → energy → spec → code" width="100%"></p>
  56. motiscope does the one thing a vision model **can't** do from a screenshot — measure
  57. *time* — and hands everything else to the model:
  58. 1. **The numbers measure the WHEN.** A dense per-frame *motion-energy curve* (native
  59. fps, effectively free) plus ffmpeg signal analysis (`scdet`, `freezedetect`,
  60. `blackdetect`, `siti`, `signalstats`) give the exact **timing**: durations, the
  61. per-segment **easing curve** (a real `cubic-bezier` fitted from the velocity
  62. profile), beat/segment boundaries, stagger timing, and loop period. A still has no
  63. time axis — so this is the part that can't be guessed. It's the moat.
  64. 2. **The frames carry the WHAT.** motiscope curates the keyframes that matter (chosen
  65. by the motion signal) and hands them to the model. Claude reads them with full
  66. vision to identify the elements and *what kind of animation* each is — fade, slide,
  67. scale, mask reveal, path draw, morph, 3D flip, text effect, whatever it sees.
  68. **motiscope deliberately does not classify animation types** — the model is better
  69. at that than any hand-coded taxonomy, so there's no fixed list to box you in.
  70. So: **measured timing + curated frames → the model recreates it.** motiscope is a
  71. precise stopwatch and a smart frame-picker; the intelligence is Claude's.
  72. **Want the real mechanism?** [**How it works**](https://kumarsashank.github.io/motiscope/how-it-works.html)
  73. walks through the motion-energy curve, why the hold threshold is anchored to the 75th
  74. percentile instead of the peak, and how easing is recovered by integrating speed — with
  75. figures drawn from real pipeline output, and ground-truth clips you can run yourself.
  76. Exact constants: [`docs/how-it-works.md`](docs/how-it-works.md).
  77. ## The motions it reads & rebuilds
  78. <p align="center"><img src="docs/demo.svg" alt="staggered entrance and easing channels" width="100%"></p>
  79. Staggered entrances, easing curves, holds, fades, loops — read off the energy curve
  80. and rebuilt as code. *(These figures are animated SVGs — the same kind of motion
  81. motiscope recreates.)*
  82. ## Install
  83. **Claude Code** — install the plugin; it bundles everything:
  84. ```
  85. /plugin marketplace add github:KumarSashank/motiscope
  86. /plugin install motiscope@motiscope
  87. ```
  88. **Codex, Cursor, or any other agent** — install the CLI, then teach your agent:
  89. ```sh
  90. git clone https://github.com/KumarSashank/motiscope.git ~/.motiscope
  91. ~/.motiscope/install.sh # one symlink into ~/.local/bin, no sudo
  92. motiscope install codex # -> ~/.agents/skills/
  93. motiscope install cursor # -> ./.cursor/skills/ + rules
  94. motiscope install agents # -> a marked block in ./AGENTS.md
  95. motiscope install list # every target
  96. ```
  97. Requires `ffmpeg` + `ffprobe` (and `python3`). Run `motiscope doctor` — or
  98. `/motiscope:doctor` in Claude Code — to check and, with your consent, install them.
  99. New here? See **[QUICKSTART.md](QUICKSTART.md)**. Full matrix and version caveats:
  100. **[PLATFORMS.md](PLATFORMS.md)**.
  101. ## Usage
  102. ```
  103. /motiscope:doctor # verify deps, scaffold config (first run)
  104. /motiscope:analyze animations/hero.mp4 # analyze a recording -> animation spec
  105. /motiscope:recreate gsap # emit GSAP code (or css | framer | lottie)
  106. ```
  107. Or just drop a recording into an `animations/` folder in your project and run
  108. `/motiscope:analyze` — it will find it.
  109. **Local files only.** Supported: `.mp4 .mov .webm .mkv .m4v .avi .gif`. To capture a
  110. web animation, screen-record it and save the file.
  111. ## Commands
  112. | Command | What it does |
  113. |---|---|
  114. | `/motiscope:analyze [path] [notes]` | Extract the motion analysis + curated frames, then characterize the animation as a spec. |
  115. | `/motiscope:recreate [gsap\|css\|framer\|lottie] [out-dir]` | Turn the spec into runnable code for a target framework. |
  116. | `/motiscope:rebuild-site [path] [gsap\|css\|framer]` | Rebuild a **whole landing page** from a walkthrough recording — sections, copy, design system, scroll animations, and generated assets. |
  117. | `/motiscope:doctor` | Verify `ffmpeg`/`ffprobe`; scaffold `~/.config/motiscope/{config.json,.env}`. |
  118. Outside Claude Code the same four workflows are skills named `motiscope-analyze`,
  119. `motiscope-recreate`, `motiscope-rebuild-site`, `motiscope-doctor` (Codex mentions them
  120. with `$name`, Cursor with `/name`), and the measurement runs as `motiscope analyze ...`.
  121. In Claude Code, GSAP output leans on the official GSAP skills (timeline / core /
  122. scrolltrigger / react / utils) for idiomatic results; elsewhere the workflow carries the
  123. equivalent guidance inline.
  124. ## Controlling frames & token cost
  125. Only the curated frames the model *sees* cost tokens (~300–400 each); the numeric
  126. analysis is free. Frame count tracks **motion complexity**, capped by a preset — it
  127. does **not** grow with video length (a 10s clip typically yields ~10 frames).
  128. | Preset | Frame cap | Resolution | Use when |
  129. |---|---|---|---|
  130. | `draft` | 12 | 512px | quick look, tight budget |
  131. | `balanced` *(default)* | 32 (usually 8–20 after dedup) | 640px | most cases |
  132. | `detailed` | 48 | 960px | dense sequences / reading text |
  133. | `landing` | 44 | 1280px | web/landing walkthroughs — cover each section + its motion |
  134. - **Focus a section** of a longer video: `--start 0:12 --end 0:15` (timestamps come
  135. back in absolute source time).
  136. - **Sample fast content densely**: `--fps 20` lays a uniform backbone (a frame every
  137. ~50ms) across the window; near-identical frames still collapse unless `--no-dedup`.
  138. - **Auto-decompose** (default for clips ≥8s with ≥2 motion beats): finds the beats,
  139. drills each motion segment densely, and skips holds — the budget follows the motion.
  140. Frames are allocated **per beat by motion magnitude** (a fast/intense beat gets more
  141. frames than a slow one). Force with `--decompose` / disable with `--no-decompose`.
  142. - **Loop detection**: looping animations are detected (energy-curve autocorrelation)
  143. and reported with a period, so recreation can set `repeat` / `yoyo`.
  144. Small elements register correctly: the primary motion signal is *localized* (built
  145. from the most-active regions), so a small button/card/icon moving on a large page is
  146. detected as real motion rather than washing out in a whole-frame average.
  147. ## Output layout
  148. Per-video working files land in a gitignored `.motiscope/<slug>/`:
  149. ```
  150. .motiscope/<slug>/
  151. manifest.json # video meta + timeline + frame index (machine artifact)
  152. motion.json # raw motion timeline: energy curve, grid, segments, beats, signals
  153. report.md # human-readable summary (energy sparkline, segment table)
  154. frames/ # curated PNGs, e.g. frame_003_t0.42s_keypose.png
  155. ```
  156. Recreated code is written to `motiscope-output/<target>/` by default.
  157. ## Asset generation (optional)
  158. If a recreation needs an image, `recreate` will ask whether to point at your own file,
  159. generate one, or use a placeholder. **Image generation is real via the `gemini` /
  160. `imagen` provider** (Imagen through the Gemini API) — set `GEMINI_API_KEY` in
  161. `~/.config/motiscope/.env` (mode `0600`; keys are never printed, written into generated
  162. code, or committed). Other providers (video, and other image backends) still write a
  163. labeled placeholder until wired.
  164. ```
  165. python3 scripts/assetgen.py generate --type image --provider gemini \
  166. --prompt "cinematic hands holding a phone, dark teal grade" --out hero.png --aspect-ratio 16:9
  167. ```
  168. Provider slots: image — **gemini/imagen (implemented)**, OpenAI, Stability, Replicate,
  169. fal; video — Runway, Replicate, fal.
  170. ## Limitations (measured vs. estimated)
  171. - **Measured (reliable):** duration, fps, segment boundaries, easing *shape*,
  172. hold/fade detection, stagger *direction*, loop period.
  173. - **Estimated (from frames):** which elements move, transform magnitudes (px / scale
  174. / rotation / opacity), colors under compression, exact overshoot, spring stiffness.
  175. - **Not recoverable from frames:** exact cubic-bezier control points (only the class),
  176. sub-pixel / sub-frame motion, true 3D / z-order, authored Lottie vector data. For
  177. production Lottie, author in After Effects.
  178. - A very gentle **ease-in**'s opening can read as a short hold because sub-pixel
  179. motion is invisible in the analysis thumbnails — the dominant easing is still
  180. recovered; check the first frames.
  181. **For best results:** capture at a high frame rate and avoid heavy compression.
  182. ## Development
  183. See [CONTRIBUTING.md](CONTRIBUTING.md). Run the test suite:
  184. ```
  185. python3 -m unittest tests.test_analyze_motion tests.test_integrations \
  186. tests.test_docs_constants tests.test_site_meta
  187. ```
  188. `skills/*/SKILL.md` is the single source of truth for the workflows; everything under
  189. `integrations/` is generated from it by `scripts/build_integrations.py`, and CI fails if
  190. the two drift apart. See [PLATFORMS.md](PLATFORMS.md#adding-a-platform).
  191. ## Credits & license
  192. MIT. See [LICENSE](LICENSE). motiscope adapts frame-analysis techniques from two MIT
  193. projects — [claude-video](https://github.com/bradautomates/claude-video) and
  194. [claude-video-vision](https://github.com/jordanrendric/claude-video-vision) — with
  195. gratitude; see [ATTRIBUTION.md](ATTRIBUTION.md).

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.