f1-replay 0.1.17

Formula 1 Race Replay and Visualization Library

f1-replay

A Python toolkit for Formula 1 data analysis and visualization. Built on FastF1 with intelligent caching, circuit plotting, and interactive race replay.

Installation

pip install f1-replay

Quick Start

Race Replay

Watch any historic race with an interactive 2D viewer:

from f1_replay import Manager

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

Or from the command line:

f1-replay 2024 monaco

The viewer includes animated car positions, live standings with gap times, strategy panel, track status overlays (safety car, VSC, red flags), rain effects, race control messages, and more.

Circuit Plotting

Generate poster-style circuit maps:

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 -- Loading data, circuit plots, race viewer, telemetry, CLI, REST API
• Python API Reference -- Auto-generated method documentation
• Architecture -- Data pipeline, caching strategy, frontend design
• Telemetry Reference -- Column definitions, units, processing pipeline

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.

Requirements

• Python 3.9+
• FastF1, Flask, Polars, NumPy, SciPy, Pandas
• Optional: matplotlib (circuit plots), orjson (faster JSON), flask-cors

License

MIT