Skip to content

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

Record real Risoux scanner screening outcomes

Cinna Davisb148ec6c23bc
diff --git a/benchmarks/risoux-real-scan-20261103.csv b/benchmarks/risoux-real-scan-20261103.csv
new file mode 100644
index 0000000..e59ccf2
--- /dev/null
+++ b/benchmarks/risoux-real-scan-20261103.csv
@@ -0,0 +1,31 @@
+case_number,opaque_id,archive_member,publisher_label,zip_crc32,sha256,status,duration_s,scanner_result,proposal_count,visual_review
+1,0b642667fd1c5a36f1dd,audio_recordings/S4A03536_20180827_020000.wav,plane_only,e7b84d76,9b22217d35ba8adaa251ebb374ced6f17351c1682d1cb9732c606642ef855750,scanned,59.99475,no_proposals,0,no_clear_long_ridge_in_0_1p6khz_spot_check
+2,23fd6e844910dad12881,audio_recordings/S4A03544_20190102_111500.wav,plane_only,1b565fd7,cb181ec7dad228997e78322cc92f9a3d8589def50b7f3aac2ed8a74fac8bef16,scanned,59.99475,proposals,1,candidate_doppler_like
+3,26f952508c32658bb55f,audio_recordings/S4A03895_20181109_210000.wav,plane_only,41a746dc,1dc75f7b8e9283e01cd2d2910f4807419fe2bb27e30f74c59121c05bf63bb412,scanned,59.99475,no_proposals,0,no_clear_long_ridge_in_0_1p6khz_spot_check
+4,3b6ee405d33a1aefd410,audio_recordings/S4A03998_20180919_040000.wav,plane_only,9b37ba40,5fa76905c6198ac511cfc5367a74c2828ae2f13698dff21f0509def362709540,scanned,59.99475,no_proposals,0,not_reviewed
+5,e8e0c8d0542079e167c2,audio_recordings/S4A04430_20190624_234500.wav,plane_only,1818c3d0,353da4a7ad420f8af7888d8f2ad1bfce4aa01ec8ee94d057b79a1d3567dd46f3,scanned,59.99475,no_proposals,0,not_reviewed
+6,dee97aeae23e647b412d,audio_recordings/S4A03536_20180919_053000.wav,plane_only,36575418,c9298ee21f3ba12c6a535a60c110ac4a1348f861c8e2e8d67790faf0893809c9,scanned,59.99475,proposals,1,candidate_doppler_like
+7,f7e99f85c5b5fcbb5588,audio_recordings/S4A03544_20181218_063000.wav,plane_only,53d6277d,375889dfdb21538540f9e37746296b7ae366d1fa3818c774c3ef3cf3f23ad5f0,scanned,59.99475,no_proposals,0,not_reviewed
+8,74ca719ad81c08d75299,audio_recordings/S4A03895_20190403_200000.wav,plane_only,5ea4dfdd,bc56dc3fb97409d805d044324f2d12c0ac09b00ce414adf3189f281077e8441b,scanned,59.99475,no_proposals,0,not_reviewed
+9,4d5f07921a35d1a6946f,audio_recordings/S4A03998_20181003_194500.wav,plane_only,ae4bbe2a,88ea555492a89d2e567e7aabb1a0c1167487c601bbf1ecd3c5116757e32eec44,scanned,59.99475,proposals,1,ambiguous_source
+10,37278f6c5e721543407c,audio_recordings/S4A04430_20181027_034500.wav,plane_only,2dd8b541,0470b2e7057b68cee772ff75369607d84ed56bc11dc12e6fbfa2ddbdc0c4e5a2,scanned,59.99475,no_proposals,0,not_reviewed
+11,9e874ba0f18237eea64d,audio_recordings/S4A03536_20180920_053000.wav,plane_only,029ef68f,6f0bc46a9002687c88e9c85fabbc1a98979b2d9e05a2694bdb037db610451024,scanned,59.99475,no_proposals,0,not_reviewed
+12,97d9fe63b4cf3928f4c8,audio_recordings/S4A03544_20190526_013000.wav,plane_only,210bb9e3,71a561fad0674836b72aacdd251363d798892ae48f08def38e1c629676289b43,scanned,59.99475,no_proposals,0,not_reviewed
+13,6a36b504ee00094de4f0,audio_recordings/S4A03895_20181118_164500.wav,plane_only,8d6d63e6,3df9d2f84e26006e5caae66c6661c554dd6f8a5d6ded1ddeb4bf56e4f24536fd,scanned,59.99475,no_proposals,0,not_reviewed
+14,ae64e1d732551c47e766,audio_recordings/S4A03998_20181105_193000.wav,plane_only,57d83f85,2cdf2aab0f617fdd8e056c782d0252b9a5922a68266d086b77e7abfa0827249f,scanned,59.99475,no_proposals,0,not_reviewed
+15,67b40a9a8ea1b99ebde0,audio_recordings/S4A04430_20180811_210000.wav,plane_only,782c963b,7951acfd079a8395a9f3d8d75309e08dfc409bd50228ca5bd18b430d0b73df76,scanned,59.99475,no_proposals,0,not_reviewed
+16,2ae928bfa5aa8a7b428f,audio_recordings/S4A03536_20181020_024500.wav,plane_only,b114ded8,d662726632c4f02f00b79ef6fd21765e530af2c74a983172db7c97428ec8d71f,scanned,59.99475,no_proposals,0,not_reviewed
+17,6f04e7025c11e5890577,audio_recordings/S4A03544_20190120_023000.wav,plane_only,8a249cce,e05184d1e976ed0a41dca0e1ab60591dd7a182c2cb16cee5fd93c4478426cae0,scanned,59.99475,no_proposals,0,not_reviewed
+18,06da8e558c5f730c7d3c,audio_recordings/S4A03895_20190117_221500.wav,plane_only,efc13cd9,d8fb6226d7f5dc3e32b16cd2507cb01f86d9090ba61b4fefabd1288a3e6c7732,scanned,59.99475,no_proposals,0,not_reviewed
+19,569336c19b5165de49a8,audio_recordings/S4A03998_20181201_163000.wav,plane_only,bef3ba03,246db8744a31c6a9acb2a6eefec6bd44866eaf683e499d8bb080759c09a43cbc,scanned,59.99475,proposals,1,ambiguous_source
+20,4a1e4e97ab811dd1fcf8,audio_recordings/S4A04430_20181006_023000.wav,plane_only,37cc53b7,b4b3e5ee8e0ddf14762fb996ed0160ac3f3c26e31ac80f62bf1b1669988a5741,scanned,59.99475,no_proposals,0,not_reviewed
+21,14ed30941e2fc53f200b,audio_recordings/S4A03536_20190403_210000.wav,plane_only,e3928e54,77678299af4700d8d305c1d32e5dcc2153787eaad9fafea9f07e9bfcfbdf9bab,scanned,59.99475,no_proposals,0,not_reviewed
+22,11377380f12c42eb4276,audio_recordings/S4A03544_20190522_003000.wav,plane_only,be72e587,9ff66797ca2684df4b181268bfc2ffa55340e17319128c40a02d6505e0eb44cc,scanned,59.99475,no_proposals,0,not_reviewed
+23,962fa313f285fa3f5876,audio_recordings/S4A03895_20190529_014500.wav,plane_only,8e257645,ea124ffa453ac0b247665e02d1e049e059c4ce62a84ab3775979e098aa1432ce,scanned,59.99475,no_proposals,0,not_reviewed
+24,0a4dba37d1036279e69a,audio_recordings/S4A03998_20180908_004500.wav,plane_only,80f4ab2b,13d2e97c61c5c0baa6ec9945bc29ad950d428c0b4e47d03adf542e6d53f06816,scanned,59.99475,no_proposals,0,not_reviewed
+25,9ea8371c0781adfcb170,audio_recordings/S4A04430_20190120_041500.wav,plane_only,2718441f,ee4a97a2105b0ccf7135ad7ac7fb7ed3b12ebce74ed2d03a3f213752f89dbe52,scanned,59.99475,no_proposals,0,not_reviewed
+26,471f08ed0296072551ee,audio_recordings/S4A03536_20190206_034500.wav,silence_no_plane,2eb64d32,d2c95ebef536547ba1b28781bd49e8e95befa7f7f58fb82246b17594c5bbc3b8,scanned,59.99475,no_proposals,0,not_reviewed
+27,7818b9b966f82501b0ea,audio_recordings/S4A03544_20190106_010000.wav,silence_no_plane,1ea7e8d8,52dd6c3688a6a5f3efe0871d23374969af7ef4b6ebf3b6151f70af7ce25bcb60,scanned,59.99475,no_proposals,0,not_reviewed
+28,74384422929238a7ae70,audio_recordings/S4A03895_20181013_030000.wav,silence_no_plane,5a0ed81b,dc3458dfc5dff622d399c0c2f7d21b3e8dbad14aee5fa8558019e6b167040b0f,scanned,59.99475,no_proposals,0,not_reviewed
+29,84fe33878b6b4d3c45e8,audio_recordings/S4A03998_20180905_040000.wav,silence_no_plane,522f759a,233b3f762333865da572a1d6b4a9146561b7ed5959f98861587fae95ad72374c,scanned,59.99475,no_proposals,0,not_reviewed
+30,c78937d53bfd4915f2e3,audio_recordings/S4A04430_20181027_014500.wav,silence_no_plane,92cda1df,63cdfae0f3b909bff36d7f4087376a147996c3448676685eb4b28cd852d639bf,scanned,59.99475,no_proposals,0,not_reviewed
diff --git a/benchmarks/risoux-real-scan-20261103.md b/benchmarks/risoux-real-scan-20261103.md
new file mode 100644
index 0000000..934abc2
--- /dev/null
+++ b/benchmarks/risoux-real-scan-20261103.md
@@ -0,0 +1,50 @@
+# Risoux real-aircraft-labeled scanner sample
+
+This scanner-only development sample uses the publisher's
+[Risoux forest soundscape dataset](https://zenodo.org/records/10701274). The
+publisher reports 1,314 one-minute field recordings, manually labeled for
+sound categories including aircraft, from recorders deployed in the French
+Jura. The source describes four recorders roughly 1 km apart; the individual
+recorder coordinates and recording clock accuracy have not been established
+here. Five filename prefixes occur in the archive and are sampling strata,
+not a claim of five independent sites. These clips cannot validate precision
+location accuracy and are outside the current CONUS search domain.
+
+With seed `20261103`, select five recordings per filename prefix labeled
+`plane=1` with no wind, rain or biophony label, and one per prefix labeled
+`plane=0, silence=1`: 25 aircraft-labeled clips and five quiet controls. These
+labels select and describe the sample; the scanner receives only opaque audio
+filenames. All 30 clips were scanned successfully and each was about 60 seconds:
+
+| Publisher label | Scanner proposals | No scanner proposal |
+| --- | ---: | ---: |
+| Aircraft, without the other specified labels | 4 | 21 |
+| Silence, no aircraft label | 0 | 5 |
+
+A quick visual review found two proposal traces that look Doppler-like and two
+whose sources remain ambiguous. Two of the 21 no-proposal aircraft-labeled
+clips were spot-checked and showed no obvious long descending tone in the
+0–1.6 kHz view. A publisher aircraft label does not establish that a usable
+tonal Doppler ridge is present, and a scanner proposal does not establish that
+its trace came from an aircraft. The 21 no-proposal results are misses against
+the broad publisher aircraft labels, not demonstrated missed Doppler ridges.
+The sample is intentionally label-selected and small; the five controls do not
+establish a general false-positive rate.
+
+[Individual outcomes and checksums](risoux-real-scan-20261103.csv) retain all
+30 cases. The publisher annotation CSV matched its published MD5; each extracted
+ZIP member passed its CRC check. The full 10.5 GB archive was not downloaded
+or verified. No flight data, flight matching, location search, manually chosen
+event windows or frequency bands were used.
+
+To reproduce with the project runtime and optional `remotezip` package:
+
+```sh
+PYTHONPATH=src python scripts/benchmark_risoux_scan.py NEW_OUTPUT_DIRECTORY
+```
+
+The script requires a new output directory and keeps audio local. The completed
+run, source mapping, individual scanner results, and review images are at
+`/home/cinna/.local/state/dopplergeist-w4-risoux-20261103/`. Audio is not
+committed. The scanner used source `2864068`; intake and discovery match main
+at `b4f6e1c`.
diff --git a/scripts/benchmark_risoux_scan.py b/scripts/benchmark_risoux_scan.py
new file mode 100644
index 0000000..c0bde74
--- /dev/null
+++ b/scripts/benchmark_risoux_scan.py
@@ -0,0 +1,101 @@
+#!/usr/bin/env python3
+"""Screen selected real Risoux soundscapes without flight matching or location search.
+
+Requires the project runtime and optional ``remotezip``. Run with a new output
+path: ``PYTHONPATH=src python scripts/benchmark_risoux_scan.py NEW_OUTPUT_DIR``.
+Publisher labels are used for sampling and comparison, not scanner inputs.
+"""
+import csv
+import hashlib
+import io
+import json
+from pathlib import Path
+import random
+import sys
+import tempfile
+import urllib.request
+
+from remotezip import RemoteZip
+
+from dopplergeist.discovery import discover_events
+from dopplergeist.intake import intake_recording
+
+
+BASE = "https://zenodo.org/records/10701274/files/"
+SEED = 20261103
+ANNOTATIONS_MD5 = "bdc6b2c62b8fcfd5d6dae36460809683"
+
+
+def select(annotations, infos):
+ by_name = {Path(info.filename).name: info for info in infos if not info.is_dir()}
+ prefixes = sorted({row["prefix"] for row in annotations})
+ if len(prefixes) != 5 or len(by_name) != 1314:
+ raise ValueError("Publisher metadata changed: expected five prefixes and 1,314 WAV members")
+ rng = random.Random(SEED)
+ chosen = {}
+ for prefix in prefixes:
+ plane = [row for row in annotations if row["prefix"] == prefix and row["plane"] == "1"
+ and row["wind"] == row["rain"] == row["biophony"] == "0"]
+ silence = [row for row in annotations if row["prefix"] == prefix
+ and row["plane"] == "0" and row["silence"] == "1"]
+ chosen[prefix] = (rng.sample(sorted(plane, key=lambda row: row["filename"]), 5)
+ + rng.sample(sorted(silence, key=lambda row: row["filename"]), 1))
+ cases = []
+ for round_index in range(6):
+ for prefix in prefixes:
+ row = chosen[prefix][round_index]
+ item = by_name[row["filename"]]
+ cases.append({"name": item.filename, "size": item.file_size, "compressed_size": item.compress_size,
+ "crc": f"{item.CRC:08x}",
+ "opaque_id": hashlib.sha256(item.filename.encode()).hexdigest()[:20],
+ "publisher_label": "plane_only" if round_index < 5 else "silence_no_plane",
+ "prefix": prefix, "round": round_index + 1})
+ return cases
+
+
+def main(output):
+ output = Path(output)
+ output.mkdir(parents=True, exist_ok=False)
+ for folder in ("audio", "scans"):
+ (output / folder).mkdir()
+ with urllib.request.urlopen(BASE + "annotations.csv?download=1", timeout=60) as response:
+ raw_annotations = response.read()
+ if hashlib.md5(raw_annotations).hexdigest() != ANNOTATIONS_MD5:
+ raise ValueError("Publisher annotation checksum changed")
+ (output / "annotations.csv").write_bytes(raw_annotations)
+ annotations = list(csv.DictReader(io.StringIO(raw_annotations.decode("utf-8-sig"))))
+ with RemoteZip(BASE + "audio_recordings.zip?download=1", timeout=120) as archive:
+ cases = select(annotations, archive.infolist())
+ (output / "selection.json").write_text(json.dumps({"seed": SEED, "cases": cases}, indent=2) + "\n")
+ with (output / "outcomes.jsonl").open("w") as log:
+ for number, case in enumerate(cases, 1):
+ identifier = case["opaque_id"]
+ row = {"opaque_id": identifier, "case_number": number}
+ try:
+ raw = archive.read(case["name"]) # zipfile verifies this member's CRC.
+ if len(raw) != case["size"]:
+ raise ValueError("Uncompressed size differs from the archive index")
+ audio = output / "audio" / (identifier + ".wav")
+ audio.write_bytes(raw)
+ row["sha256"] = hashlib.sha256(raw).hexdigest()
+ with tempfile.TemporaryDirectory(prefix="decode-", dir=output) as temporary:
+ recording = intake_recording(audio, temporary)
+ events = discover_events(recording)
+ groups = {event.get("harmonic_group_id", event["event_id"]) for event in events}
+ scan = {"status": "scanned", "duration_s": recording.metadata["duration_s"],
+ "events": events, "ridge_count": len(events), "proposal_count": len(groups),
+ "scanner_result": "proposals" if groups else "no_proposals"}
+ (output / "scans" / (identifier + ".json")).write_text(json.dumps(scan) + "\n")
+ row.update(status="scanned", duration_s=scan["duration_s"],
+ scanner_result=scan["scanner_result"], proposal_count=scan["proposal_count"])
+ except Exception as error:
+ row.update(status="error", error=str(error))
+ log.write(json.dumps(row) + "\n")
+ log.flush()
+ print(number, len(cases), identifier, row["status"], row.get("scanner_result", ""), flush=True)
+
+
+if __name__ == "__main__":
+ if len(sys.argv) != 2:
+ raise SystemExit("Usage: benchmark_risoux_scan.py NEW_OUTPUT_DIR")
+ main(sys.argv[1])