Pokidex

Analyze short-form videos (TikTok, Reels, Shorts) using AI. Extracts key frames with ffmpeg, transcribes audio with Whisper, and uses Claude to break down what makes a video work.

Video File
    |
ffmpeg (scene detection + extract frames)
ffmpeg (extract audio) --> Whisper (transcribe)
    |
Claude CLI (analyze frames in parallel batches)
    |
Claude CLI (structured summary)
    |
output/video_name/summary.md

What it tells you

1. Content Summary -- what the video is about
2. What Makes It Special -- unique creative choices
3. Virality Factors -- why it works (hook, emotional triggers, shareability)
4. Composition & Technique -- editing, camera work, pacing, audio strategy

Requirements

• ffmpeg -- frame and audio extraction
• Claude Code CLI -- AI analysis

Optional

• OpenAI Whisper -- audio transcription (skipped gracefully if not installed)

Install

# macOS
brew install ffmpeg

# Whisper (optional)
pip install openai-whisper

Usage

# Basic usage
bash pokidex.sh video.mp4

# Adjust scene detection sensitivity (lower = more frames)
bash pokidex.sh video.mp4 --scene-threshold 0.2

# Change batch size for frame analysis
bash pokidex.sh video.mp4 --batch-size 6

# All options
bash pokidex.sh video.mp4 --scene-threshold 0.3 --batch-size 4

Results are saved to output/<video_name>/:

output/video_name/
  summary.md      # Structured analysis
  analysis.txt    # Raw per-batch frame descriptions
  audio.txt       # Audio transcript (if Whisper is installed)

How it works

1. Frame extraction -- ffmpeg uses scene detection (gt(scene,0.4)) to capture transitions, plus a safety-net frame every 2 seconds to cover static scenes
2. Audio transcription -- ffmpeg extracts audio, Whisper transcribes it locally
3. Parallel batch analysis -- frames are grouped into batches (default 4) and all batches are analyzed by Claude simultaneously
4. Structured summary -- batch analyses + transcript are combined and Claude produces the final breakdown

Tuning

Parameter	Default	When to adjust
--scene-threshold	0.4	Lower to 0.2 for talking heads, raise to 0.6 for fast action
--batch-size	4	Up to 6 for more context per batch, down to 2 for detailed per-frame analysis

Scene detection threshold controls how different consecutive frames need to be to trigger a capture. The safety-net interval (mod(n,48)) captures a frame every 2 seconds at 24fps regardless of scene changes.

License

MIT