Skip to content

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

12.7 KB
Raw Blame

Real recording representation checks

Issue #61 requires fresh end-to-end runs for equivalent representations of actual recordings. The runner in scripts/run_real_metamorphic.py executes these runs through the local HTTP upload service. It accepts a recorded source, a recording-start UTC window, and an offline operator configuration.

Each arm starts a new service and job. Intake, discovery, selection, matching, search, refinement, decision and serialization run from the uploaded bytes. The runner shares only frozen historical indexes and terrain. It does not resume audio or search checkpoints. The HTTP verifier checks the actual stage artifacts and the persisted terminal result.

Frozen protocol

The versioned protocol is verification/metamorphic_protocol_v1.json. It was committed locally before the development matrix ran. The exact executed source tree was published afterward as 3094292. This was not a public preregistration. The protocol has nine sequential arms:

Arm Change from the baseline
Baseline MP3, 128 kb/s, 48 kHz, mono
Low bitrate 64 kb/s
High bitrate 192 kb/s
Sample rate 44.1 kHz
Gain −6 dB
Channels Two identical channels
Leading silence 17.25 seconds
Short discovery chunks 60-second chunks, 30-second overlap
Long discovery chunks 180-second chunks, 60-second overlap

All encodings start from the complete source recording's arithmetic channel mean at 48 kHz. No arm is encoded from another MP3 arm. The baseline keeps the operator's discovery settings. The current defaults are 120/60 seconds.

Only operator.discovery.chunk_s and overlap_s are exposed chunk controls. The protocol explicitly lists unsupported upload, decoder and detector controls. It does not insert hooks into the source algorithms.

Each job has a 240-second runtime limit and a 300-second client deadline. The encoding/decode command limit is 300 seconds. Pipeline time is at most 45 minutes across nine client deadlines, plus preparation and cleanup. Different budgets can be declared at preparation, before any outcomes exist.

Tolerances are fixed in the protocol: 2 ms for duration and residual alignment, 1 second for mapped event edges and fitted clocks, 2 Hz for median ridge frequency, and 0.05 per matched group for comparable normalized scores. Usability also requires nonclipping decoded peaks and gain-corrected PCM NRMSE at most 0.15. Group counts, flight associations and score units must agree. The runner reports displacement thresholds at 100, 500 and 1,000 metres. Accepted locations that move over 1,000 metres receive a separate serious flag.

The PCM calculation reads bounded blocks. Lag checks use twelve fixed short windows, not full-hour correlations. A measured lag is reported; it does not shift samples to improve the result. Native-rate decoded peaks and identical stereo channels are checked separately from the 4 kHz analysis PCM.

Clock mapping

If leading silence is Δ seconds, subtract Δ from both sample-zero UTC window endpoints. Subtract Δ from detected audio-relative times for comparison. Add Δ to the fitted sample-zero UTC to recover the original recording clock.

For example, 20:17:20–20:17:40 UTC becomes 20:17:02.750–20:17:22.750 UTC after 17.25 seconds of padding. The physical time of each recorded sound stays the same. The runner retains codec skip/discard metadata, decoded sample counts, and residual lag checks. Container start time is not a recording clock.

Run

Use an installed checkout with FFmpeg and the repository's dependencies. The request must have a defensible time window. Use absolute local paths for historical indexes and terrain, or run preparation where relative paths resolve. Use a stopped, immutable data cache. Active job directories are not data inputs.

PYTHONPATH=src python scripts/run_real_metamorphic.py prepare \
  --audio /absolute/path/actual-recording.wav \
  --request /absolute/path/request.json \
  --operator /absolute/path/operator.json \
  --source-note 'Identify the actual recorded source and its permission/provenance' \
  --scope-note 'Describe the search scope, clock evidence and evaluation limits' \
  --output /absolute/path/new-frozen-plan

PYTHONPATH=src python scripts/run_real_metamorphic.py run \
  --plan /absolute/path/new-frozen-plan/plan.json \
  --output /absolute/path/new-matrix-run

Preparation writes an immutable plan before encoding. It pins source bytes, configuration, historical inputs, terrain, source code, native binaries, dependencies, backend environment and FFmpeg version. Runs refuse changed inputs. Use --frozen-input PATH for an additional immutable local dependency. Every output directory must be new.

New plans also record Shapely and its GEOS runtime version. Package absence is recorded explicitly. If Shapely is installed without an identifiable GEOS version, preparation refuses the incomplete runtime pin.

The runner preserves encoded inputs, exact transformation commands, actual job artifacts and observations for every arm. It continues after an ordinary arm failure. It preserves pending arms on interruption or changed inputs.

Pairwise comparisons also fail if the material coverage state (search completion, data availability, missing-data identifiers or requested area) changes, or if verified pipeline/work-completion gates change. Measured elapsed time, peak memory and event proposal counts remain reported but are not themselves completeness failures. Raw coverage descriptions are retained separately. This check applies to newly generated reports; the recorded November 4 results are immutable. An unusable encoded arm still reaches the HTTP pipeline. Encoding failures remain explicit failures.

report.json contains all pairwise comparisons. report.md gives a short case table. Event matching uses a one-to-one assignment based on mapped time overlap and ridge frequency. It reports unmatched ridges/groups, group splits, group merges, and ambiguous alternatives. IDs and row positions do not define correspondence. Retained distant modes are compared separately.

Each case includes a one-arm reproducer command. The --case option creates a fresh job and records the other arms as not selected. It cannot pass the full-matrix requirement. The report command compares preserved observations; it never counts as another end-to-end run.

Exit zero requires all nine usable arms to reach the full pipeline and remain within the declared comparison tolerances. Exit one preserves incomplete runs or observed differences. An inconclusive scientific decision is not itself a runner failure when the complete pipeline ran. It remains an inconclusive location result.

The full-path count uses the verifier's stronger requirement: every stage must be verified and at least one diagnostic candidate must survive. Empty outcomes remain in the report. A separate count records all observed stage sequences. Neither count requires a supported location decision.

Scope of the development run

The affordable development control uses the whole released reference recording, a source-informed regional box, a narrow source-informed UTC window, and incomplete historical flight coverage. It cannot satisfy national acceptance. It does not establish independent location accuracy.

No eligible independent truth is supplied in this protocol. Truth errors at 100/500/1,000 metres remain explicitly unevaluated. Pairwise displacement is reported separately. A future eligible national evaluation needs its own predeclared request, data, budgets and evaluation-only truth protocol.

Focused contract checks use archived real ridge observations and an optional short actual recording. They do not replace any full-recording arm:

DOPPLERGEIST_REAL_METAMORPHIC_AUDIO=/absolute/path/actual-short-recording.mp3 \
  PYTHONPATH=src pytest -q tests/test_real_metamorphic_runner.py

Recorded result: 4 November 2026

All nine fresh jobs passed HTTP and persistence verification and completed the required pipeline. Each produced 23 diagnostic candidates. Every scientific decision remained inconclusive / search_incomplete. The fixed comparison criteria failed in 35 of 36 pairs, so the runner correctly exited with code 1. The 192 kb/s and identical-stereo pair had no comparison flags.

The measured summary records all nine outcomes, all 36 comparison flag sets, source and input hashes, configuration, runtime pins and raw-artifact identities. The full run took 1,192.83 seconds, including encoding and preflight checks. HTTP verification accounted for 737.92 seconds.

The table compares each arm's leading diagnostic candidate with the declared 128 kb/s baseline. These are candidate movements, not accepted-location errors. Clock differences are absolute differences after the prescribed mapping for leading silence; they do not indicate which fitted clock is later.

Arm Groups / ridges Displacement (m) Absolute clock difference (s) HTTP time (s) Worker high-water RSS (MiB)
Baseline 15 / 17 0.00 0.000000 81.16 409.34
64 kb/s 16 / 18 177.95 0.474851 101.03 430.97
192 kb/s 16 / 18 3.09 0.005837 93.50 410.20
44.1 kHz 16 / 18 1,969.93 7.452914 102.04 452.91
−6 dB 15 / 17 2.67 0.005770 80.67 431.94
Identical stereo 16 / 18 1.61 0.005285 90.59 413.76
17.25-second leading silence 13 / 16 120.24 0.213660 90.73 465.77
60/30-second discovery chunks 11 / 13 31.78 0.065637 48.30 408.05
180/60-second discovery chunks 13 / 15 30.88 0.053637 49.91 436.25

All nine representations passed the declared usability checks. Duration errors and measured residual lags were zero. Gain-corrected PCM NRMSE ranged from 0.03011 to 0.05248, below the fixed 0.15 limit. Native decoded peaks stayed below clipping. These global checks do not prove preservation of every weak acoustic cue.

Both chunk variants uploaded bytes identical to the baseline. Only the actual discovery chunk settings changed. The resulting group and ridge counts changed from 15/17 to 11/13 and 13/15. This is a direct processing-chunk sensitivity result for the declared recording and search configuration.

The 44.1 kHz arm lost the baseline's 1,396.5–1,418.5-second proposal in the 75.49–93.48 Hz band. All 23 baseline candidates used that proposal, associated with flight aa61d2:3. Its ordinal event ID in the variant belongs to a different ridge, so it cannot establish correspondence.

A five-group remnant survives at variant public rank 11 and retained-mode rank 8. Its coordinates and mapped clock exactly equal the baseline's unrefined parent at public rank 3. It lies 284.63 metres from the refined baseline winner, with an absolute clock difference of 0.494912 seconds. The 1.97 km winner movement accompanies changed detected groups and associations. It does not demonstrate accidental deletion or reordering of an identical hypothesis.

The report retains every distant_mode_lost flag. This flag means that strict full-association correspondence failed. A changed proposal population can cause that failure without proving that the same hypothesis was pruned. Score deltas remain incomparable when the mapped associations differ.

No arm produced an accepted location. Consequently, zero accepted-location pairs were evaluated; accepted-location invariance did not pass or fail. Independent truth errors remain unevaluated. The regional, source-informed inputs and incomplete historical coverage leave issue #61's national gate open.

Memory instrumentation correction

The original descendant-RSS sampler could not traverse this environment's /proc mount. All nine original aggregate readings remain unavailable. The table preserves the worker high-water measurements recorded at search completion. They are not certified peaks for the whole job.

The corrected sampler resolves the PID namespace exposed by /proc/self. When thread children files are absent, it selects descendants through the same mount's parent-PID relations before reading their RSS. Sampling errors and stop timeouts remain explicit. Measurements also survive HTTP verification exceptions.

A separate four-second actual upload verified this correction. It measured 129.74 MiB across 16 samples, stopped normally, and returned needs_input / recording_time_required. That run validates instrumentation only; it is not a tenth scientific arm. No original matrix measurement was replaced, and the nine-arm matrix was not rerun. Descendant RSS is a sampled sum and can count shared pages more than once.