ambiscape 0.1.0__tar.gz

ambiscape-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Alexander Refsum Jensenius
+
+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.

ambiscape-0.1.0/PKG-INFO

@@ -0,0 +1,96 @@
+Metadata-Version: 2.4
+Name: ambiscape
+Version: 0.1.0
+Summary: Long-duration first-order ambisonic soundscape analysis (streaming companion to ambiviz)
+Author-email: Alexander Refsum Jensenius <a.r.jensenius@imv.uio.no>
+License: MIT
+Project-URL: Repository, https://github.com/fourMs/ambiscape
+Project-URL: Issues, https://github.com/fourMs/ambiscape/issues
+Project-URL: Author ORCID, https://orcid.org/0000-0001-6171-8743
+Project-URL: Companion toolbox (ambiviz), https://github.com/fisheggg/ambiviz
+Keywords: ambisonics,soundscape,field-recording,acoustics,spatial-audio,long-duration,ISO-12913
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Multimedia :: Sound/Audio :: Analysis
+Classifier: Intended Audience :: Science/Research
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: numpy>=1.24
+Requires-Dist: scipy>=1.10
+Requires-Dist: soundfile>=0.12
+Requires-Dist: matplotlib>=3.7
+Provides-Extra: viz
+Requires-Dist: ambiviz>=0.0.1; extra == "viz"
+Provides-Extra: iso
+Requires-Dist: mosqito>=1.2; extra == "iso"
+Provides-Extra: ml
+Requires-Dist: panns-inference>=0.1; extra == "ml"
+Requires-Dist: silero-vad>=5.0; extra == "ml"
+Requires-Dist: torch>=2.0; extra == "ml"
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0; extra == "dev"
+Dynamic: license-file
+
+# ambiscape
+
+Analysis toolkit for long-duration first-order ambisonic soundscape recordings (Zoom H3-VR and other AmbiX/SN3D B-format sources).
+
+Built as the streaming companion to [ambiviz](https://github.com/fisheggg/ambiviz): ambiviz renders rich spatial visuals (AEM spherical energy maps, anglegrams, directograms) from files it can load whole; ambiscape handles the other end of the problem: recordings of hours (tens of GB) that must be processed in a stream and produces session-level summaries, timelines, and short representative excerpts that ambiviz then visualises in detail. Plot names and conventions follow ambiviz where the two overlap.
+
+## What it does
+
+- **Session model** — a folder of WAVs = one session; BWF `bext` timestamps (parsed natively, no ffmpeg needed) put all takes on an absolute clock,
+  including 2 GB recorder splits.
+- **Streaming features** (constant memory, per take, cached as `.npz`) 125 ms fast level (unweighted + A-weighted), per-second octave-band powers, spectral centroid/flatness, 96-band log spectrogram, per-octave pseudo-intensity vectors, broadband DOA (azimuth/elevation), diffuseness ψ, and per-minute full-resolution spectra for narrowband hum tracking.
+- **Descriptors** — Leq, LAeq, L10/L50/L90, dynamics, event statistics (+8 dB over a running 60 s 10th-percentile background, ≥ 0.25 s), circular direction statistics (mean azimuth, resultant length R), foreground/background energy-quartile splits.
+- **Figures** — 4-panel session overview (level + background, log spectrogram, anglegram, ψ(t)), percentile LTAS, foreground/background directogram.
+- **Room acoustics** — noise-aware truncated-Schroeder T60 from claps or incidental impulses (`analysis.decay_time`).
+- **Segment selection** — quietest / most active/typical / transition windows for archiving, listening, or ambiviz rendering (`analysis.pick_segments`).
+- **Reports** — auto-generated per-session `README.md` with metadata, descriptor table, and figures.
+- **Taxonomy figures** — from a hand-authored `annotations.json` in the session folder (the interpretive layer instruments can't supply), render a **Schaeffer typo-morphology map** (objects on the facture × mass plane, colored by Schafer function) and **Schafer timeline** (keynote lanes, signal/soundmark events, lo-fi states shaded, gap-aware panels). Schema documented in `taxonomy.py`.
+- **Calibration** — drop a `calibration.json` in the session folder (`{"dbfs_to_dbspl": 94.0, "method": "SPL app next to mic, pump running"}`) and `analyse` adds dB SPL versions of Leq/LAeq/L10/L50/L90 to the summary, making them ISO 1996-comparable.
+- **ISO 12913-3 indicators** — `ambiscape iso <folder>` computes ISO 532-1 time-varying loudness (N5, N50), DIN 45692 sharpness and Daniel & Weber roughness (via [MoSQITo](https://github.com/Eomys/MoSQITo), validated here against the 1 kHz/60 dB ≙ 4 sone reference) per ear on a binaural render of each representative segment — ambiviz's HRIR binauralizer when installed, otherwise a documented ±90° cardioid-pair fallback. Uncalibrated sessions are computed with an assumed offset and flagged (ratios between segments stay meaningful; absolute sones don't). MoSQITo runs ~5× slower than real-time, hence 30 s segments and a 10 s roughness slice by default.
+- **Draft annotations** — `ambiscape draft <folder>` pre-fills `annotations.draft.json` from the cached features: steady level regimes (fixed-reference change-point detection become keynote candidates with spans, and detected events are listed with listening hints (clock time, level, azimuth/elevation, diffuseness). You supply the ears: name the objects, fill mass/facture/kind, save as `annotations.json`.
+
+## Install
+
+```bash
+pip install -e .            # from this folder
+pip install -e ".[viz]"     # + ambiviz for AEM/segment visuals
+```
+
+## Use
+
+```bash
+ambiscape probe    "folder"
+ambiscape analyze  "folder" --notes "Living room, mic on table"
+ambiscape draft    "folder"   # pre-fill annotations.draft.json
+ambiscape taxonomy "folder"   # needs <folder>/annotations.json
+ambiscape iso      "folder"   # ISO 12913-3 indicators (MoSQITo)
+```
+
+```python
+import ambiscape as asc
+
+sess = asc.open_session("2026-07-15-Haarlem")
+paths = asc.extract_session(sess, "features")   # streams, caches npz
+F = asc.load_features(paths)                    # one absolute time axis
+print(asc.summarize(F))
+
+x, fs = asc.read_span(sess, t0=4.0, dur=6.0)    # raw audio anywhere
+print(asc.decay_time(x[:, 0], fs))              # T60 from a clap at t≈4 s
+
+asc.figures.overview(F, "overview.png", clock=sess.clock)
+```
+
+## Zoom H3-VR notes
+
+The toolbox was built using Ambisonics recordings captured with a Zoom H3-VR. The H3-VR records B-format as either AmbiX (W,Y,Z,X) or FuMa (W,X,Y,Z); `directional_energy.py` defaults to `fuma` while ambiscape auto-detects the convention from the recorder's `zTRK` tags in the BWF `bext` chunk (`io.channel_order`). Processing AmbiX files as FuMa swaps X↔Y — a reflection of all azimuths about the ±45° diagonal, which a best-circular-shift correlation does *not* absorb. Worth verifying which mode the 2023 raw files used before comparing directional results across the two corpora.
+
+## Conventions
+
+- AmbiX ACN channel order (W, Y, Z, X) as written by the H3-VR, SN3D.
+- Azimuth: 0° = front (X+), +90° = left (Y+), ±180° = rear; elevation + up. All directions are mic-relative.
+- Levels are dBFS (uncalibrated); within-session structure is exact; between-session absolute comparisons are indicative.
+- Diffuseness ψ = 1 − 2‖⟨Re W*·v⟩‖ / ⟨|W|² + ‖v‖²⟩ (0 = plane wave, 1 = diffuse).

ambiscape-0.1.0/README.md

@@ -0,0 +1,62 @@
+# ambiscape
+
+Analysis toolkit for long-duration first-order ambisonic soundscape recordings (Zoom H3-VR and other AmbiX/SN3D B-format sources).
+
+Built as the streaming companion to [ambiviz](https://github.com/fisheggg/ambiviz): ambiviz renders rich spatial visuals (AEM spherical energy maps, anglegrams, directograms) from files it can load whole; ambiscape handles the other end of the problem: recordings of hours (tens of GB) that must be processed in a stream and produces session-level summaries, timelines, and short representative excerpts that ambiviz then visualises in detail. Plot names and conventions follow ambiviz where the two overlap.
+
+## What it does
+
+- **Session model** — a folder of WAVs = one session; BWF `bext` timestamps (parsed natively, no ffmpeg needed) put all takes on an absolute clock,
+  including 2 GB recorder splits.
+- **Streaming features** (constant memory, per take, cached as `.npz`) 125 ms fast level (unweighted + A-weighted), per-second octave-band powers, spectral centroid/flatness, 96-band log spectrogram, per-octave pseudo-intensity vectors, broadband DOA (azimuth/elevation), diffuseness ψ, and per-minute full-resolution spectra for narrowband hum tracking.
+- **Descriptors** — Leq, LAeq, L10/L50/L90, dynamics, event statistics (+8 dB over a running 60 s 10th-percentile background, ≥ 0.25 s), circular direction statistics (mean azimuth, resultant length R), foreground/background energy-quartile splits.
+- **Figures** — 4-panel session overview (level + background, log spectrogram, anglegram, ψ(t)), percentile LTAS, foreground/background directogram.
+- **Room acoustics** — noise-aware truncated-Schroeder T60 from claps or incidental impulses (`analysis.decay_time`).
+- **Segment selection** — quietest / most active/typical / transition windows for archiving, listening, or ambiviz rendering (`analysis.pick_segments`).
+- **Reports** — auto-generated per-session `README.md` with metadata, descriptor table, and figures.
+- **Taxonomy figures** — from a hand-authored `annotations.json` in the session folder (the interpretive layer instruments can't supply), render a **Schaeffer typo-morphology map** (objects on the facture × mass plane, colored by Schafer function) and **Schafer timeline** (keynote lanes, signal/soundmark events, lo-fi states shaded, gap-aware panels). Schema documented in `taxonomy.py`.
+- **Calibration** — drop a `calibration.json` in the session folder (`{"dbfs_to_dbspl": 94.0, "method": "SPL app next to mic, pump running"}`) and `analyse` adds dB SPL versions of Leq/LAeq/L10/L50/L90 to the summary, making them ISO 1996-comparable.
+- **ISO 12913-3 indicators** — `ambiscape iso <folder>` computes ISO 532-1 time-varying loudness (N5, N50), DIN 45692 sharpness and Daniel & Weber roughness (via [MoSQITo](https://github.com/Eomys/MoSQITo), validated here against the 1 kHz/60 dB ≙ 4 sone reference) per ear on a binaural render of each representative segment — ambiviz's HRIR binauralizer when installed, otherwise a documented ±90° cardioid-pair fallback. Uncalibrated sessions are computed with an assumed offset and flagged (ratios between segments stay meaningful; absolute sones don't). MoSQITo runs ~5× slower than real-time, hence 30 s segments and a 10 s roughness slice by default.
+- **Draft annotations** — `ambiscape draft <folder>` pre-fills `annotations.draft.json` from the cached features: steady level regimes (fixed-reference change-point detection become keynote candidates with spans, and detected events are listed with listening hints (clock time, level, azimuth/elevation, diffuseness). You supply the ears: name the objects, fill mass/facture/kind, save as `annotations.json`.
+
+## Install
+
+```bash
+pip install -e .            # from this folder
+pip install -e ".[viz]"     # + ambiviz for AEM/segment visuals
+```
+
+## Use
+
+```bash
+ambiscape probe    "folder"
+ambiscape analyze  "folder" --notes "Living room, mic on table"
+ambiscape draft    "folder"   # pre-fill annotations.draft.json
+ambiscape taxonomy "folder"   # needs <folder>/annotations.json
+ambiscape iso      "folder"   # ISO 12913-3 indicators (MoSQITo)
+```
+
+```python
+import ambiscape as asc
+
+sess = asc.open_session("2026-07-15-Haarlem")
+paths = asc.extract_session(sess, "features")   # streams, caches npz
+F = asc.load_features(paths)                    # one absolute time axis
+print(asc.summarize(F))
+
+x, fs = asc.read_span(sess, t0=4.0, dur=6.0)    # raw audio anywhere
+print(asc.decay_time(x[:, 0], fs))              # T60 from a clap at t≈4 s
+
+asc.figures.overview(F, "overview.png", clock=sess.clock)
+```
+
+## Zoom H3-VR notes
+
+The toolbox was built using Ambisonics recordings captured with a Zoom H3-VR. The H3-VR records B-format as either AmbiX (W,Y,Z,X) or FuMa (W,X,Y,Z); `directional_energy.py` defaults to `fuma` while ambiscape auto-detects the convention from the recorder's `zTRK` tags in the BWF `bext` chunk (`io.channel_order`). Processing AmbiX files as FuMa swaps X↔Y — a reflection of all azimuths about the ±45° diagonal, which a best-circular-shift correlation does *not* absorb. Worth verifying which mode the 2023 raw files used before comparing directional results across the two corpora.
+
+## Conventions
+
+- AmbiX ACN channel order (W, Y, Z, X) as written by the H3-VR, SN3D.
+- Azimuth: 0° = front (X+), +90° = left (Y+), ±180° = rear; elevation + up. All directions are mic-relative.
+- Levels are dBFS (uncalibrated); within-session structure is exact; between-session absolute comparisons are indicative.
+- Diffuseness ψ = 1 − 2‖⟨Re W*·v⟩‖ / ⟨|W|² + ‖v‖²⟩ (0 = plane wave, 1 = diffuse).

ambiscape-0.1.0/pyproject.toml

@@ -0,0 +1,44 @@
+[build-system]
+requires = ["setuptools>=68"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "ambiscape"
+version = "0.1.0"
+description = "Long-duration first-order ambisonic soundscape analysis (streaming companion to ambiviz)"
+readme = "README.md"
+requires-python = ">=3.10"
+license = { text = "MIT" }
+authors = [{ name = "Alexander Refsum Jensenius", email = "a.r.jensenius@imv.uio.no" }]
+keywords = ["ambisonics", "soundscape", "field-recording", "acoustics",
+            "spatial-audio", "long-duration", "ISO-12913"]
+classifiers = [
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Topic :: Multimedia :: Sound/Audio :: Analysis",
+    "Intended Audience :: Science/Research",
+]
+dependencies = [
+    "numpy>=1.24",
+    "scipy>=1.10",
+    "soundfile>=0.12",
+    "matplotlib>=3.7",
+]
+
+[project.urls]
+Repository = "https://github.com/fourMs/ambiscape"
+Issues = "https://github.com/fourMs/ambiscape/issues"
+"Author ORCID" = "https://orcid.org/0000-0001-6171-8743"
+"Companion toolbox (ambiviz)" = "https://github.com/fisheggg/ambiviz"
+
+[project.optional-dependencies]
+viz = ["ambiviz>=0.0.1"]      # rich spatial visuals (anglegram/directogram/AEM) on extracted segments
+iso = ["mosqito>=1.2"]        # ISO 532-1 loudness, sharpness, roughness (ambiscape iso)
+ml = ["panns-inference>=0.1", "silero-vad>=5.0", "torch>=2.0"]  # tags + speech gate
+dev = ["pytest>=7.0"]
+
+[project.scripts]
+ambiscape = "ambiscape.cli:main"
+
+[tool.setuptools.packages.find]
+where = ["src"]

ambiscape-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

ambiscape-0.1.0/src/ambiscape/__init__.py

@@ -0,0 +1,20 @@
+"""ambiscape — long-duration first-order ambisonic soundscape analysis.
+
+Streaming companion to ambiviz (https://github.com/fisheggg/ambiviz):
+ambiscape summarizes hours of AmbiX recordings (levels, spectra, events,
+DOA/diffuseness timelines, reverberation, representative segments); ambiviz
+renders rich spatial visuals (AEM, anglegram, directogram) on the short
+excerpts ambiscape selects.
+"""
+from .io import open_session, read_bext, read_span
+from .features import extract_take, extract_session, load_features
+from .analysis import summarize, detect_events, decay_time, pick_segments
+from . import figures, taxonomy, iso
+
+__version__ = "0.1.0"
+__all__ = [
+    "open_session", "read_bext", "read_span",
+    "extract_take", "extract_session", "load_features",
+    "summarize", "detect_events", "decay_time", "pick_segments",
+    "figures", "taxonomy",
+]

ambiscape-0.1.0/src/ambiscape/analysis.py

@@ -0,0 +1,162 @@
+"""Session-level descriptors, event detection, and reverberation estimation.
+
+Descriptor conventions follow the Intercontinental-database report
+(2026-07-10): fast level = 125 ms RMS on W; events = fast level exceeding a
+running background (10th percentile in a sliding 60 s window) by >= 8 dB for
+>= 0.25 s; diffuseness/DOA from per-second pseudo-intensity vectors.
+"""
+from __future__ import annotations
+
+import numpy as np
+from scipy.ndimage import percentile_filter, median_filter
+
+EPS = 1e-20
+
+
+def db(x, eps=1e-12):
+    return 10 * np.log10(np.maximum(x, eps))
+
+
+def running_background(fast_db: np.ndarray, fast_dt: float, win_s=60.0, pct=10):
+    n = max(3, int(round(win_s / fast_dt)) | 1)
+    return percentile_filter(fast_db, pct, size=n, mode="nearest")
+
+
+def detect_events(fast_db, fast_dt, thresh_db=8.0, min_dur=0.25):
+    """Return list of dicts (onset index, length, peak index, exceedance)."""
+    bg = running_background(fast_db, fast_dt)
+    above = fast_db > bg + thresh_db
+    events = []
+    i, n = 0, len(above)
+    min_len = max(1, int(round(min_dur / fast_dt)))
+    while i < n:
+        if above[i]:
+            j = i
+            while j + 1 < n and above[j + 1]:
+                j += 1
+            if j - i + 1 >= min_len:
+                k = i + int(np.argmax(fast_db[i:j + 1]))
+                events.append(dict(i0=i, i1=j, ipk=k,
+                                   exceed=float(fast_db[k] - bg[k])))
+            i = j + 1
+        else:
+            i += 1
+    return events, bg
+
+
+def circular_stats(az_deg, weights=None):
+    """Energy-weighted circular mean (deg) and resultant length R."""
+    a = np.radians(np.asarray(az_deg, float))
+    w = np.ones_like(a) if weights is None else np.asarray(weights, float)
+    C = (w * np.cos(a)).sum() / (w.sum() + EPS)
+    S = (w * np.sin(a)).sum() / (w.sum() + EPS)
+    return float(np.degrees(np.arctan2(S, C))), float(np.hypot(C, S))
+
+
+def summarize(F: dict) -> dict:
+    """Session descriptor dict from concatenated features (see features.load_features)."""
+    fast, fasta = F["fast_db"], F["fast_dba"]
+    dt = float(np.median(np.diff(F["t_fast"]))) if len(F["t_fast"]) > 1 else 0.125
+    leq = db(np.mean(10 ** (fast.astype(np.float64) / 10)))
+    laeq = db(np.mean(10 ** (fasta.astype(np.float64) / 10)))
+    l10, l50, l90 = (float(np.percentile(fast, q)) for q in (90, 50, 10))
+    events, bg = detect_events(fast, dt)
+    dur = float(len(F["t"]))  # 1 s per feature frame; robust across take gaps
+
+    p = F["rms_w"].astype(np.float64) ** 2
+    e_fg = p >= np.percentile(p, 75)
+    e_bg = p <= np.percentile(p, 25)
+    az_mean, R = circular_stats(F["az"], weights=p)
+    az_fg, R_fg = circular_stats(F["az"][e_fg], weights=p[e_fg])
+    el_fg = float(np.median(F["el"][e_fg]))
+    psi = F["diffuse"]
+
+    return {
+        "duration_min": round(dur / 60, 1),
+        "leq_dbfs": round(float(leq), 1),
+        "laeq_dbfs": round(float(laeq), 1),
+        "leq_minus_laeq_db": round(float(leq - laeq), 1),
+        "L10": round(l10, 1), "L50": round(l50, 1), "L90": round(l90, 1),
+        "dynamics_L10_L90": round(l10 - l90, 1),
+        "events_per_min": round(len(events) / max(dur / 60, 1e-9), 1),
+        "event_median_dur_s": round(float(np.median(
+            [(e["i1"] - e["i0"] + 1) * dt for e in events])), 2) if events else None,
+        "centroid_median_hz": int(np.median(F["centroid"])),
+        "flatness_median": round(float(np.median(F["flatness"])), 3),
+        "diffuseness_median": round(float(np.median(psi)), 2),
+        "diffuseness_iqr": round(float(np.percentile(psi, 75)
+                                       - np.percentile(psi, 25)), 2),
+        "azimuth_mean_deg": round(az_mean, 0),
+        "azimuth_R": round(R, 2),
+        "azimuth_fg_deg": round(az_fg, 0),
+        "elevation_fg_median_deg": round(el_fg, 0),
+        "n_events": len(events),
+    }
+
+
+def decay_time(x: np.ndarray, fs: int, bands=((250, 500), (500, 1000),
+               (1000, 2000), (2000, 4000), (4000, 8000))) -> dict:
+    """T60 estimates from an impulse via truncated Schroeder integration.
+
+    The decay is truncated at the first re-attack (envelope rising >= 8 dB
+    above its running minimum) and at the noise floor; a linear fit of
+    -5 dB .. max(-35 dB, floor + 8 dB) is extrapolated to 60 dB.
+    Returns {band: (T60, dynamic_range_db)}.
+    """
+    from scipy import signal as sg
+    pk_i = int(np.abs(x).argmax())
+    env_bb = sg.convolve(x ** 2, np.ones(480) / 480, "same")
+    tail = 10 * np.log10(env_bb[pk_i:pk_i + 3 * fs] + 1e-15)
+    run_min = np.minimum.accumulate(tail)
+    re = np.flatnonzero((tail - run_min > 8) & (np.arange(len(tail)) > fs // 10))
+    cut = int(re[0]) if len(re) else 2 * fs
+    out = {}
+    for lo, hi in bands:
+        sos = sg.butter(4, [lo, hi], "bandpass", fs=fs, output="sos")
+        y = sg.sosfilt(sos, x)
+        env = sg.convolve(y ** 2, np.ones(240) / 240, "same")
+        pk = int(env[max(0, pk_i - 2400):pk_i + 2400].argmax()) + max(0, pk_i - 2400)
+        if pk < fs // 4:
+            continue
+        noise = float(np.median(env[:pk - fs // 8]))
+        dr = 10 * np.log10(env[pk] / (noise + EPS))
+        if dr < 20:
+            continue
+        seg = np.maximum(y[pk:pk + cut] ** 2 - noise, 0)
+        sch = np.cumsum(seg[::-1])[::-1]
+        sch_db = 10 * np.log10(sch / (sch[0] + EPS) + 1e-15)
+        tax = np.arange(len(sch_db)) / fs
+        lo_db = max(-35.0, -dr + 8)
+        m = (sch_db <= -5) & (sch_db >= lo_db)
+        if m.sum() < 150:
+            continue
+        A = np.vstack([tax[m], np.ones(int(m.sum()))]).T
+        slope, _ = np.linalg.lstsq(A, sch_db[m], rcond=None)[0]
+        if slope < 0:
+            out[f"{lo}-{hi}"] = (round(-60.0 / slope, 2), round(float(dr), 0))
+    return out
+
+
+def pick_segments(F: dict, n=4, seg_s=600.0) -> list[dict]:
+    """Suggest representative windows: quietest, most active, median-typical,
+    and (if present) the strongest state transition."""
+    t, fast = F["t_fast"], F["fast_db"]
+    dt = float(np.median(np.diff(t)))
+    win = max(1, int(seg_s / dt))
+    if len(fast) < win:
+        return [dict(kind="whole", t0=float(t[0]), dur=float(t[-1] - t[0]))]
+    k = np.ones(win) / win
+    m_lvl = np.convolve(10 ** (fast.astype(np.float64) / 10), k, "valid")
+    var = np.convolve((fast - fast.mean()) ** 2, k, "valid")
+    picks = []
+    for kind, idx in (("quietest", int(np.argmin(m_lvl))),
+                      ("most_active", int(np.argmax(var))),
+                      ("typical", int(np.argmin(np.abs(db(m_lvl) - np.median(db(m_lvl))))))):
+        picks.append(dict(kind=kind, t0=float(t[idx]), dur=seg_s))
+    smooth = median_filter(fast, size=max(3, int(30 / dt)) | 1)
+    jump = np.abs(np.diff(smooth))
+    if jump.max() > 6:
+        picks.append(dict(kind="transition",
+                          t0=float(max(t[0], t[int(np.argmax(jump))] - seg_s / 2)),
+                          dur=seg_s))
+    return picks[:n]

ambiscape-0.1.0/src/ambiscape/cli.py

@@ -0,0 +1,170 @@
+"""Command-line interface.
+
+    ambiscape probe   <session-folder>            # metadata only
+    ambiscape analyze <session-folder> [-o DIR]   # features + figures + README
+"""
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+from pathlib import Path
+
+
+def main(argv=None):
+    ap = argparse.ArgumentParser(prog="ambiscape",
+                                 description="Long-duration ambisonic soundscape analysis")
+    sub = ap.add_subparsers(dest="cmd", required=True)
+    p = sub.add_parser("probe", help="show session metadata")
+    p.add_argument("folder")
+    a = sub.add_parser("analyze", help="extract features, figures, README")
+    a.add_argument("folder")
+    a.add_argument("-o", "--out", default=None,
+                   help="output dir (default <folder>/analysis)")
+    a.add_argument("--notes", default="", help="free-text session notes for README")
+    tx = sub.add_parser("taxonomy",
+                        help="render Schaeffer map + Schafer timeline from "
+                             "<folder>/annotations.json")
+    tx.add_argument("folder")
+    tx.add_argument("-o", "--out", default=None)
+    dr = sub.add_parser("draft",
+                        help="pre-fill annotations.draft.json from detected "
+                             "states and events (needs a prior analyze run)")
+    dr.add_argument("folder")
+    dp = sub.add_parser("deposit",
+                        help="export non-identifying 1 Hz feature TSVs "
+                             "(StillStanding365 schema) to <folder>/deposit/")
+    dp.add_argument("folder")
+    sg = sub.add_parser("speechgate",
+                        help="silero-vad privacy check: fraction of speech "
+                             "in WAV file(s) before publishing")
+    sg.add_argument("path", help="a WAV file or a folder of WAVs")
+    sg.add_argument("--threshold", type=float, default=0.01,
+                    help="max allowed speech fraction (default 0.01)")
+    iso_p = sub.add_parser("iso",
+                           help="ISO 12913-3 psychoacoustic indicators "
+                                "(MoSQITo) on representative segments")
+    iso_p.add_argument("folder")
+    iso_p.add_argument("--dur", type=float, default=30.0,
+                       help="seconds per segment (default 30)")
+    iso_p.add_argument("--offset", type=float, default=None,
+                       help="dBFS->dB SPL offset override")
+    args = ap.parse_args(argv)
+
+    if args.cmd == "deposit":
+        from .deposit import export_session
+        outs = export_session(args.folder)
+        if not outs:
+            print("no cached features — run 'ambiscape analyze' first")
+            return 1
+        for o in outs:
+            print(f"wrote {o}")
+        return 0
+
+    if args.cmd == "speechgate":
+        from .ml import speech_gate
+        p = Path(args.path)
+        files = sorted(p.glob("*.wav")) + sorted(p.glob("*.WAV")) \
+            if p.is_dir() else [p]
+        ok = True
+        for f in files:
+            r = speech_gate(f, threshold=args.threshold)
+            verdict = "PASS" if r["passes"] else "FAIL"
+            ok &= r["passes"]
+            extra = ("" if r["passes"] else
+                     f" (first speech at {r['first_speech_at_s']}s)")
+            print(f"  {verdict}  {f.name}: {r['speech_fraction']*100:.2f}% "
+                  f"speech, {r['n_speech_segments']} segment(s){extra}")
+        return 0 if ok else 2
+
+    if args.cmd == "iso":
+        from .features import load_features
+        from .io import open_session
+        from . import iso as iso_mod
+        sess = open_session(args.folder)
+        fdir = Path(args.folder) / "analysis" / "features"
+        paths = sorted(fdir.glob("*.npz"))
+        if not paths:
+            print(f"no cached features in {fdir} — run 'ambiscape analyze' first")
+            return 1
+        F = load_features(paths)
+        res = iso_mod.segment_indicators(sess, F, args.folder,
+                                         dur=args.dur, offset=args.offset)
+        out = Path(args.folder) / "analysis" / "iso_indicators.json"
+        out.write_text(json.dumps(res, indent=2))
+        if not res["calibrated"]:
+            print("WARNING:", res["warning"])
+        for kind, seg in res["segments"].items():
+            print(f"  {kind} @ {seg['t0']}: N5 {seg['N5_sone_max_ear']} sone "
+                  f"(max ear), sharpness {seg['left']['sharpness_median_acum']}"
+                  f"/{seg['right']['sharpness_median_acum']} acum "
+                  f"[{seg['binaural_method']}]")
+        print(f"wrote {out}")
+        return 0
+
+    if args.cmd == "draft":
+        from .features import load_features
+        from .io import open_session
+        from .draft import draft_annotations
+        fdir = Path(args.folder) / "analysis" / "features"
+        paths = sorted(fdir.glob("*.npz"))
+        if not paths:
+            print(f"no cached features in {fdir} — run 'ambiscape analyze' first")
+            return 1
+        F = load_features(paths)
+        try:
+            sess = open_session(args.folder)
+        except (FileNotFoundError, ValueError):
+            sess = None
+        out = draft_annotations(F, args.folder, session=sess)
+        doc = json.loads(out.read_text())
+        n_obj = len(doc["objects"])
+        n_tag = sum(1 for o in doc["objects"] for h in o.get("_hints", [{}])
+                    if "tags" in h) + sum(1 for o in doc["objects"]
+                                          if "_tags" in o)
+        print(f"wrote {out} ({n_obj} draft objects, {n_tag} PANNs-tagged "
+              f"windows) — edit, save as annotations.json, then run "
+              f"'ambiscape taxonomy'")
+        return 0
+
+    if args.cmd == "taxonomy":
+        from .taxonomy import render
+        paths = render(args.folder, out_dir=args.out)
+        for p in paths:
+            print(f"wrote {p}")
+        return 0
+
+    from .io import open_session
+    sess = open_session(args.folder)
+
+    if args.cmd == "probe":
+        print(f"session {sess.name}: {len(sess.takes)} take(s), "
+              f"{sess.duration/60:.1f} min total")
+        for tk in sess.takes:
+            print(f"  {tk.path.name}: {tk.date} {tk.clock}, "
+                  f"{tk.duration/60:.1f} min, {tk.channels}ch @{tk.samplerate}")
+        return 0
+
+    from . import analysis, features, figures, report
+    out = Path(args.out) if args.out else sess.folder / "analysis"
+    out.mkdir(parents=True, exist_ok=True)
+    print(f"analyzing {sess.name} ({sess.duration/60:.1f} min)")
+    paths = features.extract_session(sess, out / "features")
+    F = features.load_features(paths)
+    summary = analysis.summarize(F)
+    from .iso import load_calibration, apply_calibration
+    cal = load_calibration(sess.folder)
+    if cal:
+        summary = apply_calibration(summary, cal)
+    figures.overview(F, out / "overview.png", title=sess.name, clock=sess.clock)
+    figures.ltas_percentiles(F, out / "ltas_percentiles.png", title=sess.name)
+    figures.directogram(F, out / "directogram.png", title=sess.name)
+    report.write_readme(sess, summary, out, notes=args.notes)
+    for k, v in summary.items():
+        print(f"  {k}: {v}")
+    print(f"wrote {out} and {sess.folder/'README.md'}")
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

ambiscape-0.1.0/src/ambiscape/deposit.py

@@ -0,0 +1,52 @@
+"""Non-identifying feature export in the StillStanding365 deposit schema.
+
+Writes one TSV per take with the columns used by the StillStanding365 Zenodo
+deposit (``audio/{day}.tsv``): per-second ``Time``, ``level_dbfs``,
+``centroid_hz``, ``low_frac`` (< 250 Hz), ``high_frac`` (> 2 kHz). A 1 Hz
+loudness/spectral envelope is far below speech timescales and carries no
+intelligible content, so these files are safe to publish where raw audio is
+not.
+
+Method notes vs. the original ``extract_audio.py``: levels here come from the
+W (omni) channel at native rate (the original used an ffmpeg 4-channel
+downmix at 8 kHz — offsets of a few tenths of a dB are expected), and band
+fractions are power fractions from the cached log-spectrogram (the original
+used magnitude fractions of an 8 kHz FFT). Trends and dynamics are directly
+comparable; absolute fraction values differ slightly by construction.
+"""
+from __future__ import annotations
+
+from pathlib import Path
+
+import numpy as np
+
+from .analysis import db
+
+
+def export_take_tsv(npz_path: str | Path, out_dir: str | Path) -> Path:
+    p = np.load(str(npz_path))
+    logf = p["logf"]
+    fc = np.sqrt(logf[:-1] * logf[1:])
+    S = p["logspec"]
+    tot = S.sum(1) + 1e-20
+    low = S[:, fc < 250].sum(1) / tot
+    high = S[:, fc > 2000].sum(1) / tot
+    level = db(p["rms_w"].astype(np.float64) ** 2)
+    out_dir = Path(out_dir)
+    out_dir.mkdir(parents=True, exist_ok=True)
+    out = out_dir / (Path(npz_path).stem + ".tsv")
+    with open(out, "w") as f:
+        f.write("Time\tlevel_dbfs\tcentroid_hz\tlow_frac\thigh_frac\n")
+        for i in range(len(level)):
+            f.write(f"{i}\t{level[i]:.1f}\t{p['centroid'][i]:.0f}\t"
+                    f"{low[i]:.3f}\t{high[i]:.3f}\n")
+    return out
+
+
+def export_session(folder: str | Path) -> list[Path]:
+    folder = Path(folder)
+    fdir = folder / "analysis" / "features"
+    outs = []
+    for npz in sorted(fdir.glob("*.npz")):
+        outs.append(export_take_tsv(npz, folder / "deposit"))
+    return outs