1337isnot1337/DOPPLERGEIST

What it does

DOPPLERGEIST is an experimental OSINT tool for estimating where an audio recording was captured. It measures Doppler-shifted frequency tracks from overflying aircraft, retrieves historical ADS-B trajectories for a justified recording-time window, models Doppler frequency and sound arrival time, and ranks candidate receiver locations. Independent flyovers are reconciled, and competing explanations can remain instead of forcing a single answer.

The workflow combines four stages: acoustic measurement, flight-trajectory collection (by default from the yearly ADSB.lol historical archive), physical modelling, and geographic search. The README reports a target of a supported estimate within 1,000 m, with a preference for 100–500 m, but also states that independent nationwide accuracy on real recordings has not yet been established.

Install and verify

Prerequisites are Python 3.11+, FFmpeg (ffmpeg and ffprobe on PATH) and Git. The README gives Linux/macOS commands specifically:

git clone https://github.com/1337isnot1337/DOPPLERGEIST.git
cd DOPPLERGEIST
python -m venv .venv
.venv/bin/python -m pip install .
.venv/bin/dopplergeist --version

Optional native acoustic and ridge backends build when a compatible C compiler is present; Python fallbacks remain available, and the project documents how to check which backend is active.

Run an analysis

Start with automatic event discovery, which scans a whole recording without requiring flight data or a data-service account:

.venv/bin/python scripts/discover_audio.py \
  path/to/recording.mp3 \
  --output results/my-discovery

Results are written to results/my-discovery/summary.json and diagnostics under discovery/. For location search, run dopplergeist analyze path/to/recording.mp3 --jobs jobs with a defensible UTC window for the first audio sample (--start-utc, --end-utc), a --time-source describing the evidence, and --online to enable historical data download. Without clock evidence the job returns needs_input. A job ID is printed; follow it with dopplergeist job JOB_ID --jobs jobs --watch.

A browser workflow is also available: dopplergeist serve --jobs jobs --online --max-runtime 14400 --port 8765, then open http://127.0.0.1:8765 and upload a recording with a UTC window. Initial acquisition can take hours and tens of gigabytes, with no automatic disk-space limit.

Constraints and reliability

A defensible recording clock is mandatory: audio-relative timing does not identify which day's flights to search, and file modification or upload times do not supply it. Data acquisition, flight archives and terrain require significant disk space, and runtime budgets can leave a search incomplete. Native Windows execution is unverified.

The README is unusually explicit about limits. No accepted blind real localization has been reported; tests on four NASA recordings produced mostly zero or unsupported proposals, and the one 474 m conditional fit may come from a background aircraft rather than the measured drone. Some searches end inconclusive / search_incomplete. Missing events, incomplete flight coverage, competing locations or inadequate sensitivity evidence can all force abstention. The code is MIT-licensed; recordings, ADS-B data and terrain keep their own rights. The author describes the project as fully AI-assisted and early beta.

HotRepo 点评

DOPPLERGEIST appeared on HotRepo's new Python-project list on 2026-11-03, its first tracked day, gaining 106 stars and 17 forks in a window of roughly 20 hours from its 2026-11-02 creation. There is no all-language daily rank record and no discussion thread data, so the available evidence is a strong single-day debut for a niche OSINT project rather than a demonstrated trend. What stands out technically is the documentation's refusal to claim validated geolocation: the benchmark tables separate synthetic, configured and real-data results, and the real-data section explicitly says none established an independently accepted automatic location. That honesty is more informative than the star count for anyone considering use.

Project source and documentation