From curves to a tested match.

1. Install and test

Download workflow ZIP ↓

Extract the ZIP. Open a terminal in its doppler-workflow folder. Requires Python 3.10 or newer.

python3 -m venv .venv
.venv/bin/python -m pip install -r requirements.txt
.venv/bin/python -m doppler_lab demo --output demo-run

Open demo-run/results/report.html. This is explicitly synthetic: it checks retrieval-independent matching, shared timing, refinement and reporting. On Windows use .venv\Scripts\python.

2. Prepare a recording job

On the lab page, analyze your recording, review which saved curves belong in the match, and choose Export matching job. Save job.json in a new folder inside the extracted companion folder. It preserves the measured frequencies and original timestamps.

.venv/bin/python -m doppler_lab check my-recording/job.json

The check covers the bounded search mode, which needs an approximate UTC start and receiver bounds. If only the date is known, use the experimental day search below: it fits location and recording time together. Unknown values remain unset; upload dates are never treated as recording dates.

Alternatively prepare a job from an existing curve export:

.venv/bin/python -m doppler_lab init detected-doppler-curves.json --output my-recording --events 1,3

Event numbers refer to positions in your exported file. The supplied example’s two prominent flyovers were events 1 and 3; this is not a universal selection rule.

3. Plan, fetch, extract

adsb.lol publishes openly licensed daily flight archives. Planning reads release metadata only. Fetching is explicit and refuses to exceed your selected byte budget.

.venv/bin/python -m doppler_lab archive-plan --date YYYY-MM-DD --output archive-plan.json
.venv/bin/python -m doppler_lab archive-fetch archive-plan.json --cache archive-cache --max-mb 4096

Inspect the plan before fetching: daily archives can be several gigabytes. Keep every part of the same release. The tool reads the split tar stream safely and verifies available checksums. Then extract the needed aircraft and emission-time interval:

.venv/bin/python -m doppler_lab archive-extract archive-cache/*.tar.* \
  --start ORIGINAL_START_WITH_TIMEZONE --end ORIGINAL_END_WITH_TIMEZONE \
  --flight-id AIRCRAFT_HEX --output my-recording/tracks.json --max-mb 4096

Replace the uppercase placeholders. Include time before the audible events for sound propagation. Omit --flight-id to inspect all aircraft within the time interval, subject to the 100-track / 500,000-point matching limit. For an unknown clock and location, use the full-day index and candidate search below instead. The README covers UTC-midnight boundaries and archive details.

4. Search with only a date

For two measured flyovers, build a full-day index and search flight pairs. No recording start or receiver bounds are required.

.venv/bin/python -m doppler_lab archive-index archive-cache/*.tar.* \
  --date YYYY-MM-DD --output day-tracks.jsonl --max-mb 6144
.venv/bin/python -m doppler_lab day-search my-recording/job.json \
  --tracks day-tracks.jsonl --date YYYY-MM-DD

The index selects aircraft intersecting 20–55°N, 130–60°W. The search uses curve shapes, sound-travel delay and one shared recording clock to prune candidates, then refines a limited shortlist. Inspect day-results/report.html and its coverage/work limits. This is an experimental heuristic search, not an exhaustive location guarantee. UTC dates can differ from local recording dates; adjacent archives may be needed.

5. Bounded search and evidence

.venv/bin/python -m doppler_lab run my-recording/job.json

The run is offline. It compares flight geometry and sound-travel delay with measured curves, then refines location and a shared clock using SciPy. Inspect results/report.html, result.json, and curves.csv. The report includes alternative grid matches and limitations. A supplied reference location is checked only after fitting.

Fit error is not a confidence probability. The model currently assumes constant source pitch, a stationary recorder, constant sound speed and compatible altitude datums. Terrain, wind and atmospheric refraction are not corrected automatically.

What the comments added

We reviewed a selection of top comments and relevant creator replies. These are leads for validation, not proof of accuracy:

• The creator confirms clear power-line hum: electrical-network frequency could help recover time, but a suitable reference for the same US grid and date is still needed.
• Pressure versus geometric altitude: preserve labels and report uncertainty; pressure altitude is not silently converted into geometric height.
• Sound speed changes with the atmosphere: sensitivity tests should precede precise location claims.
• False tonal curves and filter steepness suggest useful robustness tests. A fitted curve alone does not establish an aircraft identity.

The transcript names September 8 and the continental US. The user supplied 2026 as the recording year. The full-hour start time is unknown and can be fitted jointly with location; its 20:37 UTC mention describes a separate one-minute example. The creator explicitly says no code or tools are being released.