# Festival 4D

Turn multiple fan-shot smartphone videos of the same concert into a synchronized,
explorable **4D experience**: time-aligned multi-video playback, 3D scene reconstruction
with camera poses, a free-roam "god's eye" viewer, AR-style overlays projected onto each
video, and AI-tagged moments on a shared timeline.

> **Status: foundation phase.** The scaffold, database, frozen contracts (API, pose math,
> DB schema), and a synthetic fixture generator are in place. Feature lanes (media sync,
> reconstruction, viewer, AI events) build on top. The full README with the real-footage
> workflow is written in the integration phase (M9). See
> [`OPUS_BUILD_INSTRUCTIONS.md`](OPUS_BUILD_INSTRUCTIONS.md) for the canonical spec and
> [`plan/`](plan/) for the execution plan.

## Prerequisites

- **Python 3.11+** and [`uv`](https://docs.astral.sh/uv/) (or venv + pip)
- **ffmpeg** / **ffprobe** on your `PATH` (required)
- **COLMAP** (optional — reconstruction degrades gracefully without it)
- A classifier API key (optional — `GEMINI_API_KEY` by default; see `events_ai.py`)
- **Node 18+** for the frontend

## Quickstart (synthetic demo — no footage needed)

```bash
# 1. backend env
uv venv --python 3.12
uv pip install -e ".[dev]"

# 2. generate the synthetic fixture project (fake videos + poses + point cloud + events)
uv run python -m festival4d synthetic

# 3. serve the API (http://127.0.0.1:8000)
uv run python -m festival4d serve

# 4. in another terminal, the frontend
cd frontend
npm install
npm run dev            # http://localhost:5173
```

## Backend CLI

```
python -m festival4d synthetic     # generate the synthetic fixture (M0)
python -m festival4d ingest        # probe videos + extract audio      (lane A / M1)
python -m festival4d sync          # GCC-PHAT audio alignment           (lane A / M1)
python -m festival4d reconstruct   # COLMAP SfM + pose export           (lane B / M2)
python -m festival4d events        # audio candidates + AI classify     (lane D / M7)
python -m festival4d serve         # FastAPI app                        (M3)
```

## Tests

```bash
uv run pytest
```