NFL Ref Revision

Cheap-first scaffold for an NFL officiating review app:

• search YouTube by game title using the official YouTube Data API
• embed candidate videos in a Streamlit UI
• ingest licensed or user-provided video locally
• sample frames and create low-resolution review artifacts
• scrape official NFL Game Books for penalty frequencies
• summarize officiating accuracy from manual review data now
• run YOLO as the primary CUDA-backed inference path

Why this repo starts this way

The hardest part of this project is not Streamlit or YOLO. It is reliable and legal video sourcing plus label quality.

This scaffold intentionally starts with:

• official YouTube search and embeds instead of downloader-first scraping
• official NFL Game Books for penalty metadata
• local disk storage for development because it is the cheapest path
• manual review summaries first so you can validate the business logic before training detectors
• YOLO as the required vision backbone once the GPU stack is installed

Recommended build order

1. Search and select candidate game videos by title.
2. Ingest only video you are allowed to process.
3. Extract candidate plays and low-resolution review frames.
4. Scrape Game Books for official penalty logs and common penalty frequencies.
5. Build a manual-review dataset for penalties and call correctness.
6. Train detection and tracking models once you have real labels.

Storage recommendation

Cheapest path for MVP:

• raw videos: local disk only
• derived review clips and frames: local disk only
• summaries and labels: JSON or SQLite

Do not store full-season raw videos unless you need them. Most of the long-term value will be in:

• short play clips
• cropped player and line-of-scrimmage regions
• labels
• review summaries

Model recommendation

This repo is set up for a later Ultralytics integration, but the current official Ultralytics line is YOLO26, with YOLO11 still a stable production option. If you want the safest near-term choice, start with YOLO11 or YOLO26n/s rather than planning around YOLO v12.

Penalty detection will likely need more than one model:

• detector for players, line markers, ball, and official positions
• tracker across frames
• play-state classifier to identify snap, route contact, hold windows, or pre-snap movement
• rules layer or VLM-assisted review layer to convert detections into officiating judgments

GPU setup

The app now treats YOLO as a required part of the workflow. Streamlit will stop at startup until the GPU inference stack is available.

Install base dependencies:

# PowerShell
scripts\setup_gpu.ps1

# POSIX shell
sh scripts/setup_gpu.sh

What the helper does:

• creates .venv
• installs a CUDA-enabled PyTorch build
• installs this project plus dev tools
• verifies torch, ultralytics, and CUDA availability

The helpers currently default to the official PyTorch cu126 wheel index. If your GPU or driver needs a different build:

• PowerShell: change TorchIndexUrl in setup_gpu.ps1
• sh: set TORCH_INDEX_URL=... or edit setup_gpu.sh

Both should be adjusted to the version recommended by the official PyTorch install selector.

Run the app

# PowerShell
.venv\Scripts\activate
streamlit run streamlit_app.py

# POSIX shell
. .venv/bin/activate
streamlit run streamlit_app.py

Current capabilities

• YouTube title search with API key
• local video upload
• sampled frame extraction at reduced resolution
• official NFL Game Book penalty parsing and aggregation
• manual officiating review summarization
• required YOLO inference status checks at app startup
• YOLO batch inference over extracted local frame directories
• training manifest generation from scraped Game Books
• clip CSV export and annotation-ready YOLO frame export helpers

Clip discovery query format

Use game queries like:

• [Away Team] vs. [Home Team] Week [n] [league year]
• [Away Team] vs. [Home Team] Wild Card [league year]
• [Away Team] vs. [Home Team] Divisional Round [league year]
• [Away Team] vs. [Home Team] Conference Championship [league year]
• [Away Team] vs. [Home Team] Super Bowl [league year]

The app now keeps discovery and processing separate:

• discover YouTube clips with official search and embeds
• use X and Instagram as link-and-notes review sources
• only download or extract frames from footage you own or are licensed to use

Public datasets

Dataset notes and links live in docs/datasets.md.

Training Prep

Training utilities live under src/nfl_ref_revision/training.

Included helpers:

• prepare_dataset.py: scrape official Game Book recap URLs and write parsed reports plus a manifest
• prepare_merged_dataset.py: merge scraped manifests with manual review JSON and optional local frame links
• manifest.py: convert Game Book reports into a normalized JSONL manifest
• export_clips.py: export a clip-classification CSV from the manifest
• export_yolo.py: export an annotation-ready YOLO scaffold from manifest rows that point at extracted frame directories
• merge.py: match manual-review rows onto a manifest when safe, and append unmatched rows

Real sample scraped data is included in examples/training_seed.

Near-term next steps

• add scene and play segmentation
• add dataset export for training
• add object detection and tracking interfaces
• add penalty-specific feature extractors
• add football-specific labeling for penalty review