Documentation
Hotlap
F1 live & historical telemetry, in your browser and your terminal. One Rust core ingests F1's Live Timing feed — live, from a recording, or from any past session — normalizes it, and serves two front-ends from a single binary.
Get started
Install & run
Prerequisites: Rust (stable toolchain) and Node 18+. The binary serves the REST API, the WebSocket, and the built web GUI.
# 1. build the web GUI once → web/dist (served by the core) cd web && npm install && npm run build && cd .. # 2. replay the bundled real session; opens the dashboard cargo run -p hotlap-cli -- replay fixtures/monaco-2023-quali/
Open http://localhost:8080. The home page shows the season calendar — click any past session to load and replay it — plus the next-session countdown. Windows float, overlap, move and resize; the layout is remembered per browser.
Docker
docker compose up --build # → http://<host-ip>:8080 on your LAN # or: docker run --rm -p 8080:8080 -v hotlap-cache:/root/.cache/hotlap hotlap
CLI
Commands
The hotlap binary has five subcommands. All server modes bind
0.0.0.0:8080 by default (LAN-visible; it prints the LAN URL). Use
--addr 127.0.0.1:8080 for local-only, or another port.
| Command | What it does |
|---|---|
| serve | Start empty; load any year / event / session from the web picker on demand. [--addr] [--no-open] |
| replay <dir> | Replay a local recording or bundled fixture. [--addr] [--speed N] [--no-open] |
| live | Serve both UIs off the live feed (when a session is on air). [--record <dir>] [--auth <cookie>] |
| historical <year> <event> <session> | Download, cache and replay a past session. [--car-stride N] [--pos-stride N] [--start-minutes N] [--max-minutes N] |
| tui --replay <dir> | Full ratatui terminal dashboard over the same engine — no browser. |
hotlap serve # season calendar + picker hotlap live --record data/my-session # live + save for later replay hotlap historical 2023 Silverstone Race # big race? --car-stride 3 --pos-stride 3 hotlap tui --replay fixtures/monaco-2023-quali/
Web dashboard
Dashboard panels
Floating, resizable, overlapping windows with a taskbar and a persistent layout. Historical replay is per-tab and client-side: the browser downloads a compiled timeline once and folds it on its own clock, so seeking rebuilds full history locally.
Timing Tower
Order, gaps/intervals, sector + mini-sector strips, tyres (new/used), best lap (session-fastest in purple), live sector delta, and places gained/lost vs the grid.
Track Clock
A MultiViewer-style "Circle of Doom": drivers around a ring by relative on-track position (leader sweeping, field spread by real gaps); retired cars dropped.
Telemetry
Full-resolution speed / throttle / brake for one driver's current lap, with live speed / gear / rpm / DRS and pedal meters.
Driver Comparison
Overlay several drivers' laps (a driver's best, the session fastest, a specific lap, or another driver), aligned to seconds-into-lap.
Track Details
The real circuit in 2D (geolocation outline, chosen by true location not the GP name) and interactive 3D (three.js, from topography) — start/finish line, yellow-zone highlights, weather & race control inline.
Race Chart · Strategy · Radio · Weather · Commentary · Prediction
Position by lap; tyre stints; inline team radio; weather; F1's real live-blog time-synced to the playhead; and a prediction panel.
Terminal UI
Keyboard controls
A full ratatui dashboard against the same engine: hotlap tui --replay <dir>.
- space
- play / pause
- ← / →
- seek ∓10 s
- [ / ]
- slower / faster
- ↑ / ↓
- focus driver
- q
- quit
Configuration
Environment variables
| Variable | Purpose |
|---|---|
| HOTLAP_F1_COOKIE | F1 TV session cookie. Unlocks the gated live car telemetry + positions (CarData.z / Position.z, 2025+). Also settable with --auth on live. |
| HOTLAP_ARCHIVE_PROXY | An http / https / socks5 URL (optionally user:pass@host) in an allowed region, used to reach the geo-gated historical archive. Only the archive host is proxied; everything else stays direct. |
| HOTLAP_NO_AUTO_PROXY | Set (to any non-empty value) to disable the automatic free-proxy discovery that runs when the archive is blocked. |
The historical download cache lives under your OS cache dir (e.g. ~/.cache/hotlap/historical); re-runs of a cached session are fully offline.
Data
Data sources & access
| Data | Source | Access |
|---|---|---|
| Live timing | livetiming.formula1.com — SignalR Core (/signalrcore) | Public |
| Live car telemetry + positions | same feed, CarData.z / Position.z | F1 TV token (2025+) |
| Historical sessions | Static .jsonStream archive + season Index | Geo-gated; cached locally |
| Basic replay fallback | Jolpica / Ergast per-lap results | Public |
| Live-blog commentary | Monterosa (F1's provider since 2024) | Public |
| Circuit outlines & elevation | bacinger/f1-circuits + Open-Meteo/Open-Elevation (baked) | Offline |
| Race calendar | Jolpica / Ergast (via server proxy) | Public |
Troubleshooting
Known issues
"F1 archive unavailable" when loading a past session
Since ~Oct 2026, F1 geo-gates its historical archive (livetiming.formula1.com/static/) with a CloudFront edge function: blocked regions get an immediate 401 (x-cache: FunctionGeneratedResponse), regardless of User-Agent or headers. This is not rate limiting (that is 429) — it is region/IP-based and affects every tool reading the static archive (FastF1 included). The live feed is unaffected, and already-cached sessions still load fully.
What to do, most reliable first:
Supply a proxy
Set HOTLAP_ARCHIVE_PROXY to a trusted proxy in an allowed region. A residential/paid proxy is best.
Auto-discovery
On by default: fetches a public free-proxy list and tests it against the archive. Free proxies rarely work — F1 also WAF-blocks datacenter IPs (403). Disable with HOTLAP_NO_AUTO_PROXY.
Ergast basic replay
Offered via a popup: positions, lap times and gaps from the results API — but no telemetry, map, sectors, weather or race control. Covers 2024+.
Notes
A full race compiles to a ~50 MB client-side timeline (fine locally). A backward seek re-folds from lap 1. Live car channels need an F1 TV cookie.
Development
Web dev loop
# terminal 1 — core serving the API + WebSocket cargo run -p hotlap-cli -- replay fixtures/monaco-2023-quali/ --no-open # terminal 2 — Vite dev server (HMR), proxies /api + /ws to the core cd web && npm run dev # http://127.0.0.1:5173
TypeScript types are generated from the Rust schema so they can't drift:
cd web && npm run gen:types # regenerates src/types.gen.ts
Reference
Project layout
crates/ hotlap-schema/ # shared types → JSON Schema → TS hotlap-core/ # parser, engine, replay, timeline, recorder, # historical, fallback, proxy, commentary, events hotlap-signalr/ # F1 Live Timing SignalR client hotlap-server/ # axum WS + REST; serves web/dist; session Hub hotlap-tui/ # ratatui dashboard hotlap-cli/ # the `hotlap` binary web/ src/store.ts # WS live source + client-side timeline player src/panels/ # TimingTower, TrackClock, Telemetry, DriverComparison, # TrackDetails, Track3D, RaceChart, Strategy, Radio, … public/circuits.geojson # 40 circuits, baked elevation fixtures/ # checked-in sample sessions for offline dev/tests docs/ # report.html, documentation.html, ARCHITECTURE.md, TODO.md
Deep technical reference: ARCHITECTURE.md · roadmap & known issues: TODO.md · the designed report: report.html.