AI Football Highlights Pipeline

Single-player soccer video analysis pipeline for tracking a target player and exporting highlights.

Features

• YOLOv8 person detection (ultralytics) every detect_stride frames
• ByteTrack association (boxmot) for tracklets
• Chunked video processing (2-5 minute chunks) with per-chunk checkpoints
• ReID matching with torchreid OSNet embeddings (Apple Silicon MPS supported)
• Precision-first target selection (threshold + stability + confusable margin guard)
• Segment generation with merge/expand/filter rules
• Intensity scoring (target motion + audio RMS peaks)
• Highlight export with ffmpeg:
  • output/highlight_all.mp4
  • output/highlight_short.mp4

Setup

./setup.sh
source .venv/bin/activate

Manual setup:

python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt -r src/web/requirements.txt

System requirements:

• ffmpeg binary must be installed and available in PATH
• PyTorch build with MPS support for Apple Silicon acceleration

Apple Silicon (MPS) Notes

• src/embed.py selects device in this order: mps, cuda, then cpu
• To verify MPS in your environment:

python -c "import torch; print(torch.backends.mps.is_available())"

• If False, embeddings run on CPU.

Project Structure

.
├── config.json
├── data
│   ├── matches
│   │   └── .gitkeep
│   └── players
│       └── .gitkeep
├── output
│   └── .gitkeep
└── src
    ├── detect.py
    ├── embed.py
    ├── match.py
    ├── segment.py
    ├── intensity.py
    ├── export.py
    └── pipeline.py

Usage

Activate the virtual environment before running anything:

source .venv/bin/activate

Run pipeline:

python src/pipeline.py --config config.json

Resume mode (reuse chunk checkpoints and existing detection artifact):

python src/pipeline.py --config config.json --resume

Web UI

Run the pipeline from a browser with uploads, live progress, logs, and downloads.

Install web dependencies:

source .venv/bin/activate
# Optional if you already ran ./setup.sh
pip install -r src/web/requirements.txt

Start the web server from the project root:

uvicorn app:app --app-dir src/web --host 0.0.0.0 --port 8000 --reload

Open:

http://localhost:8000

Web workflow:

• Paste a YouTube URL or upload match video (.mp4) plus target reference image (.jpg/.png)
• Set player name and optional gallery folder path
• Tune advanced settings (stride/confidence/lost seconds/clip windows/short reel options)
• Run job and monitor progress/logs in real-time
• Download highlight_all.mp4 and highlight_short.mp4

Each job is isolated under output/{job_id} and persists its state in output/{job_id}/job.json.

Input Expectations

• Video: config.video_path
• Target references:
  • target.ref_current_game: single clear image from same match context
  • target.ref_gallery: optional folder of additional references

Example config is included in config.json.

YouTube Download

Install dependencies first (./setup.sh), then:

source .venv/bin/activate
python src/download.py "https://www.youtube.com/watch?v=VIDEO_ID"

Custom output path:

source .venv/bin/activate
python src/download.py "https://www.youtube.com/watch?v=VIDEO_ID" --output data/matches/match_001/video.mp4

Web UI also accepts a YouTube URL directly in the "New Job" form and downloads it before the pipeline runs.

Outputs

• output/detections.json
• output/checkpoints/chunk_*.json
• output/target_match.json
• output/segments.json
• output/ranked_segments.json
• output/highlight_all.mp4
• output/highlight_short.mp4
• output/summary.json