F1-Replay — Interactive Formula 1 Race Replay & Circuit Visualization

Replay any historic Formula 1 race as an animated 2D map with real telemetry data, live timing, strategy overlays, and circuit visualizations. Built on FastF1 with intelligent caching and a Flask-based viewer.

Why F1-Replay?

• Watch any race — Animated car positions on a real circuit map with sub-second telemetry
• Live timing overlay — Gap times, position changes, pit stops, and tyre strategy in real time
• Track status — Safety car, VSC, red flag overlays and rain effects rendered on canvas
• Circuit posters — Generate publication-quality circuit maps colored by speed, sectors, throttle, brake, or elevation
• One command — f1-replay 2024 monaco and you're watching the race in your browser
• Python API — Full programmatic access to seasons, weekends, sessions, and telemetry DataFrames (Polars)

Quick Start

pip install f1-replay

Race Replay

from f1_replay import Manager

mgr = Manager()
mgr.race(2024, "monaco")

Or from the command line:

f1-replay 2024 monaco

Opens an interactive viewer at http://localhost:8080 with animated car positions, live standings, strategy panel, race control messages, and more.

Circuit Plotting

mgr = Manager()
weekend = mgr.load_weekend(2024, "monaco")

weekend.plot()                        # Clean white track
weekend.plot(color_mode="speed")      # Colored by speed
weekend.plot(color_mode="sectors")    # Marshal sectors
weekend.plot(save_path="monaco.png")  # Save to file

Color modes: white, sectors, speed, throttle, brake, height

CLI

f1-replay 2024 monaco                  # Race replay (shorthand)
f1-replay 2024 8                       # By round number
f1-replay race 2024 monaco -p 9000     # Custom port
f1-replay seasons 2024                 # List races
f1-replay config --set-cache-dir /data # Set cache location

Documentation

Full documentation at f1-replay.readthedocs.io

• Usage Guide — Data loading, circuit plots, race viewer, telemetry, CLI, REST API
• Python API Reference — Auto-generated from docstrings
• Architecture — Data pipeline, caching, frontend design
• Telemetry Reference — Column definitions, units, processing

Development

git clone https://github.com/kkollsga/f1-replay.git && cd f1-replay
make install   # pip install -e ".[dev,all]"
make check     # lint + tests (196 tests)
make docs      # build Sphinx documentation

See CONTRIBUTING.md for the full development guide.

License

MIT