video-performance-analyzer 0.1.0__tar.gz

video_performance_analyzer-0.1.0/.github/workflows/publish.yml

@@ -0,0 +1,62 @@
+name: publish
+
+# Publishes to PyPI when you create a GitHub Release.
+#
+# Uses Trusted Publishing (OIDC): PyPI verifies the release came from this
+# repository's workflow, so there is no API token to store, leak or rotate.
+# One-time setup is described in RELEASING.md.
+
+on:
+  release:
+    types: [published]
+  workflow_dispatch:        # lets you do a TestPyPI dry run by hand
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Verify the version tag matches the package version
+        # A release tagged v0.2.0 that ships 0.1.0 is the classic way to publish
+        # something nobody can install correctly. Fail loudly instead.
+        if: github.event_name == 'release'
+        run: |
+          TAG="${GITHUB_REF_NAME#v}"
+          PKG=$(grep -m1 '^version' pyproject.toml | cut -d'"' -f2)
+          echo "tag=$TAG package=$PKG"
+          [ "$TAG" = "$PKG" ] || { echo "::error::tag $TAG != version $PKG"; exit 1; }
+
+      - name: Run the tests before shipping anything
+        run: |
+          python -m pip install --upgrade pip
+          pip install -e '.[dev]'
+          ruff check vpa tests
+          pytest -q
+
+      - name: Build
+        run: |
+          pip install build twine
+          python -m build
+          twine check dist/*
+
+      - uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+  publish:
+    needs: build
+    runs-on: ubuntu-latest
+    environment: pypi          # add required reviewers here if you want a gate
+    permissions:
+      id-token: write          # required for Trusted Publishing
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+      - uses: pypa/gh-action-pypi-publish@release/v1

video_performance_analyzer-0.1.0/.github/workflows/test.yml

@@ -0,0 +1,31 @@
+name: test
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+jobs:
+  test:
+    runs-on: ${{ matrix.os }}
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest, macos-latest]
+        python: ["3.11", "3.12", "3.13"]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python }}
+      - name: Install
+        # A clean install on purpose: the scoring extras are NOT installed here,
+        # so anything the core accidentally depends on will fail this job. That
+        # is exactly how an undeclared tqdm dependency slipped through once.
+        run: |
+          python -m pip install --upgrade pip
+          pip install -e '.[dev]'
+      - name: Lint
+        run: ruff check vpa tests
+      - name: Test
+        run: pytest -q

video_performance_analyzer-0.1.0/.gitignore

@@ -0,0 +1,13 @@
+__pycache__/
+*.py[cod]
+.venv/
+venv/
+dist/
+build/
+*.egg-info/
+.pytest_cache/
+.ruff_cache/
+.DS_Store
+# local data — evaluations, predictions, reports
+data/
+*.npy

video_performance_analyzer-0.1.0/CONTRIBUTING.md

@@ -0,0 +1,108 @@
+# Contributing
+
+Thanks for looking. This is a small project with a specific point of view, so
+this file covers what that is — it should save you guessing.
+
+## Setup
+
+```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]'
+
+pytest -q
+ruff check vpa tests
+```
+
+That is enough for everything except actually scoring a video. For that you also
+need ffmpeg, roughly 3GB of model weights and a lot of patience:
+
+```bash
+pip install -e '.[tribe]'
+pip install git+https://github.com/facebookresearch/tribev2.git
+vpa doctor          # says exactly what is missing
+```
+
+**CI deliberately does not install the scoring extras.** A clean core install is
+what catches undeclared dependencies — that is how an accidental reliance on
+`tqdm` was found, after it passed locally for days. If you add something to
+`vpa/` that imports a new package, declare it in `pyproject.toml`.
+
+## The one rule that matters
+
+**Never show a number without being able to say what it means and what it does
+not.**
+
+TRIBE v2 predicts fMRI response. It does not predict attention, watch time,
+clicks or sales. The whole tool is built around not letting that slide:
+
+- every metric has an entry in `vpa/explain.py`, and a test asserts it
+- the same caveats are injected into the LLM's context, so recommendations
+  inherit them rather than overclaiming
+- known artefacts are handled, not reported as insight — a cut to black spikes
+  the curve every time, so the tail is excluded from peak detection
+
+If you add a metric, add its explanation in the same change. `tests/test_explain.py`
+will fail if you do not.
+
+## Where things live
+
+| Module | Responsibility |
+|---|---|
+| `vpa/tribe.py` | Runs TRIBE and patches what stops it working off a GPU cluster |
+| `vpa/analysis/` | Predictions → response curve → comparisons |
+| `vpa/learn.py` | Correlating predicted features with real published performance |
+| `vpa/recommend.py` | Prompt construction; the rules the model must obey |
+| `vpa/providers/` | LLM backends |
+| `vpa/explain.py` | What everything means, and its limits |
+| `vpa/quiet.py` | Keeping third-party output from wrecking the progress display |
+
+## Good first contributions
+
+**Platform connectors for metrics.** Performance is entered by hand or via CSV
+today. `vpa/metrics.py` has a documented seam: anything that can produce
+`{video, views, likes, ...}` rows can feed `record()`. Instagram Graph API,
+TikTok, YouTube Analytics are all wanted. Keep manual entry working — it is the
+only thing that covers every platform.
+
+**LLM backends.** `vpa/providers/` has a `Provider` protocol and one
+OpenAI-compatible implementation covering most services. Anything with a
+different shape (Anthropic's native API, Bedrock, Vertex) needs its own class
+registered in `get_provider`.
+
+**Speed.** Scoring runs at roughly 96x realtime on CPU. Lowering `target_fps`
+helps proportionally, but nobody has measured what it costs in accuracy. A
+careful comparison of the same video at 24 and 12 fps would be genuinely
+valuable and needs no new code.
+
+**Honesty about small samples.** `vpa/learn.py` refuses to call correlations
+findings below five labelled videos. That threshold is a guess. If you know the
+statistics better than I do, improve it.
+
+## Style
+
+- Comments explain *why*, especially where the code looks odd. Most of
+  `vpa/tribe.py` is strange for a reason and each reason is written down.
+- Errors should say what to do next. `vpa doctor` is the model: state what is
+  missing and give the command that fixes it.
+- Prefer failing loudly over guessing quietly. A silent wrong number is worse
+  than an error.
+- `ruff check vpa tests` must pass. Line length 100.
+
+## Testing
+
+`pytest -q` needs no models, no API key and no network. Anything requiring those
+belongs behind a skip.
+
+Test behaviour rather than implementation. The most valuable test in the suite
+checks that the progress relay reports *climbing* values — it caught a bug where
+every relayed value was zero, which would have shipped a frozen progress bar as
+a fix for a frozen progress bar.
+
+## Licences
+
+This tool is MIT. The models are not. TRIBE v2 is CC BY-NC 4.0 — non-commercial
+— and the language pathway needs a gated Llama repo. Please do not add anything
+that obscures those terms from users; the current behaviour of stating them
+plainly is deliberate.

video_performance_analyzer-0.1.0/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.

video_performance_analyzer-0.1.0/PKG-INFO

@@ -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.