Pit Wall Copilot

Evidence-first Formula 1 team-radio review and Radio incident and context copilot.

Pit Wall Copilot turns a radio clip into a word-timed transcript, exposes the exact phrases behind operational incident tags, and adds lap context only when independent timing evidence supports it.

Live product · Open workspace · Live API

Why it exists

Race radio is valuable evidence, but it is difficult to search, align, and review consistently. Pit Wall Copilot keeps the source audio and machine output together so a reviewer can move from a transcript word to its audio, inspect why a tag exists, and see whether race timing supports the surrounding context.

The product deliberately does not infer a driver's internal state, score stress, rank urgency, establish causality, or forecast performance. If evidence is absent or conflicting, the interface says so.

What it does

• Accepts MP3, WAV, FLAC, and OGG radio clips up to 10 MB and 60 seconds.
• Decodes audio to bounded 16 kHz mono samples.
• Segments speech with Silero VAD.
• Produces CPU/int8 transcription and word timestamps with faster-whisper.
• Keeps playback and transcript highlighting on one shared playhead.
• Detects only configured, explicit operational phrases.
• Shows the exact matched phrase and incident-rule version.
• Maps radio UTC time to lap intervals when timing evidence is available.
• Reports context as aligned, ambiguous, or unaligned.
• Preserves curated and uploaded source audio during the review session.
• Provides deterministic fixtures for tests, demos, and offline UI development.
• Includes a narrated product walkthrough on the landing page.

Product surfaces

Evidence-led landing page

The responsive landing page demonstrates the real evidence pipeline, includes an interactive product film, exposes the technical provenance, and respects prefers-reduced-motion.

Live review workspace

The workspace connects to the Railway API, supports curated or uploaded audio, and keeps the player, transcript, incident evidence, and lap context synchronized.

Review flow

1. Select the curated 2018 Australian GP - car #28 radio, or upload a supported clip.
2. Load the analysis and play or scrub the original audio.
3. Select a transcript word to seek to its exact timestamp.
4. Search and filter operational incident matches.
5. Select an exact match to return to its message audio.
6. Expand lap context to inspect its status, method, and supporting evidence.
7. Treat every transcript as unreviewed and verify it against the source.

Architecture

Vercel
└── React + TypeScript + Vite SPA
    ├── evidence-led landing page
    ├── product film
    └── live review workspace
            │ HTTPS / typed JSON
            ▼
Railway
└── FastAPI / single Uvicorn worker
    ├── bounded upload staging and validation
    ├── 16 kHz mono decoding
    ├── Silero VAD speech boundaries
    ├── faster-whisper CPU/int8 word timestamps
    ├── deterministic incident lexicon v1
    ├── optional UTC-to-session lap alignment
    └── expiring audio artifact store
            │
            ▼
Hugging Face Hub
└── pinned public ASR model and curated dataset provenance

Heavy models load once per API process. Readiness is separate from basic health, so the UI can distinguish a running server from a model that is still warming.

Technology

API

Interactive OpenAPI documentation is available at the deployed API docs.

Run locally

Docker Compose

Requirements: Docker Engine with Compose, internet access for the first model download, and at least 4 GB of available RAM.

docker compose up --build

Open:

• Product: http://localhost:8080
• Workspace: http://localhost:8080/dashboard
• API docs: http://localhost:8000/docs

The ASR model is downloaded at API startup and cached in the named hf-cache volume. Stop the stack with docker compose down. Use docker compose down -v only when you intentionally want to delete that cache.

Native development

Requirements: Python 3.11, uv, Node.js, and npm.

Backend:

uv sync --frozen --group dev --group research
uv run uvicorn backend.app:app --reload

Frontend:

cd frontend
npm ci
npm run dev

Vite proxies API routes to http://localhost:8000 during development.

Environment variables

Copy .env.example for local configuration. The safe public-demo defaults work without a secret.

Never commit tokens. The model is public, so HF_TOKEN is not required for inference quality; it only authenticates Hub downloads and can improve download reliability or rate limits.

Production deployment

Railway backend

railway.toml selects backend/Dockerfile, uses /health for deployment health checks, and runs one CPU worker. Configure these service variables in Railway:

APP_MODE=public_demo
HF_HOME=/tmp/huggingface
CORS_ORIGINS=https://pit-wall-copilot.vercel.app
MAX_AUDIO_DURATION_S=60
MAX_DECODED_SAMPLES=960000
MAX_PARALLEL_ANALYSES=1
MAX_QUEUED_ANALYSES=0
ARTIFACT_TTL_S=3600

Add a newly generated read-only HF_TOKEN directly in Railway Variables if authenticated Hub downloads are desired. Do not paste it into GitHub, Vercel, issues, screenshots, or documentation.

Vercel frontend

vercel.json installs and builds the frontend and rewrites browser routes to the SPA. Set:

VITE_API_BASE=https://pit-wall-copilot-api-production.up.railway.app

If the frontend hostname changes, add its exact origin to CORS_ORIGINS on Railway and redeploy the API.

Current deployment

Models, data, and attribution

Formula 1 names, broadcasts, timing data, and marks remain the property of their respective owners. This project is unofficial and is not affiliated with Formula 1.

Curated provenance

The 12 checked-in MP3 files are exact extracts from the pinned dataset revision. backend/data/curated/manifest.json records source rows, IDs, checksums, transcript provenance, session metadata, and usage notes. backend/data/curated/alignment_validation.json records the FastF1 timing evidence used to validate the car #28 “box” call against lap 1.

python -m backend.data.curated.validate_manifest
python -m backend.data.curated.validate_alignment

Dataset transcripts are publisher-provided machine transcriptions, not verified ground truth. Checksums establish audio identity, not timestamp accuracy.

Hugging Face account checklist

Each teammate should complete this outside the repository if required by the event:

• Create or confirm their own Hugging Face account.
• Review the model and dataset pages and their applicable terms.
• Confirm access to Systran/faster-whisper-small and MikCil/f1-team-radio.
• Keep tokens only in private environment or platform-secret settings.
• Record completion in the event's approved private checklist, never in this public repository.

Neither asset is currently gated. This checklist documents account and event compliance; it does not add authentication to the product.

Product film

The checked-in walkthrough is served from frontend/public/media/pit-wall-walkthrough.mp4.

Supporting files:

• Script: scripts/product-film-script.txt
• Captions: scripts/product-film-captions.srt
• Browser recording: scripts/record-product-film.mjs
• Film generation: scripts/generate-product-film.sh

The landing page uses user-controlled playback: no autoplay, forced mute, or loop.

Verification

# Backend
uv run pytest -q
uv run pytest -q tests/test_runtime_claim_guard.py

# Frontend
cd frontend
npm test -- --run
npm run build

# Live browser flow (API + upload)
APP_URL=https://pit-wall-copilot.vercel.app node scripts/verify-live-stack.mjs

The frontend suite covers routing, source selection, player controls, transcript interaction, incident evidence, alignment states, accessibility semantics, live error states, and reduced-motion behavior. Packaging and compliance checks cover Docker structure, runtime caching, disclosure copy, model pinning, and credential signatures.

Repository map

backend/
  app.py                 FastAPI routes and runtime lifecycle
  service.py             Analysis orchestration
  pipeline/              Decode, ASR, VAD, messages, rules, alignment
  data/                  Curated manifest, validation, incident lexicon
  tests/                 Backend unit and API tests
frontend/
  src/pages/             Landing and workspace routes
  src/components/        Player, transcript, incident feed, source controls
  src/api/               Typed live and fixture adapters
  src/motion/            Reduced-motion-aware GSAP choreography
  public/media/          Product walkthrough and poster
fixtures/                Frozen v1 analysis response
schemas/                 Versioned JSON contracts
scripts/                 Film, recording, and live-stack verification
docs/                    Demo notes, status, and screenshots
railway.toml             Railway backend deployment
vercel.json              Vercel frontend deployment

Known limitations

• ASR can be wrong, especially on noisy and compressed radio.
• Word timestamps are model estimates, not human-verified ground truth.
• Phrase rules can miss unseen wording and synonyms.
• An exact phrase match does not prove the associated event occurred.
• Nearby lap events establish timing proximity, not causality.
• The curated 12-clip sample is a regression and demo set, not a population estimate.
• A single CPU worker prioritizes bounded resource use over throughput.
• Railway restarts can require the model cache to warm again.
• Uploaded audio is temporary and not a durable storage feature.

Rejected driver-state approach

The original voice-state direction failed preregistered viability gates. The dimensional audeering model reached only 0.0739 high-minus-low arousal spread and 0.3092 Spearman correlation on the fixed sample. The HuBERT fallback collapsed 10 of 12 clips to hap and found no high-stress clips at its fixed threshold. Additional candidates also failed the required 0.25 spread and 0.40 correlation bars.

The project therefore ships auditable incident and race context instead of unreliable driver-state inference. Full measurements and NO-GO evidence remain in NOTES.md.

More documentation

• docs/DEMO.md - presentation script and readiness checklist
• docs/MVP_PIPELINE_STATUS.md - component-by-component status and limitations
• NOTES.md - research decisions and rejected model evidence