---
name: motiscope-analyze
description: 'Analyze a screen recording of an animation to characterize its motion — timing, easing, transforms, and sequencing — so it can be recreated as web code. Use when the user drops or points at a video of an animation (.mp4/.mov/.webm/.mkv/.m4v/.avi/.gif) and says things like "I want this animation on my site", "recreate this motion", "how is this animated", or runs `motiscope-analyze`.'
---

# motiscope: analyze

> Analyze a screen recording of an animation to characterize its motion — timing, easing, transforms, and sequencing — so it can be recreated as web code. Use when the user drops or points at a video of an animation (.mp4/.mov/.webm/.mkv/.m4v/.avi/.gif) and says things like "I want this animation on my site", "recreate this motion", "how is this animated", or runs `motiscope-analyze`.

**Arguments** (`[path-to-video] [notes]`): take them from the user's message. If they're missing, infer them or ask.

## Running motiscope

`motiscope` is a shell command. If it isn't found it isn't on your PATH — see
https://github.com/KumarSashank/motiscope#install. The reference guides live under
`$(motiscope home)/references/`.

**Invoking the sibling skills.** In Codex, mention a skill with `$motiscope-recreate`. In
Cursor, use `/motiscope-recreate`. Elsewhere, just follow that skill's `SKILL.md`.

**Seeing the frames — do not skip this.** The curated keyframes are PNG files on disk, and
you must actually look at them. Codex: use the `view_image` tool (if it's unavailable,
enable `tools.view_image = true` in `~/.codex/config.toml`, or have the user relaunch with
`codex -i frame1.png,frame2.png`). Cursor: the file-reading tool accepts `.png` and puts
the image in context. If you genuinely cannot open images, **say so** — you can still
report the measured timing, but you cannot know *what* is animating, and you must not
guess it from the filenames.

Turn a screen recording of an animation into a precise, target-agnostic **animation spec** you can hand to ``motiscope-recreate``. A bundled Python pipeline measures the motion (a dense per-frame motion-energy curve + ffmpeg signal analysis — this is the source of truth for timing and easing) and extracts a small set of curated PNG keyframes for you to *see*. You combine the two into the spec.


## Step 0 — preflight (silent on success)

```bash
motiscope doctor --check
```

Exit 0 → proceed silently. Non-zero → `ffmpeg`/`ffprobe` are missing; hand off to ``motiscope-doctor`` (don't try to analyze without them).

## Step 1 — resolve the input video

- If the user gave a path (in `$1` or their message), use it.
- Otherwise scan the drop folder and project root:
  ```bash
  ls -t animations/*.{mp4,mov,webm,mkv,m4v,avi,gif} *.{mp4,mov,webm,mkv,m4v,avi,gif} 2>/dev/null | head
  ```
  - Several candidates → ask the user which one.
  - Exactly one → use it.
  - None → tell the user to drop a recording into `animations/` (or pass a path) and stop.

**Local files only.** motiscope does not download URLs. If the user pastes a URL, ask them to screen-record it and drop the file in.

## Step 2 — run the pipeline

```bash
motiscope analyze "<video>" --preset balanced
```

It writes to `.motiscope/<slug>/` and prints a summary, the `report.md` path, and the ordered curated frame list.

### Choose a preset (this is the main token dial)

The number of frames you Read is what costs tokens (~300–400 tokens/frame); the numeric analysis is free. Frame count tracks *motion complexity*, capped by the preset — it does **not** grow with video length.

| Preset | Frame cap | Resolution | Use when |
|---|---|---|---|
| `--preset draft` | 12 | 512px | quick look, tight token budget |
| `--preset balanced` *(default)* | 32 (usually lands 8–20 after dedup) | 640px | most cases |
| `--preset detailed` | 48 | 960px | dense multi-beat sequences, or reading on-screen text |
| `--preset landing` | 44 | 1280px | **web/landing walkthroughs** — cover each section's design at readable resolution + its in-section motion |

Start with `balanced`. Only reach for `detailed` if the animation is intricate or you couldn't read a label; use `draft` for a fast first pass. If the user hasn't said, pick `balanced` and mention they can ask for more detail.

### Focus a section of a longer video (`--start` / `--end`)

For anything longer than ~15s, or when the user points at a specific moment ("the part around 0:12", "the last second"), analyze just that window instead of a sparse whole-clip scan. Times accept `SS`, `MM:SS`, or `HH:MM:SS`; frame/segment timestamps come back in **absolute** source time.

```bash
motiscope analyze "<video>" --preset detailed --start 0:12 --end 0:15
```

### Capture fast content densely (`--fps`)

Within a (short) focus window you can force a uniform sample rate so nothing between keyposes is missed — e.g. `--fps 20` gives up to a frame every ~50ms. Near-identical frames are still collapsed unless you pass `--no-dedup`. Combine with a short window so the budget isn't blown:

```bash
motiscope analyze "<video>" --start 1.0 --end 3.0 --fps 20 --frame-budget 48
```

### Complex / long animations: auto-decompose

For clips ≥8s with two or more motion beats, `ingest.py` **auto-decomposes** by default: it finds the beats, then concentrates frames on each *motion* segment (drilling densely) and gives each *hold* just one representative frame — so the budget is spent on motion, not dead air. A 10s clip with a 5s hold in the middle spends ~0 frames on the hold. The report notes when this happened.

Control it with `--decompose` (force on) / `--no-decompose` (force the flat single-pass). Auto is the right default; force it off only if you specifically want even coverage across the whole timeline.

Other flags: `--frame-budget N` / `--resolution W` override the preset; `--format jpg` for gradient-heavy recordings that bloat as PNG; `--no-dedup` to keep every sampled frame; `--out DIR` (default `.motiscope/`).

> **Small elements register now.** The primary motion signal is *localized* (built from the most-active regions of the frame), so a small button/card/icon moving on a large page reads as real motion instead of washing out. The stagger direction in the report tells you the sequencing (e.g. `left-to-right, ~200ms each`) — use it when building the spec's `stagger`.

## Step 3 — read the analysis, then the frames

**The division of labor is the whole point:**
- **The numbers give you the WHEN.** `report.md` measured the *timing* you can't see in a still: exact durations, the per-segment **easing curve** (a real cubic-bezier fitted from the velocity profile), the beat/segment boundaries, the stagger *timing* (~ms between items), and any loop period. Trust these — a screenshot has no time axis, so this is the one thing that isn't guessable.
- **You give the WHAT.** The frames are yours to read with full vision. Identify the elements and — crucially — **what *kind* of animation each one is.** motiscope does **not** classify animation types, and you are **not** limited to fade/slide/scale: name whatever you actually see — a mask reveal, a path/line draw, a morph, a rotate/skew, a 3D flip, a text split/typewriter, a blur, a color shift, a parallax, a physics/spring bounce, particles, a clip-path wipe, anything. The pipeline deliberately leaves this to your perception because you're better at it than any hand-coded classifier.

Steps:
1. Read the printed `report.md` for the measured timing (energy sparkline, segment/beat table with the fitted `cubic-bezier`, stagger timing, loop).
2. Read **every curated frame in one message** (parallel Reads) so you see them in order. Filenames encode `t=<seconds>` + why each was picked, so you can line frames up against the measured timeline.

**Read timing from the numbers; read everything else from the frames.**

### The frames are evidence, not an inventory

Frames are chosen by the **motion-energy signal**. Anything small, low-contrast, briefly
visible, or mostly occluded barely moves that signal and **may not appear in a single curated
frame** — while still being a headline feature of the animation. A train crossing a bridge was
missed exactly this way.

Before you commit to a spec:

- Ask **"is anything else moving?"** and go check the clip, not just the frames. Diff a region
  across the whole video, or sample uniformly at a rate the curation skipped.
- If the user names something you cannot see, **believe them and go look**. Its absence from
  the frames is not evidence of its absence from the animation.

### Before you trust a number

A failed automated measurement does not crash. It returns a **confident float**.

- **Two estimators, or you have none.** Measure the same quantity a second, independent way
  (different scale, different feature, different algorithm). Agreement is a result; a
  disagreement of 6× means at least one is lying, and you cannot tell which by looking.
- **Say "not recoverable"** when methods disagree. Averaging `-0.03 .. 0.63` into `0.30`
  invents a fact. Reporting the range *is* the finding.
- **Occluded features report clamped constants.** A value that is pinned at a frame edge, or
  that stays put while everything around it moves, is not a measurement.
- **Scroll-driven ≠ time-driven.** For a parallax, scroll-zoom or pinned section, the seconds
  in the recording are *the recorder's*. Only **ratios** (layer speed ÷ scroll speed) are
  intrinsic. One clip can contain both kinds of clock.

The full list, with the real failures behind each one, is in
`references/measurement-traps.md`. Read it before reporting any velocity, easing or ratio you
derived yourself rather than reading out of `report.md`.

## Step 4 — produce the animation spec

Emit a target-agnostic spec: a **timing skeleton (measured) + your visual reading (what each element is and does)**. Schema:

```json
{
  "duration_ms": 2000,
  "canvas": { "w": 800, "h": 600, "bg": "#ffffff" },
  "loop": false,
  "scroll_driven": false,
  "elements": [{ "id": "card", "role": "card" }],
  "timeline": [
    { "target": "card", "start_ms": 0, "dur_ms": 400,
      "ease": "ease-out", "bezier": [0.16, 1, 0.3, 1],
      "animation": "fade + slide up",
      "props": { "opacity": [0, 1], "y": [24, 0] },
      "source": { "timing": "measured", "everything_else": "seen" } }
  ],
  "stagger": { "children": "card", "each_ms": 80 },
  "notes": "e.g. 'headline does a per-word mask reveal'; 'logo path draws in'"
}
```

Rules:
- **`start_ms`, `dur_ms`, `ease`, `bezier`, stagger `each_ms`, loop `period_ms` are MEASURED** — copy them from `report.md`/`motion.json` verbatim. Especially: use the fitted **`cubic-bezier`** directly (CSS `cubic-bezier(...)`, Framer `[..]`, GSAP `CustomEase`) — it's the real curve, not a guess.
- **`animation`, `elements`, `props` (magnitudes/direction/colors), and the animation *type* are YOURS from the frames** — describe the actual effect in the free-text `animation` field (open vocabulary), and put your best-estimate property values in `props`. Direction, scale, rotation, opacity, morph, draw, etc. all come from what you see, not from the numbers.
- Be honest about a leading `hold`: a gentle ease-in's slow start can read as a short hold (sub-pixel motion is invisible in the analysis thumbnails). Check the first frames — if the element already moved slightly, treat it as the start of the ease, not a delay.
- **Loops:** if the report flags a loop, set `"loop": true` with `period_ms`. It can be a *half*-cycle for back-and-forth motion — decide loop-vs-yoyo from the frames.
- If an effect can't be reduced to `props` (a complex morph, a particle system, a shader), say so in `animation`/`notes` and let `recreate` build it directly from your description — don't force it into simple props.
- **Scroll-driven captures:** set `"scroll_driven": true` and do **not** copy `duration_ms` into the spec as if it were the design's. Report **ratios** (layer speed ÷ page-scroll speed) and note which quantities belong to the recorder. A clip can be scroll-driven *and* contain a time-driven object (a train, a spinner, a looping badge) — measure that object's speed separately.
- **Label every number you derived yourself** (a velocity, a ratio, a period) as measured, estimated, or **not recoverable**. Never let a chosen value read as a measured one.

## Step 5 — offer to recreate

Summarize the animation in one or two sentences, then offer:

> Recreate this as **GSAP**, **CSS**, **Framer Motion**, or **Lottie/SVG**? Run ``motiscope-recreate` <target>`.

The spec you just built is saved in `.motiscope/<slug>/manifest.json`; `recreate` will reload it (plus `motion.json`) if you don't hand it over directly.

## Notes

- **Token cost** lives entirely in the frames (~24–48 PNGs). The motion curve is numbers — effectively free. If you already analyzed this clip in the session, don't re-run; reason from what you have.
- Best results come from high-fps, lightly-compressed captures. Warn the user if a recording is heavily compressed or very low frame rate.