Python tool for aircraft Doppler audio geolocation using historical ADS-B flight data (Source-available)
Python acoustic-geolocationads-baircraft-trackingairplaneaudio-forensicsdoppler-effectdoppler-shiftgeolocationosintsignal-processing
Add FAQ section to README.md
Cinna Davisa359acb3f48f
diff --git a/README.md b/README.mdindex 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 winFor 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 limitsThe 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.