Skip to content

Python tool for aircraft Doppler audio geolocation using historical ADS-B flight data (Source-available)

3.3 KB
Raw Blame

DOPPLERGEIST

DOPPLERGEIST — aircraft Doppler audio geolocation

DOPPLERGEIST is a Python CLI and local web application for aircraft Doppler audio geolocation. It detects candidate flyover signals in recordings, retrieves historical ADS-B flight tracks, models acoustic propagation, and ranks possible recording locations.

Automatic MP3 flyover analysis and ranked aircraft search

The illustrated real-recording experiment ranked a location 476 m from an inferred reference within a constrained search. The reference was not surveyed ground truth; independent blind geolocation accuracy has not been established. Read the experiment.

Install

Requires Python 3.11+. Intel Macs require Python 3.11–3.13; Python 3.14 on Intel macOS is not supported. Install FFmpeg separately so that both ffmpeg and ffprobe are on your PATH.

The full CLI and browser workflow require Linux or macOS. Native Windows wheels support discover only: analyze, serve, and job depend on POSIX facilities and fail to start. For the full workflow on Windows, use WSL with Linux, Python, and FFmpeg installed inside it.

For the CLI:

pipx install dopplergeist
dopplergeist --help

For a Python environment:

python -m pip install dopplergeist

Use

Detect candidate acoustic events without flight-data downloads:

dopplergeist discover recording.mp3 --output results/discovery

Launch the locally hosted upload interface:

dopplergeist serve --jobs jobs --online --port 8765

Open http://127.0.0.1:8765. For historical flight matching, a defensible UTC window for the first audio sample is required; the recording upload timestamp is not sufficient. Geographic searches can consume substantial time, storage, and downloaded aircraft/terrain data.

For CLI analysis with an independently supported recording clock:

dopplergeist analyze recording.mp3 --jobs jobs \
  --start-utc "2026-01-01T00:00:00Z" \
  --end-utc "2026-01-01T00:10:00Z" \
  --time-source "replace with independently supported clock evidence" \
  --online

Documentation

License

PolyForm Noncommercial License 1.0.0. Noncommercial uses are permitted under the terms of that license; commercial uses that are not otherwise authorized need a separate agreement with the applicable copyright holders. Earlier MIT-licensed releases retain the permissions originally granted for those versions. Commercial licensing details.