Analysis toolkit for long-duration (hours) first-order ambisonic soundscape recordings (Zoom H3-VR and other AmbiX/SN3D B-format sources), processed in a stream with constant memory.
pip install ambiscape # core
pip install "ambiscape[iso]" # + ISO 532-1 loudness/sharpness/roughness
pip install "ambiscape[ml]" # + AudioSet tagging, speech privacy gate
pip install "ambiscape[viz]" # + ambiviz (HRIR binaural, AEM visuals)ambiscape probe <session-folder> # metadata
ambiscape analyze <session-folder> # features, descriptors, figures, README
ambiscape draft <session-folder> # pre-fill taxonomy annotations
ambiscape taxonomy <session-folder> # Schaeffer map + Schafer timeline
ambiscape rhythm <session-folder> # strike-level rhythm of periodic sources
ambiscape modspec <session-folder> # micro/meso/macro modulation profile
ambiscape tonality <session-folder> # tonal tracks, harmonicity, pitch classes
ambiscape spatial <session-folder> # direct/diffuse split, pass-bys, azimuth R(t)
ambiscape schedule <session-folder> # match events against civic time grids
ambiscape timbre <session-folder> # event timbre templates (no-ML clustering)
ambiscape music <session-folder> # librosa tempogram + chromagram [music]
ambiscape iso <session-folder> # ISO 12913-3 indicators
ambiscape speechgate <wav-or-folder> # privacy check before publishing
ambiscape deposit <session-folder> # non-identifying 1 Hz TSV export
ambiscape resolve <session-folder> # per-state descriptors (on/off, day/night)
ambiscape catalog <corpus-folder> # aggregate all summary.json -> CSV
ambiscape longitudinal <corpus-folder> # trend + seasonal over dated sessions
ambiscape scenes <folder> # analyze each WAV as an independent scene
ambiscape capture <root> # always-on feature-extraction daemon [capture]A session is a folder of WAVs on one absolute clock (BWF timestamps,
parsed natively); a single one-off recording opens as its own scene with
open_recording(path). analyze produces a per-session README.md with a
descriptor table (Leq, LAeq, L10/L50/L90, events, diffuseness ψ, azimuthal
concentration R, …) and overview figures (level + spectrogram + anglegram +
ψ timeline, percentile spectra, directogram).
Everything the CLI does is a library call, and version 0.3 adds a notebook-oriented case-study toolbox — machine on/off states, source fingerprints, civic-grid scans, bit-exact segment export:
import ambiscape as asc
from ambiscape import background, features, schedule, states
sess = asc.open_session("2026-07-15-Haarlem-loft")
F = features.load_features(
features.extract_session(sess, "analysis/features"))
segs = states.state_segments(states.band_level(F, (250, 1000))) # vent on/off
fp = background.source_fingerprint(F, night_minutes, morning_minutes)
bells = schedule.grid_scan(F, 900.0, band=(350, 800)) # church clock
asc.export_segment(sess, t0, 600.0, "seg6_vent_switchoff.wav")
from ambiscape import enf # v0.4: grid-frequency traces
enf.enf_summary(enf.enf_track(sess)) # mains ENF wander, mHz-level
from ambiscape import ecology, iso # v0.5: ratings & indices
ecology.indices(F) # ACI, ADI/AEI, NDSI, BI, H
iso.room_criteria(iso.background_octaves_db(F)) # NR / NC / RC (HVAC idiom)
asc.decay_metrics(x[:, 0], fs) # T60 + EDT, C50/C80, D50
from ambiscape import biophony, ml # v0.6: nature & animals
biophony.summarize_biophony(F) # narrowband/temporal/spatial
ml.birdnet_session(sess, F=F, hifi_max_diffuse=0.75, lat=52.4, lon=4.6)See the machine-states guide and the executable session report it was built for.
- User guide & API reference — the session model and conventions, feature/descriptor definitions, room acoustics and ISO indicators, the taxonomy workflow, machine listening, deposit export.
- Wiki — research context, field-recording protocol, design decisions, recipes, roadmap.
- ambiviz renders rich spatial visuals from ambisonic files
- librosa
MIT — see LICENSE. Developed in the AMBIENT project at fourMs / RITMO, University of Oslo.