Design Decisions

Why the toolbox works the way it does — the reasoning behind choices that would otherwise look arbitrary.

Streaming, not loading

The unit of interest is the session: a night is 20+ GB of 4-channel PCM. Everything is computed in 60-second blocks with constant memory, and cached per take as .npz so analysis iterations after the first pass are near-instant. This is the complementary regime to ambiviz, which deliberately loads whole (short) files to render dense spatial visuals.

Pseudo-intensity vector for DOA

Two estimator families exist for FOA direction: virtual-speaker decodes with per-frame argmax (ambiviz's directogram; good at resolving discrete reflections) and the pseudo-intensity vector Re{W*·[X,Y,Z]} (the DirAC tradition). ambiscape uses intensity because it additionally yields elevation and diffuseness ψ from the same computation, and because an energy-weighted vector integrates gracefully over the long time frames streaming analysis works with. ψ = 1 − 2‖⟨Re W*·v⟩‖/⟨|W|²+‖v‖²⟩ is normalized so a plane wave gives 0 and an ideal diffuse field 1 under SN3D.

Empirically, ψ turned out to be one of the most discriminative descriptors in the corpus work: transit halls and open fields sit at 0.84–0.90, lived domestic interiors at 0.6–0.8, and rooms dominated by one running machine collapse to ≈ 0.2. Reading ψ together with azimuthal concentration R distinguishes anisotropic envelopment (high ψ, high R) from point-source rooms (low ψ, high R) — two situations a mono recording cannot tell apart.

The event criterion

Events = 125 ms fast level ≥ 8 dB above a running background (10th percentile in a sliding 60 s window) for ≥ 0.25 s. Chosen once, frozen, and reused across all corpus reports so event rates stay comparable between studies. Change it and you change every historical number — if you need a different criterion, add a second one rather than editing this one.

Channel-convention auto-detection

Recorders write B-format in either AmbiX (W,Y,Z,X) or FuMa (W,X,Y,Z), and the difference is catastrophic for spatial analysis while being invisible in casual listening: a FuMa map applied to AmbiX data feeds the near-empty Z channel into the horizontal decode, collapsing every azimuth onto a 0°/180° axis. We found exactly this signature in a real deposited dataset — identical axis alignment across hundreds of different rooms — which is physically implausible and diagnosable from derived data alone. Hence io.channel_order reads the recorder's zTRK tags per file and the docs tell you what the artifact looks like. Lesson: conventions must be read from metadata, never assumed.

Human-in-the-loop taxonomy

Detection is mechanical; classification into Schaeffer's typo-morphology or Schafer's functional categories is a listening judgment. The draft → listen/edit → taxonomy workflow enforces that split: the machine proposes regimes, events, hints (including AudioSet tags, explicitly framed as suggestions), and a human confirms or corrects. We deliberately do not auto-generate final annotations.

Ethics-driven deposit format

The 1 Hz level/centroid/band-fraction TSV (from the StillStanding365 deposit) is below speech timescales and hence publishable where raw audio from private spaces is not. Adopting it as an export target means every corpus using ambiscape has an open-data layer by default — a positive design outcome of a privacy constraint. The speechgate command (silero-vad) mechanizes the check for the excerpts that are published as audio.

ISO positioning

Descriptors follow ISO 1996 conventions (Leq, LAeq, percentile levels); psychoacoustic indicators follow ISO 12913-3 via MoSQITo (validated against the 1 kHz/60 dB ≙ 4 sone reference); calibration is a single documented offset. Consumer recorders are not Class-1 chains, so the honest claim is "ISO 12913-informed" — the standards are the shared vocabulary, not a conformance badge.