A Claude Code skill that watches any social media video and reverse-engineers it into a structured content intelligence report. Drop a TikTok, Instagram Reel, YouTube video, Reddit post, or X video URL and get back a full breakdown: hook analysis, storytelling structure, CTA mechanics, visual notes, and a replication playbook.
Works on any platform yt-dlp supports.
git clone https://github.com/Mharis-code/videoanalyzer
cd videoanalyzer
python install.pyThat's it. The installer handles dependencies, copies the skill to Claude Code, and sets up the config. After it finishes, open Claude Code in any project and type:
/video-analyze https://www.tiktok.com/@creator/video/...
Every analysis generates a structured markdown report covering:
- Format Breakdown — category, execution style, and why the format performs
- Topic and Angle — the specific reframe or contrarian positioning the creator uses
- Hook Analysis — spoken hook, visual hook, hook category, and a swipeable madlib template
- Storytelling Structure — timestamped beat-by-beat table of how the video is built
- CTA Analysis — what the creator asks for, when, and the engagement mechanic behind it
- Visual and Production Notes — setting, editing pace, social proof elements, pattern interrupts
- Replication Playbook — 3-5 specific, actionable things to copy into your own content
SKILL.md is the Claude prompt. It tells Claude how to run the pipeline, read the output, analyze the frames and transcript, and format the report. Claude Code reads this file when you invoke /video-analyze.
When you run /video-analyze [URL], Claude executes this sequence:
URL
└─ download.py → downloads the video and subtitles via yt-dlp
└─ frames.py → extracts frames at auto-scaled fps using ffmpeg
└─ transcribe.py → parses VTT subtitle file into timestamped segments
└─ whisper.py → fallback transcription via Groq or OpenAI if no captions
└─ watch.py → orchestrates all of the above, prints a markdown report
Claude then reads each frame image using its vision capability, cross-references the transcript, and writes the final analysis.
watch.py — Entry point. Accepts a URL or local file path, orchestrates the full pipeline, and prints a markdown report to stdout listing frame paths and transcript. Supports --start / --end range flags for zooming into a section of a long video.
download.py — Downloads via yt-dlp at up to 720p. Also fetches English subtitles (manual first, then auto-generated) in VTT format. Parses the info.json for title, uploader, and duration metadata. Handles local file paths as well as URLs.
frames.py — Probes video metadata with ffprobe, then extracts frames with ffmpeg at an auto-scaled fps. The fps is calculated from a frame budget, not a fixed rate: short videos get dense coverage, long videos are capped at 80 frames to control token cost. Focused range mode (--start / --end) uses a denser budget because the user is zooming in for detail. Max fps is capped at 2.0. Frames are output as 512px-wide JPEGs with timestamps.
transcribe.py — Parses WebVTT subtitle files into clean timestamped segments. Handles YouTube auto-subs which emit rolling duplicate cues (each line appears 2-3 times as it scrolls) by deduplicating consecutive identical lines and merging their time ranges.
whisper.py — Fallback transcription for videos with no captions. Extracts mono 16kHz 64kbps MP3 audio (about 480 kB/min) with ffmpeg, then uploads to Groq (whisper-large-v3) or OpenAI (whisper-1) via the standard API. Pure Python stdlib — no pip packages required beyond Python itself. Includes retry logic with exponential backoff for rate limits.
setup.py — Preflight checker. Run python scripts/setup.py --check at any time to verify all dependencies are in place.
| Dependency | Purpose | Required |
|---|---|---|
| Python 3.9+ | Runs the pipeline scripts | Yes |
| yt-dlp | Downloads videos from any platform | Yes |
| ffmpeg + ffprobe | Frame extraction and audio processing | Yes |
| GROQ_API_KEY or OPENAI_API_KEY | Whisper transcription fallback | No (optional) |
Without a Whisper API key the skill still works — videos with native captions get a full transcript, videos without captions come back frames-only.
python install.pyThe installer does the following in sequence:
- Checks Python 3.9+ — exits with a clear message if the version is too old
- Installs yt-dlp and ffmpeg — auto-installs via Homebrew on macOS, via winget on Windows; prints manual install commands on Linux
- Copies skill files to
~/.claude/skills/video-analyze/so the skill is available globally in Claude Code (Chat, Code, and Cowork modes) - Patches script paths in
SKILL.mdto match your machine's file system - Scaffolds
~/.config/watch/.envfor your optional Whisper API key
After install, restart your terminal (required on Windows for the new PATH to take effect), then run python install.py once more to confirm everything is green.
Open ~/.config/watch/.env and fill in one key:
GROQ_API_KEY=your_key_here
Groq is preferred — it runs whisper-large-v3, is faster than OpenAI, and costs a fraction of the price. Get a key at console.groq.com/keys.
OpenAI is the compatible fallback. Get a key at platform.openai.com/api-keys.
If you open this repo folder directly in Claude Code, CLAUDE.md tells Claude to run the installer automatically. Claude will:
- Check your setup status
- Run
install.pyif anything is missing - Walk you through adding a Whisper API key if needed
- Confirm the skill is ready to use
No manual steps required.
If you prefer to install dependencies yourself and copy files manually:
macOS
brew install yt-dlp ffmpegWindows
winget install yt-dlp.yt-dlp
winget install Gyan.FFmpegLinux
sudo apt install ffmpeg
pipx install yt-dlpThen copy the repo contents to your global Claude skills directory:
Windows: C:\Users\YourName\.claude\skills\video-analyze\
macOS / Linux: ~/.claude/skills/video-analyze/
The directory must contain SKILL.md at its root and the scripts/ subfolder. After copying, edit SKILL.md and replace __SKILL_SCRIPTS_PATH__ with the full path to the scripts/ folder on your machine.
Basic:
/video-analyze https://www.tiktok.com/@creator/video/1234567890
Supported platforms:
- TikTok
- Instagram Reels
- YouTube (Shorts and long-form)
- Reddit videos
- X / Twitter
- Any platform yt-dlp supports
Local file:
/video-analyze /path/to/video.mp4
Long videos: Videos over 10 minutes get a sparse frame budget by design. The skill will warn you and suggest re-running with --start / --end flags to zoom into a specific section.
Analysis files are saved to:
projects/content-creation-system/drafts/analysis/YYYY-MM-DD-[platform]-[creator-slug].md
The folder is created automatically. The file path is printed at the end of each analysis.
yt-dlp is not installed error
Run yt-dlp --version in a fresh terminal to confirm it is on your PATH. On Windows, a terminal restart is required after winget installs new binaries.
ffmpeg frame extraction failed
Both ffmpeg and ffprobe must be on your PATH. They ship together — install the full ffmpeg package, not just the codec. Run ffmpeg -version and ffprobe -version to confirm.
Video downloads but transcript is empty
The video has no native captions and no Whisper key is configured. Open ~/.config/watch/.env and add a GROQ_API_KEY or OPENAI_API_KEY.
Groq returns 403
This is a Cloudflare WAF block on Python's default urllib user-agent. The script sets a custom User-Agent to work around it. If you are still seeing it, make sure you are using the latest version of whisper.py from this repo.
Rate limit (429) on Whisper
The script retries with exponential backoff automatically. If it keeps failing, your key may have hit its quota — swap between Groq and OpenAI keys in ~/.config/watch/.env.
Skill not loading in Claude Code
Confirm SKILL.md is at the root of the video-analyze/ folder in your Claude skills directory, not inside a subfolder. Run python scripts/setup.py --check from the install directory to verify the pipeline is intact.
videoanalyzer/
README.md — this file
SKILL.md — Claude Code skill prompt (paths patched at install time)
CLAUDE.md — guides Claude through automated setup when the repo is opened
install.py — one-shot installer: deps, skill files, .env config
scripts/
watch.py — pipeline entry point
download.py — yt-dlp wrapper + subtitle fetch
frames.py — ffmpeg frame extraction with auto-fps budgeting
transcribe.py — WebVTT parser with YouTube dedup
whisper.py — Groq / OpenAI Whisper transcription (pure stdlib)
setup.py — preflight checker and .env scaffolder