Hook Retention Analyzer — Local Kit (Download)
Hook Retention Analyzer
What you're buying: a download package (skill instructions + Python scripts) that runs on your own computer inside your own AI agent — it is not a cloud service.
You need: an AI agent that supports skills (e.g. Claude Code or Codex) — its subscription or API costs are yours; Python 3.9+, ffmpeg and faster-whisper.
Third-party services: none. All measurements run locally; the Whisper model (~150 MB) downloads free on first run. You supply the video file.
At which second does your short lose viewers? Local measurements plus AI judgement tell you what's wrong with your opening — and exactly how to fix it.
What you get
- 🎞️ Contact sheet: one frame every 0.5 s for the first 10 s, auto-marked with cuts (CUT), first spoken word (VOICE) and likely on-screen text (TEXT?)
- 📈 Per-second timeline: loudness curve, cuts, the timing of every word, on-screen text spans
- 🧮 Transparent 7-point score (out of 100): pattern interrupt, curiosity gap, time to first word, visual change, payoff promise, on-screen text, audio energy. 3 are measured by code, 4 judged by AI from the frames — every item cites its timestamp evidence
- 🔧 Fixes down to the second, e.g. "add 2 cuts between 1.0 and 3.0 s"
- ✍️ 3 rewritten hooks, each with voice-over, on-screen text and a shot list — ready to re-shoot
- ⚖️ Side-by-side comparison of several videos
Example
A 20-second space-facts short scored 65/100 (Grade C): the spoken hook starts instantly (0.10 s to first word), but the first 3 seconds are one static image with a quiet mix (−32 dBFS). Top fix: show the scale comparison in frame 1 and add a big headline. A product ad in the same test scored 68 and was flagged for a 4.6-second static stretch.
Try it — copy a prompt
- "Analyse the first 10 seconds of
my_short.mp4and tell me why people swipe away." - "Compare these 3 shorts and tell me which hook is strongest and how to fix the other two."
Why buy it
One payment, analyse every video you make — no per-report fees. Everything is measured locally from your file.
Who it's for
Short-form creators, social media managers and agencies who want concrete, second-by-second hook fixes.
What it measures
| Item | How |
|---|---|
| Time to first word | Local Whisper word timestamps, cross-checked with audio onset |
| Speech rate | words (or CJK characters) per second for 0–3, 0–6, 0–10 s |
| Cuts | ffmpeg scene detection |
| Visual change | frame difference every 0.5 s, plus cuts |
| Loudness | dBFS every 0.1 s, plus audio onset |
| On-screen text | high-contrast text-band detection (a hint only; the AI confirms by looking) |
Requirements
- Python 3.9+ and ffmpeg
pip install pillow faster-whisper(first run downloads a Whisper model, ~150 MB)- Optional:
pip install opencc-python-reimplemented(Traditional Chinese transcripts)
Limitations (please read)
- This is an estimate, not platform analytics. Scores come from editing rules of thumb and opening measurements. It can't read your YouTube or TikTok dashboards and can't predict real views or retention — A/B test the rewritten hooks.
- Whisper may mishear brand names or jargon; the AI defers to on-screen text.
- Time-to-first-word is accurate to about ±0.2 s.
- Text detection is heuristic: it sees whether there's text, not how readable it is — readability is judged by the AI from the frames.
- It doesn't edit or re-export your video; it gives fixes and shot lists.
- Needs a video file; it can't analyse a pasted URL.
Files
SKILL.md— agent workflowscripts/analyze_hook.py— measurements (frames, cuts, loudness, speech)scripts/make_report.py— HTML / MD report and comparison tablereferences/hook-rubric.md— the 7 scoring criteria and anchorsreferences/hook-patterns.md— 10 hook formulas and shot rulesreferences/scores-schema.md— score file format
