winget install --id=d4vid87.hookecho -e Advanced NEXRAD weather radar viewer — an open-source homage to supercell-wx, built from scratch in Rust with wgpu + egui. Deep per-site Level 2 / Level 3 analysis plus national situational awareness, forecast environment overlays, and warning intelligence — on Windows, Linux, and Android.
Advanced NEXRAD weather radar viewer — an open-source homage to
supercell-wx, built from scratch in Rust
with wgpu + egui. Deep per-site Level 2 / Level 3 analysis plus national
situational awareness, forecast environment overlays, and warning intelligence —
on Windows, Linux, and Android.
KTLX 0.5° reflectivity — Moore, Oklahoma, 20 May 2013. Replayed from the public archive inside the app, one scan every few seconds, with the tornado warning that was in force at the time.
Animated wind. HRRR 10 m wind as drifting particles coloured by speed — built from NOAA's free GRIB grids, so it needs no API key.
Hook_Echo-WX-x86_64.AppImage from
Releases, chmod +x, run.Hook_Echo-WX-setup-x86_64.exe (setup wizard) or Hook_Echo-WX-x86_64.msi
(MSI, for scripted/enterprise installs). A portable
hookecho-windows-x86_64.zip is there too: unzip, run hookecho.exe.Hook_Echo-WX-arm64-v8a.apk from
Releases (adb install -r …, or open it on-device with
"install unknown apps" enabled). The same Rust app as desktop,
with a Material 3 phone UI — see .android/README.mdcargo run --release (needs a Rust toolchain; on Linux also
ALSA/Wayland/GTK dev headers — see .github/workflows/ci.yml). Android builds
via android/build.sh (NDK + cargo-ndk).Versioned v* releases are the stable channel. Every push to main also
refreshes a latest rolling prerelease carrying the
same five artifacts, if you want the newest work without waiting for a tag.
First launch opens a setup wizard: pick your home radar site, a theme (13 built in), and how warnings should reach you (chime and/or ntfy.sh push to your phone). After that, three one-time callouts point at the controls you'll actually use. Re-run the wizard anytime from the sidebar's App → Setup wizard.
Hook Echo-WX is a map with its controls docked around it — no menu bar, no floating cards over the weather:
Ctrl+K; Enter runs the top match.
Drag a row by its icon to pin it above the rest of its category, and collapse
the whole sidebar to a single button when you want the map and nothing else.That's the whole of it. Searching for a place is the same box — type a name and take the Fly to row at the bottom of the results.
| Search everything | One sidebar for everything |
|---|---|
 |  |
| Joplin, MO — 22 May 2011 | Mayfield, KY — 11 Dec 2021 |
Radar times read in the selected radar's local time, not Zulu — a KEPZ pane shows MDT while a KTLX pane shows CDT, side by side. Settings → Units puts it back to UTC if you'd rather work in Zulu.
Every expert control is still there, in the sidebar's Layer options section, which shows a layer's settings only once that layer is on — so the forecast-hour slider appears when you turn on future radar, and stays out of the way when you haven't.
Search a place in the sidebar and it flies there, with a Save marker button if you want to keep it. Markers are what the warning, lightning and rain-arrival alerts watch. Tap one on the map to rename or remove it.
Storm screenshots are historic events replayed through the app's own archive timeline — the same scrubbing you'd do live. Forecast and national layers are live data, captured as they came in. Everything is on the Mapbox Satellite Streets basemap; a dozen others ship too, from a dark vector map to GOES satellite imagery.
All six Level 2 moments on a GPU polar pipeline, with VCP-aware tilt selection,
velocity dealiasing, storm-relative velocity, and GRLevelX .pal color tables.
Reflectivity shows you the storm's structure; velocity shows you what it's doing —
the tight red-against-green couplet below is a tornado on the ground.
| Reflectivity | Velocity (dealiased) |
|---|---|
 |  |
| KBMX — Tuscaloosa, AL, 27 Apr 2011 | KTLX — El Reno, OK, 31 May 2013 |
Split the window into four panes and give each one its own product, cameras linked — reflectivity, velocity, correlation coefficient and differential reflectivity on the same storm at the same second. One action does the same trick with four tilts instead, so you can see how a storm leans with height. Cross-sections slice it vertically in any product — click two points and you get the storm in profile, core and overhang and all.
| Four products at once | Cross-section |
|---|---|
 |  |
| KTLX — Moore, OK, 20 May 2013 | KTLX — Moore, OK, 20 May 2013 |
Every screenshot in this section is a replay. The timeline reaches back to June 1991, so any archived storm loads the same way the live one does — a supercell from fifteen years ago, or a hurricane coming ashore:
KTBW 0.5° reflectivity — Hurricane Ian, 28 September 2022.
And because the archive is there, you can ask how the warnings did. The verification lab scores an office's warnings for a day against the storm reports that came in — POD, FAR, CSI, lead times, and the individual rows behind them, including the reports nobody warned for (the red dots on the map). The arbitration is the Iowa Environmental Mesonet's, so the numbers agree with the published ones instead of being a private opinion.
KTLX — 20 May 2013. OUN's warnings scored against that day's reports.
Every tracked cell in one sortable table — hail size, tops, VIL, rotation flags — and clicking a row flies you there. Alongside it, an active-alerts panel sorted worst-first, with clickable NWS bulletins and parsed storm-motion vectors. Scrub into the archive and the panel fills with the warnings that were actually in force at that moment.
| Storm attributes | Active alerts |
|---|---|
 |  |
| KTBW — live | KBMX — 27 Apr 2011 outbreak |
HRRR future radar rides the timeline's forecast tail, so scrubbing past the present keeps going into the model. It is labeled the whole time it is on — model output should never be mistaken for something a radar actually saw.
HRRR future radar, +1 h. The banner stays up for as long as the layer is on: forecast, not observed.
Any point on the map gives you the plain NWS forecast for that spot, and the WPC surface analysis draws the national weather map — fronts with their proper pips, highs and lows with pressures.
| Surface analysis | Point forecast |
|---|---|
 |  |
| WPC coded surface analysis, live | Tap anywhere — KBMX, live |
Also on the forecast tail: rotation tracks (HRRR max updraft-helicity swaths — where storms are forecast to rotate, accumulated across the hours you scrub to) and near-surface wildfire smoke.
Every radar in the country stitched into one mosaic, updated every couple of minutes — the view for "what's happening everywhere" rather than "what's happening here" — plus rainfall accumulated over the last hour or day.
| National mosaic | 24-hour rainfall |
|---|---|
 |  |
| MRMS composite reflectivity, live | MRMS gauge-corrected precipitation, live |
There is also a multi-radar mosaic built the other way round: instead of a national 1 km product, every radar covering your view contributes its own base reflectivity at full resolution, composited nearest-radar-wins so neighbouring sites join without a seam. It shows which radars it used and how old the oldest scan in it is, because radars scan on their own schedules and a composite is never one instant.
Six radars, one picture — live N0B composite
Alongside them: individual lightning flashes from the GOES satellite's lightning mapper (fading as they age), cloud-to-ground lightning density, rotation tracks and azimuthal shear, MESH hail size and 24-hour hail swaths, surface precipitation type, and FLASH flash-flood recurrence intervals. Every gridded layer draws its own scale and units.
eventMotionDescription is parsed into a storm-motion vector —
warned-storm dot, projected 15/30/45/60-minute path, and ETA readouts to your
saved locations.urgent-priority phone push.
VIL density over the Mayfield, KY supercell — computed here from the 11 Dec 2021 volume, four years after it was recorded.
crates/hdf5lite), because the reference C library can't ship in the Android
build.R), and
screenshot / GIF / MP4 loop export.POST of one position and returns GET of the
list. There is no default relay; the endpoint sees your live position.F8) and an auto-tour of active
warnings (F9).hookecho:// link carrying the site,
place, zoom and (when you're scrubbed back) the time. Opens the app right
there — on Android, straight from the link.ffmpeg installed — the card says so plainly when
you don't, and everything else on it keeps working.
Cameras come from the FAA and from Caltrans, whose twelve districts publish
~3,300 cameras keyless and stream video from most of them. No other state DOT
publishes an open camera API, so that is the coverage, not a national map.
The electric field is NOAA's PPEF model: the equatorial ionospheric field
in mV/m, predicted from solar wind. That is space weather, not the storm over
your head — for the kV/m a chaser means, point the card at a ground field
mill's JSON in Settings and it charts that instead.
On Android the cards work the same, minus live video: the camera shows its
newest still instead, refreshed on the poll clock (a phone can't spawn ffmpeg,
and a video decoder per open card is not what its battery is for).
The same Rust app, rebuilt around the phone. KTLX 0.5° reflectivity, 20 May 2013, playing out of the archive at half speed with the tornado warnings of the day counting up on the alert badge.
Android is not the desktop squeezed onto a smaller screen — it is a Material 3 layout over the same renderer, the same data paths and the same action registry:
 |  |
| Map first. The radar owns the screen; one chip names the site and VCP. | One sheet, three snaps. Drag it up for the scrubber, speed, products and tilts; drag it to full for the archive. |
 |  |
| Everything else is a sheet. The same described, categorized action registry the desktop sidebar uses. | Alerts in view, tap to fly there and read the full text. |
WindowInsets, including the keyboard, so a focused field rises above it.hookecho --status prints what's happening at your saved locations — current
conditions from the nearest station and any active alert whose polygon comes
within that location's watch radius:
$ hookecho --status
Home: 74°F 62%rh SW 12kt (KOKC)
‼ Tornado Warning until 14:30
Cabin: 71°F 70%rh calm (KSWO)
Pass LAT,LON to report on somewhere you haven't saved, --line for a single
line about home (status bars), or --json for the whole report:
hookecho --status 35.3,-97.5
hookecho --status --line # 74°F 62%rh SW 12kt · ‼ Tornado Warning until 14:30
hookecho --status --json
Home Assistant, without leaving the machine hookecho runs on:
command_line:
- sensor:
name: Home weather alerts
command: "hookecho --status --json"
value_template: "{{ (value_json | selectattr('home') | first).alerts | count }}"
scan_interval: 300
polybar:
[module/hookecho]
type = custom/script
exec = hookecho --status --line
interval = 300
tmux:
set -g status-right '#(hookecho --status --line) | %H:%M'
hookecho --serve answers the same questions over HTTP, for the machine with no
display attached:
hookecho --serve # http://127.0.0.1:8080
hookecho --serve 9000 --bind 0.0.0.0
| Endpoint | What it returns |
|---|---|
/status.json | conditions and nearby alerts for every saved location |
/alerts.json | alerts only |
/obs.json | conditions only |
/snapshot.png?site=KTLX | a 1000×1000 radar render — &product=VEL, &basemap=none |
JSON answers are cached for a minute and snapshots for five, so polling it every 30 seconds costs the upstream services nothing extra.
There's a container for it, if that's easier than a systemd unit:
docker build -t hookecho .
docker run -d -p 127.0.0.1:8080:8080 \
-v ~/.config/hookecho:/root/.config/hookecho \
-v hookecho-cache:/root/.cache/hookecho hookecho
Mount your settings so it reports on your saved locations. The image is ~660 MB
because it carries Mesa's lavapipe software Vulkan driver — that's what renders
/snapshot.png with no GPU and no display attached.
It binds loopback unless you tell it otherwise. This endpoint says where you
live and what is warned there; --bind 0.0.0.0 exposes that to everything on
your network, and there is no authentication in front of it. Put it behind a
reverse proxy if it needs to leave the machine.
The command_line sensor above is the no-install path. For something richer
there's a custom component in custom_components/hookecho:
point it at a machine running --serve and you get, per saved location, a
device carrying temperature, dewpoint, humidity, wind, gust and pressure
sensors, an alert count sensor and an alert active binary sensor
(attributes: event, expiry, distance, escalation tier), plus one radar
camera entity showing the live snapshot.
Install via HACS as a custom repository, or copy the custom_components/hookecho
directory into your Home Assistant config/custom_components/ and restart. Then
add the integration and give it the host and port. Polling is once a minute,
which is the server's own cache window.
Remember the server has to be reachable from Home Assistant — that means
--bind 0.0.0.0 (or the container), and a network you're willing to expose your
saved locations on.
The app also builds for wasm and runs on a canvas — the same HookEchoApp, not
a cut-down viewer. Build it and serve it:
cargo install wasm-bindgen-cli # once
./scripts/web/build.sh
cargo run --release -- --serve 8080 --web-root web
Then open . Radar, the vector basemap, alerts and point
forecasts all work: the Level 2 buckets and api.weather.gov allow cross-origin
requests. This is a core viewer, though, not parity. There is no filesystem,
so settings are defaults each load and caches are memory-only; there is no live
chunk stream, no audio or spoken warnings, no camera, plugin or GPS support, and
any feed whose host refuses cross-origin requests simply doesn't load. Anything
that needs those is on the desktop and Android builds.
Placefiles work as they do everywhere else — URLs, icon sheets, a layer manager with per-file opacity and paint order. Beyond that, anything that can print a placefile can be a plugin: the app runs your command on a cadence, hands it the current site, view box, product and the instant on screen (so it works during an archive replay too), and draws what comes back. No SDK, no build step, no language requirement — the shipped examples are a Python script and twenty lines of shell. See docs/plugins.md.
crates/hookecho — the app: egui UI and wgpu render pipelines.crates/wxdata — data plumbing: Level 2 (AWS), MRMS, HRRR (future radar and
environment fields), NWS alerts with storm motion and escalation, IEM archived
warnings and live/archived storm reports, SPC outlooks and climatology, METAR,
NHC tropical, aviation SIGMETs, Area Forecast Discussions, ProbSevere,
placefiles, spotters, GOES GLM lightning, WPC surface fronts, NWS point
forecasts, TDS detection, sounding indices, and CAPPI/cross-section/3D
resampling.crates/nexrad-level3 — from-scratch NEXRAD Level 3 (RPG) product decoder:
storm-cell packets (15/19/20/23) and digital radial arrays (packet 16 —
DVL/EET/HHC), golden-tested against MetPy.crates/hdf5lite — minimal read-only HDF5 reader, just enough for the
netCDF-4 files NOAA publishes. Exists because the reference reader is a C
library the Android build can't take; checked against h5py on real granules.vendor/gribberish — vendored GRIB2 decoder (PNG-packing and MRMS
local-parameter fixes; grep hookecho patch:).scripts/shots — the screenshot harness that produced everything above.Also worth reading: docs/DATA.md — every feed the app decodes, with its cadence, latency and whether it needs a key; ROADMAP.md — what's next and what isn't planned; CONTRIBUTING.md — how the workspace fits together and what a patch has to clear.
Every data-backed feature has a headless CLI verifier (renders a PNG or prints a report without opening a window), e.g.:
cargo run --release -- --headless out.png KTLX --moment VEL --dealias
cargo run --release -- --headless-mrms mosaic.png
cargo run --release -- --headless-alerts # motion + escalation lines
cargo run --release -- --headless-archwarn 2013-05-20T20:00:00Z
cargo run --release -- --headless-env sbcape cape.png # sbcape|mlcape|srh1|srh3
cargo run --release -- --headless-field preciptype ptype.png
cargo run --release -- --headless-l3grid hhc KTLX hca.png # dvl|eet|hhc
cargo run --release -- --headless-metar KTLX
cargo run --release -- --headless-tropical
cargo run --release -- --headless-cappi KTLX 3 cappi.png
cargo run --release -- --headless-reports 2013-05-20T19:00Z 2013-05-20T21:00Z
cargo run --release -- --headless-afd KTLX
cargo run --release -- --headless-aviation
cargo run --release -- --headless-indices -97.5 35.3
cargo run --release -- --headless-glm # GOES satellite lightning
cargo run --release -- --headless-fronts # WPC surface analysis
cargo run --release -- --headless-hrrr uh 3 uh.png # refc|uh|smoke
cargo test # 303 offline unit tests
The screenshots in this README are regenerated by scripts/shots/shoot.sh,
which drives the real binary on a nested X display — see
scripts/shots/README.md.
MIT — see LICENSE.