dopplertrack 0.1.0__tar.gz

dopplertrack-0.1.0/LICENSE

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

dopplertrack-0.1.0/PKG-INFO

@@ -0,0 +1,149 @@
+Metadata-Version: 2.4
+Name: dopplertrack
+Version: 0.1.0
+Summary: Acoustic geolocation from inaudible aircraft Doppler curves matched against ADS-B flight tracks
+Keywords: doppler,ads-b,geolocation,acoustics,osint,spectrogram
+Author: MacCallister Higgins
+Author-email: MacCallister Higgins <maccallister.higgins@gmail.com>
+License-Expression: MIT
+License-File: LICENSE
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Science/Research
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Scientific/Engineering
+Requires-Dist: matplotlib>=3.11.2
+Requires-Dist: numpy>=2.5.4
+Requires-Dist: pandas>=3.1.0
+Requires-Dist: pillow>=13.0.0
+Requires-Dist: requests>=2.34.2
+Requires-Dist: scipy>=1.18.1
+Requires-Dist: soundfile>=0.14.0
+Requires-Python: >=3.12
+Project-URL: Homepage, https://github.com/mjshiggins/dopplertrack
+Project-URL: Issues, https://github.com/mjshiggins/dopplertrack/issues
+Description-Content-Type: text/markdown
+
+# dopplertrack
+
+Acoustic geolocation from the Doppler curves of propeller aircraft.
+
+Any outdoor (and many indoor) recordings contain faint, usually inaudible
+tones from aircraft flying over: the propeller blade-pass fundamental and its
+harmonics, between roughly 60 and 400 Hz. As the aircraft passes, the tone
+sweeps down in frequency. The exact shape of that sweep depends on where the
+listener was relative to the aircraft's real trajectory. With historical
+ADS-B data for every flight that day, each candidate location on the ground
+predicts a different curve, and the recording picks out the one that matches.
+
+This is a reimplementation of the technique shown in colsto's video
+["I discovered a sound that leaks your exact location"](https://www.youtube.com/watch?v=UytYrhYLOKI).
+No code was released with that video; this project is an open, automatic
+version of the method. See `docs/superpowers/specs/` for the design.
+
+## Status
+
+Proof of concept. Validated against the author's reference recording
+(known answer: Oyster Bay, NY, 2026-09-08). See the results section below.
+
+## Pipeline
+
+1. `spectrogram` — decode any audio/video with ffmpeg, high-resolution STFT of
+   the 40–450 Hz band, whitened per frequency bin so only *changing* tones stand out.
+2. `fit` — fit an ideal straight-pass Doppler curve (f0, speed, CPA slant
+   distance, CPA time) to a time/frequency window. The fit seeds a search
+   with coarse parameter ranges.
+3. `extract-region` — pull every flight that touched a bounding box out of an
+   [adsb.lol](https://github.com/adsblol/globe_history_2026) daily archive and
+   drop known jets using ICAO Doc 8643 engine classes.
+4. `search` — for every grid point (200 m) and every flight, compute the
+   closest point of approach (CPA), its slant distance (using a DEM for the
+   observer's elevation) and the *heard* CPA time (propagation delay). Keep
+   points that hear an event-1-like pass, then exactly Δt later an
+   event-2-like pass, with no other prop flight in between. Model the exact
+   Doppler curve each survivor would hear from the real trajectory
+   (emission-time radial velocity) and score it against the spectrogram.
+   Event 1's placement absorbs measurement error; event 2's placement is
+   locked to the flight geometry.
+
+## Usage
+
+```bash
+uv sync
+uv run dopplertrack spectrogram recording.mp4 rec.npz
+uv run dopplertrack fit rec.npz --window 2090 2200 --band 95 200 --harmonics 2 --out ev1.json
+uv run dopplertrack fit rec.npz --window 3020 3130 --band 95 195 --out ev2.json
+uv run dopplertrack extract-region /path/to/adsb-day --bbox 40.4 41.3 -74.4 -72.6 traces_ny.npz
+uv run dopplertrack search rec.npz --events ev1.json ev2.json --traces traces_ny.npz \
+    --bbox 40.4 41.3 -74.4 -72.6 --spacing 200 --out results.csv
+```
+
+`search --point LAT LON` scores a single known location instead of a grid,
+which is the quickest way to validate the data and physics on a recording
+whose location you already know.
+
+## Changes from the method in the video
+
+The physics and the search strategy are the author's. What differs:
+
+- **Automatic curve measurement.** The video measures each Doppler curve by
+  hand, sliding f0 / speed / distance / CPA-time until the overlay looks
+  right, then choosing "generous ranges" by eye. `fit` does this without a
+  person: the window is whitened per frequency bin so stationary tones
+  (mains hum, machinery) vanish, a vectorised grid search over all four
+  parameters maximises spectrogram brightness under the curve, and a
+  Nelder-Mead pass refines it. The ideal-curve fit still only seeds coarse
+  filters; final ranking uses real trajectories.
+- **Harmonic-aware fitting and scoring.** When a flyover shows a second
+  harmonic, fundamental and harmonic are scored together, which constrains
+  the curve more tightly than one line.
+- **Open, documented data path.** The video used a paid/scraped ADS-B feed
+  and did not release code. Here every input is a public dataset with a
+  loader: adsb.lol daily archives, ICAO Doc 8643 engine classes, AWS
+  terrain tiles.
+- **Search engineering.** A KD-tree corridor around each flight path limits
+  CPA computation to grid points that could possibly hear it; distance math
+  is chunked so multi-hour tracks do not exhaust memory; the time-shift and
+  f0 sweeps of the locked scorer run as one array operation per candidate.
+- **Single-event, known-time mode as a first-class command.** The video
+  demonstrates locating from one faint one-minute curve when the recording
+  time is known; `search-single` exposes that directly.
+
+Kept unchanged on purpose: emission-time radial velocity (not
+observation-time), propagation-delayed CPA times, slant distance with a DEM,
+the inter-event offset filter, the silence filter, and locked two-event
+scoring where event 1 absorbs measurement error and event 2 is placed purely
+by flight geometry.
+
+## Data sources (all free)
+
+| Need | Source |
+|---|---|
+| Historical ADS-B | adsb.lol `globe_history_YYYY` GitHub releases (~4 GB/day) |
+| Aircraft engine class | OpenSky mirror of ICAO Doc 8643 |
+| Elevation | AWS Terrain Tiles (Terrarium) |
+
+## Development
+
+```bash
+uv run pytest
+```
+
+## Releasing
+
+Releases are driven by git tags. Pushing a tag `vX.Y.Z` that matches the
+version in `pyproject.toml` runs `.github/workflows/release.yml`, which runs
+the tests, builds the sdist and wheel, attaches them to a GitHub Release with
+generated notes, and publishes to PyPI through trusted publishing (no API
+token stored anywhere).
+
+```bash
+uv version 0.2.0            # bump pyproject.toml
+git commit -am "Release 0.2.0"
+git tag v0.2.0 && git push && git push --tags
+```
+
+One-time setup for PyPI: on pypi.org, add a *pending publisher* for project
+`dopplertrack` with owner `mjshiggins`, repository `dopplertrack`, workflow
+`release.yml`, environment `pypi`, and create a `pypi` environment in the
+GitHub repository settings. Until that exists the `pypi` job fails and the
+GitHub Release still succeeds.

dopplertrack-0.1.0/README.md

@@ -0,0 +1,124 @@
+# dopplertrack
+
+Acoustic geolocation from the Doppler curves of propeller aircraft.
+
+Any outdoor (and many indoor) recordings contain faint, usually inaudible
+tones from aircraft flying over: the propeller blade-pass fundamental and its
+harmonics, between roughly 60 and 400 Hz. As the aircraft passes, the tone
+sweeps down in frequency. The exact shape of that sweep depends on where the
+listener was relative to the aircraft's real trajectory. With historical
+ADS-B data for every flight that day, each candidate location on the ground
+predicts a different curve, and the recording picks out the one that matches.
+
+This is a reimplementation of the technique shown in colsto's video
+["I discovered a sound that leaks your exact location"](https://www.youtube.com/watch?v=UytYrhYLOKI).
+No code was released with that video; this project is an open, automatic
+version of the method. See `docs/superpowers/specs/` for the design.
+
+## Status
+
+Proof of concept. Validated against the author's reference recording
+(known answer: Oyster Bay, NY, 2026-09-08). See the results section below.
+
+## Pipeline
+
+1. `spectrogram` — decode any audio/video with ffmpeg, high-resolution STFT of
+   the 40–450 Hz band, whitened per frequency bin so only *changing* tones stand out.
+2. `fit` — fit an ideal straight-pass Doppler curve (f0, speed, CPA slant
+   distance, CPA time) to a time/frequency window. The fit seeds a search
+   with coarse parameter ranges.
+3. `extract-region` — pull every flight that touched a bounding box out of an
+   [adsb.lol](https://github.com/adsblol/globe_history_2026) daily archive and
+   drop known jets using ICAO Doc 8643 engine classes.
+4. `search` — for every grid point (200 m) and every flight, compute the
+   closest point of approach (CPA), its slant distance (using a DEM for the
+   observer's elevation) and the *heard* CPA time (propagation delay). Keep
+   points that hear an event-1-like pass, then exactly Δt later an
+   event-2-like pass, with no other prop flight in between. Model the exact
+   Doppler curve each survivor would hear from the real trajectory
+   (emission-time radial velocity) and score it against the spectrogram.
+   Event 1's placement absorbs measurement error; event 2's placement is
+   locked to the flight geometry.
+
+## Usage
+
+```bash
+uv sync
+uv run dopplertrack spectrogram recording.mp4 rec.npz
+uv run dopplertrack fit rec.npz --window 2090 2200 --band 95 200 --harmonics 2 --out ev1.json
+uv run dopplertrack fit rec.npz --window 3020 3130 --band 95 195 --out ev2.json
+uv run dopplertrack extract-region /path/to/adsb-day --bbox 40.4 41.3 -74.4 -72.6 traces_ny.npz
+uv run dopplertrack search rec.npz --events ev1.json ev2.json --traces traces_ny.npz \
+    --bbox 40.4 41.3 -74.4 -72.6 --spacing 200 --out results.csv
+```
+
+`search --point LAT LON` scores a single known location instead of a grid,
+which is the quickest way to validate the data and physics on a recording
+whose location you already know.
+
+## Changes from the method in the video
+
+The physics and the search strategy are the author's. What differs:
+
+- **Automatic curve measurement.** The video measures each Doppler curve by
+  hand, sliding f0 / speed / distance / CPA-time until the overlay looks
+  right, then choosing "generous ranges" by eye. `fit` does this without a
+  person: the window is whitened per frequency bin so stationary tones
+  (mains hum, machinery) vanish, a vectorised grid search over all four
+  parameters maximises spectrogram brightness under the curve, and a
+  Nelder-Mead pass refines it. The ideal-curve fit still only seeds coarse
+  filters; final ranking uses real trajectories.
+- **Harmonic-aware fitting and scoring.** When a flyover shows a second
+  harmonic, fundamental and harmonic are scored together, which constrains
+  the curve more tightly than one line.
+- **Open, documented data path.** The video used a paid/scraped ADS-B feed
+  and did not release code. Here every input is a public dataset with a
+  loader: adsb.lol daily archives, ICAO Doc 8643 engine classes, AWS
+  terrain tiles.
+- **Search engineering.** A KD-tree corridor around each flight path limits
+  CPA computation to grid points that could possibly hear it; distance math
+  is chunked so multi-hour tracks do not exhaust memory; the time-shift and
+  f0 sweeps of the locked scorer run as one array operation per candidate.
+- **Single-event, known-time mode as a first-class command.** The video
+  demonstrates locating from one faint one-minute curve when the recording
+  time is known; `search-single` exposes that directly.
+
+Kept unchanged on purpose: emission-time radial velocity (not
+observation-time), propagation-delayed CPA times, slant distance with a DEM,
+the inter-event offset filter, the silence filter, and locked two-event
+scoring where event 1 absorbs measurement error and event 2 is placed purely
+by flight geometry.
+
+## Data sources (all free)
+
+| Need | Source |
+|---|---|
+| Historical ADS-B | adsb.lol `globe_history_YYYY` GitHub releases (~4 GB/day) |
+| Aircraft engine class | OpenSky mirror of ICAO Doc 8643 |
+| Elevation | AWS Terrain Tiles (Terrarium) |
+
+## Development
+
+```bash
+uv run pytest
+```
+
+## Releasing
+
+Releases are driven by git tags. Pushing a tag `vX.Y.Z` that matches the
+version in `pyproject.toml` runs `.github/workflows/release.yml`, which runs
+the tests, builds the sdist and wheel, attaches them to a GitHub Release with
+generated notes, and publishes to PyPI through trusted publishing (no API
+token stored anywhere).
+
+```bash
+uv version 0.2.0            # bump pyproject.toml
+git commit -am "Release 0.2.0"
+git tag v0.2.0 && git push && git push --tags
+```
+
+One-time setup for PyPI: on pypi.org, add a *pending publisher* for project
+`dopplertrack` with owner `mjshiggins`, repository `dopplertrack`, workflow
+`release.yml`, environment `pypi`, and create a `pypi` environment in the
+GitHub repository settings. Until that exists the `pypi` job fails and the
+GitHub Release still succeeds.

dopplertrack-0.1.0/pyproject.toml

@@ -0,0 +1,44 @@
+[project]
+name = "dopplertrack"
+version = "0.1.0"
+description = "Acoustic geolocation from inaudible aircraft Doppler curves matched against ADS-B flight tracks"
+readme = "README.md"
+authors = [
+    { name = "MacCallister Higgins", email = "maccallister.higgins@gmail.com" }
+]
+license = "MIT"
+license-files = ["LICENSE"]
+requires-python = ">=3.12"
+keywords = ["doppler", "ads-b", "geolocation", "acoustics", "osint", "spectrogram"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Science/Research",
+    "Programming Language :: Python :: 3",
+    "Topic :: Scientific/Engineering",
+]
+
+dependencies = [
+    "matplotlib>=3.11.2",
+    "numpy>=2.5.4",
+    "pandas>=3.1.0",
+    "pillow>=13.0.0",
+    "requests>=2.34.2",
+    "scipy>=1.18.1",
+    "soundfile>=0.14.0",
+]
+
+[project.urls]
+Homepage = "https://github.com/mjshiggins/dopplertrack"
+Issues = "https://github.com/mjshiggins/dopplertrack/issues"
+
+[project.scripts]
+dopplertrack = "dopplertrack.cli:main"
+
+[build-system]
+requires = ["uv_build>=0.8.3,<0.9.0"]
+build-backend = "uv_build"
+
+[dependency-groups]
+dev = [
+    "pytest>=9.2.0",
+]

dopplertrack-0.1.0/src/dopplertrack/__init__.py

@@ -0,0 +1,2 @@
+def hello() -> str:
+    return "Hello from dopplertrack!"

dopplertrack-0.1.0/src/dopplertrack/adsb.py

@@ -0,0 +1,161 @@
+"""Read adsb.lol / readsb `globe_history` daily archives and classify aircraft."""
+from __future__ import annotations
+
+import csv
+import gzip
+import io
+import json
+import os
+from concurrent.futures import ProcessPoolExecutor
+from dataclasses import dataclass
+from pathlib import Path
+
+import numpy as np
+import requests
+
+from .geo import lla_to_enu
+
+FT = 0.3048
+KT = 0.514444
+_DOC8643_URL = "https://opensky-network.org/datasets/metadata/doc8643AircraftTypes.csv"
+
+
+def _cache_dir() -> Path:
+    p = Path(os.environ.get("DOPPLERTRACK_CACHE", Path.home() / ".cache" / "dopplertrack"))
+    p.mkdir(parents=True, exist_ok=True)
+    return p
+
+
+class AircraftTypes:
+    """ICAO Doc 8643 designator -> engine class ('Piston', 'Turboprop', 'Jet', ...)."""
+
+    def __init__(self, path: str | Path | None = None):
+        p = Path(path) if path else _cache_dir() / "doc8643AircraftTypes.csv"
+        if not p.exists():
+            p.write_bytes(requests.get(_DOC8643_URL, timeout=120).content)
+        self.types: dict[str, dict] = {}
+        with open(p, newline="", encoding="utf-8") as fh:
+            for row in csv.DictReader(fh):
+                self.types.setdefault(row["Designator"], row)
+
+    def engine(self, designator: str | None) -> str | None:
+        r = self.types.get(designator or "")
+        return r["EngineType"] if r else None
+
+    def is_prop(self, designator: str | None, unknown_ok: bool = True) -> bool:
+        e = self.engine(designator)
+        if e is None:
+            return unknown_ok
+        return any(k in e for k in ("Piston", "Turboprop", "Electric"))
+
+
+@dataclass
+class Trace:
+    icao: str
+    reg: str | None
+    typ: str | None
+    desc: str | None
+    t: np.ndarray        # unix seconds
+    lat: np.ndarray
+    lon: np.ndarray
+    alt: np.ndarray      # metres MSL (geometric when available, else barometric)
+    gs: np.ndarray       # m/s (nan if missing)
+    on_ground: np.ndarray
+
+    def __len__(self):
+        return len(self.t)
+
+    def segments(self, max_gap_s: float = 90.0) -> list[slice]:
+        """Index slices of contiguous airborne data."""
+        out = []
+        if len(self.t) == 0:
+            return out
+        brk = np.where((np.diff(self.t) > max_gap_s) | (self.on_ground[1:] != self.on_ground[:-1]))[0] + 1
+        starts = np.r_[0, brk]; ends = np.r_[brk, len(self.t)]
+        for s, e in zip(starts, ends):
+            if e - s >= 2 and not self.on_ground[s]:
+                out.append(slice(s, e))
+        return out
+
+    def resample(self, sl: slice, dt: float = 1.0):
+        """Uniformly resampled (t, lat, lon, alt) over one segment."""
+        t = self.t[sl]
+        tq = np.arange(t[0], t[-1], dt)
+        return (tq, np.interp(tq, t, self.lat[sl]), np.interp(tq, t, self.lon[sl]), np.interp(tq, t, self.alt[sl]))
+
+    def enu(self, sl: slice, lat0: float, lon0: float, dt: float = 1.0):
+        tq, la, lo, al = self.resample(sl, dt)
+        return tq, lla_to_enu(la, lo, al, lat0, lon0)
+
+
+def parse_trace_file(path: str | Path) -> Trace | None:
+    raw = Path(path).read_bytes()
+    if raw[:2] == b"\x1f\x8b":
+        raw = gzip.decompress(raw)
+    d = json.loads(raw)
+    base = float(d.get("timestamp", 0.0))
+    rows = d.get("trace") or []
+    t, lat, lon, alt, gs, grd = [], [], [], [], [], []
+    for r in rows:
+        if r[1] is None or r[2] is None:
+            continue
+        a = r[3]
+        on_ground = a == "ground"
+        geom = r[10] if len(r) > 10 else None
+        if isinstance(geom, (int, float)):
+            am = geom * FT
+        elif isinstance(a, (int, float)):
+            am = a * FT
+        elif on_ground:
+            am = np.nan
+        else:
+            continue
+        t.append(base + r[0]); lat.append(r[1]); lon.append(r[2]); alt.append(am)
+        gs.append(r[4] * KT if isinstance(r[4], (int, float)) else np.nan); grd.append(on_ground)
+    if not t:
+        return None
+    return Trace(d.get("icao", Path(path).stem.split("_")[-1]), d.get("r"), d.get("t"), d.get("desc"),
+                 np.array(t), np.array(lat), np.array(lon), np.array(alt), np.array(gs), np.array(grd))
+
+
+def _scan_one(args):
+    path, bbox = args
+    try:
+        tr = parse_trace_file(path)
+    except Exception:
+        return None
+    if tr is None:
+        return None
+    lat0, lat1, lon0, lon1 = bbox
+    m = (tr.lat >= lat0) & (tr.lat <= lat1) & (tr.lon >= lon0) & (tr.lon <= lon1)
+    if not m.any():
+        return None
+    return tr
+
+
+def load_region(archive_dir: str | Path, bbox: tuple[float, float, float, float],
+                workers: int | None = None) -> list[Trace]:
+    """All traces with at least one point inside bbox=(lat_min, lat_max, lon_min, lon_max)."""
+    files = sorted(Path(archive_dir).glob("traces/*/trace_full_*.json"))
+    out = []
+    with ProcessPoolExecutor(workers or os.cpu_count()) as ex:
+        for tr in ex.map(_scan_one, ((str(f), bbox) for f in files), chunksize=256):
+            if tr is not None:
+                out.append(tr)
+    return out
+
+
+def save_traces(traces: list[Trace], path: str | Path):
+    np.savez_compressed(path, n=len(traces),
+                        meta=np.array([json.dumps([t.icao, t.reg, t.typ, t.desc]) for t in traces]),
+                        **{f"a{i}": np.stack([t.t, t.lat, t.lon, t.alt, t.gs, t.on_ground.astype(float)]) for i, t in enumerate(traces)})
+
+
+def load_traces(path: str | Path) -> list[Trace]:
+    z = np.load(path, allow_pickle=False)
+    out = []
+    for i in range(int(z["n"])):
+        icao, reg, typ, desc = json.loads(str(z["meta"][i]))
+        a = z[f"a{i}"]
+        out.append(Trace(icao, reg, typ, desc, a[0], a[1], a[2], a[3], a[4], a[5].astype(bool)))
+    return out

dopplertrack-0.1.0/src/dopplertrack/audio.py

@@ -0,0 +1,101 @@
+"""Audio decoding and whitened low-band spectrograms."""
+from __future__ import annotations
+
+import subprocess
+from dataclasses import dataclass
+from pathlib import Path
+
+import numpy as np
+import scipy.signal as ss
+
+
+def load_audio(path: str | Path, sr: int = 4000) -> tuple[np.ndarray, int]:
+    """Decode any ffmpeg-readable file to mono float32 at `sr` Hz."""
+    cmd = ["ffmpeg", "-v", "error", "-i", str(path), "-ac", "1", "-ar", str(sr),
+           "-f", "f32le", "-acodec", "pcm_f32le", "-"]
+    raw = subprocess.run(cmd, check=True, capture_output=True).stdout
+    return np.frombuffer(raw, dtype=np.float32).copy(), sr
+
+
+@dataclass
+class Spectrogram:
+    t: np.ndarray      # (T,) centre time of each frame, s
+    f: np.ndarray      # (F,) bin frequencies, Hz
+    S: np.ndarray      # (F, T) whitened power, dB above per-bin median
+
+    @property
+    def dt(self) -> float:
+        return float(self.t[1] - self.t[0])
+
+    @property
+    def df(self) -> float:
+        return float(self.f[1] - self.f[0])
+
+    def sample(self, t, f, fill=0.0):
+        """Bilinear sample at (t, f) pairs (arrays); outside the grid -> fill."""
+        t = np.asarray(t, float); f = np.asarray(f, float)
+        ti = (t - self.t[0]) / self.dt
+        fi = (f - self.f[0]) / self.df
+        ok = (ti >= 0) & (ti <= len(self.t) - 1) & (fi >= 0) & (fi <= len(self.f) - 1) & np.isfinite(ti) & np.isfinite(fi)
+        out = np.full(t.shape, fill, float)
+        ti = ti[ok]; fi = fi[ok]
+        i0 = np.floor(ti).astype(int); j0 = np.floor(fi).astype(int)
+        i1 = np.minimum(i0 + 1, len(self.t) - 1); j1 = np.minimum(j0 + 1, len(self.f) - 1)
+        wt = ti - i0; wf = fi - j0
+        v = (self.S[j0, i0] * (1 - wt) * (1 - wf) + self.S[j0, i1] * wt * (1 - wf)
+             + self.S[j1, i0] * (1 - wt) * wf + self.S[j1, i1] * wt * wf)
+        out[ok] = v
+        return out
+
+    def crop(self, t0, t1, f0=None, f1=None) -> "Spectrogram":
+        m = (self.t >= t0) & (self.t <= t1)
+        fm = np.ones_like(self.f, bool)
+        if f0 is not None: fm &= self.f >= f0
+        if f1 is not None: fm &= self.f <= f1
+        return Spectrogram(self.t[m], self.f[fm], self.S[np.ix_(fm, m)])
+
+    def save(self, path):
+        np.savez_compressed(path, t=self.t, f=self.f, S=self.S.astype(np.float32))
+
+    @classmethod
+    def load(cls, path) -> "Spectrogram":
+        z = np.load(path)
+        return cls(z["t"], z["f"], z["S"])
+
+
+def compute_spectrogram(x: np.ndarray, sr: int, nperseg: int = 8192, hop_s: float = 0.25,
+                        fmin: float = 40.0, fmax: float = 450.0,
+                        whiten_window_s: float | None = 600.0) -> Spectrogram:
+    """High-resolution STFT in the low band, converted to dB and whitened.
+
+    Whitening subtracts, per frequency bin, the running median over
+    `whiten_window_s` (or the global median if None). This flattens mains
+    hum and stationary machinery so only *changing* tones stand out.
+    """
+    hop = max(1, int(round(hop_s * sr)))
+    f, t, Z = ss.stft(x, sr, nperseg=nperseg, noverlap=nperseg - hop, window="hann",
+                      boundary=None, padded=False)
+    band = (f >= fmin) & (f <= fmax)
+    L = 10 * np.log10(np.abs(Z[band]) ** 2 + 1e-20)
+    f = f[band]
+    if whiten_window_s is None:
+        L = L - np.median(L, axis=1, keepdims=True)
+    else:
+        w = int(whiten_window_s / (hop / sr))
+        if w >= L.shape[1]:
+            L = L - np.median(L, axis=1, keepdims=True)
+        else:
+            # block-wise running median (cheap, adequate for slow drifts)
+            nb = int(np.ceil(L.shape[1] / w))
+            med = np.zeros_like(L)
+            centers = []
+            for b in range(nb):
+                sl = slice(b * w, min((b + 1) * w, L.shape[1]))
+                med[:, sl] = np.median(L[:, sl], axis=1, keepdims=True)
+                centers.append((sl.start + sl.stop) / 2)
+            # linearly blend block medians to avoid seams
+            cm = np.array([np.median(L[:, b * w:min((b + 1) * w, L.shape[1])], axis=1) for b in range(nb)])  # (nb, F)
+            idx = np.arange(L.shape[1])
+            med = np.stack([np.interp(idx, centers, cm[:, k]) for k in range(L.shape[0])])
+            L = L - med
+    return Spectrogram(t, f, L.astype(np.float32))