virality-analyzer

Virality Analyzer

A free Claude Code skill that scores any Higgsfield-generated video for virality potential and renders a cinematic local dashboard explaining why it works (or doesn't).

Built on top of Higgsfield's virality_predictor MCP tool. When you ask Claude Code "is this viral?" it auto-fires this skill: uploads/trims your video if needed, runs the prediction, computes a verdict (PASS / MARGINAL / RECUT HOOK / KILL), and opens a local infographic in your browser with bars, an engagement curve, a 5-region brain breakdown, and a plain-English "why" layer.

What you see

When the skill fires, your default browser opens to http://127.0.0.1:<port>/ showing:

• Verdict — PASS / MARGINAL / RECUT HOOK / KILL — with a one-line action
• Viral Potential % — animated radial gauge (0–100)
• Why this works / doesn't work — 3–7 plain-English bullets generated from the data
• 5 metric cards — Hook (0–3s), Overall, Brain Engagement, Sustain, Engagement Peak — each with a bar and a one-line interpretation
• Engagement curve — Chart.js line of normalized engagement across the video's seconds
• Brain regions — visual cortex / auditory / language / attention / DMN bars (DMN inverted because lower DMN = more focus)
• Recommended action — what to do next ("re-cut first 1–2s", "post it", "kill it")

How to install

You need Claude Code installed first (anthropic.com/claude-code). Then run:

npx skills add github.com/mergedmediateam/virality-analyzer

The Vercel Agent Skills CLI auto-detects Claude Code and installs the skill to ~/.agents/skills/virality-analyzer/. Restart Claude Code; the skill is now auto-discovered.

Or install manually by copying this repo's contents to ~/.claude/skills/virality-analyzer/:

git clone https://github.com/mergedmediateam/virality-analyzer ~/.claude/skills/virality-analyzer

How to use

In any Claude Code chat, say one of:

• "Score this video: [Higgsfield URL or media_id]"
• "Is this video viral? [path to local mp4]"
• "Rate this reel" (then paste it)
• "Should I post this?"

That's it. The skill handles everything: uploading external files to Higgsfield, trimming videos longer than 16 seconds (Higgsfield's API cap), running the prediction, and opening the dashboard.

Requirements

This skill is free, but it depends on tools you must have installed yourself:

If any of these is missing, the skill will tell you what to install before failing.

How it works under the hood

1. Identify input. UUID (Higgsfield media_id or job_id), URL, or local file path.
2. Pre-flight if external file — Glob to find it → ffprobe for duration → ffmpeg re-encode trim if > 16s → media_upload (presigned URL) → curl PUT → media_confirm.
3. Fire predictor — virality_predictor({action: "create", medias: [{role: "video", id}]}).
4. Poll — job_display({ids}) every 20–25 seconds, capped at 3 polls (~60s).
5. Extract scores — hook_score, viral_potential, overall_score, brain_engagement, sustain, peak_second + 5-region cortical breakdown (visual_occipital / auditory_temporal / language_frontotemporal / frontoparietal_attention / default_mode).
6. Compute verdict — see thresholds in dashboard/render.py (compute_verdict()).
7. Render local dashboard — Python writes a populated HTML to <temp>/virality-analyzer-<jobid>/index.html, spawns a detached python -m http.server on a free port, opens it in the default browser.

Calibration

Default verdict thresholds are heuristics for short-form Instagram Reels. They will under-rate slow-burn cinematic content because the predictor is Reels-tuned (it rewards punchy stop-scroll openings).

After you've scored 5+ of your own videos with known real-world performance, edit the thresholds in dashboard/render.py, inside compute_verdict(). The defaults:

viral_potential ≥ 70 AND hook_score ≥ 60        →  PASS
viral_potential 55–69 AND hook_score ≥ 50       →  MARGINAL
hook_score < 50 AND sustain ≥ 70                →  RECUT HOOK
viral_potential < 55 AND sustain < 70           →  KILL
peak_second > duration / 2                      →  HOOK FAILS (override)
DMN does not crash before duration / 2          →  HOOK FAILS (override)

Methodology disclaimer

Higgsfield ships this disclaimer with every result, repeated here:

"Predictive proxy metrics, not guaranteed performance or clinical measures."

The internal model (brain_activity) simulates 5 cortical regions on the fsaverage FreeSurfer template. It is a proxy for engagement, not a neural recording. Treat the scores as a directional signal, not gospel. The real test is still posting and watching analytics.

License

MIT — see LICENSE. Use it, fork it, modify it. Attribution appreciated but not required.

Built with

• Higgsfield — the prediction model
• Claude Code — the skill runtime
• Chart.js — engagement curve
• Inter + JetBrains Mono — typography