Hotlap Project Report
HOTLAP PROJECT REPORT · v0.2

HOTLAP

Formula 1 telemetry — live & historical

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.

6
Rust crates
~10.1k
Lines of code
2
Front-ends
11
Dashboard panels
40
Circuits w/ elevation
56
Commits

Overview

One pipeline, three sources

01 — THE IDEA

Live and replay share one code path

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.

02 — THIN CLIENTS

Two UIs over one state stream

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

Install & run

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

Environment variables

VariablePurpose
HOTLAP_F1_COOKIEF1 TV session cookie — unlocks live car telemetry + positions (CarData.z/Position.z, gated 2025+). Everything else is public.
HOTLAP_ARCHIVE_PROXYhttp/https/socks5 proxy (allowed region) for the geo-gated historical archive. Only the archive host is routed through it.
HOTLAP_NO_AUTO_PROXYSet 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

The data pipeline

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;
CrateResponsibility
hotlap-schemaShared types; derives JSON Schema, exported to TypeScript so Rust and the web can't drift.
hotlap-coreParser, engine (state + broadcaster), recorder, replay clock, timeline compiler, historical fetch/index, archive proxy, Ergast fallback, commentary, event detection, telemetry densification.
hotlap-signalrF1 Live Timing SignalR client: negotiate → connect → Subscribe → parse frames.
hotlap-serveraxum WebSocket + REST; a runtime session Hub; serves the built web GUI.
hotlap-tuiratatui terminal dashboard, in-process over the same engine.
hotlap-cliThe hotlap binary: serve · live · replay · historical · tui.

Under the hood

Pipeline internals

A few of the problems that needed real engineering rather than a library call.

Compressed telemetry
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.
Telemetry densification
Each 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.
Client-side replay
For historical sessions the server pre-compiles the whole recording into one ordered patch timeline; the web downloads it once and folds it on its own clock. Replay is independent per tab, seeking rebuilds full per-lap history locally (a backward seek re-folds from lap 1), and the server does no per-seek work.
Delta protocol
The engine diffs each state change as an RFC 7386 merge-patch and broadcasts it. New clients get a snapshot, then patches — keeping the wire small under high-rate car data.
Archive resilience
F1's static archive is now geo-gated, so it is reached via an optional / auto-discovered proxy (archive host only); when it can't be reached, the user is offered an Ergast-reconstructed basic replay. The season index is TTL-cached with a last-good fallback.
No schema drift
Types live once in hotlap-schema; schemars → JSON Schema → generated types.gen.ts. A Rust field rename surfaces as a TypeScript error, not a silent mismatch.
Circuit elevation
Real topography for all 40 circuits is fetched once from open elevation APIs and baked into the bundled GeoJSON as [lng, lat, elevation] — Spa and Kyalami (~1450 m) show dramatic relief, Zandvoort (~8 m) is nearly flat.

Web dashboard

Eleven panels, one window manager

Floating, resizable, overlapping windows with a taskbar and a persistent layout — fed by a single state stream into a zustand store.

TIMING

Timing Tower

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.

RING

Track Clock

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.

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, live yellow-zone highlights, weather & race control inline.

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.

FEED

Commentary & Radio

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

Where it all comes from

DataSourceAccess
Live timing & telemetrylivetiming.formula1.com — SignalR CoreF1 TV gated (2025+)
Historical sessionsStatic .jsonStream archive + season IndexGeo-gated · cached
Basic replay fallbackJolpica / Ergast per-lap resultsPublic
Live-blog commentaryMonterosa (F1's provider since 2024)Public
Circuit outlinesbacinger/f1-circuits GeoJSON (bundled)Offline
Circuit elevationOpen-Meteo / Open-Elevation (baked in)Offline
Race calendarJolpica / Ergast — via server proxyPublic

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

Known issues & limitations

ARCHIVE · GEO-GATE

F1's historical archive is geo-gated (since ~Oct 2026)

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.

SIZE

Large race timelines

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.

SEEK

Backward seek re-folds from lap 1

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

Built with

RUST

Core · Server · TUI

tokio · axum (+ws) · reqwest
serde / schemars
tokio-tungstenite
flate2 + base64 · clap
ratatui · chrono

WEB

React dashboard

React 19 + TypeScript + Vite
zustand (state)
react-rnd (windows)
uPlot (charts)
three.js (3D track)

METHOD

Discipline

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

How it came together

Built in phases, each independently runnable, then extended round by round against real sessions.

Phases P0–P5
Core, both UIs, live & historical

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.

Runtime
Session picker & Hub

A server Hub swaps the loaded session at runtime; hotlap serve starts empty and loads any year / event / session from the UI.

Realism
Maps, telemetry, commentary

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.

Identity
Liquid-glass UI, landing & live mode

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.

Scale views
Track Clock & split telemetry

A MultiViewer-style "Circle of Doom" ring; Telemetry split into a single-driver view and a dedicated Driver Comparison panel.

Resilience
Client-side replay & archive fallbacks

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

Where it stands

Working today

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

On the roadmap

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