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.
The whole app as wasm, on live data, with nothing to install.
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.
-lightgrey){kind=icon}
Hook_Echo-WX-x86_64.AppImage from
Releases, chmod +x, run. Debian/Ubuntu users can install
hookecho__amd64.deb from the same place
(sudo apt install ./hookecho_*.deb) to get the menu entry and icon.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.md.Hook_Echo-WX-macos.zip from
Releases. The build is made and smoke-tested in CI but has
never been run on real Apple hardware, and it is ad-hoc signed, so Gatekeeper
will ask before it opens. Homebrew users can build it instead:
brew install --HEAD d4vid87/hookecho/hookecho (formula in
packaging/homebrew). macOS testers wanted — there
is no Apple hardware behind this project, so an
issue saying what did or did not work is the only way this
build stops being experimental.flatpak install hookecho does not.cargo 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 artifacts, if you want the newest work without waiting for a tag.
First launch opens a four-card setup: home radar site, map and theme (13 built
in), and how warnings should reach you (chime and/or ntfy.sh
push to your phone). The last card offers a 60-second tour — four stops
spotlighted on the live map, two of which you finish by doing the thing rather
than reading about it. Neither is forced, and both re-run from the sidebar's
App section, Ctrl+K, or Settings → General.
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.A pane layout is a dozen clicks to rebuild — two sites, their products and tilts, the overlays and field layers that go with them — and it is the same dozen clicks every time. Save the arrangement from the command palette and restore it in one.
Three are there on first run: Chase (reflectivity beside storm-relative velocity, cameras locked), National overview (the MRMS mosaic under the warnings), and Analysis (one storm at four heights). They adopt whichever radar is on screen, and deleting them is final.
Everything the app downloads is cached and every cache is trimmed to a cap at startup. Settings → Storage shows each one's size against that cap, with a button to clear it and a button to open it. Nothing there is irreplaceable — clearing a cache costs the next fetch and nothing else.
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 |
/cells.json?site=KTLX | every storm cell the radar's algorithms track — hail size, tops, VIL, TVS, forecast track |
/health.json | version, uptime and how stale the answers are, for a container health check |
/snapshot.png?site=KTLX | a radar render — &product=VEL, &basemap=none, &size=512 (256–2048), &zoom=6.5, &tilt=1 |
JSON answers are cached for a minute and snapshots for five, so polling it every 30 seconds costs the upstream services nothing extra.
The server binds loopback and answers anyone who asks. Putting it on a network
(--bind 0.0.0.0, or a container port that isn't 127.0.0.1:) means publishing
where you live, so set a token first — serve_token in settings.json, or
--serve-token on the command line, which wins:
curl -H 'Authorization: Bearer hunter2' http://boxname:8080/status.json
curl 'http://boxname:8080/snapshot.png?site=KTLX&token=hunter2'
Every route is behind it, /metrics and the CORS proxy included. The
?token= form is there for dashboards that can only fetch a URL and have no
place to put a header.
For a desktop widget rather than a server, --snapshot writes the same render
straight to a file:
hookecho --snapshot ~/.cache/radar.png KTLX --size 480 --zoom 7 --every 120
It renders, renames the finished file into place (so a widget polling on its own
clock never catches a half-written PNG), and repeats. Point conky, feh --reload, or a wallpaper script at the file.
There's a container for it, if that's easier than a systemd unit:
docker run -d -p 127.0.0.1:8080:8080 \
-v ~/.config/hookecho:/root/.config/hookecho \
-v hookecho-cache:/root/.cache/hookecho \
ghcr.io/d4vid87/hookecho:latest
:latest is rebuilt from main on every push; released versions are tagged
(:0.7.0). docker build -t hookecho . still works if you'd rather build it.
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), a nearest storm
sensor giving the distance to the closest cell the radar is tracking
(attributes: cell id, bearing, max dBZ, hail size, TVS), plus one radar
camera entity showing the live snapshot.
The nearest-storm sensor is the one to automate on: it answers "is a storm coming" minutes before anybody issues a warning, and goes unavailable — never zero — when nothing is being tracked.
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. Set serve_token if that network is not one you control.
A hosted build of main runs at **** if you only
want to look at it.
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. Live chunk streaming works too, so a browser tab updates sweep by
sweep during a scan rather than waiting out the whole volume. Settings persist to
localStorage, and alert sounds and spoken warnings play through the browser's
own audio and speechSynthesis. This is a core viewer, though, not parity.
There is no filesystem, so caches are memory-only and imports and exports are
out; there is 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.
The bundle is static files plus one CORS proxy — the feeds NOAA serves without
Access-Control-Allow-Origin need an origin of your own in front of them, or the
page loads and draws nothing. The proxy's rules (exact-match allowlist, GET only,
64 MB cap, narrowed content types) live once in web/_worker.js/proxy-core.js;
each host is a few lines of wiring around it.
The Worker also answers /geo.json with the visitor's rough position from
Cloudflare's own geo-IP, which is how the demo opens on the radar nearest you
instead of the configured default site. No third-party lookup and no browser
permission prompt; a #goto= deep link still wins. A host without it just opens
on the default.
Cloudflare Pages — web/_worker.js/, deployed by
.github/workflows/demo.yml. That's what hookecho.pages.dev is, and it is the
only host this repo deploys to.
Any other host works the same way if it can run one small function on
/proxy/*. A purely static host cannot: without the proxy the app opens, and
then sits empty.
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.
hookecho://goto/… opens the app at a place and, optionally, a time. The
desktop registers the scheme on install (Linux .desktop, Windows registry,
macOS bundle); on Android a notification tap uses the same path.
hookecho://goto/KTLX # a radar site
hookecho://goto/KTLX,-97.28,35.33,9 # site, lon, lat, zoom
hookecho://goto/,-97.28,35.33,9 # no site: just the view
hookecho://goto/KTLX,-97.28,35.33,9,2013-05-20T20:00:00Z # and an instant
hookecho://goto/KTLX,-97.28,35.33,9,VEL,1 # and a product and tilt
The timestamp is RFC 3339 and puts the timeline where it was, so a link can
point at a moment in the archive rather than at "now". The trailing fields are
recognized by shape, not position: a timestamp, a product code (VEL, ZDR,
CC, …) and a tilt index can appear in any order, and any you leave out keep
whatever the person opening the link already had.
The browser build takes the same thing in the URL fragment, which never leaves the client — no server sees where you are looking:
https://hookecho.pages.dev/#goto=KTLX,-97.28,35.33,9,VEL
"Copy link to this view" in the command palette writes the right form for whichever build you are running.
Every action in the command palette is bindable, and the defaults are listed in
Settings → Hotkeys. ? opens the cheat sheet over whatever is on screen. The
ones worth knowing before you look:
| Key | What it does |
|---|---|
← → | step one frame |
R | instant replay from the in-RAM buffer |
Page Up / Page Down | tilt up / down |
1–6 | products: reflectivity, velocity, spectrum width, ZDR, PHI, CC |
Ctrl+K | command palette |
L | the drawer |
A | the alert panel |
Z | cycle the basemap |
M | mute |
F3 | change site |
? | cheat sheet |
The whole interface is reachable from the keyboard, and the widget tree is published to screen readers (AT-SPI on Linux, UI Automation on Windows). There is a High contrast theme in Settings → General for low vision and for reading the screen in direct sun, an OLED black theme for night use, and colorblind-safe reflectivity and velocity color tables in Settings → Palettes (a viridis ramp whose brightness rises with dBZ, and a blue/orange diverging velocity table — red/green diverging tables do not survive protan or deutan vision).
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/GUIDE.md — the task-by-task user guide, "how do I actually do this"; 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; ARCHITECTURE.md — how the code is shaped; CONTRIBUTING.md — how the workspace fits together and what a patch has to clear; CHANGELOG.md — what changed per release; docs/promotion.md — how a release is cut and announced.
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 run --release -- --headless-rules KTLX # would your alert rules fire?
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.