Acoustic geolocation from the Doppler curves of propeller aircraft.
Any outdoor (and many indoor) recordings contain faint, usually inaudible tones from aircraft flying over: the propeller blade-pass fundamental and its harmonics, between roughly 60 and 400 Hz. As the aircraft passes, the tone sweeps down in frequency. The exact shape of that sweep depends on where the listener was relative to the aircraft's real trajectory. With historical ADS-B data for every flight that day, each candidate location on the ground predicts a different curve, and the recording picks out the one that matches.
This is a reimplementation of the technique shown in colsto's video "I discovered a sound that leaks your exact location". No code was released with that video; this project is an open, automatic version of the method, with the search extended from a hand-drawn box to a whole continent.
Status
Validated on two recordings with known answers: the video author's one-hour reference clip (Oyster Bay, NY, 2026-09-08) and a 12-hour public eagle-cam stream (North Fort Myers, FL, 2024-12-28). Both are searched against every propeller flight over the continental US that day, with no region given.
| Oyster Bay | eagle cam | |
|---|---|---|
| flights that day, CONUS | 35,427 | 13,046 |
| flight pairs scored | 9,669 | 13,298 |
| rank of the true pair, two events | 1 | 15 |
rank with further detected flyovers (--extra) |
1 | 1 |
| best point from the truth | 32 m | 627 m |
| margin over the runner-up | 24 % | 13 % |
| verdict (p) | located (0.001) | located (0.06) |
| verdict from the two events alone | ambiguous (0.23) | ambiguous (0.48) |
| wall time, 16 threads, after the index | 18 min | 6 min |
A third recording, 12 hours from a railway camera in Atlanta searched the same way, is a negative: every pair of real flyovers puts the camera within 440 m and in the top 6–32 of tens of thousands of pairs, and none wins, because the modelled curve of the true track has a kink the audio lacks and a smoother track elsewhere fits better. Its archived stream had also lost 107 s in the middle, which put the extra flyovers on a different clock. The details and what they add to the roadmap are in the experiments page.
Two flyovers locate a recording when at least one passed low and to the side; two high, nearly overhead passes leave a plateau a few kilometres wide and a continent full of pairs that fit, which is what the extra flyovers are for. A margin is not a confidence: a box that does not contain the answer still returns a winner. So every search ends with a verdict: the winner is judged against the thousands of wrong pairs the same search scored on the same audio, and p is the chance a wrong winner would lead the next wrong pair by that much. The audio searched in a box 150 km from the answer gets "no match" (p = 0.88); of twenty searches of the railcam audio with no right answer among the pairs, two were called located, so p < 0.1 is a weak claim. The experiments behind these numbers, the regional searches that came first, and the failures along the way are in docs/experiments.md.
Usage
uv sync
uv run dopplertrack spectrogram recording.mp4 rec.npz
uv run dopplertrack detect rec.npz --band 60 300 --top 10 --out detected.json
uv run dopplertrack fit rec.npz --window 2090 2200 --band 95 200 --harmonics 2 --out ev1.json
uv run dopplertrack fit rec.npz --window 3020 3130 --band 95 195 --out ev2.json
uv run dopplertrack fetch 2026-09-08 day.npz --bbox 24 50 -125 -66 # one index per day, reused by every search
uv run dopplertrack search rec.npz --events ev1.json ev2.json --day day.npz --harmonics 2 1 \
--cands cands.npz --extra ev3.json ev4.json --out results.csv
uv run dopplertrack refine rec.npz results.csv --events ev1.json ev2.json --day day.npz \
--harmonics 2 1 --extra ev3.json ev4.json --out fine.csvspectrogramdecodes any audio or video with ffmpeg and whitens a high-resolution STFT of the 40–450 Hz band per frequency bin, so only changing tones stand out.detectfinds the flyovers: an ideal straight-pass Doppler curve (f0, speed, CPA distance, CPA time) is grid-searched in a sliding window and the local maxima are refined and ranked.fitdoes the same in one window you choose. Either writes event JSON thatsearchtakes as it is.fetchstreams one day of adsb.lol history from GitHub (4 GB, nothing stored), drops known jets, and writes the day index a search runs on: every flight resampled to 1 Hz in one Earth-centred frame, plus a sample per flight per 10 s.--bboxlimits it to a region,--archive DIRreads an archive already on disk.searchranks (location, flight pair) candidates over the index, see below.--bboxrestricts it to a region,--point LAT LONscores one known location (the quickest check on a recording whose answer you know), and one event with--utc TIMEsearches a single flyover whose time is known.--candscaches the candidate table, so a change to the scorer reruns only the scoring.--extrarescores the best pairs with further flyovers.refinelays a 50 m grid around one result, optionally with more events.
How the search works
- Join. Two events heard Δt apart at fitted slant distances d1 and d2 mean the two aircraft were within d1 + d2 of each other, Δt apart in emission time (give or take the propagation delays). That is a join over the day's 10 s samples with KD-trees, speed-gated, and it leaves a few tens of thousands of flight pairs out of hundreds of millions.
- Lens. For each pair, ground points are laid only where both flights could have been heard: a 1 km lattice first, then 200 m where it passes. Every point gets the exact closest point of approach to each real trajectory: slant distance (with a DEM for the observer's elevation), speed, and the heard CPA time. Points must hear an event-1-like pass, then exactly Δt later an event-2-like pass, with no other propeller flight within 6 km in between.
- Score. The Doppler curve each survivor would hear is modelled from the real trajectory (emission-time radial velocity) and scored against the spectrogram. Event 1's placement is swept over small time shifts and f0 scales, which absorb measurement error; event 2 is placed with the same shift, locked to the flight geometry. Score = brightness under both curves.
- More events. For the best pairs, each further flyover is matched to a
flight at the pair's best point and scored at all of its points with that
point's shift, so every event is on one clock.
refinedoes the same on a fine grid. - Verdict. At most one scored pair is right; the rest are the null distribution for this recording. The upper tail of their scores is fitted as exponential, and the gap between the winner and the best other pair is tested against it: located (p < 0.1), ambiguous (p < 0.5), or no match.
The ideal-curve fits only seed the gates (--v-tol, --d-tol; open them
for a faint or turning pass); ranking uses real trajectories throughout.
--score ridge scores how closely a curve follows the ridge traced in the
window instead of the brightness under it.
Differences from the method in the video
The physics and the search strategy are the author's. What differs:
- Automatic curve measurement. The video slides f0, speed, distance and
CPA time by hand until the overlay looks right.
fitanddetectdo it with a grid search plus Nelder-Mead on the whitened window. - Pairs of flights, not points along one flight. The video lays points along every flight matching event 1 at the fitted distance and tests them for event 2, which needs tight hand-fitted ranges. Joining flight pairs on the geometry of both events first stays cheap under the wide gates an automatic fit needs; with tight gates it reduces to the video's method.
- Harmonic-aware fitting and scoring, where a flyover shows a second harmonic.
- Open data path. adsb.lol daily archives, ICAO Doc 8643 engine classes and AWS terrain tiles, each with a loader; nothing scraped or paid.
- One command for every search. A box, a known point, or one flyover with a known time are options on the same search, not separate methods.
Kept on purpose: emission-time radial velocity, propagation-delayed CPA times, slant distance with a DEM, the inter-event offset filter, the silence filter, and locked two-event scoring.
Data sources (all free)
| Need | Source |
|---|---|
| Historical ADS-B | adsb.lol globe_history_YYYY GitHub releases (~4 GB/day) |
| Aircraft engine class | OpenSky mirror of ICAO Doc 8643 |
| Elevation | AWS Terrain Tiles (Terrarium) |
Development
The suite runs on synthetic flights in about three minutes. The Oyster Bay
check against the real recording is opt-in: set DOPPLERTRACK_OYSTER_BAY
to a directory holding rec.npz and traces_ny.npz (see
tests/test_oyster_bay.py). The original design notes are in
docs/superpowers/specs/; CHANGELOG.md lists the changes
per release.
Releasing
Pushing a tag vX.Y.Z that matches the version in pyproject.toml runs
.github/workflows/release.yml: tests, sdist and wheel, a GitHub Release
with generated notes, and PyPI through trusted publishing.
uv version 0.3.0 # bump pyproject.toml git commit -am "Release 0.3.0" git tag v0.3.0 && git push && git push --tags
