dopplergeist 0.1.1__tar.gz

dopplergeist-0.1.1/LICENSE

@@ -0,0 +1,75 @@
+# PolyForm Noncommercial License 1.0.0
+
+<https://polyformproject.org/licenses/noncommercial/1.0.0>
+
+Required Notice: Copyright 2026 Cinna Davis
+
+## Acceptance
+
+In order to get any license under these terms, you must agree to them as both strict obligations and conditions to all your licenses.
+
+## Copyright License
+
+The licensor grants you a copyright license for the software to do everything you might do with the software that would otherwise infringe the licensor's copyright in it for any permitted purpose.  However, you may only distribute the software according to [Distribution License](#distribution-license) and make changes or new works based on the software according to [Changes and New Works License](#changes-and-new-works-license).
+
+## Distribution License
+
+The licensor grants you an additional copyright license to distribute copies of the software.  Your license to distribute covers distributing the software with changes and new works permitted by [Changes and New Works License](#changes-and-new-works-license).
+
+## Notices
+
+You must ensure that anyone who gets a copy of any part of the software from you also gets a copy of these terms or the URL for them above, as well as copies of any plain-text lines beginning with `Required Notice:` that the licensor provided with the software.  For example:
+
+> Required Notice: Copyright Yoyodyne, Inc. (http://example.com)
+
+## Changes and New Works License
+
+The licensor grants you an additional copyright license to make changes and new works based on the software for any permitted purpose.
+
+## Patent License
+
+The licensor grants you a patent license for the software that covers patent claims the licensor can license, or becomes able to license, that you would infringe by using the software.
+
+## Noncommercial Purposes
+
+Any noncommercial purpose is a permitted purpose.
+
+## Personal Uses
+
+Personal use for research, experiment, and testing for the benefit of public knowledge, personal study, private entertainment, hobby projects, amateur pursuits, or religious observance, without any anticipated commercial application, is use for a permitted purpose.
+
+## Noncommercial Organizations
+
+Use by any charitable organization, educational institution, public research organization, public safety or health organization, environmental protection organization, or government institution is use for a permitted purpose regardless of the source of funding or obligations resulting from the funding.
+
+## Fair Use
+
+You may have "fair use" rights for the software under the law. These terms do not limit them.
+
+## No Other Rights
+
+These terms do not allow you to sublicense or transfer any of your licenses to anyone else, or prevent the licensor from granting licenses to anyone else.  These terms do not imply any other licenses.
+
+## Patent Defense
+
+If you make any written claim that the software infringes or contributes to infringement of any patent, your patent license for the software granted under these terms ends immediately. If your company makes such a claim, your patent license ends immediately for work on behalf of your company.
+
+## Violations
+
+The first time you are notified in writing that you have violated any of these terms, or done anything with the software not covered by your licenses, your licenses can nonetheless continue if you come into full compliance with these terms, and take practical steps to correct past violations, within 32 days of receiving notice.  Otherwise, all your licenses end immediately.
+
+## No Liability
+
+***As far as the law allows, the software comes as is, without any warranty or condition, and the licensor will not be liable to you for any damages arising out of these terms or the use or nature of the software, under any kind of legal claim.***
+
+## Definitions
+
+The **licensor** is the individual or entity offering these terms, and the **software** is the software the licensor makes available under these terms.
+
+**You** refers to the individual or entity agreeing to these terms.
+
+**Your company** is any legal entity, sole proprietorship, or other kind of organization that you work for, plus all organizations that have control over, are under the control of, or are under common control with that organization.  **Control** means ownership of substantially all the assets of an entity, or the power to direct its management and policies by vote, contract, or otherwise.  Control can be direct or indirect.
+
+**Your licenses** are all the licenses granted to you for the software under these terms.
+
+**Use** means anything you do with the software requiring one of your licenses.

dopplergeist-0.1.1/MANIFEST.in

@@ -0,0 +1 @@
+prune evidence

dopplergeist-0.1.1/PKG-INFO

@@ -0,0 +1,105 @@
+Metadata-Version: 2.4
+Name: dopplergeist
+Version: 0.1.1
+Summary: Aircraft Doppler audio geolocation using historical flight tracks
+License-Expression: PolyForm-Noncommercial-1.0.0
+Project-URL: Homepage, https://github.com/1337isnot1337/DOPPLERGEIST
+Project-URL: Documentation, https://github.com/1337isnot1337/DOPPLERGEIST/tree/main/docs
+Project-URL: Source, https://github.com/1337isnot1337/DOPPLERGEIST
+Project-URL: Issues, https://github.com/1337isnot1337/DOPPLERGEIST/issues
+Project-URL: Releases, https://github.com/1337isnot1337/DOPPLERGEIST/releases
+Keywords: aircraft,doppler,acoustic-geolocation,audio-forensics,ads-b,signal-processing
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Science/Research
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Programming Language :: Python :: Implementation :: CPython
+Classifier: Topic :: Scientific/Engineering :: Physics
+Classifier: Topic :: Multimedia :: Sound/Audio :: Analysis
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+License-File: licenses/MIT-legacy.txt
+License-File: src/dopplergeist/web/leaflet-license.txt
+Requires-Dist: numpy
+Requires-Dist: scipy
+Requires-Dist: pandas
+Requires-Dist: soundfile
+Requires-Dist: pyproj
+Requires-Dist: rasterio
+Requires-Dist: matplotlib
+Requires-Dist: requests
+Requires-Dist: pyarrow
+Requires-Dist: shapely>=2.0
+Provides-Extra: test
+Requires-Dist: pytest>=8; extra == "test"
+Dynamic: license-file
+
+# DOPPLERGEIST
+
+![DOPPLERGEIST — aircraft Doppler audio geolocation](https://raw.githubusercontent.com/1337isnot1337/DOPPLERGEIST/main/assets/dopplergeist-banner.svg)
+
+**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](https://raw.githubusercontent.com/1337isnot1337/DOPPLERGEIST/main/assets/livermore-automatic-mp3.png)
+
+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](https://github.com/1337isnot1337/DOPPLERGEIST/blob/main/docs/LIVERMORE_DEMO.md).
+
+## Install
+
+Requires **Python 3.11+**. Install **FFmpeg** separately so that both `ffmpeg` and `ffprobe` are on your `PATH`.
+
+For the CLI:
+
+```sh
+pipx install dopplergeist
+dopplergeist --help
+```
+
+For a Python environment:
+
+```sh
+python -m pip install dopplergeist
+```
+
+## Use
+
+Detect candidate acoustic events without flight-data downloads:
+
+```sh
+dopplergeist discover recording.mp3 --output results/discovery
+```
+
+Launch the locally hosted upload interface:
+
+```sh
+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:
+
+```sh
+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
+
+- [Source code and full README](https://github.com/1337isnot1337/DOPPLERGEIST)
+- [Installation and reproducibility](https://github.com/1337isnot1337/DOPPLERGEIST/blob/main/docs/SETUP.md)
+- [How the geolocation pipeline works](https://github.com/1337isnot1337/DOPPLERGEIST/blob/main/docs/METHODOLOGY.md)
+- [Validation and limitations](https://github.com/1337isnot1337/DOPPLERGEIST/blob/main/docs/CONFIDENCE.md)
+- [Issues and feature requests](https://github.com/1337isnot1337/DOPPLERGEIST/issues)
+
+## 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](https://github.com/1337isnot1337/DOPPLERGEIST/blob/main/COMMERCIAL-LICENSING.md).

dopplergeist-0.1.1/README.md

@@ -0,0 +1,202 @@
+
+<h1 align="center">DOPPLERGEIST</h1>
+<p align="center">Aircraft Doppler Audio Geolocation</p>
+<p align="center">
+  <img src="assets/dopplergeist-banner.svg" alt="DOPPLERGEIST — Acoustic geolocation through Doppler analysis" width="100%">
+</p>
+
+**DOPPLERGEIST** is a source-available Python toolkit for aircraft Doppler audio geolocation. It detects acoustic flyover patterns in recordings, matches them against historical ADS-B flight trajectories, and ranks possible recording locations.
+
+The project provides automatic audio discovery, aircraft-data acquisition, geographic search, and a locally hosted browser interface. It is built for acoustic geolocation research, audio forensics, and studying location information carried by background sound.
+
+<h3 align="center">Example: automatic MP3 analysis</h3>
+
+![Automatic MP3 flyover and ranked aircraft search](assets/livermore-automatic-mp3.png)
+
+<sub>A real MP3 was analyzed without manually supplied event windows, frequency bands, or flight IDs. DOPPLERGEIST selected 466 nearby aircraft from a historical flight archive and ranked 105 candidate locations. The leading candidate was **476 m from an inferred reference** in a city-sized search with an approximately 10-second recording-time window. The reference is not surveyed ground truth, and the run remained inconclusive. [View the full experiment and ranking.](docs/LIVERMORE_DEMO.md#all-aircraft-archive-mp3-ranking)</sub>
+
+[Capabilities](#capabilities) · [Quickstart](#quickstart) · [How it works](#how-it-works) · [FAQ](#frequently-asked-questions) · [Results](#validation-and-results) · [Documentation](#documentation-and-references)
+
+## Is Colsto's airplane Doppler geolocation code available?
+
+Colsto did not release the original tools or source code from his [aircraft Doppler geolocation demonstration](https://www.youtube.com/watch?v=UytYrhYLOKI).
+
+**DOPPLERGEIST is an independent implementation**, inspired by the approach in that video. It contains independently written code and is not affiliated with Colsto. If you want to experiment with aircraft Doppler signatures and historical flight-track matching, you can install and run DOPPLERGEIST locally.
+
+## Capabilities
+
+| Capability | What DOPPLERGEIST provides |
+| --- | --- |
+| **Automatic acoustic discovery** | Scans an entire recording for moving frequency tracks and groups related harmonics, without manually selecting event windows or frequency bands. |
+| **Historical aircraft data** | Acquires and indexes ADSB.lol flight archives; caches reusable trajectory, terrain, and geoid inputs. |
+| **Location search** | Compares predicted Doppler and sound-arrival patterns across candidate receiver locations, including evidence from multiple independent flyovers. |
+| **Geographic profiles** | Search profiles for the contiguous United States, Germany, Spain, and metropolitan France (including Corsica), with optional user-provided regional bounds. |
+| **Local browser application** | Recording uploads, persistent analysis jobs, inspectable results, progress monitoring, and supported resume/cancellation workflows. |
+| **Research and reproducibility** | Configured measurement/replay commands, documented experiments, diagnostic artifacts, and decision rules for unresolved searches. |
+
+The integrated application and command-line workflow are available on `main`. See [how it works](#how-it-works) and [validation and results](#validation-and-results) for the distinction between a ranked hypothesis and an accepted location.
+
+## Quickstart
+
+**PyPI distribution:** Once the first PyPI release is published, install the CLI without cloning the repository:
+
+```bash
+pipx install dopplergeist
+dopplergeist --help
+```
+
+To use the Python package in an existing environment instead, run `python -m pip install dopplergeist`. Install **FFmpeg** separately; `ffmpeg` and `ffprobe` must be available on `PATH`. See [PyPI release status and setup](docs/PYPI.md). The examples below use `.venv/bin/dopplergeist`; users of the `pipx` installation can run `dopplergeist` directly.
+
+**Source checkout (available now):**
+
+Requirements: **Python 3.11+**, **FFmpeg** (`ffmpeg` and `ffprobe` on `PATH`), and Git. These commands target Linux and macOS:
+
+```bash
+git clone https://github.com/1337isnot1337/DOPPLERGEIST.git
+cd DOPPLERGEIST
+python -m venv .venv
+.venv/bin/python -m pip install .
+.venv/bin/dopplergeist --version
+```
+
+A compatible C compiler enables optional native acceleration; Python fallbacks are available. For environment checks and alternative installation methods, see [Setup](docs/SETUP.md), [Performance](docs/PERFORMANCE.md), and [Docker](docs/DOCKER.md).
+
+### Option A: use the browser interface
+
+```bash
+.venv/bin/dopplergeist serve --jobs jobs --online --max-runtime 14400 --port 8765
+```
+
+Open **http://127.0.0.1:8765** and upload a recording. For historical flight matching, supply a supported UTC time window for the **first audio sample**. The interface runs locally; `--online` permits downloading public aircraft and terrain data.
+
+### Option B: analyze a recording from the CLI
+
+```bash
+.venv/bin/dopplergeist analyze path/to/recording.mp3 --jobs jobs
+```
+
+This creates a persistent job and runs acoustic analysis. To enable historical matching, provide `--start-utc`, `--end-utc`, and `--time-source` with the evidence for the recording clock, plus `--online` if the required data is not already configured locally. Without a defensible recording time, the job reports `needs_input` rather than assuming a date.
+
+For a full online regional analysis, allow enough time for both historical-data acquisition and search. The job limit defaults to **one hour**; initial acquisition can take longer. Replace the sample clock window, source description, and Berlin bounds below with independent evidence for your recording, and increase `--max-runtime` if your data and search scope require it:
+
+```bash
+.venv/bin/dopplergeist analyze path/to/recording.mp3 \
+  --start-utc "2026-01-01T00:00:00Z" \
+  --end-utc "2026-01-01T00:10:00Z" \
+  --time-source "replace with the source establishing the first-sample clock" \
+  --country DE --bounds 13.0 52.0 14.0 53.0 \
+  --online --max-runtime 21600
+```
+
+To check progress after the job ID is printed:
+
+```bash
+.venv/bin/dopplergeist job JOB_ID --jobs jobs --watch
+```
+
+The progress percentage is stage-based and can remain unchanged during long tile subdivisions. Recent search-file activity is a liveness clue, not proof that the queue is shrinking or that a location was found.
+
+The default country profile is `US` (contiguous United States); use `--country DE` for Germany, `--country ES` for Spain, or `--country FR` for metropolitan France including Corsica. Spain and France use broad geographic envelopes without country polygons, so add independently justified `--bounds WEST SOUTH EAST NORTH` for a regional search. The France profile excludes overseas territories. See [country profiles](docs/COUNTRIES.md) and the [local upload workflow](docs/PRODUCT.md) for request options, cancellation, resuming jobs, and upload limits.
+
+**Data requirements:** Initial online acquisition may take hours and tens of gigabytes of disk space, depending on the recording time and search region. Downloads and caches are reusable; the application does not enforce an automatic disk-space cap.
+
+### Option C: discover acoustic events without flight data
+
+```bash
+.venv/bin/dopplergeist discover \
+  path/to/recording.mp3 \
+  --output results/my-discovery
+```
+
+This scans the full recording locally without downloading ADS-B archives. Inspect `results/my-discovery/summary.json` and the saved `discovery/` diagnostics. See [Automatic audio discovery](docs/AUDIO_DISCOVERY.md) for detector details and options.
+
+For configured research workflows, `dopplergeist run` and `dopplergeist measure` remain available; see [Methodology](docs/METHODOLOGY.md).
+
+## How it works
+
+1. **Detect the signal.** Decode the recording, identify moving spectral tracks, and group harmonics that may belong to one flyover.
+2. **Prepare flight history.** Retrieve or load aircraft trajectories for the recording's supported time window, tracking gaps in available data.
+3. **Predict the audio.** Model Doppler shifts and sound-arrival delays from flight paths, receiver geometry, and acoustic propagation.
+4. **Rank locations.** Compare modeled and observed signals across geographic candidates and multiple flyovers; preserve alternative explanations when evidence is insufficient.
+
+The software records diagnostic evidence and can return an inconclusive result rather than selecting an unsupported coordinate. The underlying models are described in [Methodology](docs/METHODOLOGY.md) and [Confidence and decision rules](docs/CONFIDENCE.md).
+
+## Frequently asked questions
+
+### Can I geolocate an MP3 recording?
+
+DOPPLERGEIST accepts MP3 recordings and can automatically detect candidate aircraft Doppler events. With a justified recording-time window and appropriate flight data, it can search and rank possible recording locations. A successful location determination is not guaranteed.
+
+### Do I need to know when the recording was made?
+
+**Yes, for historical flight matching.** The software needs a defensible UTC time or bounded time window for the first audio sample. Without that information, it can still analyze the sound, but geographic matching returns `needs_input`.
+
+### Can DOPPLERGEIST run offline?
+
+**Yes, for acoustic discovery.** Location search also works with appropriately configured historical flight and terrain data already available locally. The `--online` flag allows the program to acquire missing public data.
+
+### How accurate is DOPPLERGEIST?
+
+In a constrained real-MP3 demonstration, the highest-ranked location was **476 m from an inferred reference**, not a surveyed microphone position. Independent blind accuracy on real recordings has not yet been established. See [validation and results](#validation-and-results) for both successful fits and unsuccessful evaluations.
+
+### Can I upload an audio file in a browser?
+
+**Yes.** Run `dopplergeist serve` after installation and open the local interface. It is a self-hosted application, not a public cloud upload service.
+
+### Is DOPPLERGEIST free and open source?
+
+DOPPLERGEIST is **source-available, not OSI-approved open source**. It is licensed under [PolyForm Noncommercial 1.0.0](LICENSE), which permits use, modification, and distribution for permitted noncommercial purposes, subject to its terms. Commercial use outside those permissions requires separate authorization; see [Commercial licensing](COMMERCIAL-LICENSING.md).
+
+## Validation and results
+
+DOPPLERGEIST has been exercised on synthetic fixtures, real aircraft recordings, historical flight tracks, and browser/API workflows. These experiments demonstrate components of the pipeline; **no independently accepted blind real-recording localization has yet been established**.
+
+| Experiment | Observed result | How to interpret it |
+| --- | --- | --- |
+| **Automatic Livermore MP3, regional all-aircraft archive** | Selected and searched 466 nearby aircraft and returned 105 ranked locations; the first was **476 m from an inferred reference**. | Fully automatic event selection, but a constrained region and approximate 10-second clock window; the reference is not surveyed truth and the result was inconclusive. [Details](docs/LIVERMORE_DEMO.md#all-aircraft-archive-mp3-ranking). |
+| **Configured two-flyover real-audio replay** | Leading location **43.86 m from a public reference**. | Used source-informed events and geographic bounds; the reference is not surveyed, and the model did not accept a location. [Clean replay](docs/verification/CLEAN_REPLAY.md). |
+| **40 real smartphone aircraft recordings** | Automatic discovery produced candidate acoustic groups in **36 of 40** files. | These are acoustic proposals, not verified aircraft detections or geolocation successes. [Discovery results](docs/AUDIO_DISCOVERY.md). |
+| **Five public field recordings** | Three returned rankings, with no retained candidate within 1 km of the publisher-reported sites; two returned no candidate. | Recorder clocks and exact microphone positions were not confirmed, so these are development outcomes rather than a calibrated accuracy benchmark. [Experiment](docs/PUBLIC_RECORDING_EXPERIMENT_2026-11-03.md). |
+| **NASA and WSU measured-trajectory recordings** | Produced mixed detection results and no validated automatic location. | Original real-data tests, including unsuccessful cases. [Verification](docs/verification/WORKER_E2E_2026-11-03.md) and [NASA benchmark](benchmarks/README.md#real-nasa-supplied-trajectory-session-benchmark). |
+
+Searches depend on acoustic evidence, reliable recording-time information, sufficient historical flight coverage, and physical-model support. A ranked score is not a calibrated location probability, and incomplete or competing hypotheses may lead to an **inconclusive** decision. Full experimental conditions, negative findings, and reproducibility records remain available in the linked reports.
+
+### Performance engineering
+
+Optional native backends, reuse of acoustic calculations, and checkpointed search are implemented and measured. In one pinned bounded regional HTTP replay, optimizations reduced elapsed time from **62.03 seconds to 37.19 seconds (1.67×)** without changing the compared scientific outputs. This is a workload-specific result, not a general national-search runtime claim. See [measured performance and reproduction](docs/PERFORMANCE.md#measured-native-computation-and-bounded-reuse) and [data/search architecture](docs/DATA_AND_SCALE.md).
+
+## Documentation and references
+
+- [Local upload workflow](docs/PRODUCT.md) — browser UI, API, job monitoring, limits, cancellation, and resume.
+- [Methodology](docs/METHODOLOGY.md) — Doppler geometry, trajectory fitting, and acoustic propagation.
+- [Automatic audio discovery](docs/AUDIO_DISCOVERY.md) — acoustic detector design and evaluation.
+- [Data acquisition and geographic search](docs/DATA_AND_SCALE.md) — ADS-B archives, indexing, terrain, coverage, and search.
+- [Country profiles](docs/COUNTRIES.md) — supported search domains and regional configuration.
+- [Confidence and decision rules](docs/CONFIDENCE.md) — candidate interpretation and inconclusive outcomes.
+- [Performance](docs/PERFORMANCE.md) and [pipeline measurements](docs/PIPELINE_PERFORMANCE_2026-11-03.md) — measured optimizations and comparisons.
+- [Livermore demonstration](docs/LIVERMORE_DEMO.md), [real-data verification](docs/verification/WORKER_E2E_2026-11-03.md), and [benchmark instructions](benchmarks/README.md) — recorded experiments and reproduction.
+- [Finite-search evidence](docs/FINITE_SEARCH_PRODUCER.md) and [scoring assessment](docs/SCORING_ASSESSMENT.md) — candidate accounting and coverage of evaluated hypotheses.
+- [Setup](docs/SETUP.md), [Docker](docs/DOCKER.md), and [data provenance](docs/DATA_SOURCES.md) — installation, deployment, and third-party data terms.
+
+## License
+
+DOPPLERGEIST is distributed under the **[PolyForm Noncommercial License 1.0.0](LICENSE)** (`PolyForm-Noncommercial-1.0.0`). It is **source-available, not OSI-approved open-source software**. Noncommercial uses, modification, and distribution are permitted subject to the license. Commercial use not otherwise permitted requires authorization from the relevant rights holders. See [Commercial licensing](COMMERCIAL-LICENSING.md).
+
+Recordings, aircraft archives, terrain datasets, and other third-party materials retain their own licenses, rights, and attribution requirements.
+
+## Contributing and development
+
+Contributions, reproducible test recordings with appropriate permissions, documentation improvements, and independently verifiable evaluations are welcome. See [CONTRIBUTING.md](CONTRIBUTING.md), the [issue tracker](https://github.com/1337isnot1337/DOPPLERGEIST/issues), and the [development discussion](https://github.com/1337isnot1337/DOPPLERGEIST/discussions/39).
+
+Created by **Cinna Davis** with extensive AI-assisted development. Thanks to @henriklied, @EirikAskheim, @kleindotc, and other contributors. Follow updates on [X](https://x.com/1337isnot1337) or [LinkedIn](https://www.linkedin.com/in/cinna-davis/).
+
+## Star history
+
+<p align="center">
+  <a href="https://www.star-history.com/#1337isnot1337/DOPPLERGEIST&Date">
+    <picture>
+      <source media="(prefers-color-scheme: dark)" srcset="https://api.star-history.com/svg?repos=1337isnot1337/DOPPLERGEIST&type=Date&theme=dark" />
+      <img alt="DOPPLERGEIST star history" src="https://api.star-history.com/svg?repos=1337isnot1337/DOPPLERGEIST&type=Date" width="650" />
+    </picture>
+  </a>
+</p>

dopplergeist-0.1.1/docs/PYPI_README.md

@@ -0,0 +1,64 @@
+# DOPPLERGEIST
+
+![DOPPLERGEIST — aircraft Doppler audio geolocation](https://raw.githubusercontent.com/1337isnot1337/DOPPLERGEIST/main/assets/dopplergeist-banner.svg)
+
+**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](https://raw.githubusercontent.com/1337isnot1337/DOPPLERGEIST/main/assets/livermore-automatic-mp3.png)
+
+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](https://github.com/1337isnot1337/DOPPLERGEIST/blob/main/docs/LIVERMORE_DEMO.md).
+
+## Install
+
+Requires **Python 3.11+**. Install **FFmpeg** separately so that both `ffmpeg` and `ffprobe` are on your `PATH`.
+
+For the CLI:
+
+```sh
+pipx install dopplergeist
+dopplergeist --help
+```
+
+For a Python environment:
+
+```sh
+python -m pip install dopplergeist
+```
+
+## Use
+
+Detect candidate acoustic events without flight-data downloads:
+
+```sh
+dopplergeist discover recording.mp3 --output results/discovery
+```
+
+Launch the locally hosted upload interface:
+
+```sh
+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:
+
+```sh
+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
+
+- [Source code and full README](https://github.com/1337isnot1337/DOPPLERGEIST)
+- [Installation and reproducibility](https://github.com/1337isnot1337/DOPPLERGEIST/blob/main/docs/SETUP.md)
+- [How the geolocation pipeline works](https://github.com/1337isnot1337/DOPPLERGEIST/blob/main/docs/METHODOLOGY.md)
+- [Validation and limitations](https://github.com/1337isnot1337/DOPPLERGEIST/blob/main/docs/CONFIDENCE.md)
+- [Issues and feature requests](https://github.com/1337isnot1337/DOPPLERGEIST/issues)
+
+## 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](https://github.com/1337isnot1337/DOPPLERGEIST/blob/main/COMMERCIAL-LICENSING.md).

dopplergeist-0.1.1/licenses/MIT-legacy.txt

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Cinna Davis
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

dopplergeist-0.1.1/pyproject.toml

@@ -0,0 +1,54 @@
+[build-system]
+requires = ["setuptools>=77.0.3"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "dopplergeist"
+version = "0.1.1"
+description = "Aircraft Doppler audio geolocation using historical flight tracks"
+readme = "docs/PYPI_README.md"
+keywords = ["aircraft", "doppler", "acoustic-geolocation", "audio-forensics", "ads-b", "signal-processing"]
+classifiers = [
+  "Development Status :: 4 - Beta",
+  "Environment :: Console",
+  "Intended Audience :: Science/Research",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
+  "Programming Language :: Python :: 3.13",
+  "Programming Language :: Python :: 3.14",
+  "Programming Language :: Python :: Implementation :: CPython",
+  "Topic :: Scientific/Engineering :: Physics",
+  "Topic :: Multimedia :: Sound/Audio :: Analysis",
+]
+license = "PolyForm-Noncommercial-1.0.0"
+license-files = ["LICENSE", "licenses/MIT-legacy.txt", "src/dopplergeist/web/leaflet-license.txt"]
+requires-python = ">=3.11"
+dependencies = ["numpy", "scipy", "pandas", "soundfile", "pyproj", "rasterio", "matplotlib", "requests", "pyarrow", "shapely>=2.0"]
+
+[project.urls]
+Homepage = "https://github.com/1337isnot1337/DOPPLERGEIST"
+Documentation = "https://github.com/1337isnot1337/DOPPLERGEIST/tree/main/docs"
+Source = "https://github.com/1337isnot1337/DOPPLERGEIST"
+Issues = "https://github.com/1337isnot1337/DOPPLERGEIST/issues"
+Releases = "https://github.com/1337isnot1337/DOPPLERGEIST/releases"
+
+[project.optional-dependencies]
+test = ["pytest>=8"]
+
+[project.scripts]
+dopplergeist = "dopplergeist.cli:main"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.setuptools.package-data]
+"dopplergeist.web" = ["*.html", "*.js", "*.css", "leaflet-license.txt"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+
+[tool.cibuildwheel]
+build = "cp311-* cp312-* cp313-* cp314-*"
+skip = "*-musllinux_*"
+test-command = "dopplergeist --help && python -c \"from importlib.resources import files; assert files('dopplergeist.web').joinpath('index.html').is_file()\""

dopplergeist-0.1.1/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

dopplergeist-0.1.1/setup.py

@@ -0,0 +1,40 @@
+import os
+
+from setuptools import Extension, setup
+
+
+extension = Extension(
+    "dopplergeist._native_ridge",
+    ["src/dopplergeist/_native_ridge.c"],
+    optional=True,
+    extra_compile_args=["/O2", "/fp:strict"] if os.name == "nt" else
+        ["-O3", "-ffp-contract=off", "-fno-fast-math"],
+    libraries=[] if os.name == "nt" else ["m"],
+)
+
+acoustic_extension = Extension(
+    "dopplergeist._native_acoustic",
+    ["src/dopplergeist/_native_acoustic.c"],
+    optional=True,
+    extra_compile_args=["/O2", "/fp:strict"] if os.name == "nt" else
+        ["-O3", "-ffp-contract=off", "-fno-fast-math"],
+    libraries=[] if os.name == "nt" else ["m"],
+)
+
+cpa_extension = Extension(
+    "dopplergeist._native_cpa",
+    ["src/dopplergeist/_native_cpa.c"],
+    optional=True,
+    extra_compile_args=["/O2", "/fp:strict"] if os.name == "nt" else
+        ["-O3", "-ffp-contract=off", "-fno-fast-math"],
+    libraries=[] if os.name == "nt" else ["m"],
+)
+
+index_extension = Extension(
+    "dopplergeist._native_index",
+    ["src/dopplergeist/_native_index.c"],
+    optional=True,
+    extra_compile_args=["/O2"] if os.name == "nt" else ["-O3"],
+)
+
+setup(ext_modules=[extension, acoustic_extension, cpa_extension, index_extension])

dopplergeist-0.1.1/src/dopplergeist/__init__.py

@@ -0,0 +1 @@
+"""Aircraft-acoustic geolocation reproduction."""