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.

CommandWhat it does
serveStart 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]
liveServe 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

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.

RING

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.

GRAPH

Telemetry

Full-resolution speed / throttle / brake for one driver's current lap, with live speed / gear / rpm / DRS and pedal meters.

COMPARE

Driver Comparison

Overlay several drivers' laps (a driver's best, the session fastest, a specific lap, or another driver), aligned to seconds-into-lap.

MAP

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.

MORE

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

VariablePurpose
HOTLAP_F1_COOKIEF1 TV session cookie. Unlocks the gated live car telemetry + positions (CarData.z / Position.z, 2025+). Also settable with --auth on live.
HOTLAP_ARCHIVE_PROXYAn 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_PROXYSet (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

DataSourceAccess
Live timinglivetiming.formula1.com — SignalR Core (/signalrcore)Public
Live car telemetry + positionssame feed, CarData.z / Position.zF1 TV token (2025+)
Historical sessionsStatic .jsonStream archive + season IndexGeo-gated; cached locally
Basic replay fallbackJolpica / Ergast per-lap resultsPublic
Live-blog commentaryMonterosa (F1's provider since 2024)Public
Circuit outlines & elevationbacinger/f1-circuits + Open-Meteo/Open-Elevation (baked)Offline
Race calendarJolpica / Ergast (via server proxy)Public

Troubleshooting

Known issues

ARCHIVE · GEO-GATE

"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:

1 · RELIABLE

Supply a proxy

Set HOTLAP_ARCHIVE_PROXY to a trusted proxy in an allowed region. A residential/paid proxy is best.

2 · BEST-EFFORT

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.

3 · FALLBACK

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+.

OTHER

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.