Skip to content

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

Add FAQ section to README.md

Cinna Davisa359acb3f48f
diff --git a/README.md b/README.md
index 97c6d82..adc8f5f 100644
--- a/README.md
+++ b/README.md
@@ -20,6 +20,16 @@ Designed for local experimentation, audio forensics research, and investigation
[Current status](#current-status) · [Quickstart](#quickstart) · [How it works](#how-it-works) · [Results](#experimental-results) · [Documentation](#documentation-and-references)
+## Is Colsto's airplane Doppler geolocation code available?
+
+Colsto did not publicly release the code or tools used in his [aircraft Doppler geolocation demonstration](https://www.youtube.com/watch?v=UytYrhYLOKI).
+
+**DOPPLERGEIST is an independent Python implementation** inspired by that technique. It does not contain Colsto's original code and is not affiliated with him.
+
+If you're looking for a tool to analyze airplane Doppler signatures in audio recordings and compare them against historical ADS-B flight tracks, DOPPLERGEIST provides an experimental implementation.
+
+See the [Quickstart](#quickstart) to get started.
+
## Current status
| Area | Available now | Entry point or remaining work |
@@ -122,6 +132,40 @@ Open `http://127.0.0.1:8765` and upload a recording. Supply a defensible UTC win
For more detail please see [Methodology](docs/METHODOLOGY.md).
+## Frequently asked questions
+
+### Can I geolocate an MP3 recording?
+
+DOPPLERGEIST supports MP3 recordings and can automatically search audio for candidate aircraft Doppler signatures. It compares acoustic measurements with historical flight trajectories to investigate possible recording locations.
+
+### Do I need to know when the audio was recorded?
+
+Yes, for historical flight matching. DOPPLERGEIST needs a defensible recording start time or bounded UTC time window. Without it, acoustic analysis can still run, but the geographic search returns `needs_input` rather than guessing a location.
+
+### Can DOPPLERGEIST run offline?
+
+Partially. Automatic audio event discovery works locally without downloading flight data. Geographic matching requires historical aircraft and terrain data, which can be downloaded with `--online` or supplied through a configured offline data source.
+
+Initial data acquisition may require hours and tens of gigabytes of storage.
+
+### How accurate is DOPPLERGEIST?
+
+DOPPLERGEIST is experimental software.
+
+In one real-MP3 experiment, the highest-ranked candidate was approximately 476 meters from the reference location under a constrained regional search.
+
+Independent blind geolocation accuracy on real recordings has not yet been established. The software may return inconclusive results when the evidence is insufficient.
+
+### Can I upload an audio file through a browser?
+
+Yes. DOPPLERGEIST includes a locally hosted browser interface. After installation, run `dopplergeist serve` to start the application, then open the local address it provides.
+
+### Is DOPPLERGEIST free and open source?
+
+DOPPLERGEIST is free to use for permitted noncommercial purposes and is source-available under the [PolyForm Noncommercial License 1.0.0](LICENSE).
+
+The license permits noncommercial use, modification, and redistribution subject to its terms. Commercial use requires separate authorization.
+
## Search and scientific limits
The target is a supported location estimate within **1,000 m**, preferably **100–500 m or better**, using real recordings without truth-informed event selection or geographic bounds. Evaluation reports 100/500/1,000 m thresholds without rewriting historical experiments' original thresholds.