video-performance-analyzer 0.1.0__py3-none-any.whl

video_performance_analyzer-0.1.0.dist-info/METADATA

@@ -0,0 +1,253 @@
+Metadata-Version: 2.5
+Name: video-performance-analyzer
+Version: 0.1.0
+Summary: Predict and compare how videos land, using Meta's TRIBE v2 brain-encoding model, with LLM recommendations that learn from real performance.
+Project-URL: Homepage, https://github.com/christopher-inegbedion/video-performance-analyzer
+Project-URL: Issues, https://github.com/christopher-inegbedion/video-performance-analyzer/issues
+Author: video-performance-analyzer contributors
+License: MIT
+License-File: LICENSE
+Keywords: analysis,creative,ffmpeg,fmri,neuroscience,tribe,video
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Multimedia :: Video
+Requires-Python: >=3.11
+Requires-Dist: httpx>=0.27
+Requires-Dist: numpy>=1.26
+Requires-Dist: platformdirs>=4.2
+Requires-Dist: rich>=13.7
+Requires-Dist: tomli-w>=1.0
+Requires-Dist: tqdm>=4.66
+Requires-Dist: typer>=0.12
+Provides-Extra: dev
+Requires-Dist: pytest>=8; extra == 'dev'
+Requires-Dist: ruff>=0.5; extra == 'dev'
+Provides-Extra: tribe
+Requires-Dist: faster-whisper>=1.0; extra == 'tribe'
+Requires-Dist: torch<2.7,>=2.5; extra == 'tribe'
+Description-Content-Type: text/markdown
+
+# video-performance-analyzer
+
+[![PyPI](https://img.shields.io/pypi/v/video-performance-analyzer)](https://pypi.org/project/video-performance-analyzer/)
+[![Python](https://img.shields.io/pypi/pyversions/video-performance-analyzer)](https://pypi.org/project/video-performance-analyzer/)
+[![test](https://github.com/christopher-inegbedion/video-performance-analyzer/actions/workflows/test.yml/badge.svg)](https://github.com/christopher-inegbedion/video-performance-analyzer/actions/workflows/test.yml)
+[![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](LICENSE)
+
+Predict how a video lands before you publish it — then find out whether the
+prediction was right, and get better advice because of it.
+
+`vpa` runs Meta's **TRIBE v2** brain-encoding model over your video, reduces the
+output to a response curve you can read, compares it against a reference video
+and against your own back catalogue, and asks an LLM for concrete editing
+recommendations. When you later record what the video actually did — views,
+likes, watch-through — it learns, and goes back to revise advice it has already
+given you.
+
+```
+vpa analyse my-cut-v3.mp4 --reference competitor-ad.mp4 \
+    --segments "hook:0-3,montage:3-16,card:16-19,end:19-24"
+```
+
+```
+╭─ my-cut-v3 ──────────────────────────────────────────────────╮
+│ 24.1s · 25 timesteps · Audio, Video                          │
+╰──────────────────────────────────────────────────────────────╯
+╭─ predicted response over time ───────────────────────────────╮
+│ ▃▄▄▅▅▆▇▇▆▇▇▇▆▅▄▃▃▃▃▂▂▂▂█                                     │
+│ 0s                  24s                                      │
+╰──────────────────────────────────────────────────────────────╯
+  opening_2s           0.882   Mean response over the first two seconds.
+  trough_value         0.777   Lowest normalised response.
+  decay               +0.055   Opening minus closing.
+```
+
+---
+
+## What this actually measures — read this first
+
+TRIBE v2 predicts **fMRI brain response**. It does not predict attention, watch
+time, clicks, or sales. Treating "more predicted response" as "better advert" is
+an inference the model does not make and its authors do not claim.
+
+This matters enough that the tool is built around it:
+
+- Every metric shown has a plain-English explanation attached (`vpa explain`).
+- The same caveats are injected into the LLM's context, so recommendations
+  inherit them rather than overclaiming.
+- Known artefacts are flagged automatically. A cut to black spikes the curve
+  every time; `vpa` detects that and excludes it from peak-finding rather than
+  reporting it as your ending landing.
+- Position matters more than content. In testing, the *same images* scored
+  highest in one edit and lowest in another purely because of where they sat.
+
+Use it to rank variants of the same idea. Don't use it as a verdict on one video.
+
+## Install
+
+```bash
+pip install video-performance-analyzer          # core
+pip install 'video-performance-analyzer[tribe]' # + scoring dependencies (~3GB of models)
+pip install git+https://github.com/facebookresearch/tribev2.git
+```
+
+TRIBE itself is not on PyPI, so that last line is always needed for scoring.
+
+<details>
+<summary>From source instead</summary>
+
+```bash
+git clone https://github.com/christopher-inegbedion/video-performance-analyzer.git
+cd video-performance-analyzer
+python3.12 -m venv .venv && source .venv/bin/activate
+pip install -e '.[dev]'
+```
+</details>
+
+You also need **ffmpeg** (`brew install ffmpeg` / `apt install ffmpeg`) and an
+API key for whichever LLM you point it at:
+
+```bash
+export OPENROUTER_API_KEY=sk-or-...
+vpa doctor      # tells you exactly what is missing
+```
+
+## Use
+
+```bash
+vpa analyse cut.mp4                       # score one video
+vpa analyse cut.mp4 -r reference.mp4      # compare against something
+vpa show eval_a1b2c3                      # revisit a past evaluation
+vpa list evals                            # everything you have run
+vpa ask eval_a1b2c3                       # ask questions about it
+vpa explain artefacts                     # what the numbers can't tell you
+vpa tui                                   # interactive session
+```
+
+### Describing your structure
+
+Even segments are a poor guide. Tell it where your real beats are and the report
+speaks your language:
+
+```bash
+vpa analyse cut.mp4 --segments "hook:0-3,montage:3-16,card:16-19,logo:19-24"
+```
+
+### The learning loop
+
+This is what makes the tool improve. Record what a published video did:
+
+```bash
+vpa metrics add my-cut-v3 --views 12400 --likes 380 --platform instagram
+vpa metrics template -o metrics.csv && vpa metrics import metrics.csv
+vpa metrics show          # what it has learned so far
+```
+
+Once outcomes exist, two things change:
+
+1. New recommendations weight **real performance above predicted response**.
+2. Old evaluations become *stale* — their advice predates what you now know.
+   `vpa retrofit` revisits them and writes a new generation of recommendations
+   saying what changed. Nothing is overwritten; you can read every generation
+   with `vpa show <id> -g 1`.
+
+The tool is deliberately honest about sample size. Below five labelled videos it
+refuses to call correlations findings and says so in plain terms.
+
+## Configuration
+
+```bash
+vpa config init      # writes a commented config file
+vpa config show      # effective settings and where they came from
+```
+
+Any OpenAI-compatible endpoint works — OpenRouter (default), OpenAI, Together,
+Groq, or a local model:
+
+```toml
+[llm]
+model    = "google/gemini-2.5-flash"
+base_url = "https://openrouter.ai/api/v1"
+
+[tribe]
+target_fps = 24        # 60fps costs ~2.5x for identical footage
+enable_language = false # true needs a gated Llama repo + HF token
+
+[analysis]
+ignore_tail_s = 1.5    # don't let the cut-to-black spike become a "finding"
+```
+
+For a fully local setup, point `base_url` at Ollama (`http://localhost:11434/v1`)
+and no API key is needed.
+
+## Running TRIBE on a laptop
+
+TRIBE ships configured for Meta's GPU cluster. `vpa` patches the known problems
+automatically and tells you what it changed:
+
+| Problem | What happens without the fix |
+|---|---|
+| `device: cuda` baked into the checkpoint | `Torch not compiled with CUDA enabled` |
+| `num_workers: 20` baked in | DataLoader workers die silently; the process sits at 3% CPU looking alive |
+| `compute_type` hardcoded to `float16` | CPU speech extraction always fails |
+| `uvx whisperx` resolves a broken torchaudio | `module 'torchaudio' has no attribute 'list_audio_backends'` |
+| Language pathway needs gated `meta-llama/Llama-3.2-1B` | 401 on an otherwise working run |
+
+The last two are why word timings are generated locally with faster-whisper and
+written to the `.tsv` cache TRIBE reads — whisperx is never invoked. The language
+pathway is **off by default**, so vision + audition work with no licence gate.
+
+### How long it takes
+
+Scoring is dominated entirely by the video encoder. Setup — importing the
+package, loading the checkpoint, building events — is about 8 seconds. Everything
+after that scales with how much footage you feed it.
+
+Measured on an Apple Silicon laptop (CPU only), roughly **96x realtime**:
+
+| video length | time to score |
+|---:|---:|
+| 10s | ~16 min |
+| 15s | ~24 min |
+| 24s | ~38 min |
+| 60s | ~96 min |
+
+**This is not an interactive tool.** Start a run and come back to it.
+
+Three ways to make it tractable:
+
+- **Halve the frame rate.** `target_fps = 12` roughly halves the encode, because
+  cost is proportional to frames. V-JEPA samples frames rather than reading every
+  one, so the quality cost is plausibly small — but that is untested, so measure
+  it on your own material before trusting it.
+- **Score an excerpt.** For a feed asset the first 6-10 seconds is where the
+  scroll decision happens. Scoring only the opening is a legitimate strategy.
+- **Use a GPU.** This is what the model was built for and it is a different order
+  of magnitude. Set `device = "cuda"`.
+
+There is no caching or warm-start trick that helps: the cost is the encoder, not
+the setup.
+
+## Licences
+
+This tool is MIT. The models are not:
+
+- **TRIBE v2** is **CC BY-NC 4.0 — non-commercial**. Using it to optimise
+  commercial advertising is arguably outside that licence. That is your call to
+  make deliberately, and the tool says so rather than hiding it.
+- The language pathway uses **Llama-3.2-1B**, which is gated and carries Meta's
+  own terms.
+
+## Development
+
+```bash
+pip install -e '.[dev]'
+pytest -q
+ruff check vpa
+```
+
+Contributions welcome — see [CONTRIBUTING.md](CONTRIBUTING.md). Platform
+connectors for metrics ingestion (`vpa/metrics.py` has a documented seam) and
+additional LLM providers (`vpa/providers/`) are the most useful places to start.

video_performance_analyzer-0.1.0.dist-info/RECORD

@@ -0,0 +1,24 @@
+vpa/__init__.py,sha256=2gNybQfaKtq13Cb9P2z4wj-UOxc0m0rxgl8Jl1r1P-0,126
+vpa/cli.py,sha256=dWDoWq_6yPSMJj3s0ORVg9LUiEyh4YxhWYKszH1m2v8,25260
+vpa/config.py,sha256=leBAmzZe5QH5sW9Gx2ETRMiDtmMkIyQXzGD61EUrPoQ,6200
+vpa/db.py,sha256=_HSJ00MaXtB2IcF7hpfUWX5ZJHyeCSm8SispjdqXSdQ,13231
+vpa/explain.py,sha256=BiR_zvGYtuNDKUHZntcsoD_9mfVUDn-UmKbidwsx54Q,6982
+vpa/learn.py,sha256=4A1ImXZ1k7ZG0xVaH7ERxDryrvUjZPgAV32bR0kKT7Q,8689
+vpa/metrics.py,sha256=lSCG7yo1-Qci9czkkpiD1jiS9XiozefqdUXNLQvWzuI,6047
+vpa/pipeline.py,sha256=ay03uAxQRBMimx8udFgA_E5mvNsFX-IJ844g19ayFSg,8490
+vpa/quiet.py,sha256=nn6H_JUYPl8k1799YgpqQgFaZVtnyN4ULwbjHgxbXoA,6473
+vpa/recommend.py,sha256=HyQa6b4emlzQ_-GVlSl_Dyl1fEylLesWBnQ9UqG6ntM,9432
+vpa/report.py,sha256=smwGAZybs3esJSjF3ssXlq0k6RHamgbyzkwcZ-zMWk0,9403
+vpa/tribe.py,sha256=BOVBFCeJ-9KXThBYg8-NtZzipJjnXlQHvKZnRpk5kqU,13624
+vpa/tui.py,sha256=uC8xTvkblgmCGOI62MjB6vkPgqjgQ5VT-HPme3uQes8,16259
+vpa/analysis/__init__.py,sha256=Ji53bt316vP833J3NMyr74gAo-G4LPxObQ43L53Jp0Y,71
+vpa/analysis/compare.py,sha256=UOo0PMri6V-0p7lYE24aC-Vj7-efET-V2eSUhQuT2mg,7356
+vpa/analysis/features.py,sha256=wn_pKn6dYipF1AXWlm1GTcYx0YUDU8Ub-VNWOhc8jnc,6264
+vpa/providers/__init__.py,sha256=rJF0Hq4hKh445VkBibELxQOzJGWeH4NA0pXJrwoM3zk,1067
+vpa/providers/base.py,sha256=M5xFuDzFVR92Q3yYK_0rktzwhns6nJZMTqzWQ0zZ2cM,639
+vpa/providers/openai_compatible.py,sha256=ljhydNxz1wpaE4VDGutOtayAjqmbyuSf5p3bfFDooxs,4633
+video_performance_analyzer-0.1.0.dist-info/METADATA,sha256=hwf9bk_Azl5tnX_0KqwpK8QBS4aaVSZy0yu-9hKbmsg,10483
+video_performance_analyzer-0.1.0.dist-info/WHEEL,sha256=W3fkpkm7-wf9vBI5Z-7s0eWkeM-spu78I8Neb98DeEg,87
+video_performance_analyzer-0.1.0.dist-info/entry_points.txt,sha256=6FN3aTDsUNXm2l-MF9csud-nKGo-741Xm5oGkF0NQsg,36
+video_performance_analyzer-0.1.0.dist-info/licenses/LICENSE,sha256=CdgeYt4HxEjFH8ctMYwR8AcvTaq3hOC9sQFA1MY4rfs,1655
+video_performance_analyzer-0.1.0.dist-info/RECORD,,

video_performance_analyzer-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.32.4
+Root-Is-Purelib: true
+Tag: py3-none-any

video_performance_analyzer-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+vpa = vpa.cli:app

video_performance_analyzer-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,36 @@
+MIT License
+
+Copyright (c) 2026 video-performance-analyzer contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+
+---
+
+NOTE ON MODEL LICENCES
+
+This tool orchestrates third-party models that carry their own terms:
+
+  * Meta TRIBE v2 (facebook/tribev2, facebook/tribev2-mini) is released under
+    CC BY-NC 4.0 — NON-COMMERCIAL use only. Using it to optimise commercial
+    advertising is arguably outside that licence. This is your decision to make,
+    not this tool's.
+  * TRIBE's language pathway uses meta-llama/Llama-3.2-1B, a gated repository
+    requiring licence acceptance and a HuggingFace token.
+
+The MIT licence above covers this tool's own source code only.

vpa/__init__.py

@@ -0,0 +1,3 @@
+"""video-performance-analyzer — predict how a video lands, and learn from what actually happened."""
+
+__version__ = "0.1.0"

vpa/analysis/__init__.py

@@ -0,0 +1 @@
+"""Turning raw cortical predictions into things a human can act on."""

vpa/analysis/compare.py

@@ -0,0 +1,192 @@
+"""Compare one video's response profile against a reference, and against history.
+
+Two comparisons, deliberately different in kind:
+
+  * 1:1 — your cut against one reference you are trying to emulate or beat.
+    Curves are resampled to a common length so videos of different durations can
+    be laid over each other. Position matters more than duration here.
+
+  * history — your cut against your own past evaluations. This is where the
+    tool becomes more useful the longer you use it, because past evaluations
+    can carry real published performance.
+"""
+
+from __future__ import annotations
+
+from dataclasses import asdict, dataclass, field
+from typing import Any
+
+import numpy as np
+
+from .features import Features, resample
+
+
+@dataclass
+class SectionDelta:
+    label: str
+    subject: float
+    reference: float
+    delta: float
+    verdict: str  # ahead | behind | level
+
+
+@dataclass
+class Comparison:
+    reference_label: str
+    correlation: float          # shape similarity, -1..1
+    same_shape: bool
+    subject_summary: dict[str, float]
+    reference_summary: dict[str, float]
+    deltas: dict[str, float]    # headline metric differences
+    sections: list[SectionDelta] = field(default_factory=list)
+    aligned_subject: list[float] = field(default_factory=list)
+    aligned_reference: list[float] = field(default_factory=list)
+    notes: list[str] = field(default_factory=list)
+
+    def to_dict(self) -> dict[str, Any]:
+        d = asdict(self)
+        d["sections"] = [
+            asdict(s) if not isinstance(s, dict) else s for s in self.sections
+        ]
+        return d
+
+
+_HEADLINE = ("opening_2s", "closing_2s", "peak_value", "trough_value", "swing",
+             "variability", "decay", "sustained_above")
+
+
+def _summary(f: Features) -> dict[str, float]:
+    return {k: float(getattr(f, k)) for k in _HEADLINE}
+
+
+def compare(subject: Features, reference: Features, ref_label: str,
+            same_shape_r: float = 0.85, points: int = 60) -> Comparison:
+    """Lay two response curves over each other and report the differences."""
+    a = resample(subject.trace, points)
+    b = resample(reference.trace, points)
+
+    r = 0.0 if a.std() == 0 or b.std() == 0 else float(np.corrcoef(a, b)[0, 1])
+
+    sub_s, ref_s = _summary(subject), _summary(reference)
+    deltas = {k: round(sub_s[k] - ref_s[k], 4) for k in _HEADLINE}
+
+    # Compare in fifths of each video, so structure lines up proportionally even
+    # when the two cuts are different lengths.
+    sections: list[SectionDelta] = []
+    names = ["first fifth", "second fifth", "middle fifth", "fourth fifth", "final fifth"]
+    chunk = points // 5
+    for i, name in enumerate(names):
+        lo, hi = i * chunk, (i + 1) * chunk if i < 4 else points
+        sa, sb = float(a[lo:hi].mean()), float(b[lo:hi].mean())
+        d = sa - sb
+        verdict = "ahead" if d > 0.05 else ("behind" if d < -0.05 else "level")
+        sections.append(
+            SectionDelta(name, round(sa, 3), round(sb, 3), round(d, 3), verdict)
+        )
+
+    notes: list[str] = []
+    if subject.tail_spike or reference.tail_spike:
+        notes.append(
+            "One or both videos spike on the final step. That is almost always a "
+            "hard cut (to black or to a card), not the ending landing — treat it "
+            "as an artefact."
+        )
+    if subject.modalities and reference.modalities and \
+            set(subject.modalities) != set(reference.modalities):
+        notes.append(
+            f"Modality mismatch: subject scored on {', '.join(subject.modalities)}; "
+            f"reference on {', '.join(reference.modalities)}. Compare shapes, not "
+            "absolute magnitudes."
+        )
+    if abs(subject.duration_s - reference.duration_s) > max(subject.duration_s, 1) * 0.4:
+        notes.append(
+            f"Durations differ a lot ({subject.duration_s:.1f}s vs "
+            f"{reference.duration_s:.1f}s). Curves were stretched to align; "
+            "position is comparable, pacing is not."
+        )
+
+    return Comparison(
+        reference_label=ref_label,
+        correlation=round(r, 3),
+        same_shape=bool(r >= same_shape_r),
+        subject_summary={k: round(v, 4) for k, v in sub_s.items()},
+        reference_summary={k: round(v, 4) for k, v in ref_s.items()},
+        deltas=deltas,
+        sections=sections,
+        aligned_subject=[round(float(x), 4) for x in a],
+        aligned_reference=[round(float(x), 4) for x in b],
+        notes=notes,
+    )
+
+
+@dataclass
+class HistoryPosition:
+    """Where this evaluation sits among the user's own past work."""
+
+    n_previous: int
+    percentiles: dict[str, float]      # metric -> 0..100 within own history
+    best_performing: dict[str, Any] | None   # features of highest-engagement past video
+    trend: dict[str, str]              # metric -> improving | declining | flat
+    notes: list[str] = field(default_factory=list)
+
+    def to_dict(self) -> dict[str, Any]:
+        return asdict(self)
+
+
+def position_in_history(subject: Features, history: list[dict[str, Any]]) -> HistoryPosition:
+    """Rank this video's profile against previous evaluations.
+
+    `history` entries are {"features": Features-dict, "engagement": float|None, ...}
+    """
+    notes: list[str] = []
+    if not history:
+        return HistoryPosition(0, {}, None, {}, ["No previous evaluations to compare against yet."])
+
+    pct: dict[str, float] = {}
+    for key in _HEADLINE:
+        past = [float(h["features"][key]) for h in history if key in h.get("features", {})]
+        if not past:
+            continue
+        cur = float(getattr(subject, key))
+        pct[key] = round(100.0 * sum(p < cur for p in past) / len(past), 1)
+
+    # Trend across the last few, oldest -> newest.
+    trend: dict[str, str] = {}
+    if len(history) >= 3:
+        for key in ("opening_2s", "sustained_above", "decay"):
+            series = [float(h["features"][key]) for h in history if key in h.get("features", {})]
+            if len(series) >= 3:
+                half = len(series) // 2
+                first = np.mean(series[:half])
+                last = np.mean(series[half:])
+                diff = last - first
+                if key == "decay":  # lower decay is better
+                    trend[key] = (
+                        "improving" if diff < -0.02
+                        else ("declining" if diff > 0.02 else "flat")
+                    )
+                else:
+                    trend[key] = (
+                        "improving" if diff > 0.02
+                        else ("declining" if diff < -0.02 else "flat")
+                    )
+
+    scored = [h for h in history if h.get("engagement") is not None]
+    best = None
+    if scored:
+        best_entry = max(scored, key=lambda h: h["engagement"])
+        best = {
+            "label": best_entry.get("label"),
+            "engagement": best_entry["engagement"],
+            "features": {k: best_entry["features"].get(k) for k in _HEADLINE},
+        }
+        notes.append(
+            f"Your best-performing measured video is '{best_entry.get('label') or 'unlabelled'}'."
+        )
+    else:
+        notes.append(
+            "No published performance recorded yet. Add views/likes with "
+            "`vpa metrics add` and recommendations start learning from outcomes."
+        )
+
+    return HistoryPosition(len(history), pct, best, trend, notes)