/motiscope-analyze

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)

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:

  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

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.

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:

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 no