Analyze

motiscope: analyze

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.

<!-- motiscope:preamble:start -->

Resolve the scripts directory (do this first)

Every command below runs a bundled script. Set SCRIPTS:

SCRIPTS="${CLAUDE_PLUGIN_ROOT:-}/scripts"
# Fallback for harnesses that don't export CLAUDE_PLUGIN_ROOT: this SKILL.md lives at
# <plugin>/skills/analyze/SKILL.md, so scripts are two levels up. Use the absolute
# path of the directory containing the SKILL.md you just Read.
if [ ! -f "$SCRIPTS/ingest.py" ]; then
  SCRIPTS="<absolute dir of this SKILL.md>/../../scripts"
fi
if [ ! -f "$SCRIPTS/ingest.py" ]; then
  echo "ERROR: cannot find ingest.py — check the plugin install." >&2; exit 1
fi

On Windows use python instead of python3 in every command below.

<!-- motiscope:preamble:end -->

Step 0 — preflight (silent on success)

python3 "$SCRIPTS/mvsetup.py" --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 (AskUserQuestion) 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

python3 "$SCRIPTS/ingest.py" "<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.

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.

python3 "$SCRIPTS/ingest.py" "<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:

python3 "$SCRIPTS/ingest.py" "<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.