Analyze Video

Analyze a video file with Gemini and return a structured markdown report.

Python 3.10+
google-genai installed globally (any Python the shell finds via python3 works — verified working at version 1.64.0)
GEMINI_API_KEY set in the user's shell environment (e.g. exported in ~/.zshrc)

video path (required) — path to the video file
--prompt (optional) — custom analysis prompt; defaults to a structured-report prompt with anti-hallucination rules
--fps (optional) — custom frame sampling rate (useful for catching sub-second cuts in fast-paced footage)
--model (optional) — Gemini model ID; defaults to gemini-3-flash-preview

Verify the video file exists at the given path. If not, report the error and stop.

python3 ~/.claude/skills/video-analyzer/scripts/analyze_video.py $ARGUMENTS

Upload the video — inline for files ≤18MB, Files API for larger files (with up-to-300s polling for ACTIVE state)
Send the prompt to Gemini with the video attached
Print the full markdown report to stdout (info/progress lines go to stderr)

Missing API key: confirm echo $GEMINI_API_KEY is non-empty in their shell. If it's only in ~/.zshrc, they may need to start a new terminal or source ~/.zshrc.
Unsupported format: must be one of mp4, mov, avi, webm, mpeg, mpg, wmv, 3gpp, 3gp, flv
Upload timeout: large file or slow connection — retry, or use a shorter clip
Model error / 404: try a different model with --model gemini-2.5-flash

A markdown report printed to stdout with these sections:

Top-Level Summary — 2-3 sentence overview of what actually happens
Scene-by-Scene Breakdown — MM:SS timestamps for each cut/scene with on-screen content, actions, and verbatim text
Audio — verbatim transcript with timestamps, OR an honest "no audio / silent / ambient only" note (the prompt explicitly forbids inventing narrators)
Visual Details — on-screen text, UI elements, products, branding, people
Key Moments — 3-7 timestamped highlights a viewer would remember

Claude Vision