A local-first F1 telemetry application. One Rust core ingests Formula 1's Live Timing feed — live, from a recording, or from any past session — normalizes it, and serves it to two front-ends: a browser window-manager dashboard and a terminal UI.
Overview
Every source — the live SignalR feed, a local recording, or F1's historical archive — normalizes to the same message shape and flows through the same parser → state → broadcast pipeline. A session you record replays through the exact code that rendered it live, which makes replay a free correctness check on the live path.
The core serves a normalized SessionState as a snapshot plus merge-patch deltas. The TUI links the core in-process; live mode streams over WebSocket; historical replay is folded in the browser from a compiled timeline. None re-implement parsing — they render state.
Get started
One Rust binary serves the REST API, the WebSocket, and the built web GUI. Build the web once, then run any mode. Prerequisites: Rust (stable) and Node 18+.
1Build the web GUI once
# outputs web/dist, which the core serves cd web && npm install && npm run build && cd ..
2Replay the bundled real session
# opens the dashboard at http://localhost:8080 cargo run -p hotlap-cli -- replay fixtures/monaco-2023-quali/
3Or start empty and pick any session from the UI
cargo run -p hotlap-cli -- serve # season calendar + picker cargo run -p hotlap-cli -- live # live feed (when a session is on) cargo run -p hotlap-cli -- historical 2023 Silverstone Race cargo run -p hotlap-cli -- tui --replay fixtures/monaco-2023-quali/
4Or run it in Docker
docker compose up --build # → http://<host-ip>:8080 on your LAN
| Variable | Purpose |
|---|---|
| HOTLAP_F1_COOKIE | F1 TV session cookie — unlocks live car telemetry + positions (CarData.z/Position.z, gated 2025+). Everything else is public. |
| HOTLAP_ARCHIVE_PROXY | http/https/socks5 proxy (allowed region) for the geo-gated historical archive. Only the archive host is routed through it. |
| HOTLAP_NO_AUTO_PROXY | Set to disable automatic free-proxy discovery when the archive is blocked. |
Full command reference, the web dev loop, panel guide and troubleshooting are in the documentation.
Architecture
Sources differ only in the adapter that produces RawMessage { topic, payload, offset_ms }; parsing, state, and broadcast are identical downstream.
%%{init: {'theme':'dark','themeVariables':{'fontFamily':'IBM Plex Mono, monospace','primaryColor':'#10141c','primaryBorderColor':'#2a3444','primaryTextColor':'#e9edf3','lineColor':'#4a5565','clusterBkg':'#0b0e14','clusterBorder':'#1c2430'}}}%%
flowchart TD
L["Live · SignalR"] --> P
R["Recording · JSONL"] --> P
H["Historical · static .jsonStream"] --> P
P["PARSER
decode .z · expand CarData entries"] --> E["ENGINE
SessionState · RFC-7386 merge-patch"]
E --> REC["Recorder
raw → .jsonl"]
E --> TL["Timeline compile
(per-tab client replay)"]
E --> B["Broadcaster"]
B --> WS["/ws · snapshot + patches"]
E --> API["REST /api/*"]
TL --> WEB["Web GUI (React)"]
WS --> WEB
API --> WEB
E --> TUI["Terminal UI (ratatui)"]
classDef src fill:#131821,stroke:#2a3444,color:#9aa6b6;
classDef core fill:#161b24,stroke:#e10600,color:#e9edf3;
classDef io fill:#0d1118,stroke:#2a3444,color:#41d6e0;
classDef ui fill:#131821,stroke:#2a3444,color:#e9edf3;
class L,R,H src; class P,E,REC,B,TL core; class WS,API io; class WEB,TUI ui;
| Crate | Responsibility |
|---|---|
| hotlap-schema | Shared types; derives JSON Schema, exported to TypeScript so Rust and the web can't drift. |
| hotlap-core | Parser, engine (state + broadcaster), recorder, replay clock, timeline compiler, historical fetch/index, archive proxy, Ergast fallback, commentary, event detection, telemetry densification. |
| hotlap-signalr | F1 Live Timing SignalR client: negotiate → connect → Subscribe → parse frames. |
| hotlap-server | axum WebSocket + REST; a runtime session Hub; serves the built web GUI. |
| hotlap-tui | ratatui terminal dashboard, in-process over the same engine. |
| hotlap-cli | The hotlap binary: serve · live · replay · historical · tui. |
Under the hood
A few of the problems that needed real engineering rather than a library call.
CarData.z / Position.z are base64 of raw DEFLATE (no zlib header) — decoded as inflate(-MAX_WBITS). The car channel map: 0=RPM 2=Speed 3=Gear 4=Throttle 5=Brake 45=DRS.CarData message bundles ~4 timestamped samples (~5 Hz). Folding one message into one state step would collapse traces to ~1 Hz, so each message is split into one frame per entry, timed by its own Utc — restoring full-resolution traces.hotlap-schema; schemars → JSON Schema → generated types.gen.ts. A Rust field rename surfaces as a TypeScript error, not a silent mismatch.[lng, lat, elevation] — Spa and Kyalami (~1450 m) show dramatic relief, Zandvoort (~8 m) is nearly flat.Web dashboard
Floating, resizable, overlapping windows with a taskbar and a persistent layout — fed by a single state stream into a zustand store.
Order, gaps and intervals, sector & mini-sector strips, tyres (new/used), best lap (session-fastest in purple), a live running sector delta, and places gained/lost vs the grid.
A MultiViewer-style "Circle of Doom": drivers around a ring by relative on-track position — the leader sweeping, the field spread by real time gaps — retired cars dropped, labels de-cluttered.
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, live yellow-zone highlights, weather & race control inline.
Full-resolution speed / throttle / brake for one driver's current lap, with live speed / gear / rpm / DRS and pedal meters.
Overlay several drivers' laps — a driver's best, the session fastest, a specific lap, or another driver — aligned to seconds-into-lap.
F1's real live-blog (via Monterosa), time-synced to the playhead; team-radio clips played inline. Plus Race Chart, Strategy, Weather and Prediction.
Data
| Data | Source | Access |
|---|---|---|
| Live timing & telemetry | livetiming.formula1.com — SignalR Core | F1 TV gated (2025+) |
| Historical sessions | Static .jsonStream archive + season Index | Geo-gated · cached |
| Basic replay fallback | Jolpica / Ergast per-lap results | Public |
| Live-blog commentary | Monterosa (F1's provider since 2024) | Public |
| Circuit outlines | bacinger/f1-circuits GeoJSON (bundled) | Offline |
| Circuit elevation | Open-Meteo / Open-Elevation (baked in) | Offline |
| Race calendar | Jolpica / Ergast — via server proxy | Public |
The live feed (/signalrcore) is public; only live car telemetry + positions need an F1 TV token. The historical static archive was public but, since ~Oct 2026, F1 geo-gates it at the CloudFront edge — Hotlap reaches it via an optional proxy, or degrades to the Ergast basic replay. Already-cached sessions replay fully offline.
Caveats
F1 added a CloudFront edge-function access gate on livetiming.formula1.com/static/: requests from blocked regions get an immediate 401 Unauthorized (x-cache: FunctionGeneratedResponse), regardless of User-Agent or headers. This is not rate limiting (that is 429) — it is region/IP-based, it only began after the gate was deployed (a same-URL fetch succeeded days earlier), and it affects every tool reading the static archive (FastF1 included). The live feed is unaffected. Three mitigations, most-reliable first: (1) a trusted proxy via HOTLAP_ARCHIVE_PROXY (allowed region, archive host only); (2) automatic proxy discovery from a public list — though free proxies rarely work, as F1 also WAF-blocks datacenter IPs (a 403), so a residential/paid proxy is usually needed; (3) an Ergast basic replay (positions, lap times, gaps — no telemetry, map, sectors, weather or race control), offered via a user prompt.
A full race compiles to a ~50 MB client-side timeline (car/position thinned 2×). Fine for local/LAN; enable HTTP compression for remote hosting. First (uncached) loads are download-bound.
Client-side replay rebuilds full per-lap history on a backward seek by re-folding the timeline from the start — a brief synchronous pass on a long race. No keyframe optimization yet.
Stack
tokio · axum (+ws) · reqwest
serde / schemars
tokio-tungstenite
flate2 + base64 · clap
ratatui · chrono
React 19 + TypeScript + Vite
zustand (state)
react-rnd (windows)
uPlot (charts)
three.js (3D track)
One pipeline for live/replay. Schema-generated TS. Parser, merge, replay-clock and densification covered by unit + integration tests; a recording replays identically to live.
Development
Built in phases, each independently runnable, then extended round by round against real sessions.
Workspace + pipeline; the web MVP and the ratatui TUI; the SignalR live client; FastF1-style historical fetch — verified end-to-end on 2023 Monaco qualifying.
A server Hub swaps the loaded session at runtime; hotlap serve starts empty and loads any year / event / session from the UI.
2D/3D circuit maps from geolocation + baked elevation; full-resolution telemetry with lap-vs-lap comparison; F1's actual live-blog time-synced to the playhead.
An iOS-style glass theme; an F1 home with a roaming orb, local-time countdown and the weekend calendar; a web Live button with a track-local clock.
A MultiViewer-style "Circle of Doom" ring; Telemetry split into a single-driver view and a dedicated Driver Comparison panel.
Per-tab timeline replay with full-history seeking; and, when F1 geo-gated the archive, an archive proxy plus a prompted Ergast basic replay.
Status & next
done Live mode from the web (track-local clock, timers) done Per-tab client-side replay, instant full-history seek done Track Clock, telemetry + comparison, race chart done Archive proxy + prompted Ergast fallback
next Smaller timelines (keyframes, HTTP compression) next Confirm if the archive gate is permanent; auth path later F1 TV auth for live car channels; reconnect later Saveable named layouts; packaging