Skip to content

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

Add per-curve web evidence and user-assisted review

Stecca824c4d64de90
diff --git a/README.md b/README.md
index 72071a7..eca1186 100644
--- a/README.md
+++ b/README.md
@@ -32,7 +32,7 @@
| **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, metropolitan France (including Corsica), and Italy (including Sicily and Sardinia), plus generated bounding envelopes for every other country and territory, grouped by continent ([COUNTRIES.md](docs/COUNTRIES.md)), with optional user-provided regional bounds. |
-| **Local browser application** | Recording uploads, persistent analysis jobs, inspectable results, progress monitoring, and supported resume/cancellation workflows. |
+| **Local browser application** | Recording uploads, persistent analysis jobs, per-curve spectrogram/audio evidence, false-positive review with user-assisted re-analysis, 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.
diff --git a/docs/AUDIO_DISCOVERY.md b/docs/AUDIO_DISCOVERY.md
index b0ba2a8..4b6c9c3 100644
--- a/docs/AUDIO_DISCOVERY.md
+++ b/docs/AUDIO_DISCOVERY.md
@@ -6,6 +6,8 @@ Intake decodes the original audio at 4 kHz and 24 kHz. Discovery combines ridge
`discovery/discovery.json` contains the input hash, detector settings, canonical proposal intervals and measured child tracks. Tracks belonging to a proposal share a `harmonic_group_id`; downstream association should count the group once while retaining its measured tracks. Times are relative to the first decoded sample. `--plot-summary` renders a track overview and `--plot-event-details` renders individual track plots. Use a new output directory for each run.
+Automatic analyses also write per-ridge spectrogram crops, ridge CSVs, bounded raw audio excerpts, illustrative band-limited excerpts and `discovery/event-media.json`. The raw excerpt is the primary listening evidence; the band-limited excerpt is not used by detection or scoring. Media failures are recorded in the index and do not stop the analysis. `discover` can render per-event plots with `--plot-event-details`; audio excerpts are generated by the automatic upload path.
+
Discovery uses fixed settings. A track is acoustic evidence, not proof that the source is an aircraft or that the pitch change was caused by physical motion. Missed, fragmented, merged and spurious proposals remain possible. Runtime, memory and disk use depend on recording length and content. Historical results from earlier discovery versions do not establish this detector's general performance or location accuracy.
[Earlier discovery documentation and historical results](archive/AUDIO_DISCOVERY_LEGACY.md) are preserved separately.
diff --git a/docs/INTERFACES.md b/docs/INTERFACES.md
index b531574..c2e9245 100644
--- a/docs/INTERFACES.md
+++ b/docs/INTERFACES.md
@@ -56,6 +56,17 @@ The automatic national acceptance test omits any truth-derived bounding box.
The request has no event windows, bands, known flight IDs or ground-truth location.
Those remain available in the separate research configuration interface.
+Optional `excluded_event_ids` is an explicit, nonempty list of automatically
+discovered event IDs to omit **after discovery** in this analysis. Optional
+`review_source_job_id` links the request to the job whose local review produced
+the exclusions and is valid only with `excluded_event_ids`. These fields never
+modify an earlier job. They exist for a user-assisted re-analysis started from
+the browser's curve review; they are not event windows, bands or truth inputs.
+The orchestrator keeps every discovered event in `discovery/discovery.json`,
+validates the excluded IDs against that discovery, and records the exclusion in
+`provenance.json` and the result `review` record. A request without these fields
+is unchanged.
+
## Intake metadata
`RecordingMetadata` records the original file's lowercase `source_sha256`, decoded
@@ -154,6 +165,14 @@ must be unique. If events are included, candidate event references must resolve.
An inconclusive job may retain ranked alternatives for diagnostics; its status
must prevent the UI from presenting them as an accepted location.
+Optional `review` marks a user-assisted analysis:
+`{"user_assisted": true, "excluded_event_ids": [...], "source_job_id": "..."}`.
+It is present only when the request supplied review exclusions. `events` contains
+the proposals actually searched; excluded proposals remain in the discovery
+artifact. `source_job_id` is optional. This record does not change the event
+contract, scores or decision thresholds, but downstream reporting must distinguish
+the result from an unassisted automatic run.
+
Optional `coverage` has `search_complete` (boolean), `data_status` (`available`,
`partial`, `unavailable`), and a list of known `limitations`. Optional
`requested_area` uses the request SearchArea shape; optional `missing_data` lists
@@ -171,7 +190,11 @@ assessment is available.
`artifacts` maps names to paths relative to that job's output directory, without
absolute paths or `..` traversal. Suggested names are `report`, `provenance`, and
-event-specific plots/arrays. The provenance artifact should record input/data/code
+event-specific plots/arrays. Automatic discovery writes per-event spectrogram
+crops, bounded raw and band-limited audio excerpts, ridge CSVs and
+`discovery/event-media.json`. The band-limited excerpt is a listening aid only and
+must not feed detection or scoring. A media-render error is recorded per event and
+does not fail the analysis. The provenance artifact should record input/data/code
hashes, configuration, time/altitude assumptions, searched/missing coverage and
runtime. The service must independently enforce output-directory containment when
serving files, including symlink handling. Do not embed huge spectra in job JSON.
diff --git a/docs/PRODUCT.md b/docs/PRODUCT.md
index bd18627..9887006 100644
--- a/docs/PRODUCT.md
+++ b/docs/PRODUCT.md
@@ -149,6 +149,39 @@ Missing time is a required-input result. Scores are ranking statistics, not
probabilities. Sensitivity radii must not be described as calibrated confidence.
An inconclusive result may retain candidate hypotheses for inspection.
+## Curve evidence and local review
+
+Automatic jobs write one media record per discovered ridge in `discovery/`:
+
+- `{event_id}.png`: a spectrogram crop with the measured ridge overlaid;
+- `{event_id}-audio.wav`: a bounded excerpt of the preserved recording, with
+ 1.5 s of padding and at most 60 s of audio;
+- `{event_id}-band.wav`: an illustrative band-limited excerpt for listening;
+- `{event_id}.csv`: the measured ridge points;
+- `event-media.json`: an index of the generated media and any per-event render
+ errors.
+
+The raw excerpt is the primary listening evidence. The band-limited excerpt is
+not used for detection, scoring or acceptance. A media-rendering failure is
+recorded in `event-media.json` and does not fail the analysis. Jobs analyzed
+before this feature show the measured ridge chart and data, with a note that
+media generation requires a new analysis.
+
+The browser groups ridges by harmonic group and lets a local reviewer label each
+ridge, or all ridges in a group, as `confirmed` or `false_positive`, with an
+optional note. Labels are stored in `event-reviews.json` in the job directory.
+They are annotations: they never change that job's scores, candidates, status,
+coverage or displayed location. The labels are downloadable with the other job
+artifacts.
+
+**Re-analyze without N false positives** starts a new job from the preserved
+original upload. The new request records `excluded_event_ids` and
+`review_source_job_id`; after discovery, only the explicitly marked event IDs are
+removed before search. The new job reports `review.user_assisted: true` and its
+provenance records the exclusion. The original job and its result remain
+unchanged. A reviewed exclusion is a user-assisted analysis, not an automatic
+result, and must not be presented as independent automatic validation.
+
## HTTP surface
- `GET /api/capabilities`: declared coverage, upload/work limits, and whether a flight provider and online acquisition are configured.
@@ -161,7 +194,17 @@ An inconclusive result may retain candidate hypotheses for inspection.
- `POST /api/jobs/{id}/resume`: explicitly continue a stopped job with a valid completed audio checkpoint.
- `GET /api/jobs/{id}/artifacts`: relative file paths and byte counts.
- `GET /api/jobs/{id}/artifacts/{path}`: download one artifact. Private operator
- configuration is excluded. Paths cannot escape the job directory.
+ configuration is excluded. Paths cannot escape the job directory. PNG, SVG,
+ WAV, MP3, FLAC, M4A and OGG artifacts are served inline; other files download.
+- `GET /api/jobs/{id}/reviews`: saved `confirmed` / `false_positive` labels and
+ optional notes for this job.
+- `POST /api/jobs/{id}/reviews`: JSON body
+ `{"label":"confirmed|false_positive|unreviewed","event_ids":["..."],"note":"optional"}`.
+ The label applies to every listed event. Unknown event IDs or labels are
+ rejected. This changes annotations only, never the result file.
+- `POST /api/jobs/{id}/reanalyze`: start a new user-assisted job that excludes
+ every curve currently marked `false_positive`. Returns the new queued job.
+ Requires at least one false-positive label.
Upload example (header metadata uses actual JSON, not a string-encoded file):
@@ -401,6 +444,11 @@ synthetic runs have produced accurate hypotheses and inconclusive decisions;
those are different outcomes. See the [README](../README.md#experimental-results)
for the reported results.
+Curve review labels are local human annotations, not calibrated probabilities or
+aircraft identities. A user-assisted re-analysis is explicitly marked and is not
+automatic validation. Media excerpts are illustrative diagnostics; listening to
+the band-limited excerpt does not establish that a proposal is an aircraft.
+
Independent real recordings with established recording time and location,
reliable global hypothesis discrimination, and calibrated false-localization
rates remain open. The acceptance goal is within 1,000 m, preferably 100–500 m;
diff --git a/src/dopplergeist/automatic.py b/src/dopplergeist/automatic.py
index aebc996..de53b93 100644
--- a/src/dopplergeist/automatic.py
+++ b/src/dopplergeist/automatic.py
@@ -89,22 +89,33 @@ def analyze(request, output_dir, config=None, progress=lambda *args, **kwargs: N
write_json(output / "request.json", request)
write_json(output / "provenance.json", provenance)
state = {"coverage": {"search_complete": False, "data_status": "unavailable", "limitations": [], "requested_area": request["search"]}}
+ excluded_event_ids = list(request.get("excluded_event_ids", []))
+ if excluded_event_ids:
+ state["review"] = {"user_assisted": True, "excluded_event_ids": sorted(excluded_event_ids)}
+ if request.get("review_source_job_id"):
+ state["review"]["source_job_id"] = request["review_source_job_id"]
+ provenance["event_selection"] = "automatic_whole_recording_with_user_review_exclusions"
+ provenance["excluded_event_ids"] = sorted(excluded_event_ids)
def finish(status, reason_code=None, message=None, **fields):
provenance["elapsed_s"] = time.monotonic() - began
provenance["status"] = status
provenance["coverage"] = fields.get("coverage", state["coverage"])
+ if "review" in state:
+ provenance["review"] = state["review"]
write_json(output / "provenance.json", provenance)
artifacts = {"provenance": "provenance.json", "request": "request.json"}
for name, path in (("intake", "intake/intake.json"), ("recording", "intake/recording.json"),
("discovery", "discovery/discovery.json"), ("discovery_plot", "discovery/discovery.png"),
+ ("event_media", "discovery/event-media.json"),
("search_report", "search/search-report.json"), ("refinement", "refined-candidates.json"),
("spectral_comparison", "spectral-comparison.json"),
("data_provenance", "data-provenance.json"), ("decision", "decision.json")):
if (output / path).is_file():
artifacts[name] = path
- for path in sorted((output / "discovery").glob("event-*.png")):
- artifacts[path.stem] = path.relative_to(output).as_posix()
+ for path in sorted((output / "discovery").glob("*.png")):
+ if path.name != "discovery.png":
+ artifacts[path.stem] = path.relative_to(output).as_posix()
value = dict(state, status=status, stage="complete", progress=1, artifacts=artifacts, **fields)
if reason_code:
value.update(reason_code=reason_code, message=message)
@@ -136,10 +147,13 @@ def analyze(request, output_dir, config=None, progress=lambda *args, **kwargs: N
return finish("failed", "invalid_configuration", "Spectral comparison accepts only work limits and spectral grid settings.")
if not resume:
progress("intake", 0.05, message="Decoding audio.")
+ def report_intake_progress(**details):
+ fraction, message = _decode_progress(0.05, 0.14, "Decoding audio", **details)
+ progress("intake", fraction, message=message)
+
try:
recording = intake_recording(request["audio_path"], output / "intake", time_window=request.get("time_window"),
- progress_callback=_throttled(lambda **details: progress(
- "intake", *_decode_progress(0.05, 0.14, "Decoding audio", **details))))
+ progress_callback=_throttled(report_intake_progress))
except AudioIntakeError as exc:
return finish("failed", exc.code, str(exc))
state["recording"] = recording.metadata
@@ -154,15 +168,27 @@ def analyze(request, output_dir, config=None, progress=lambda *args, **kwargs: N
events = [validate_event(event) for event in discover_events(
recording, output_dir=output / "discovery", settings=discovery_settings,
+ plot_event_details=True, event_audio=True,
progress_callback=_throttled(report_discovery_progress))]
_save_audio_checkpoint(output, request, config)
state["recording"] = recording.metadata
- state["events"] = events
provenance["discovered_events"] = len({event.get("harmonic_group_id", event["event_id"]) for event in events})
provenance["discovered_ridges"] = len(events)
+ if excluded_event_ids:
+ known = {event["event_id"] for event in events}
+ missing = sorted(set(excluded_event_ids) - known)
+ if missing:
+ return finish("failed", "invalid_configuration",
+ f"Excluded event IDs were not discovered: {', '.join(missing)}")
+ events = [event for event in events if event["event_id"] not in set(excluded_event_ids)]
+ provenance["searched_events"] = len({event.get("harmonic_group_id", event["event_id"]) for event in events})
+ provenance["searched_ridges"] = len(events)
+ state["events"] = events
if recording.time_status == "needs_input":
return finish("needs_input", "recording_time_required", "Supply a defensible UTC window for the start of this recording. File creation and upload times are not recording clocks.", required_fields=["time_window"])
if not events:
+ if excluded_event_ids:
+ return finish("inconclusive", "no_supported_events", "All discovered acoustic proposals were excluded by review.")
return finish("inconclusive", "no_supported_events", "No supported moving-tone Doppler events were discovered in the recording.")
# Coverage remains unassessed until the search report is available.
# Keep the initial state for explicit acquisition failure results.
diff --git a/src/dopplergeist/contracts.py b/src/dopplergeist/contracts.py
index 0030c37..d20ea17 100644
--- a/src/dopplergeist/contracts.py
+++ b/src/dopplergeist/contracts.py
@@ -32,6 +32,10 @@ class AnalysisRequest(TypedDict):
audio_path: str
time_window: NotRequired[RecordingTimeWindow | None]
search: NotRequired[SearchArea]
+ # Optional, explicit post-discovery review exclusion. This never changes an
+ # earlier automatic result; it starts a new, user-assisted analysis.
+ excluded_event_ids: NotRequired[list[str]]
+ review_source_job_id: NotRequired[str]
class RecordingMetadata(TypedDict):
@@ -93,6 +97,12 @@ class CoverageReport(TypedDict):
missing_data: NotRequired[list[str]]
+class ReviewRecord(TypedDict):
+ user_assisted: Literal[True]
+ excluded_event_ids: list[str]
+ source_job_id: NotRequired[str]
+
+
class JobResult(TypedDict):
schema_version: Literal[1]
job_id: str
@@ -103,6 +113,7 @@ class JobResult(TypedDict):
coverage: NotRequired[CoverageReport]
events: NotRequired[list[DetectedEvent]]
candidates: NotRequired[list[LocationCandidate]]
+ review: NotRequired[ReviewRecord]
reason_code: NotRequired[str]
message: NotRequired[str]
required_fields: NotRequired[list[str]]
@@ -124,6 +135,12 @@ def _text(value, name):
raise ValueError(f"{name} must be a nonempty string")
+def _job_id(value, name):
+ if (not isinstance(value, str) or len(value) != 32
+ or any(character not in "0123456789abcdef" for character in value)):
+ raise ValueError(f"{name} must be a lowercase 32-character hexadecimal job ID")
+
+
def _number(value, name, low=-math.inf, high=math.inf):
if isinstance(value, bool) or not isinstance(value, (int, float)):
raise ValueError(f"{name} must be a finite number")
@@ -157,10 +174,25 @@ def _utc(value):
def validate_request(value):
- request = _record(value, ("schema_version", "audio_path"), ("time_window", "search"))
+ request = _record(value, ("schema_version", "audio_path"),
+ ("time_window", "search", "excluded_event_ids", "review_source_job_id"))
if type(request["schema_version"]) is not int or request["schema_version"] != 1:
raise ValueError("Unsupported schema_version")
_text(request["audio_path"], "audio_path")
+ excluded = request.get("excluded_event_ids")
+ if excluded is not None:
+ if not isinstance(excluded, list) or not excluded:
+ raise ValueError("excluded_event_ids must be a nonempty list")
+ for event_id in excluded:
+ _text(event_id, "excluded event ID")
+ if len(set(excluded)) != len(excluded):
+ raise ValueError("excluded_event_ids must not repeat an ID")
+ request["excluded_event_ids"] = sorted(excluded)
+ source_job_id = request.get("review_source_job_id")
+ if source_job_id is not None:
+ _job_id(source_job_id, "review_source_job_id")
+ if excluded is None:
+ raise ValueError("review_source_job_id requires excluded_event_ids")
window = request.get("time_window")
if window is not None:
window = _record(window, ("start_utc", "end_utc", "source"), ("source_detail",))
@@ -276,7 +308,8 @@ def validate_candidate(value):
def validate_result(value):
- optional = ("stage", "progress", "recording", "coverage", "events", "candidates", "reason_code", "message", "required_fields", "artifacts")
+ optional = ("stage", "progress", "recording", "coverage", "events", "candidates", "review",
+ "reason_code", "message", "required_fields", "artifacts")
result = _record(value, ("schema_version", "job_id", "status"), optional)
if type(result["schema_version"]) is not int or result["schema_version"] != 1:
raise ValueError("Unsupported schema_version")
@@ -308,6 +341,20 @@ def validate_result(value):
raise ValueError(f"{name} must be a list")
if name in result:
result[name] = [validator(item) for item in result[name]]
+ if "review" in result:
+ review = _record(result["review"], ("user_assisted", "excluded_event_ids"), ("source_job_id",))
+ if review["user_assisted"] is not True:
+ raise ValueError("A review record must state user_assisted=true")
+ excluded = review["excluded_event_ids"]
+ if not isinstance(excluded, list) or not excluded:
+ raise ValueError("review.excluded_event_ids must be a nonempty list")
+ for event_id in excluded:
+ _text(event_id, "review excluded event ID")
+ if len(set(excluded)) != len(excluded):
+ raise ValueError("review.excluded_event_ids must not repeat an ID")
+ if "source_job_id" in review:
+ _job_id(review["source_job_id"], "review.source_job_id")
+ result["review"] = review
ids = [event["event_id"] for event in result.get("events", [])]
if len(set(ids)) != len(ids):
raise ValueError("Event IDs must be unique")
diff --git a/src/dopplergeist/discovery.py b/src/dopplergeist/discovery.py
index 8bb4600..15b669a 100644
--- a/src/dopplergeist/discovery.py
+++ b/src/dopplergeist/discovery.py
@@ -5,6 +5,7 @@ aircraft identity. No straight-pass speed/slant fit is required for acceptance.
"""
from dataclasses import asdict, dataclass, replace
import json
+import math
from pathlib import Path
from statistics import median
from tempfile import TemporaryDirectory
@@ -351,7 +352,7 @@ def _discover_baseline_events(recording, *, output_dir=None, settings=None, plot
def discover_events(recording, *, output_dir=None, settings=None, plot_summary=True, plot_event_details=False,
- progress_callback=None):
+ event_audio=False, progress_callback=None):
"""Discover acoustic proposals; ``progress_callback(phase=..., **counts)`` reports activity only."""
from .advanced_discovery import discover
from .intake import intake_recording
@@ -403,11 +404,8 @@ def discover_events(recording, *, output_dir=None, settings=None, plot_summary=T
report("writing_plots")
if plot_summary:
_plot_groups(groups, output / "discovery.png", recording.metadata["duration_s"], settings.max_gap_s)
- if plot_event_details:
- plot_settings = replace(settings, max_frequency_hz=8000.)
- for event in events:
- points = np.array([[p["time_s"], p["frequency_hz"], p["weight"]] for p in event["ridge"]])
- _plot_event(auxiliary, [points], event, plot_settings, output / f"{event['event_id']}.png")
+ _write_event_media(auxiliary, events, output, settings,
+ plot_event_details=plot_event_details, event_audio=event_audio)
return events
if output_dir is not None:
@@ -416,6 +414,118 @@ def discover_events(recording, *, output_dir=None, settings=None, plot_summary=T
return run(Path(temporary))
+_EVENT_AUDIO_PADDING_S = 1.5
+_EVENT_AUDIO_MAX_S = 60.0
+
+
+def _event_clip_bounds(event, duration_s):
+ """Return an audio-relative interval for a bounded playback excerpt."""
+ duration_s = float(duration_s)
+ wanted_start = max(0.0, event["start_s"] - _EVENT_AUDIO_PADDING_S)
+ wanted_end = min(duration_s, event["end_s"] + _EVENT_AUDIO_PADDING_S)
+ wanted_length = wanted_end - wanted_start
+ length = min(_EVENT_AUDIO_MAX_S, duration_s, wanted_length)
+ center = (wanted_start + wanted_end) / 2
+ start = max(0.0, min(center - length / 2, duration_s - length))
+ end = start + length
+ truncated = wanted_length > length + 1e-9
+ return start, end, truncated
+
+
+def _band_limited(data, sample_rate_hz, band_hz):
+ """Isolate an event's measured band for listening only, not for analysis."""
+ if len(data) < 64:
+ return None
+ nyquist = sample_rate_hz / 2
+ low, high = float(band_hz[0]), float(band_hz[1])
+ center = max(1.0, math.sqrt(max(low, 1.0) * max(high, 1.0)))
+ width = max(high - low, 0.25 * center, 20.0)
+ low = max(20.0, low - 0.1 * width)
+ high = min(nyquist * 0.98, high + 0.1 * width)
+ if not 0 < low < high < nyquist or high - low < 10.0:
+ return None
+ sos = signal.butter(3, [low, high], btype="bandpass", fs=sample_rate_hz, output="sos")
+ return np.asarray(signal.sosfiltfilt(sos, data), dtype=np.float32)
+
+
+def _write_event_audio(recording, event, path, *, band_limited=False):
+ """Write one bounded recording excerpt, optionally band-limited."""
+ sample_rate_hz = int(recording.metadata["sample_rate_hz"])
+ start, end, truncated = _event_clip_bounds(event, recording.metadata["duration_s"])
+ samples = np.memmap(recording.samples_path, dtype="<f4", mode="r")
+ first = max(0, int(round(start * sample_rate_hz)))
+ last = min(len(samples), int(round(end * sample_rate_hz)))
+ data = np.asarray(samples[first:last], dtype=np.float32).copy()
+ if len(data) == 0:
+ raise ValueError("Event excerpt is empty")
+ if band_limited:
+ filtered = _band_limited(data, sample_rate_hz, event["band_hz"])
+ if filtered is None:
+ return None
+ data = filtered
+ fade = min(len(data), max(1, int(round(0.01 * sample_rate_hz))))
+ ramp = np.linspace(0.0, 1.0, fade, dtype=np.float32)
+ data[:fade] *= ramp
+ data[-fade:] *= ramp[::-1]
+ peak = float(np.max(np.abs(data)))
+ if not math.isfinite(peak):
+ raise ValueError("Event excerpt contains a non-finite sample")
+ if band_limited and peak > 0:
+ data = data * (0.95 / peak)
+ elif peak > 1.0:
+ data = data / peak
+ from soundfile import write
+ write(path, data, sample_rate_hz, subtype="PCM_16")
+ return {"path": path.name, "start_s": first / sample_rate_hz,
+ "end_s": last / sample_rate_hz, "truncated": truncated}
+
+
+def _write_event_media(recording, events, output, settings, *, plot_event_details, event_audio):
+ """Write per-event plot, ridge and audio evidence without failing discovery."""
+ media = {"schema_version": 1,
+ "clip": {"padding_s": _EVENT_AUDIO_PADDING_S, "max_duration_s": _EVENT_AUDIO_MAX_S},
+ "scope": "illustrative excerpts from the preserved recording; band-limited audio is not used for detection or scoring",
+ "events": {}}
+ plot_settings = replace(settings, max_frequency_hz=8000.)
+ for event in events:
+ event_id = event["event_id"]
+ entry = {}
+ errors = []
+ points = np.array([[point["time_s"], point["frequency_hz"], point.get("weight", 1.0)]
+ for point in event["ridge"]])
+ try:
+ np.savetxt(output / f"{event_id}.csv", points, delimiter=",",
+ header="time_s,frequency_hz,weight", comments="")
+ entry["ridge_csv"] = f"{event_id}.csv"
+ except (OSError, ValueError) as exc:
+ errors.append(f"ridge_csv: {type(exc).__name__}: {exc}")
+ if plot_event_details:
+ try:
+ _plot_event(recording, [points], event, plot_settings, output / f"{event_id}.png")
+ entry["image"] = f"{event_id}.png"
+ except Exception as exc: # A diagnostic render must not fail analysis.
+ errors.append(f"image: {type(exc).__name__}: {exc}")
+ if event_audio:
+ try:
+ raw = _write_event_audio(recording, event, output / f"{event_id}-audio.wav")
+ audio = {"raw": raw["path"], "start_s": raw["start_s"],
+ "end_s": raw["end_s"], "truncated": raw["truncated"],
+ "sample_rate_hz": recording.metadata["sample_rate_hz"]}
+ band = _write_event_audio(recording, event, output / f"{event_id}-band.wav",
+ band_limited=True)
+ if band:
+ audio["band_limited"] = band["path"]
+ entry["audio"] = audio
+ except Exception as exc:
+ errors.append(f"audio: {type(exc).__name__}: {exc}")
+ if errors:
+ entry["errors"] = errors
+ media["events"][event_id] = entry
+ (output / "event-media.json").write_text(
+ json.dumps(media, indent=2, allow_nan=False) + "\n")
+ return media
+
+
def _plot_groups(groups, path, duration, max_gap_s=2.0):
import matplotlib
matplotlib.use("Agg")
diff --git a/src/dopplergeist/event_reviews.py b/src/dopplergeist/event_reviews.py
new file mode 100644
index 0000000..2fb07ce
--- /dev/null
+++ b/src/dopplergeist/event_reviews.py
@@ -0,0 +1,108 @@
+"""Persistent local review labels for discovered acoustic proposals.
+
+Labels are annotations. They do not alter an automatic job's scores, candidates,
+status or location. A separate user-assisted analysis can exclude the event IDs
+explicitly marked ``false_positive``.
+"""
+from datetime import datetime, timezone
+import json
+import os
+from pathlib import Path
+import threading
+
+REVIEW_FILE = "event-reviews.json"
+REVIEW_LABELS = {"confirmed", "false_positive"}
+_REVIEW_LOCK = threading.RLock()
+
+
+class ReviewError(ValueError):
+ """Invalid or unreadable review data."""
+
+
+def _now():
+ return datetime.now(timezone.utc).replace(microsecond=0).isoformat().replace("+00:00", "Z")
+
+
+def _atomic_write(path, value):
+ path = Path(path)
+ temporary = path.with_name(path.name + ".tmp")
+ temporary.write_text(json.dumps(value, indent=2, allow_nan=False) + "\n")
+ os.replace(temporary, path)
+
+
+def _validate_entry(event_id, entry):
+ if not isinstance(event_id, str) or not event_id.strip():
+ raise ReviewError("Review labels must use nonempty event IDs")
+ if not isinstance(entry, dict) or entry.keys() - {"label", "note", "updated_utc"}:
+ raise ReviewError(f"Invalid review entry for {event_id}")
+ if entry.get("label") not in REVIEW_LABELS:
+ raise ReviewError(f"Unknown review label for {event_id}")
+ for name in ("note", "updated_utc"):
+ if name in entry and not isinstance(entry[name], str):
+ raise ReviewError(f"{name} must be text for {event_id}")
+ if len(entry.get("note", "")) > 1000:
+ raise ReviewError(f"Review note is too long for {event_id}")
+
+
+def read_reviews(job_dir):
+ path = Path(job_dir) / REVIEW_FILE
+ if not path.is_file():
+ return {"schema_version": 1, "labels": {}}
+ try:
+ value = json.loads(path.read_text())
+ except (OSError, json.JSONDecodeError) as exc:
+ raise ReviewError(f"Saved review labels are unreadable: {exc}") from exc
+ if (not isinstance(value, dict) or value.keys() - {"schema_version", "labels", "updated_utc"}
+ or value.get("schema_version") != 1 or not isinstance(value.get("labels"), dict)):
+ raise ReviewError("Saved review labels have an unsupported shape")
+ if "updated_utc" in value and not isinstance(value["updated_utc"], str):
+ raise ReviewError("updated_utc must be text")
+ for event_id, entry in value["labels"].items():
+ _validate_entry(event_id, entry)
+ return value
+
+
+def write_reviews(job_dir, labels):
+ with _REVIEW_LOCK:
+ value = {"schema_version": 1, "labels": {key: labels[key] for key in sorted(labels)}}
+ if value["labels"]:
+ value["updated_utc"] = _now()
+ _atomic_write(Path(job_dir) / REVIEW_FILE, value)
+ return value
+
+
+def apply_review(job_dir, known_event_ids, label, event_ids, note=None):
+ if label not in REVIEW_LABELS and label != "unreviewed":
+ raise ReviewError("Review label must be confirmed, false_positive or unreviewed")
+ if not isinstance(event_ids, list) or not event_ids:
+ raise ReviewError("Choose at least one event to review")
+ if len(set(event_ids)) != len(event_ids):
+ raise ReviewError("Review event IDs must not repeat")
+ known = set(known_event_ids)
+ unknown = sorted(set(event_ids) - known)
+ if unknown:
+ raise ReviewError(f"Unknown event IDs: {', '.join(unknown)}")
+ if note is not None and not isinstance(note, str):
+ raise ReviewError("Review note must be text")
+ note = (note or "").strip()
+ if len(note) > 1000:
+ raise ReviewError("Review note must be at most 1000 characters")
+ with _REVIEW_LOCK:
+ reviews = read_reviews(job_dir)
+ labels = dict(reviews["labels"])
+ updated = _now()
+ for event_id in event_ids:
+ if label == "unreviewed":
+ labels.pop(event_id, None)
+ else:
+ entry = {"label": label, "updated_utc": updated}
+ if note:
+ entry["note"] = note
+ labels[event_id] = entry
+ return write_reviews(job_dir, labels)
+
+
+def false_positive_ids(job_dir):
+ reviews = read_reviews(job_dir)
+ return sorted(event_id for event_id, entry in reviews["labels"].items()
+ if entry["label"] == "false_positive")
diff --git a/src/dopplergeist/jobs.py b/src/dopplergeist/jobs.py
index 89ec199..d9f1dc7 100644
--- a/src/dopplergeist/jobs.py
+++ b/src/dopplergeist/jobs.py
@@ -15,6 +15,7 @@ import time
import uuid
from .contracts import validate_request, validate_result
+from .event_reviews import false_positive_ids
TERMINAL = {"needs_input", "succeeded", "inconclusive", "failed", "cancelled"}
PROGRESS_STALE_AFTER_S = 60.0
@@ -64,7 +65,8 @@ def result(job_dir, status, **fields):
def _evidence(value):
- return {key: value[key] for key in ("recording", "events", "candidates", "coverage", "artifacts") if key in value}
+ return {key: value[key] for key in ("recording", "events", "candidates", "coverage", "review", "artifacts")
+ if key in value}
@contextmanager
@@ -326,6 +328,31 @@ class JobManager:
thread.start()
return queued
+ def reanalyze(self, job_id):
+ """Start a new user-assisted job excluding this job's false-positive events."""
+ directory = self.directory(job_id)
+ current = self.get(job_id)
+ excluded = false_positive_ids(directory)
+ if not excluded:
+ raise ValueError("Mark at least one discovered curve as a false positive first")
+ known = {event["event_id"] for event in current.get("events", [])}
+ unknown = sorted(set(excluded) - known)
+ if unknown:
+ raise ValueError(f"Saved review labels reference unknown events: {', '.join(unknown)}")
+ try:
+ request = read_json(directory / "request.json")
+ input_info = read_json(directory / "input.json")
+ except (OSError, json.JSONDecodeError) as exc:
+ raise ValueError(f"Saved job input is unreadable: {exc}") from exc
+ request.pop("audio_path", None)
+ request["excluded_event_ids"] = sorted(set(excluded) | set(request.get("excluded_event_ids", [])))
+ request["review_source_job_id"] = job_id
+ input_path = directory / Path(str(input_info.get("path", ""))).name
+ if not input_path.is_file():
+ raise ValueError("The preserved original upload is unavailable")
+ with input_path.open("rb") as source:
+ return self.submit(request, source, input_path.stat().st_size, suffix=input_path.suffix)
+
def wait(self, job_id):
thread = self._threads.get(job_id)
if thread:
diff --git a/src/dopplergeist/service.py b/src/dopplergeist/service.py
index 0bfc9b9..bfd300c 100644
--- a/src/dopplergeist/service.py
+++ b/src/dopplergeist/service.py
@@ -6,12 +6,15 @@ from importlib.resources import files
from pathlib import Path
from urllib.parse import unquote, urlsplit
+from .event_reviews import apply_review, read_reviews
from .geography import public_profiles
from .jobs import JobManager, TERMINAL
_EXCLUDED_ARTIFACTS = {"operator.json", "cancel", ".control.lock"}
_SENSITIVE_LOCATION_OUTPUTS = {"search", "refined-candidates.json", "decision.json", "spectral-comparison.json"}
_RESTRICTED_RESULT_CODES = {"restricted_location", "region_policy_unavailable"}
+_INLINE_SUFFIXES = {".png", ".svg", ".wav", ".mp3", ".flac", ".m4a", ".ogg"}
+_JSON_BODY_LIMIT = 64 * 1024
class JobServer(ThreadingHTTPServer):
@@ -46,6 +49,23 @@ class Handler(BaseHTTPRequestHandler):
if origin and origin not in {"http://" + host for host in allowed}:
raise PermissionError("Requests must originate from this local interface")
+ def _json_body(self):
+ if self.headers.get_content_type() != "application/json":
+ raise ValueError("Send review data as application/json")
+ try:
+ length = int(self.headers.get("Content-Length", "0"))
+ except ValueError:
+ raise ValueError("Invalid Content-Length") from None
+ if length <= 0 or length > _JSON_BODY_LIMIT:
+ raise ValueError(f"Review body must contain 1..{_JSON_BODY_LIMIT} bytes")
+ try:
+ value = json.loads(self.rfile.read(length))
+ except json.JSONDecodeError as exc:
+ raise ValueError(f"Invalid review JSON: {exc}") from exc
+ if not isinstance(value, dict):
+ raise ValueError("Review body must be a JSON object")
+ return value
+
def _route(self):
self._check_origin()
parts = [unquote(p) for p in urlsplit(self.path).path.strip("/").split("/")]
@@ -74,6 +94,21 @@ class Handler(BaseHTTPRequestHandler):
from .jobs import status_for_display
directory = manager.directory(job_id)
return self._reply(status_for_display(directory, manager.get(job_id)))
+ if self.command == "GET" and parts[3:] == ["reviews"]:
+ return self._reply(read_reviews(manager.directory(job_id)))
+ if self.command == "POST" and parts[3:] == ["reviews"]:
+ current = manager.get(job_id)
+ known = [event["event_id"] for event in current.get("events", [])]
+ if not known:
+ raise ValueError("This job has no discovered events to review")
+ body = self._json_body()
+ if body.keys() - {"label", "event_ids", "note"}:
+ raise ValueError("Review body accepts only label, event_ids and note")
+ return self._reply(apply_review(manager.directory(job_id), known,
+ body.get("label"), body.get("event_ids"),
+ body.get("note")))
+ if self.command == "POST" and parts[3:] == ["reanalyze"]:
+ return self._reply(manager.reanalyze(job_id), 202)
if self.command == "GET" and parts[3:] == ["guidance"]:
from .guidance import explain_job
return self._reply(explain_job(manager.directory(job_id)))
@@ -110,7 +145,7 @@ class Handler(BaseHTTPRequestHandler):
if (current.get("status") not in TERMINAL
and resolved_relative.parts[0] in _SENSITIVE_LOCATION_OUTPUTS):
raise PermissionError("Location artifacts are unavailable while analysis is running.")
- return self._file(path, download=path.suffix not in {".png", ".svg"})
+ return self._file(path, download=path.suffix.lower() not in _INLINE_SUFFIXES)
if self.command == "GET":
asset = {"/": "index.html", "/app.js": "app.js", "/style.css": "style.css",
"/leaflet.js": "leaflet.js", "/leaflet.css": "leaflet.css",
diff --git a/src/dopplergeist/web/app.js b/src/dopplergeist/web/app.js
index ee52974..aa0bbe9 100644
--- a/src/dopplergeist/web/app.js
+++ b/src/dopplergeist/web/app.js
@@ -2,7 +2,22 @@
const $ = id => document.getElementById(id);
const terminal = new Set(['needs_input', 'succeeded', 'inconclusive', 'failed', 'cancelled']);
let activeJob = null, renderedJob = null, timer = null, maxBytes = 100 * 1024 * 1024;
+let artifactJob = null, artifactPaths = new Set(), mediaJob = null, mediaIndex = null;
+let reviews = {schema_version: 1, labels: {}}, evidenceKey = '';
+let hideFalsePositives = false, reanalysisPending = false;
+try { hideFalsePositives = localStorage.getItem('dopplergeist-hide-false') === '1'; } catch (_) { /* optional */ }
const node = (tag, text, cls) => { const n = document.createElement(tag); if (text !== undefined) n.textContent = text; if (cls) n.className = cls; return n; };
+const artifactUrl = (id, path) => `/api/jobs/${id}/artifacts/${path.split('/').map(encodeURIComponent).join('/')}`;
+const REVIEW_LABELS = {confirmed: 'Confirmed curve', false_positive: 'False positive', unreviewed: 'Unreviewed'};
+const reviewLabel = event => reviews.labels?.[event.event_id]?.label || 'unreviewed';
+const reviewNote = event => reviews.labels?.[event.event_id]?.note || '';
+function resetEvidence() {
+ artifactJob = null; artifactPaths = new Set(); mediaJob = null; mediaIndex = null;
+ reviews = {schema_version: 1, labels: {}}; evidenceKey = '';
+}
+function hasArtifact(id, path) {
+ return artifactJob === id && artifactPaths.has(path);
+}
// Older services and unavailable capability responses expose only legacy CONUS.
const CONUS_PROFILE = {country: 'US', coverage: 'conus', name: 'Contiguous United States (CONUS)', bounds_wsen: [-125, 24, -66, 50]};
let countryProfiles = [CONUS_PROFILE], areaControl = null, countrySelectionSupported = false;
@@ -110,22 +125,55 @@ function renderRecent() {
$('recent-panel').hidden = !$('recent').children.length;
} catch (_) { /* Optional recent-job links. */ }
}
-async function artifacts(id) {
- const response = await api(`/api/jobs/${id}/artifacts`);
- if (id !== activeJob) return;
- $('resume').hidden = !['cancelled', 'failed', 'inconclusive'].includes($('status').textContent) || !response.artifacts.some(item => item.path === 'resume.json');
+function renderArtifacts(id, items, status) {
+ artifactJob = id; artifactPaths = new Set(items.map(item => item.path));
+ $('resume').hidden = !['cancelled', 'failed', 'inconclusive'].includes(status)
+ || !artifactPaths.has('resume.json');
$('artifacts').replaceChildren(); $('diagnostics').replaceChildren();
- for (const item of response.artifacts) {
- const href = `/api/jobs/${id}/artifacts/${item.path.split('/').map(encodeURIComponent).join('/')}`;
+ for (const item of items) {
+ const href = artifactUrl(id, item.path);
const li = node('li'); const a = node('a', item.path); a.href = href; a.download = '';
li.append(a, node('span', ` · ${(item.bytes / 1024).toFixed(1)} KB`, 'muted')); $('artifacts').append(li);
- if (/\.png$/i.test(item.path) && /event|spectro|discovery|model|location/i.test(item.path)) {
+ if (/\.png$/i.test(item.path) && !/^discovery\/event-[^/]+\.png$/i.test(item.path)
+ && /event|spectro|discovery|model|location/i.test(item.path)) {
const figure = node('figure', undefined, 'diagnostic'); const img = node('img');
img.src = href; img.alt = `Analysis evidence: ${item.path}`; img.loading = 'lazy';
figure.append(img, node('figcaption', item.path)); $('diagnostics').append(figure);
}
}
}
+
+async function loadMediaIndex(id) {
+ if (mediaJob === id) return;
+ mediaJob = id; mediaIndex = null;
+ if (!hasArtifact(id, 'discovery/event-media.json')) return;
+ try {
+ const value = await api(artifactUrl(id, 'discovery/event-media.json'));
+ if (mediaJob === id && value && typeof value === 'object') mediaIndex = value;
+ } catch (_) { /* Older or partial jobs may not have a readable media index. */ }
+}
+
+async function refreshEvidence(id, value, force = false) {
+ if (id !== activeJob || !value) return;
+ const key = `${id}:${value.status}:${value.progress ?? ''}:${value.events?.length || 0}:${(value.review?.excluded_event_ids || []).join(',')}`;
+ if (!force && key === evidenceKey) return;
+ evidenceKey = key;
+ try {
+ const [reviewValue, artifactValue] = await Promise.all([
+ api(`/api/jobs/${id}/reviews`),
+ api(`/api/jobs/${id}/artifacts`),
+ ]);
+ if (id !== activeJob) return;
+ reviews = reviewValue;
+ renderArtifacts(id, artifactValue.artifacts, value.status);
+ await loadMediaIndex(id);
+ if (id !== activeJob) return;
+ renderEvents(value);
+ } catch (error) {
+ evidenceKey = '';
+ if (id === activeJob) $('connection').textContent = `Could not read curve evidence: ${error.message}`;
+ }
+}
function coordinateCopyControl(lat, lon) {
const control = node('div', undefined, 'coordinate-copy');
const button = node('button', 'Copy coordinates', 'secondary');
@@ -181,7 +229,7 @@ function stageLabel(value) {
const index = STAGES.findIndex(([name]) => name === value.stage);
const label = index < 0 ? (value.stage || '').replaceAll('_', ' ')
: `Step ${index + 1}/${STAGES.length}: ${STAGES[index][1]}`;
- const elapsed = Number.isFinite(value.elapsed_seconds) ? ` � ${formatDuration(value.elapsed_seconds)} elapsed` : '';
+ const elapsed = Number.isFinite(value.elapsed_seconds) ? ` � ${formatDuration(value.elapsed_seconds)} elapsed` : '';
return `${label}${elapsed}`;
}
@@ -237,13 +285,304 @@ function render(value) {
}
});
}
- $('events').replaceChildren();
- if (value.events?.length) {
- const groups = new Set(value.events.map(event => event.harmonic_group_id || event.event_id)).size;
- $('events').append(node('h3', `${groups} acoustic proposal groups · ${value.events.length} ridge records`));
- for (const event of value.events) $('events').append(node('div', `${event.event_id} · ${event.start_s.toFixed(1)}–${event.end_s.toFixed(1)} s · ${event.band_hz.map(x => x.toFixed(0)).join('–')} Hz${event.harmonic_group_id ? ` · group ${event.harmonic_group_id}` : ''}`, 'event'));
+ const assist = $('review-assist');
+ if (value.review?.user_assisted) {
+ const excluded = value.review.excluded_event_ids?.length || 0;
+ const source = value.review.source_job_id ? ` from job ${value.review.source_job_id.slice(0, 12)}` : '';
+ assist.textContent = `User-assisted re-analysis${source}: ${excluded} curve${excluded === 1 ? '' : 's'} marked false positive ${excluded === 1 ? 'was' : 'were'} excluded before search. This is not an automatic result.`;
+ assist.hidden = false;
+ } else {
+ assist.textContent = ''; assist.hidden = true;
+ }
+ renderEvents(value);
+}
+const svgNode = (tag, attributes = {}) => {
+ const element = document.createElementNS('http://www.w3.org/2000/svg', tag);
+ for (const [key, value] of Object.entries(attributes)) element.setAttribute(key, value);
+ return element;
+};
+
+function formatEventSeconds(value) {
+ return Number.isFinite(value) ? value.toFixed(1) : '—';
+}
+
+function formatQuality(value) {
+ if (!Number.isFinite(value)) return String(value);
+ return Math.abs(value) >= 1000 || (Math.abs(value) < 0.001 && value !== 0)
+ ? value.toExponential(2) : String(Number(value.toPrecision(4)));
+}
+
+function eventGroups(value) {
+ const groups = new Map();
+ for (const event of value.events || []) {
+ const key = event.harmonic_group_id || event.event_id;
+ if (!groups.has(key)) groups.set(key, []);
+ groups.get(key).push(event);
+ }
+ return groups;
+}
+
+function ridgeChart(event) {
+ if (!Array.isArray(event.ridge) || event.ridge.length < 2) return null;
+ const width = 340, height = 128, left = 38, right = 8, top = 10, bottom = 22;
+ const t0 = Math.min(event.start_s, event.ridge[0].time_s);
+ const t1 = Math.max(event.end_s, event.ridge[event.ridge.length - 1].time_s);
+ let f0 = event.band_hz[0], f1 = event.band_hz[1];
+ const fpad = Math.max(1, (f1 - f0) * 0.05);
+ f0 -= fpad; f1 += fpad;
+ const dx = Math.max(1e-9, t1 - t0), df = Math.max(1e-9, f1 - f0);
+ const x = value => left + ((value - t0) / dx) * (width - left - right);
+ const y = value => height - bottom - ((value - f0) / df) * (height - top - bottom);
+ const svg = svgNode('svg', {
+ viewBox: `0 0 ${width} ${height}`, class: 'ridge-chart', role: 'img',
+ 'aria-label': `Measured ridge for ${event.event_id}: ${formatEventSeconds(t0)} to ${formatEventSeconds(t1)} seconds, ${Math.round(event.band_hz[0])} to ${Math.round(event.band_hz[1])} hertz`,
+ });
+ svg.append(svgNode('rect', {x: 0, y: 0, width, height, fill: '#0d1517'}));
+ svg.append(svgNode('line', {x1: left, y1: top, x2: left, y2: height - bottom, stroke: '#334247'}));
+ svg.append(svgNode('line', {x1: left, y1: height - bottom, x2: width - right, y2: height - bottom, stroke: '#334247'}));
+ const segments = []; let current = [];
+ for (const point of event.ridge) {
+ if (current.length && point.time_s - current[current.length - 1].time_s > 2) {
+ segments.push(current); current = [];
+ }
+ current.push(point);
+ }
+ if (current.length) segments.push(current);
+ for (const segment of segments) {
+ if (segment.length < 2) continue;
+ svg.append(svgNode('polyline', {
+ points: segment.map(point => `${x(point.time_s).toFixed(1)},${y(point.frequency_hz).toFixed(1)}`).join(' '),
+ fill: 'none', stroke: '#baf078', 'stroke-width': '1.8',
+ 'stroke-linejoin': 'round', 'stroke-linecap': 'round',
+ }));
+ }
+ const label = (attributes, text) => {
+ const element = svgNode('text', {fill: '#a6b8bd', 'font-size': '9', ...attributes});
+ element.textContent = text; svg.append(element);
+ };
+ label({x: left - 4, y: top + 4, 'text-anchor': 'end'}, String(Math.round(f1)));
+ label({x: left - 4, y: height - bottom + 4, 'text-anchor': 'end'}, String(Math.round(f0)));
+ label({x: left, y: height - 6}, `${formatEventSeconds(t0)} s`);
+ label({x: width - right, y: height - 6, 'text-anchor': 'end'}, `${formatEventSeconds(t1)} s`);
+ return svg;
+}
+
+async function submitReview(jobId, eventIds, label, note = '') {
+ try {
+ const saved = await api(`/api/jobs/${jobId}/reviews`, {
+ method: 'POST', headers: {'Content-Type': 'application/json'},
+ body: JSON.stringify({label, event_ids: eventIds, note}),
+ });
+ if (jobId !== activeJob) return;
+ reviews = saved;
+ $('connection').textContent = '';
+ renderEvents(renderedJob, true);
+ } catch (error) {
+ if (jobId !== activeJob) return;
+ $('connection').textContent = `Could not save review labels: ${error.message}`;
+ renderEvents(renderedJob, true);
+ }
+}
+
+function reviewControl(event, jobId) {
+ const wrapper = node('div', undefined, 'event-review');
+ const row = node('div', undefined, 'review-row');
+ row.append(node('label', 'Review', 'review-label'));
+ const select = node('select', undefined, 'review-select');
+ select.setAttribute('aria-label', `Review ${event.event_id}`);
+ for (const [value, text] of Object.entries(REVIEW_LABELS)) {
+ const option = node('option', text); option.value = value; select.append(option);
+ }
+ select.value = reviewLabel(event);
+ const note = node('input', undefined, 'review-note');
+ note.type = 'text'; note.maxLength = 1000;
+ note.placeholder = 'Optional review note';
+ note.value = reviewNote(event);
+ let saveTimer = null;
+ const save = (always = false) => {
+ if (!always && select.value === 'unreviewed') return;
+ clearTimeout(saveTimer);
+ saveTimer = setTimeout(() => submitReview(jobId, [event.event_id], select.value, note.value.trim()), 250);
+ };
+ select.addEventListener('change', () => save(true));
+ note.addEventListener('change', () => save(false));
+ row.append(select);
+ wrapper.append(row, note, node('p', 'Annotations do not change this job\'s scores, candidates or location.', 'help'));
+ return wrapper;
+}
+
+function groupReviewControl(group, jobId) {
+ const labels = new Set(group.map(reviewLabel));
+ const select = node('select', undefined, 'review-select');
+ select.setAttribute('aria-label', 'Review all curves in this harmonic group');
+ const prompt = node('option', 'Group review…'); prompt.value = ''; select.append(prompt);
+ for (const [value, text] of Object.entries(REVIEW_LABELS)) {
+ const option = node('option', text); option.value = value; select.append(option);
+ }
+ select.value = labels.size === 1 ? [...labels][0] : '';
+ select.addEventListener('change', () => {
+ if (select.value) submitReview(jobId, group.map(event => event.event_id), select.value, '');
+ });
+ return select;
+}
+
+async function startReanalysis(count, button) {
+ if (reanalysisPending) return;
+ if (!confirm(`Start a new user-assisted analysis without ${count} curve${count === 1 ? '' : 's'} marked false positive? The current job and its result will not change.`)) return;
+ reanalysisPending = true; button.disabled = true;
+ try {
+ const queued = await api(`/api/jobs/${activeJob}/reanalyze`, {method: 'POST'});
+ selectJob(queued.job_id);
+ } catch (error) {
+ $('connection').textContent = `Could not start re-analysis: ${error.message}`;
+ button.disabled = false;
+ } finally {
+ reanalysisPending = false;
+ }
+}
+
+function eventCard(value, event) {
+ const id = event.event_id;
+ const label = reviewLabel(event);
+ const card = node('article', undefined, `event-card ${label}`);
+ const head = node('div', undefined, 'event-card-head');
+ head.append(node('strong', id), node('span', REVIEW_LABELS[label], `badge ${label}`));
+ card.append(head);
+ card.append(node('p', `${formatEventSeconds(event.start_s)}–${formatEventSeconds(event.end_s)} s · ${Math.round(event.band_hz[0])}–${Math.round(event.band_hz[1])} Hz${event.harmonic_group_id ? ` · ${event.harmonic_group_id}` : ''}`, 'mono'));
+ const chart = ridgeChart(event);
+ if (chart) card.append(chart);
+ const media = mediaJob === value.job_id ? mediaIndex?.events?.[id] || null : null;
+ const imagePath = media?.image ? `discovery/${media.image}` : `discovery/${id}.png`;
+ if (hasArtifact(value.job_id, imagePath)) {
+ const figure = node('figure', undefined, 'event-figure');
+ const link = node('a');
+ link.href = artifactUrl(value.job_id, imagePath);
+ link.target = '_blank'; link.rel = 'noopener noreferrer';
+ const image = node('img');
+ image.src = link.href;
+ image.alt = `Spectrogram crop with the measured ridge for ${id}`;
+ image.loading = 'lazy';
+ link.append(image);
+ figure.append(link, node('figcaption', 'Spectrogram crop with measured ridge. Open full image.', 'help'));
+ card.append(figure);
+ }
+ const audio = media?.audio || null;
+ const rawPath = audio?.raw ? `discovery/${audio.raw}` : `discovery/${id}-audio.wav`;
+ if (hasArtifact(value.job_id, rawPath)) {
+ const box = node('div', undefined, 'event-audio');
+ const bounds = audio
+ ? `${formatEventSeconds(audio.start_s)}–${formatEventSeconds(audio.end_s)} s${audio.truncated ? ' · centered excerpt' : ''}`
+ : 'event excerpt';
+ box.append(node('span', `Raw audio · ${bounds}`, 'help'));
+ const raw = document.createElement('audio');
+ raw.controls = true; raw.preload = 'none';
+ raw.src = artifactUrl(value.job_id, rawPath);
+ raw.setAttribute('aria-label', `Raw recording excerpt for ${id}`);
+ box.append(raw);
+ const bandPath = audio?.band_limited ? `discovery/${audio.band_limited}` : null;
+ if (bandPath && hasArtifact(value.job_id, bandPath)) {
+ box.append(node('span', 'Band-limited excerpt · illustrative, not used for detection or scoring', 'help'));
+ const band = document.createElement('audio');
+ band.controls = true; band.preload = 'none';
+ band.src = artifactUrl(value.job_id, bandPath);
+ band.setAttribute('aria-label', `Band-limited recording excerpt for ${id}`);
+ box.append(band);
+ }
+ card.append(box);
+ }
+ const csvPath = media?.ridge_csv ? `discovery/${media.ridge_csv}` : `discovery/${id}.csv`;
+ if (hasArtifact(value.job_id, csvPath)) {
+ const line = node('p', undefined, 'event-link');
+ const link = node('a', 'Measured ridge CSV');
+ link.href = artifactUrl(value.job_id, csvPath); link.download = '';
+ line.append(link); card.append(line);
+ }
+ const quality = Object.entries(event.quality || {});
+ if (quality.length) {
+ const details = node('details');
+ details.append(node('summary', 'Measured ridge & quality'));
+ const list = node('ul');
+ for (const [key, number] of quality) {
+ list.append(node('li', `${key.replaceAll('_', ' ')}: ${formatQuality(number)}`));
+ }
+ details.append(list); card.append(details);
+ }
+ if (media?.errors?.length) {
+ const details = node('details');
+ details.append(node('summary', 'Media generation notes'));
+ const list = node('ul');
+ for (const error of media.errors) list.append(node('li', error));
+ details.append(list); card.append(details);
+ }
+ card.append(reviewControl(event, value.job_id));
+ return card;
+}
+
+let eventsSignature = '';
+
+function renderEvents(value, force = false) {
+ if (!value) return;
+ const signature = `${value.job_id}|${value.events?.length || 0}|${Object.keys(reviews.labels || {}).sort().map(id => `${id}:${reviews.labels[id].label}:${reviews.labels[id].note || ''}`).join(',')}|${artifactJob}|${artifactPaths.size}|${mediaJob}|${mediaIndex ? Object.keys(mediaIndex.events || {}).length : 0}|${hideFalsePositives}`;
+ if (!force && signature === eventsSignature) return;
+ eventsSignature = signature;
+ const container = $('events');
+ container.replaceChildren();
+ if (!value.events?.length) return;
+ const groups = eventGroups(value);
+ const all = value.events;
+ const falseCount = all.filter(event => reviewLabel(event) === 'false_positive').length;
+ const confirmedCount = all.filter(event => reviewLabel(event) === 'confirmed').length;
+ const header = node('div', undefined, 'section-row event-section-head');
+ const title = node('div');
+ title.append(node('h3', `${groups.size} acoustic proposal groups · ${all.length} ridge records`));
+ title.append(node('p', `${confirmedCount} confirmed · ${falseCount} false positive · ${all.length - confirmedCount - falseCount} unreviewed. Review labels do not change this job's result.`, 'help'));
+ header.append(title);
+ const actions = node('div', undefined, 'event-actions');
+ const filterLabel = node('label', undefined, 'inline-control');
+ const filter = document.createElement('input');
+ filter.type = 'checkbox'; filter.checked = hideFalsePositives;
+ filter.addEventListener('change', () => {
+ hideFalsePositives = filter.checked;
+ try { localStorage.setItem('dopplergeist-hide-false', hideFalsePositives ? '1' : '0'); } catch (_) { /* optional */ }
+ renderEvents(renderedJob, true);
+ });
+ filterLabel.append(filter, document.createTextNode(' Hide false positives'));
+ actions.append(filterLabel);
+ if (falseCount) {
+ const button = node('button', `Re-analyze without ${falseCount} false positive${falseCount === 1 ? '' : 's'}`, 'secondary');
+ button.type = 'button';
+ button.addEventListener('click', () => startReanalysis(falseCount, button));
+ actions.append(button);
+ }
+ header.append(actions); container.append(header);
+ if (artifactJob === value.job_id && !hasArtifact(value.job_id, 'discovery/event-media.json')) {
+ container.append(node('p', 'This job has no per-curve media index; it was analyzed before images and audio excerpts were generated. The measured ridge chart and data are still available. Re-run the analysis to add media.', 'help'));
+ }
+ for (const [groupId, group] of groups) {
+ const section = node('section', undefined, 'event-group');
+ const groupHead = node('div', undefined, 'event-group-head');
+ const groupTitle = node('div');
+ const start = Math.min(...group.map(event => event.start_s));
+ const end = Math.max(...group.map(event => event.end_s));
+ const low = Math.min(...group.map(event => event.band_hz[0]));
+ const high = Math.max(...group.map(event => event.band_hz[1]));
+ groupTitle.append(node('h4', groupId));
+ groupTitle.append(node('span', `${group.length} ridge${group.length === 1 ? '' : 's'} · ${formatEventSeconds(start)}–${formatEventSeconds(end)} s · ${Math.round(low)}–${Math.round(high)} Hz`, 'help'));
+ groupHead.append(groupTitle);
+ if (group.length > 1) groupHead.append(groupReviewControl(group, value.job_id));
+ section.append(groupHead);
+ const visible = group.filter(event => !hideFalsePositives || reviewLabel(event) !== 'false_positive');
+ if (!visible.length) {
+ section.append(node('p', 'All curves in this group are marked false positive and hidden.', 'help'));
+ } else {
+ const grid = node('div', undefined, 'event-grid');
+ for (const event of visible) grid.append(eventCard(value, event));
+ section.append(grid);
+ }
+ container.append(section);
}
}
+
async function readGuidance(value) {
const id = value.job_id;
try {
@@ -284,8 +623,12 @@ async function poll(id) {
const value = await api(`/api/jobs/${id}`);
if (id !== activeJob) return;
$('connection').textContent = ''; render(value);
- if (terminal.has(value.status)) await Promise.all([artifacts(id), readGuidance(value)]);
- else timer = setTimeout(() => poll(id), 1000);
+ if (terminal.has(value.status)) {
+ await Promise.all([refreshEvidence(id, value, true), readGuidance(value)]);
+ } else {
+ if (value.events?.length) void refreshEvidence(id, value);
+ timer = setTimeout(() => poll(id), 1000);
+ }
} catch (error) {
if (id !== activeJob) return;
$('connection').textContent = `Could not read this job: ${error.message}. Start the service with the same jobs directory to reconnect.`;
@@ -294,6 +637,8 @@ async function poll(id) {
}
function selectJob(id) {
activeJob = id;
+ resetEvidence();
+ eventsSignature = '';
history.replaceState(null, '', `/?job=${encodeURIComponent(id)}`);
remember(id); poll(id);
}
@@ -328,7 +673,7 @@ $('upload-form').addEventListener('submit', async event => {
finally { $('submit').disabled = false; }
});
$('cancel').addEventListener('click', async () => {
- try { const value = await api(`/api/jobs/${activeJob}/cancel`, {method: 'POST'}); render(value); await artifacts(activeJob); }
+ try { const value = await api(`/api/jobs/${activeJob}/cancel`, {method: 'POST'}); render(value); await refreshEvidence(activeJob, value, true); }
catch (error) { $('connection').textContent = error.message; }
});
$('resume').addEventListener('click', async () => {
diff --git a/src/dopplergeist/web/index.html b/src/dopplergeist/web/index.html
index 86b9dbd..17ff59b 100644
--- a/src/dopplergeist/web/index.html
+++ b/src/dopplergeist/web/index.html
@@ -4,7 +4,7 @@
<body>
<header><a href="/" class="brand">DOPPLER<span>GEIST</span></a><span class="tag">Aircraft sound → location evidence</span></header>
<main>
-<section class="intro"><p class="eyebrow">ACOUSTIC GEOLOCATION</p><h1>Find the flights.<br>Test the location.</h1><p>Upload a recording to discover aircraft Doppler curves, search historical flight tracks, and inspect the evidence. When the evidence cannot support a location, the result is inconclusive.</p><p class="scope">Search coverage: <strong id="supported-areas">contiguous United States (CONUS)</strong>, including smaller selected areas. Location goal: 100–500 m or better preferred; up to 1,000 m acceptable. Localization accuracy remains under evaluation.</p></section>
+<section class="intro"><p class="eyebrow">ACOUSTIC GEOLOCATION</p><h1>Find the flights.<br>Test the location.</h1><p>Upload a recording to discover aircraft Doppler curves, search historical flight tracks, and inspect the evidence. Each proposal carries a spectrogram crop and audio excerpts; you can mark false positives and start a separate user-assisted re-analysis without changing the original result. When the evidence cannot support a location, the result is inconclusive.</p><p class="scope">Search coverage: <strong id="supported-areas">contiguous United States (CONUS)</strong>, including smaller selected areas. Location goal: 100–500 m or better preferred; up to 1,000 m acceptable. Localization accuracy remains under evaluation.</p></section>
<div class="layout">
<section class="panel" aria-labelledby="upload-heading"><h2 id="upload-heading">New analysis</h2><form id="upload-form">
<p id="data-setup" class="notice" hidden></p>
@@ -30,7 +30,7 @@
</fieldset>
<p id="limits" class="help"></p><button id="submit" type="submit">Upload &amp; analyze <span aria-hidden="true">→</span></button><p id="upload-error" role="alert"></p>
</form></section>
-<section class="panel results" aria-labelledby="results-heading"><div class="section-row"><h2 id="results-heading">Analysis</h2><button id="cancel" class="secondary" hidden>Stop job</button><button id="resume" class="secondary" hidden>Resume job</button></div><div id="empty"><div class="wave" aria-hidden="true">∿∿∿</div><h3>Your evidence will appear here</h3><p>Detected curves, location hypotheses, uncertainty, and downloadable artifacts stay attached to each job.</p></div><div id="job" hidden><p id="job-id" class="mono"></p><div class="section-row"><strong id="status" role="status" aria-live="polite"></strong><span id="stage" class="muted"></span></div><progress id="progress" max="1" value="0" aria-label="Analysis progress"></progress><p id="message"></p><p id="required" class="notice" hidden></p><div id="coverage"></div><section id="guidance" aria-label="Evidence-based next steps" hidden></section><div id="candidates"></div><div id="events"></div><div id="diagnostics"></div><details id="downloads"><summary>Download run artifacts</summary><ul id="artifacts"></ul></details><p id="connection" role="alert"></p></div></section>
+<section class="panel results" aria-labelledby="results-heading"><div class="section-row"><h2 id="results-heading">Analysis</h2><button id="cancel" class="secondary" hidden>Stop job</button><button id="resume" class="secondary" hidden>Resume job</button></div><div id="empty"><div class="wave" aria-hidden="true">∿∿∿</div><h3>Your evidence will appear here</h3><p>Detected curves, location hypotheses, uncertainty, and downloadable artifacts stay attached to each job.</p></div><div id="job" hidden><p id="job-id" class="mono"></p><div class="section-row"><strong id="status" role="status" aria-live="polite"></strong><span id="stage" class="muted"></span></div><progress id="progress" max="1" value="0" aria-label="Analysis progress"></progress><p id="message"></p><p id="required" class="notice" hidden></p><div id="coverage"></div><section id="guidance" aria-label="Evidence-based next steps" hidden></section><div id="candidates"></div><p id="review-assist" class="notice review-assist" hidden></p><div id="events"></div><div id="diagnostics"></div><details id="downloads"><summary>Download run artifacts</summary><ul id="artifacts"></ul></details><p id="connection" role="alert"></p></div></section>
</div>
<section id="recent-panel" class="recent" hidden><h2>Recent jobs on this browser</h2><ul id="recent"></ul></section>
<footer>Scores rank hypotheses; they are not probabilities. An inconclusive result can include alternatives without supporting a precise location.</footer>
diff --git a/src/dopplergeist/web/style.css b/src/dopplergeist/web/style.css
index 42ae529..ab315bc 100644
--- a/src/dopplergeist/web/style.css
+++ b/src/dopplergeist/web/style.css
@@ -11,3 +11,42 @@
.leaflet-container a.leaflet-control-zoom-in,.leaflet-container a.leaflet-control-zoom-out{color:#16334b}
.coordinate-copy{display:flex;align-items:center;flex-wrap:wrap;gap:10px;margin-top:10px}
+
+.review-assist{border-color:#5c7f3f;background:#1d2a18;color:#d9f0bd}
+.event-section-head{align-items:flex-start!important;gap:16px;flex-wrap:wrap;margin-top:26px}
+.event-section-head h3{margin:0 0 6px}
+.event-actions{display:flex;flex-wrap:wrap;gap:12px;align-items:center}
+.inline-control{display:flex!important;align-items:center;gap:6px;margin:0!important;font-size:12px;font-weight:500;color:var(--muted)}
+.inline-control input{width:auto;margin:0}
+.event-group{border-top:1px solid var(--edge);padding:20px 0 6px}
+.event-group-head{display:flex;justify-content:space-between;align-items:flex-start;gap:14px;flex-wrap:wrap;margin-bottom:14px}
+.event-group-head h4{margin:0 0 5px;font-size:14px;letter-spacing:.01em}
+.event-group-head .review-select{max-width:210px}
+.event-grid{display:grid;grid-template-columns:repeat(auto-fit,minmax(270px,1fr));gap:14px}
+.event-card{min-width:0;padding:15px;background:#111b1e;border:1px solid var(--edge);border-radius:10px;font-size:12px;line-height:1.55}
+.event-card.false_positive{opacity:.72;border-color:#6b4c4c}
+.event-card.confirmed{border-color:#4f6b46}
+.event-card-head{display:flex;align-items:center;justify-content:space-between;gap:8px;margin-bottom:6px}
+.event-card-head strong{font-size:13px;overflow-wrap:anywhere}
+.badge{flex:none;border:1px solid var(--edge);border-radius:99px;padding:2px 8px;font-size:10px;color:var(--muted);white-space:nowrap}
+.badge.false_positive{border-color:#8c5555;color:#ffb9ac;background:#2b1b1b}
+.badge.confirmed{border-color:#5f8053;color:#cdeab8;background:#1c2819}
+.event-card .mono{font-size:10px;margin:0 0 10px}
+.ridge-chart{display:block;width:100%;height:auto;border:1px solid var(--edge);border-radius:6px;margin:0 0 12px;background:#0d1517}
+.ridge-chart text{font-family:inherit}
+.event-figure{margin:0 0 12px}
+.event-figure img{display:block;width:100%;max-height:260px;object-fit:contain;border-radius:6px;background:#0d1517}
+.event-figure figcaption{margin-top:5px;font-size:10px}
+.event-audio{display:flex;flex-direction:column;gap:5px;margin:0 0 10px}
+.event-audio audio{width:100%;height:34px}
+.event-audio .help{font-size:10px}
+.event-link{margin:0 0 8px}
+.event-review{border-top:1px solid var(--edge);margin-top:12px;padding-top:10px}
+.review-row{display:flex;align-items:center;gap:10px}
+.review-row label.review-label{display:inline-block;margin:0;font-size:11px;color:var(--muted);flex:none}
+.review-select{width:auto!important;min-width:120px;padding:7px!important;font-size:11px!important}
+.review-note{margin-top:7px!important;padding:8px!important;font-size:11px!important}
+.event-review .help{margin:6px 0 0;font-size:10px}
+.event-card details{margin-top:10px;padding-top:10px}
+.event-card details ul{font-size:10px}
+@media(max-width:760px){.event-grid{grid-template-columns:1fr}.event-group-head .review-select{max-width:none;width:100%}}
diff --git a/tests/test_automatic.py b/tests/test_automatic.py
index 557e13c..b754bf2 100644
--- a/tests/test_automatic.py
+++ b/tests/test_automatic.py
@@ -46,7 +46,9 @@ def submit_and_wait(tmp_path, payload, *, time_window=None, config=None):
final = manager.wait(queued["job_id"])
directory = manager.directory(queued["job_id"])
with urllib.request.urlopen(base + f"/api/jobs/{queued['job_id']}") as response:
- assert json.load(response) == final
+ shown = json.load(response)
+ display_only = {"progress_stale", "progress_age_seconds", "elapsed_seconds"}
+ assert {key: value for key, value in shown.items() if key not in display_only} == final
with urllib.request.urlopen(base + f"/api/jobs/{queued['job_id']}/artifacts/input.mp3") as response:
assert response.read() == payload
return final, directory
@@ -90,6 +92,10 @@ def test_moving_tone_mp3_discovers_events_then_reports_missing_data(tmp_path, di
assert final["status"] == "inconclusive" and final["reason_code"] == "data_unavailable", final
assert len(final["events"]) >= 1
assert list((directory / "discovery").glob("event-*.png"))
+ media = json.loads((directory / "discovery/event-media.json").read_text())
+ assert media["events"]
+ assert any("audio" in entry and (directory / "discovery" / entry["audio"]["raw"]).is_file()
+ for entry in media["events"].values())
assert final["coverage"]["data_status"] == "unavailable"
from dataclasses import asdict
from dopplergeist.discovery import DiscoverySettings
diff --git a/tests/test_automatic_review.py b/tests/test_automatic_review.py
new file mode 100644
index 0000000..960d095
--- /dev/null
+++ b/tests/test_automatic_review.py
@@ -0,0 +1,89 @@
+"""Automatic orchestration checks for explicit review exclusions.
+
+These use a fake recording and discoverer so they exercise orchestration, not
+detection accuracy or synthetic field data.
+"""
+import json
+
+from dopplergeist import automatic
+
+
+def event(event_id, group_id, start_s, end_s):
+ return {
+ "event_id": event_id, "harmonic_group_id": group_id,
+ "start_s": start_s, "end_s": end_s, "band_hz": [100.0, 200.0],
+ "ridge": [
+ {"time_s": start_s, "frequency_hz": 100.0, "weight": 3.0},
+ {"time_s": (start_s + end_s) / 2, "frequency_hz": 150.0, "weight": 3.5},
+ {"time_s": end_s, "frequency_hz": 200.0, "weight": 3.0},
+ ],
+ "quality": {"median_contrast": 3.0},
+ }
+
+
+class FakeRecording:
+ time_status = "needs_input"
+ source_path = None
+ metadata = {
+ "source_sha256": "0" * 64, "duration_s": 40.0, "sample_rate_hz": 4000,
+ "channels": 1, "source_format": "wav",
+ }
+
+
+def request(tmp_path, **fields):
+ source = tmp_path / "source.wav"
+ source.write_bytes(b"not decoded in this orchestration check")
+ return {"schema_version": 1, "audio_path": str(source), **fields}
+
+
+def run(tmp_path, monkeypatch, request_value, *, time_status="needs_input"):
+ recording = FakeRecording()
+ recording.time_status = time_status
+ monkeypatch.setattr("dopplergeist.intake.intake_recording", lambda *args, **kwargs: recording)
+ monkeypatch.setattr("dopplergeist.discovery.discover_events",
+ lambda *args, **kwargs: [event("event-0001", "group-a", 0.0, 10.0),
+ event("event-0002", "group-b", 20.0, 30.0)])
+ monkeypatch.setattr(automatic, "_save_audio_checkpoint", lambda *args, **kwargs: None)
+ output = tmp_path / "job"
+ value = automatic.analyze(request_value, output)
+ return value, output
+
+
+def test_exclusions_filter_the_searched_events_and_record_user_assistance(tmp_path, monkeypatch):
+ value, output = run(tmp_path, monkeypatch, request(
+ tmp_path, excluded_event_ids=["event-0002"], review_source_job_id="a" * 32))
+ assert value["status"] == "needs_input"
+ assert [item["event_id"] for item in value["events"]] == ["event-0001"]
+ assert value["review"] == {
+ "user_assisted": True, "excluded_event_ids": ["event-0002"], "source_job_id": "a" * 32,
+ }
+ provenance = json.loads((output / "provenance.json").read_text())
+ assert provenance["event_selection"] == "automatic_whole_recording_with_user_review_exclusions"
+ assert provenance["excluded_event_ids"] == ["event-0002"]
+ assert provenance["discovered_ridges"] == 2
+ assert provenance["searched_ridges"] == 1
+
+
+def test_excluding_every_event_returns_inconclusive_without_searching(tmp_path, monkeypatch):
+ value, _ = run(tmp_path, monkeypatch, request(
+ tmp_path, excluded_event_ids=["event-0001", "event-0002"]), time_status="ok")
+ assert value["status"] == "inconclusive"
+ assert value["reason_code"] == "no_supported_events"
+ assert "excluded by review" in value["message"]
+ assert value["events"] == []
+ assert value["review"]["excluded_event_ids"] == ["event-0001", "event-0002"]
+
+
+def test_unknown_exclusion_is_an_explicit_failure(tmp_path, monkeypatch):
+ value, _ = run(tmp_path, monkeypatch, request(tmp_path, excluded_event_ids=["event-9999"]))
+ assert value["status"] == "failed"
+ assert value["reason_code"] == "invalid_configuration"
+ assert "event-9999" in value["message"]
+ assert value["review"]["excluded_event_ids"] == ["event-9999"]
+
+
+def test_no_review_fields_leave_the_automatic_result_unchanged(tmp_path, monkeypatch):
+ value, _ = run(tmp_path, monkeypatch, request(tmp_path))
+ assert value["status"] == "needs_input"
+ assert [item["event_id"] for item in value["events"]] == ["event-0001", "event-0002"]
+ assert "review" not in value
diff --git a/tests/test_contracts.py b/tests/test_contracts.py
index b0c7706..eb88707 100644
--- a/tests/test_contracts.py
+++ b/tests/test_contracts.py
@@ -174,3 +174,31 @@ def test_artifact_paths_cannot_leave_job_directory(path):
result["artifacts"]["report"] = path
with pytest.raises(ValueError, match="relative"):
validate_result(result)
+
+
+def test_review_exclusions_are_optional_and_auditable():
+ request = {"schema_version": 1, "audio_path": "clip.mp3",
+ "excluded_event_ids": ["event-2", "event-1"], "review_source_job_id": "a" * 32}
+ clean = validate_request(request)
+ assert clean["excluded_event_ids"] == ["event-1", "event-2"]
+ assert clean["review_source_job_id"] == "a" * 32
+ assert "excluded_event_ids" not in validate_request({"schema_version": 1, "audio_path": "clip.mp3"})
+ for change in ({"excluded_event_ids": []}, {"excluded_event_ids": ["event-1", "event-1"]},
+ {"excluded_event_ids": ["event-1"], "review_source_job_id": "not-a-job"},
+ {"review_source_job_id": "a" * 32}):
+ invalid = {"schema_version": 1, "audio_path": "clip.mp3", **change}
+ with pytest.raises(ValueError):
+ validate_request(invalid)
+
+ result = example("job-result")
+ result["review"] = {"user_assisted": True, "excluded_event_ids": ["event-1"],
+ "source_job_id": "b" * 32}
+ assert validate_result(result)["review"]["user_assisted"] is True
+ for review in ({"user_assisted": False, "excluded_event_ids": ["event-1"]},
+ {"user_assisted": True, "excluded_event_ids": []},
+ {"user_assisted": True, "excluded_event_ids": ["event-1"],
+ "source_job_id": "../other"}):
+ invalid = example("job-result")
+ invalid["review"] = review
+ with pytest.raises(ValueError):
+ validate_result(invalid)
diff --git a/tests/test_event_media.py b/tests/test_event_media.py
new file mode 100644
index 0000000..b89ca3e
--- /dev/null
+++ b/tests/test_event_media.py
@@ -0,0 +1,108 @@
+"""Focused checks for per-event listening/viewing media generation."""
+import json
+from types import SimpleNamespace
+
+import numpy as np
+import pytest
+import soundfile as sf
+
+from dopplergeist import discovery
+from dopplergeist.discovery import DiscoverySettings, _event_clip_bounds, _write_event_media
+
+
+def recording(tmp_path, duration_s=3.0, sample_rate_hz=24000):
+ samples = (0.2 * np.sin(2 * np.pi * 440 * np.arange(int(duration_s * sample_rate_hz)) / sample_rate_hz)).astype("<f4")
+ path = tmp_path / "recording.f32"
+ samples.tofile(path)
+ return SimpleNamespace(
+ samples_path=path,
+ metadata={"sample_rate_hz": sample_rate_hz, "duration_s": duration_s,
+ "source_sha256": "0" * 64},
+ )
+
+
+def event(event_id="event-0001", start_s=0.5, end_s=2.5, band_hz=(400.0, 480.0)):
+ return {
+ "event_id": event_id, "start_s": start_s, "end_s": end_s,
+ "band_hz": list(band_hz), "harmonic_group_id": "harmonics-0001",
+ "ridge": [
+ {"time_s": start_s, "frequency_hz": band_hz[0], "weight": 3.0},
+ {"time_s": (start_s + end_s) / 2, "frequency_hz": sum(band_hz) / 2, "weight": 3.5},
+ {"time_s": end_s, "frequency_hz": band_hz[1], "weight": 3.0},
+ ],
+ "quality": {"median_contrast": 3.2, "support_fraction": 0.9},
+ }
+
+
+def test_event_media_writes_plot_ridge_audio_and_index(tmp_path):
+ source = recording(tmp_path)
+ output = tmp_path / "discovery"
+ output.mkdir()
+ media = _write_event_media(source, [event()], output, DiscoverySettings(),
+ plot_event_details=True, event_audio=True)
+ entry = media["events"]["event-0001"]
+ assert entry["image"] == "event-0001.png"
+ assert entry["ridge_csv"] == "event-0001.csv"
+ assert entry["audio"]["raw"] == "event-0001-audio.wav"
+ assert entry["audio"]["band_limited"] == "event-0001-band.wav"
+ assert entry["audio"]["truncated"] is False
+ assert (output / "event-0001.png").stat().st_size > 0
+ assert (output / "event-0001.csv").read_text().startswith("time_s,frequency_hz,weight")
+ for name in ("event-0001-audio.wav", "event-0001-band.wav"):
+ info = sf.info(output / name)
+ assert info.samplerate == 24000
+ assert info.frames > 0
+ assert json.loads((output / "event-media.json").read_text()) == media
+
+
+def test_media_generation_failure_is_reported_without_stopping_discovery(tmp_path, monkeypatch):
+ source = recording(tmp_path)
+ output = tmp_path / "discovery"
+ output.mkdir()
+
+ def fail(*args, **kwargs):
+ raise OSError("no audio device")
+
+ monkeypatch.setattr(discovery, "_write_event_audio", fail)
+ media = _write_event_media(source, [event()], output, DiscoverySettings(),
+ plot_event_details=False, event_audio=True)
+ entry = media["events"]["event-0001"]
+ assert "audio" not in entry
+ assert any("audio" in error for error in entry["errors"])
+
+
+def test_audio_excerpt_is_bounded_around_long_events():
+ start, end, truncated = _event_clip_bounds({"start_s": 10.0, "end_s": 90.0}, 100.0)
+ assert end - start == pytest.approx(discovery._EVENT_AUDIO_MAX_S)
+ assert truncated is True
+ assert 0 <= start < end <= 100.0
+
+
+def test_audio_excerpt_near_recording_end_stays_in_bounds():
+ start, end, truncated = _event_clip_bounds({"start_s": 95.0, "end_s": 99.0}, 100.0)
+ assert 0 <= start < end <= 100.0
+ assert truncated is False
+
+
+def test_discover_events_writes_per_curve_media_for_a_moving_tone(tmp_path):
+ """Software smoke for the automatic discovery media wiring, not accuracy evidence."""
+ from dopplergeist.discovery import discover_events
+ from dopplergeist.intake import intake_recording
+
+ sample_rate = 8000
+ times = np.arange(sample_rate * 40) / sample_rate
+ frequency = 220 - times
+ wave = 0.3 * np.sin(2 * np.pi * np.cumsum(frequency) / sample_rate)
+ wave += np.random.default_rng(44).normal(0, 0.002, len(times))
+ source = tmp_path / "control.wav"
+ sf.write(source, wave, sample_rate)
+ recording = intake_recording(source, tmp_path / "intake")
+ output = tmp_path / "discovery"
+ events = discover_events(recording, output_dir=output, plot_event_details=True, event_audio=True)
+ assert events
+ media = json.loads((output / "event-media.json").read_text())
+ assert media["events"]
+ entries = [entry for entry in media["events"].values() if "image" in entry and "audio" in entry]
+ assert entries
+ assert (output / entries[0]["image"]).is_file()
+ assert (output / entries[0]["audio"]["raw"]).is_file()
diff --git a/tests/test_event_reviews.py b/tests/test_event_reviews.py
new file mode 100644
index 0000000..c6786d8
--- /dev/null
+++ b/tests/test_event_reviews.py
@@ -0,0 +1,57 @@
+"""Focused checks for local review-label persistence.
+
+These use no audio or flight data; they only exercise the annotation contract.
+"""
+import json
+
+import pytest
+
+from dopplergeist.event_reviews import (
+ ReviewError, apply_review, false_positive_ids, read_reviews, write_reviews,
+)
+
+
+def test_review_labels_roundtrip_and_clear(tmp_path):
+ applied = apply_review(tmp_path, {"event-1", "event-2"}, "false_positive",
+ ["event-1"], "steady engine tone")
+ assert applied["labels"]["event-1"]["label"] == "false_positive"
+ assert applied["labels"]["event-1"]["note"] == "steady engine tone"
+ assert false_positive_ids(tmp_path) == ["event-1"]
+ assert read_reviews(tmp_path) == applied
+
+ confirmed = apply_review(tmp_path, {"event-1", "event-2"}, "confirmed", ["event-2"])
+ assert confirmed["labels"]["event-2"]["label"] == "confirmed"
+ assert confirmed["labels"]["event-2"].get("note") is None
+ assert false_positive_ids(tmp_path) == ["event-1"]
+
+ cleared = apply_review(tmp_path, {"event-1", "event-2"}, "unreviewed", ["event-1"])
+ assert "event-1" not in cleared["labels"]
+ assert false_positive_ids(tmp_path) == []
+
+
[email protected]("label", ["maybe", "", None])
+def test_unknown_review_label_is_rejected(tmp_path, label):
+ with pytest.raises(ReviewError):
+ apply_review(tmp_path, {"event-1"}, label, ["event-1"])
+
+
+def test_unknown_event_is_rejected(tmp_path):
+ with pytest.raises(ReviewError, match="Unknown event"):
+ apply_review(tmp_path, {"event-1"}, "false_positive", ["event-9"])
+
+
+def test_review_note_is_bounded(tmp_path):
+ with pytest.raises(ReviewError, match="1000"):
+ apply_review(tmp_path, {"event-1"}, "false_positive", ["event-1"], "x" * 1001)
+
+
+def test_corrupt_or_unknown_review_file_fails_closed(tmp_path):
+ (tmp_path / "event-reviews.json").write_text("{")
+ with pytest.raises(ReviewError, match="unreadable"):
+ read_reviews(tmp_path)
+ write_reviews(tmp_path, {})
+ value = json.loads((tmp_path / "event-reviews.json").read_text())
+ value["labels"]["event-1"] = {"label": "unsupported"}
+ (tmp_path / "event-reviews.json").write_text(json.dumps(value))
+ with pytest.raises(ReviewError, match="Unknown review label"):
+ read_reviews(tmp_path)
diff --git a/tests/test_progress_reporting.py b/tests/test_progress_reporting.py
index 8a02a9e..01a57d4 100644
--- a/tests/test_progress_reporting.py
+++ b/tests/test_progress_reporting.py
@@ -126,3 +126,32 @@ def test_elapsed_time_starts_when_worker_starts(tmp_path, monkeypatch):
monkeypatch.setattr(automatic, "analyze", silent_step)
jobs.execute(directory)
assert observed["elapsed"] < 5
+
+
+def test_intake_progress_wrapper_passes_message_by_keyword(tmp_path, monkeypatch):
+ """Regression for the service progress callback's two-argument signature."""
+ class Recording:
+ time_status = "ok"
+ source_path = None
+ metadata = {"source_sha256": "0" * 64, "duration_s": 10.0, "sample_rate_hz": 4000,
+ "channels": 1, "source_format": "wav"}
+
+ def fake_intake(source, output, *, time_window=None, progress_callback=None):
+ progress_callback(decoded_s=0.0, duration_s=10.0)
+ return Recording()
+
+ monkeypatch.setattr("dopplergeist.intake.intake_recording", fake_intake)
+ monkeypatch.setattr("dopplergeist.discovery.discover_events", lambda *args, **kwargs: [])
+ monkeypatch.setattr(automatic, "_save_audio_checkpoint", lambda *args, **kwargs: None)
+ source = tmp_path / "source.wav"
+ source.write_bytes(b"orchestration-only")
+ calls = []
+
+ def progress(stage, fraction, **fields):
+ calls.append((stage, fraction, fields))
+
+ value = automatic.analyze({"schema_version": 1, "audio_path": str(source)}, tmp_path / "out",
+ progress=progress)
+ assert value["status"] == "inconclusive"
+ assert any(stage == "intake" and fields.get("message", "").startswith("Decoding audio:")
+ for stage, fraction, fields in calls)
diff --git a/tests/test_service.py b/tests/test_service.py
index c2228c6..b080664 100644
--- a/tests/test_service.py
+++ b/tests/test_service.py
@@ -176,3 +176,125 @@ def test_restricted_result_artifacts_are_denied(tmp_path, monkeypatch):
with pytest.raises(urllib.error.HTTPError) as error:
request(url + f"/api/jobs/{job_id}/artifacts/keep.txt")
assert error.value.code == 403
+
+
+def job_with_events(manager, job_id="0123456789abcdef0123456789abcdef"):
+ directory = manager.root / job_id
+ directory.mkdir()
+ event = {
+ "event_id": "event-0001", "start_s": 0.0, "end_s": 10.0,
+ "band_hz": [100.0, 200.0], "harmonic_group_id": "harmonics-0001",
+ "ridge": [{"time_s": 0.0, "frequency_hz": 100.0, "weight": 3.0},
+ {"time_s": 5.0, "frequency_hz": 150.0, "weight": 3.5},
+ {"time_s": 10.0, "frequency_hz": 200.0, "weight": 3.0}],
+ "quality": {"median_contrast": 3.2},
+ }
+ before = result(directory, "inconclusive", reason_code="insufficient_evidence",
+ message="Retained proposals are not a supported location.", events=[event])
+ (directory / "request.json").write_text(json.dumps({
+ "schema_version": 1, "audio_path": str(directory / "input.mp3"),
+ }))
+ (directory / "input.json").write_text(json.dumps({
+ "path": "input.mp3", "bytes": 4, "sha256": "0" * 64,
+ }))
+ (directory / "input.mp3").write_bytes(b"fake")
+ return directory, before
+
+
+def post_json(url, value):
+ request_url = urllib.request.Request(
+ url, data=json.dumps(value).encode(), method="POST",
+ headers={"Content-Type": "application/json"})
+ with urllib.request.urlopen(request_url, timeout=5) as response:
+ return response.status, json.loads(response.read())
+
+
+def test_review_labels_are_separate_from_result_and_start_user_assisted_reanalysis(tmp_path, monkeypatch):
+ with running_server(tmp_path, monkeypatch) as (manager, url):
+ directory, before = job_with_events(manager)
+ job_id = directory.name
+ assert request(url + f"/api/jobs/{job_id}/reviews")[1]["labels"] == {}
+
+ status, reviewed = post_json(url + f"/api/jobs/{job_id}/reviews", {
+ "label": "false_positive", "event_ids": ["event-0001"], "note": "steady wind tone"})
+ assert status == 200
+ assert reviewed["labels"]["event-0001"]["label"] == "false_positive"
+ assert reviewed["labels"]["event-0001"]["note"] == "steady wind tone"
+ assert request(url + f"/api/jobs/{job_id}/reviews")[1] == reviewed
+ assert read_json(directory / "result.json") == before
+ artifact_paths = [item["path"] for item in request(url + f"/api/jobs/{job_id}/artifacts")[1]["artifacts"]]
+ assert "event-reviews.json" in artifact_paths
+ (directory / "discovery").mkdir()
+ (directory / "discovery/event-0001-audio.wav").write_bytes(b"RIFF" + b"0" * 40)
+ with urllib.request.urlopen(
+ url + f"/api/jobs/{job_id}/artifacts/discovery/event-0001-audio.wav") as response:
+ assert response.headers.get_content_type().startswith("audio/")
+ assert response.headers.get("Content-Disposition") is None
+
+ reanalysis = urllib.request.Request(url + f"/api/jobs/{job_id}/reanalyze", data=b"", method="POST")
+ with urllib.request.urlopen(reanalysis, timeout=5) as response:
+ assert response.status == 202
+ queued = json.loads(response.read())
+ assert queued["status"] == "queued"
+ assert queued["job_id"] != job_id
+ new_directory = manager.directory(queued["job_id"])
+ new_request = read_json(new_directory / "request.json")
+ assert new_request["excluded_event_ids"] == ["event-0001"]
+ assert new_request["review_source_job_id"] == job_id
+ assert (new_directory / "input.mp3").read_bytes() == b"fake"
+ assert read_json(directory / "result.json") == before
+
+
+def test_review_api_rejects_unknown_labels_events_and_empty_reanalysis(tmp_path, monkeypatch):
+ with running_server(tmp_path, monkeypatch) as (manager, url):
+ job = request(url + "/api/jobs", b"payload", {"schema_version": 1})[1]
+ with pytest.raises(urllib.error.HTTPError) as error:
+ post_json(url + f"/api/jobs/{job['job_id']}/reviews",
+ {"label": "false_positive", "event_ids": ["event-0001"]})
+ assert error.value.code == 400
+ assert request(url + f"/api/jobs/{job['job_id']}/reviews")[1]["labels"] == {}
+
+ directory, _ = job_with_events(manager)
+ job_id = directory.name
+ for body in (
+ {"label": "false_positive", "event_ids": ["event-9999"]},
+ {"label": "maybe", "event_ids": ["event-0001"]},
+ {"label": "false_positive", "event_ids": []},
+ {"label": "false_positive", "event_ids": ["event-0001"], "extra": True},
+ ):
+ with pytest.raises(urllib.error.HTTPError) as error:
+ post_json(url + f"/api/jobs/{job_id}/reviews", body)
+ assert error.value.code == 400
+
+ post_json(url + f"/api/jobs/{job_id}/reviews", {"label": "confirmed", "event_ids": ["event-0001"]})
+ with pytest.raises(urllib.error.HTTPError) as error:
+ request(url + f"/api/jobs/{job_id}/reanalyze", b"")
+ assert error.value.code == 400
+
+
+def test_review_labels_survive_manager_restart(tmp_path, monkeypatch):
+ with running_server(tmp_path, monkeypatch) as (manager, url):
+ directory, _ = job_with_events(manager)
+ post_json(url + f"/api/jobs/{directory.name}/reviews",
+ {"label": "false_positive", "event_ids": ["event-0001"]})
+ restarted = JobManager(tmp_path)
+ try:
+ assert read_json(directory / "event-reviews.json")["labels"]["event-0001"]["label"] == "false_positive"
+ finally:
+ restarted.close()
+
+
+def test_reanalysis_carries_forward_prior_exclusions(tmp_path, monkeypatch):
+ with running_server(tmp_path, monkeypatch) as (manager, url):
+ directory, _ = job_with_events(manager)
+ request_value = read_json(directory / "request.json")
+ request_value["excluded_event_ids"] = ["event-0000"]
+ (directory / "request.json").write_text(json.dumps(request_value))
+ post_json(url + f"/api/jobs/{directory.name}/reviews",
+ {"label": "false_positive", "event_ids": ["event-0001"]})
+ reanalysis = urllib.request.Request(url + f"/api/jobs/{directory.name}/reanalyze",
+ data=b"", method="POST")
+ with urllib.request.urlopen(reanalysis, timeout=5) as response:
+ queued = json.loads(response.read())
+ new_request = read_json(manager.directory(queued["job_id"]) / "request.json")
+ assert new_request["excluded_event_ids"] == ["event-0000", "event-0001"]