# F1 Race Replay: a Python telemetry viewer for FastF1 sessions

> IAmTomShaw/f1-race-replay renders an Arcade replay of a chosen Formula 1 session, with a simulated Safety Car, a live leaderboard and per-driver telemetry. It is a data-analysis tool, not a way to watch the broadcast.

**IAmTomShaw/f1-race-replay** — An interactive Formula 1 race visualisation and data analysis tool built with Python! 🏎️

- Repository: https://github.com/IAmTomShaw/f1-race-replay
- Stars: 6,258 · Forks: 828
- Language: Python
- License: not declared
- Published: 2026-09-22 · Updated: 2026-09-22 · Language: en
- Canonical page: https://hysenlabs.com/projects/iamtomshaw-f1-race-replay

## What f1-race-replay is for, and who it is not for

The project renders a Formula 1 session as an animated track view. Cars move around a drawn circuit, a leaderboard tracks position and tyre compound, and a lap and race-time display runs alongside. The README frames it as a visualisation and replay tool for race telemetry, built on top of FastF1 session data.

The audience is narrow but clear. You need Python 3.11 or newer, and you need to be comfortable running a script. There is no hosted version, no web front end and no package on an index. If you want to watch a race broadcast, this is the wrong tool: it draws positions from telemetry, it does not play video. If you already pull FastF1 sessions into notebooks and want to see a stint unfold spatially, the fit is much better.

One design choice stands out. The README states the Safety Car position is simulated, placed roughly 500 metres ahead of the race leader on the track reference polyline, because the F1 API does not provide GPS telemetry for the actual Safety Car. The deployment timing itself is real, taken from session.track_status. That split, real timing plus invented position, is the honest way to handle missing data, and it is worth understanding before you read anything into the animation.

## How the replay pipeline works from FastF1 session to Arcade frame

The flow starts with a session identifier: a year and a round number, plus optional flags for a Sprint or Qualifying session. FastF1 fetches the session, and the project computes a telemetry dataset from it. That computation is the expensive part, and the README is explicit that loading a session for the first time takes noticeably longer because telemetry must be downloaded, processed and cached locally. Later launches of the same session are faster because the result is read back from a cache.

Cached results are stored as .pkl files. The Safety Car computation lives in _compute_safety_car_positions() in src/f1_data.py, and each rendered frame carries a safety_car field with x and y world coordinates, a phase and an alpha value. The phase moves through deploying, on_track and returning, and alpha runs from 0.0 to 1.0 for the fade animation. The README gives the frame shape directly:

```json
{
  "safety_car": {
    "x": 1234.56,
    "y": 7890.12,
    "phase": "on_track",
    "alpha": 1.0
  }
}
```

Rendering is handled by Arcade, with pyglet underneath, and the GUI menu is built with pyside6. questionary and rich cover the optional CLI menu. The dependency list in requirements.txt is short and readable: fastf1, pandas, matplotlib, numpy, arcade, pyglet, pyside6, questionary, rich. There is no server component, no database and no network service beyond the FastF1 data fetch, which keeps the deployment story simple.

## Installing f1-race-replay and replaying a first race

The README gives a standard virtual environment setup. Clone the repository, create the environment, install from requirements.txt. The FastF1 cache folder is created automatically on first run; the README notes that if it is not created, you can make a folder named .fastf1-cache in the project root yourself.

```bash
git clone https://github.com/IAmTomShaw/f1-race-replay
cd f1-race-replay
python3 -m venv venv
source venv/bin/activate
pip install -r requirements.txt
```

On Windows the activation step differs: the README gives python -m venv venv followed by .\venv\Scripts\activate. Once dependencies are in place, running the entry point with no arguments opens the graphical menu, where you pick the year and round.

```bash
python main.py
```

If you already know the event, you can skip the menu and go straight to a viewer run. The README's example uses 2025 and round 12. Expect a long first load while telemetry downloads, then a rendered track with cars, a leaderboard and the insights menu, which the README says launches automatically with the replay.

```bash
python main.py --viewer --year 2025 --round 12
```

Two flags are worth knowing early. --sprint selects a Sprint session if the event has one, and --refresh-data forces re-computation of the telemetry dataset instead of reading the cached version. The README states that if you have existing cached .pkl files from previous runs, you must re-run with --refresh-data to generate Safety Car position data; older caches simply show no Safety Car. If the pull data process fails, the README's troubleshooting step is pip install --upgrade fastf1.

## The Safety Car is simulated, and that matters for interpretation

This is the part of the project most likely to be misread. The animation shows an orange circle, drawn at 8px radius against 6px for regular cars, with an outline ring and an always-visible SC label. It deploys from the pit lane over roughly three seconds, runs ahead of the leader with a steady amber glow, then returns to the pit lane over roughly three seconds with a fading pulse. The labels change through SC DEPLOYING, SC and SC IN.

None of that position data is real. The README states the F1 API does not provide GPS telemetry for the actual Safety Car, so the project approximates its position about 500 metres ahead of the race leader along the track reference polyline. What is real is the deployment timing, which comes from session.track_status and the track status code 4. So the animation tells you when a Safety Car period happened and gives you a plausible picture of the field under it. It does not tell you where the real Safety Car was, and it should not be used to reason about gaps to the Safety Car or about the exact moment of a pit stop under caution.

There is a second, quieter consequence. Because the Safety Car field is computed into the cached dataset, anyone holding caches from an earlier version of the project sees a replay with no Safety Car at all, and no error explaining why. The README does flag this and points at --refresh-data, but it is the kind of silent degradation that costs an afternoon if you have not read that note.

## Qualifying support and other rough edges

The README describes Qualifying session replays as recently added and still being refined, with telemetry visualisation covering speed, gear, throttle and brake over lap distance. The --qualifying flag exists and the feature is documented, but the project itself labels it as in development. Treat it as usable with caveats rather than finished, and expect the same first-run download cost as a race session.

The GUI menu carries a similar note. The README calls it a new feature and asks users to report issues. The CLI menu remains available via python main.py --cli, and the README shows it prompting with a series of questions answered by arrow keys and enter. That CLI path is the more settled of the two interfaces, which is a slightly unusual position for a desktop tool: the graphical front end is the newer, less proven surface.

There is also a real usability cost in the caching model. The first run for any new session is slow enough that the README warns about it up front. That is inherent to downloading and processing telemetry rather than a defect, but it shapes how you use the tool. It suits a session you intend to study repeatedly, not a quick look at five different races.

## How it compares with FastF1 plotting and with broadcast replays

The most direct alternative is FastF1 itself. FastF1 already exposes session data, telemetry and track status, and it ships plotting helpers built on matplotlib, which is in this project's dependency list. If you want a speed trace, a gear chart or a lap-time comparison, FastF1's own plotting gets you there without an Arcade window. The difference is the spatial, time-stepped view: f1-race-replay animates cars around a circuit with playback controls, so you can pause, rewind, fast forward and change speed. FastF1's plots are static. If your question is where two drivers were relative to each other at a given moment, the replay answers it in a way a line chart does not.

The other comparison is with broadcast replays, and that is where the naming could mislead. A broadcast replay is video of the race. This project renders positions from telemetry on a schematic track. It will not show you an overtake, a lock-up or a pit stop, and it has no commentary, no onboard cameras and no timing graphics from the world feed. The README's own framing is visualisation and data analysis, and that is the accurate description.

## Maintenance, licence and what to check before adopting

The repository is not archived and the last push was on 2026-07-12. There are no retrieved releases, so the project is consumed from the default branch rather than from tagged versions. That has a practical consequence: pinning is on you. Record the commit you cloned, because there is no release number to point at if behaviour changes between your run and a colleague's.

The licence is not stated in the repository metadata retrieved for this article. Before you redistribute the code, bundle it into another product or ship it internally at any scale, check the repository for a licence file and, if there is none, ask the maintainer directly. Absent an explicit licence, the safe assumption is that no rights are granted beyond what default copyright allows. This is not legal advice, and it is the single largest unknown in the project.

Upgrade cost is mostly external. The tool sits on FastF1, Arcade, pyglet, pyside6, pandas, matplotlib and numpy, and a breaking change in any of those can surface as a failed run rather than a clear error. The README's own troubleshooting entry, pip install --upgrade fastf1, is evidence that FastF1 version drift has already caused pull data failures. Python 3.11 or newer is a hard floor, so environments still on 3.10 cannot run it at all.

## Conclusion

Adopt it if you already work with FastF1 and want a visual layer over session data, and you can live with a first run that downloads and caches telemetry. Skip it if you want to watch a broadcast race; the README describes a rendered track with simulated Safety Car positions, not video. Before committing, verify that the Safety Car phase data appears in your cached frames, since the README states older .pkl caches show no Safety Car until you re-run with --refresh-data.

## FAQ

### How do I install f1-race-replay?

Clone the repository, create a virtual environment with Python 3.11 or newer, and run pip install -r requirements.txt. The README then has you start it with python main.py for the GUI menu.

### How do I replay a specific F1 race with f1-race-replay?

Pass the year and round to the viewer, for example python main.py --viewer --year 2025 --round 12. Add --sprint for a Sprint session or --qualifying for a Qualifying session.

### Why is the first run of f1-race-replay so slow?

The README states that loading a session for the first time takes noticeably longer because telemetry data must be downloaded, processed and cached locally. Subsequent launches of the same session are significantly faster.

### Why is there no Safety Car in my f1-race-replay replay?

The README states that if you have existing cached .pkl files from previous runs, you must re-run with --refresh-data to generate Safety Car position data, and that older cached files will simply show no Safety Car.

### Is the Safety Car position in f1-race-replay real?

The deployment timing comes from real track status data via FastF1, but the README states the F1 API does not provide GPS telemetry for the actual Safety Car, so its position is simulated about 500 metres ahead of the race leader.

## Sources

- [IAmTomShaw/f1-race-replay on GitHub](https://github.com/IAmTomShaw/f1-race-replay)
- [Issues](https://github.com/IAmTomShaw/f1-race-replay/issues)
- [README](https://github.com/IAmTomShaw/f1-race-replay/blob/main/README.md)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/iamtomshaw-f1-race-replay