DOPPLERGEIST v0.1.2

DOPPLERGEIST 0.1.2 makes the improved acoustic Doppler discovery algorithm the default for discovery and automatic analysis.

• Groups measured frequency tracks into acoustic event proposals.
• Retains the tracks for downstream analysis and reports detector settings.
• Includes Python package and command-line updates.

Install with pipx install dopplergeist or python -m pip install dopplergeist. Python 3.11+ and FFmpeg are required; Intel macOS supports Python 3.11–3.13. Acoustic proposals do not by themselves establish aircraft identity or recording location.

DOPPLERGEIST v0.1.1 (PyPI beta)

DOPPLERGEIST 0.1.1 is the first PyPI distribution release for the aircraft Doppler audio geolocation toolkit.

• Distributable Python package and CLI for Python 3.11–3.14.
• Platform wheels for Linux x86-64 and ARM64, macOS Intel and ARM64, and Windows AMD64.
• Includes the local browser interface, native acceleration extensions, and noncommercial license notices.
• Cross-platform source and binary distribution build checks passed before release.

Install after the PyPI publication workflow completes:

pipx install dopplergeist
dopplergeist --help

Python 3.11+ is required; install FFmpeg and ffprobe separately. For installation details see docs/SETUP.md.

License: PolyForm Noncommercial 1.0.0 for the current distribution. Prior MIT-licensed versions retain their previously granted permissions; commercial rights require a separate agreement with the appropriate copyright holders.

This beta has not established independently validated blind real-recording geolocation accuracy. Inspect the methodology and recorded experiments before interpreting location rankings.

DOPPLERGEIST v0.1.0 (experimental beta)

Experimental beta, not validated for blind real-world geolocation. DOPPLERGEIST is a source-available aircraft-Doppler audio-geolocation research tool. A ranked location candidate is not verified evidence of where a recording was made.

Included in this release

• Python CLI (dopplergeist analyze, serve, job, cancel, and resume) plus local browser-based audio upload and saved, inspectable jobs.
• Automatic full-recording acoustic discovery, harmonic grouping, and joint comparison of multiple independent aircraft flyovers.
• Historical ADS-B trajectory matching, terrain/geoid handling, bounded and resumable geographic searches, and receiver-region profiles for CONUS and Germany.
• Optional native acoustic and closest-approach acceleration, search screening, checkpointing, runtime diagnostics, and Docker setup.
• Explicit needs_input and inconclusive outcomes when the clock, coverage, model evidence, or search completion does not justify a location.

Install and try it

Requires Python 3.11+, FFmpeg (ffmpeg and ffprobe on PATH) and Git. Linux and macOS are supported for the documented quickstart; native Windows execution is unverified.

git clone --depth 1 --branch v0.1.0 https://github.com/1337isnot1337/DOPPLERGEIST.git
cd DOPPLERGEIST
python -m venv .venv
.venv/bin/python -m pip install .
.venv/bin/dopplergeist --help
.venv/bin/dopplergeist analyze path/to/recording.mp3 --jobs jobs

For the browser UI, run .venv/bin/dopplergeist serve --jobs jobs --online --max-runtime 14400 --port 8765, then open http://127.0.0.1:8765 on the same machine. Historical flight/terrain acquisition can consume hours and tens of gigabytes.

Evidence and limitations

• Installation/static CI passed at this tag. The Docker build job passed; consult the linked workflow for the final image-publication status.
• The documented real-MP3 demo ranks a candidate 476 m from an inferred reference, but uses source-informed regional and approximately ten-second timing priors. It is not a blind accuracy result.
• A separate regional five-public-recording experiment produced no candidate within 1 km of a publisher-reported site, and two recordings produced no candidate. Those sources' clock and microphone coordinates were not independently confirmed.
• A pinned regional end-to-end benchmark improved from 62.03 s to 37.19 s (1.67×) with optional native and bounded computation reuse. That benchmark does not establish CONUS runtime or scientific localization accuracy.
• Independent blind field accuracy, calibrated false-positive rates, and native Windows operation remain unverified. A defensible UTC recording-time window is needed for historical flight matching.

Documentation

• Quickstart and current status
• Local upload workflow
• Data and search
• Performance methodology
• Public-recording verification

Earlier research checkpoint, multi-event fixtures, and six-event CLI replay evidence remain archived separately.

License: PolyForm Noncommercial 1.0.0. Commercial use requires separate authorization. This prerelease includes GitHub-generated source archives; no separately tested executable binaries are attached.

Research checkpoint: code, data, results, and implementation handoff

Code, tests, source investigation, configurations, readable reports and diagnostic plots are on main. This release contains the complete collected inputs and experiment outputs: 738 files in eight data assets (6,187,146,655 bytes), plus a per-file manifest and SHA256 checksums.

The YouTube MP4 is excluded. The linked reference WAV used by the experiments is included. Two YouTube metadata files are exported with descriptive fields only, omitting transient media/request fields. Original and exported hashes are recorded.

Start with the collaborator handoff, artifact restoration, and data provenance.

Validation: 11 tests passed. Historical results include 21.89 m and 40.87 m synthetic location errors and 43.86 m from the mapped public platform in a regional two-event real test. The faint-event result is 357.47 m off. Automatic full-recording event discovery, the MP3 upload interface, and blind national real-audio validation remain unfinished.

For the real regional replay, download data-source.tar.gz, data-adsb-derived.tar.gz, and data-terrain.tar.gz. The two raw ADS-B archive parts are needed only to repeat ingestion. Extract bundles from the repository root into a clean checkout; see the restoration instructions before overwriting existing data or results.

Six-event isolated CLI replay evidence (inconclusive)

The actual installed CLI/job replay used frozen source 39634c3fc565a3d025a661f90eddae54430591f9 and wheel SHA256 62d310e01d4a4e26317ad11b686e604bb79551c934efc73b02f6fc89bf1c28a8.

The original job finished inconclusive / ambiguous_locations after 47 min 52 s. It automatically detected six groups, used all six in joint associations, completed the declared finite synthetic CONUS tile pass and refinement, and retained 106 product candidate records. Post-terminal evaluation found the leading candidate 0.06125 m from synthetic truth with all six correct flight IDs. This is diagnostic candidate error; the pipeline did not assert a supported location. Finite-mode/decision and independent real-clock/GPS gates remain open.

The bundle and external manifest preserve 62 verified members: complete readable outputs and plots, the original startup failure, protocol, truth-access log, evaluation of all 306 product/fine/coarse records, immutable Python wheel, derived index/operator, and a nested archive of all 76,328 coarse checkpoints with its hash ledger. No source media, virtual environment, Python cache or transient stream URL is included. Original MP3, terrain and track inputs remain in the canonical fixture release; its six-event archive SHA256 is a6d79edca1407324ad77fee6b97812eb11f7a84cdb2308d12bd8f2663d4b396c.

Verify SHA256SUMS and manifest.json before extraction. The bundle contains post-run labels; keep its evidence tree outside backend mounts. Use only the canonical inputs plus derived index/operator, installed wheel and dependencies in the input-only namespace. Map the historical runner's host paths to the new installation. Exact full-job RSS is unavailable because an outer timer measured the namespace launcher; valid search-stage native peak RSS is 365.512 MiB, and the measurement control is preserved.

This prerelease preserves experimental verification evidence. It does not promote the integration branch to canonical main or establish real-world accuracy.

Dependency export correction: use the separately attached runtime-requirements-active.txt, verified by DEPENDENCY_SHA256SUMS. The original bundle export included both system and private Requests metadata as simultaneous pins. Actual imports use Requests 2.34.2. dependency-pin-correction.json records all nine active module paths/versions and a successful clean binary-resolution dry run for all 28 direct/transitive packages. The original bundle, experiment source, input bytes and outcome are preserved.

Multi-flyover synthetic fixtures — 2026-11-03

Independent emission-domain synthetic development fixtures with three, four and six flyovers. Generator: 1f03425.

Each bundle has a label-free inputs directory (MP3, opaque trajectories, synthetic terrain/geoid, finite-population coverage and a request with a declared synthetic clock). Truth, renderer WAV and generation provenance are separate. For a blinded run, expose only inputs to the backend; do not mount the generator, truth or generation manifest.

Frozen default discovery recovered 3/3, 4/4 and 6/6 independent groups, with no missed/extra groups under post-run interval matching. No flight-association or location result is established by those discovery checks. Complete results and code are being integrated in the repository. This corpus is synthetic development evidence, not the independent real-world holdout.

Verify asset SHA256 values with SHA256SUMS and every extracted file against manifest.json. The source YouTube MP4 is excluded.