Virality

Predicts how much of a viewer's brain a short video actually activates, before you post it.

Sends a video clip to a HuggingFace Inference Endpoint running Meta FAIR's TRIBE v2 — a multimodal brain-encoder model trained on 1,000+ hours of fMRI data across 720 subjects. The model returns predicted brain activation across ~20k cortical vertices, per timestep. We aggregate that into three numbers a creator can act on:

• Engagement score (0–100) — composite of peak amplitude, sustained activation, and average activation
• Peak hook timestamp — the moment in the video where predicted brain activation is highest (the actual hook)
• Hold rate (0–100) — how steady the activation curve is, i.e. whether attention drops off after the opening

A line chart of activation over the duration of the video is also rendered, so you can see exactly where the engagement spikes and where it drops.

Best use: rank variants of the same hook (V1 vs V2 vs V3 of an opening) before posting. Not for predicting absolute reach — that depends on distribution, not just stimulus.

Step 1 — Verify endpoint is set up

This skill calls a HuggingFace Inference Endpoint that the user has to deploy once, ahead of time. Before running anything, check .env at project root for both:

HF_TOKEN=hf_xxx
HF_TRIBE_ENDPOINT=https://xxx.endpoints.huggingface.cloud

If either is missing, stop and walk the user through the one-time setup below. Do not attempt to call the endpoint without both keys.

One-time HuggingFace endpoint setup (only the first time)

1. Open https://ui.endpoints.huggingface.co/new
2. Repository: paste facebook/tribev2
3. Endpoint name: tribev2 (or anything — note it down)
4. Cloud / region: AWS, us-east-1 (or closest)
5. Instance type: GPU · NVIDIA A10G (24 GB) — minimum for this model
6. Container type: Custom
7. Custom handler path: upload the contents of skills/references/tribev2-handler/ from this project as the handler. The handler files are:

• handler.py
• requirements.txt
• README.md

1. Auto-scaling: set "Scale to zero" to 15 minutes so you only pay while it's running
2. Click Create Endpoint. Initial build takes ~10 min while it pulls the TRIBE weights and dependencies.
3. Once status is Running, copy the endpoint URL (looks like https://xxxxx.us-east-1.aws.endpoints.huggingface.cloud) and your HF access token (https://huggingface.co/settings/tokens — needs read scope).
4. Add both to .env at project root:

    HF_TOKEN=hf_your_token
    HF_TRIBE_ENDPOINT=https://your-endpoint-url

Cost: ~$1.30/hour while running, $0 while scaled to zero. Cold start adds ~30s to the first request after idle.

Step 2 — Get the video

Ask the user for the video they want to score:

"Drop the path to the video you want to score. MP4 / MOV / WebM all work. Best results on clips ≤30s — TRIBE was trained on naturalistic stimuli around that length."

Validate:

• File exists
• Extension is in .mp4, .mov, .webm, .m4v
• Duration ≤60s (warn if longer; the endpoint will still process it but the hook window is the part that matters)

If the user just drops a long-form video and the goal is hook prediction, suggest trimming to the first 15s with ffmpeg -i input.mp4 -t 15 -c copy hook.mp4 and scoring that.

Step 3 — Pick a brand and output name

Brand selection: scan ./brands/ for subfolders that contain brand-identity/visual-guidelines.md.

• One brand → use it, confirm: "Using brand: [name]"
• Multiple → list and ask
• None → ask for a brand name and create the folder; or accept a --no-brand mode and save to ./virality/[output-name]/ at project root

Output name: ask the user for a short slug — e.g. gels-launch-hook-v1, reid-monday-reel. Slug it: lowercase, hyphens, no spaces.

If the user already gave a name when starting the skill, skip the prompt.

Step 4 — Write virality-spec.json

Create the output folder and write the input metadata before calling the endpoint, so a crashed run still leaves a trace.

brands/[brand-name]/virality/[output-name]/
  virality-spec.json

virality-spec.json format:

{
  "output_name": "[output-name]",
  "brand": "[brand-name]",
  "video_path": "absolute/path/to/video.mp4",
  "video_duration_seconds": 14.2,
  "model": "facebook/tribev2",
  "endpoint": "https://xxxxx.endpoints.huggingface.cloud",
  "created_at": "2026-05-10T..."
}

Step 5 — Run the scorer

Run from project root:

python3 skills/references/generate-virality.py brands/[brand-name]/virality/[output-name] --video path/to/video.mp4

The script:

1. Uploads the video to the HF Inference Endpoint
2. Receives predicted activation array (n_timesteps, n_vertices) plus segment metadata
3. Computes engagement score, peak hook timestamp, hold rate, mean activation
4. Renders activation-timeline.png — line chart of total activation over time, with the peak marked and the first 3s "hook window" shaded
5. Writes score.json with all numbers

Cold start: ~30–60s on first call after idle. Warm calls: ~10–20s for a 15s video.

Step 6 — Present the results

Once the script finishes, read score.json and print a clean summary:

Virality score for [output-name]:

  Engagement score:    72 / 100
  Peak hook at:        1.4s
  Hold rate:           81 / 100
  Mean activation:     0.42

  Saved:
    brands/[brand]/virality/[output-name]/score.json
    brands/[brand]/virality/[output-name]/activation-timeline.png

Then offer interpretation, honestly framed:

"Read this as: relative ranking signal, not absolute prediction. A 72 means the brain-response model thinks this clip activates more cortex than something scoring 50. Use it to compare V1 vs V2 of the same hook — not to predict view count."

If the user has already scored other variants in the same brand, list them so they can compare:

Other scores in this brand:
  hook-v1   62 / 100   peak 0.8s
  hook-v2   71 / 100   peak 1.2s
  hook-v3   72 / 100   peak 1.4s   ← this one

Score interpretation cheatsheet

These thresholds are starting points. Once the user has scored 10+ of their own posts and knows their actual view counts, we can re-calibrate the bands against real performance — that's the v2 of this skill.

Notes & limits

• What this is: TRIBE v2 predicts the brain response of an "average" subject. Useful as a directional signal for stimulus strength.
• What this is not: a view-count predictor. Distribution, timing, audience, captions, and IG/TikTok algorithm weights all matter — this scores the stimulus only.
• No personalization in v1. Tyler Germain's version (the reel that inspired this) blends TRIBE output with his past video performance. We can add that in v2 once the user has a CSV of their post performance — score this skill's outputs against actual views and learn a per-creator weighting.
• Not for static images — TRIBE v2 takes video, audio, or text. For a still ad, treat it like a 1s static video clip and score it that way, but the signal is much noisier.
• 5s hemodynamic offset is already applied by the model — peak hook timestamps are aligned with the video timeline, no manual correction needed.
• Cost per run: ~$0.05–$0.20 depending on cold start and duration. Only billed while endpoint is running — set scale-to-zero aggressively.

Troubleshooting

• "HF_TOKEN not found" → you skipped Step 1 setup. Walk through it.
• "503 endpoint scaling up" → cold start, retry in 30s.
• "413 payload too large" → video over ~50MB. Compress with ffmpeg -i in.mp4 -vf scale=720:-1 -c:v libx264 -crf 28 out.mp4.
• Timeline chart looks flat → either the clip is too short (<2s, no fMRI timesteps) or your video had no audio. Try with audio + ≥3s duration.
• "Different scores on identical reruns" → expected, TRIBE has stochastic components. Differences <5 points are noise; rank variants by a wider margin.