ambiscape

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. Stereo, binaural, and mono recordings — including a phone's .m4a — are analysed too: a lateral left/right cue is recovered from stereo, and 2-channel binaural ear signals are handled directly (see Mono, stereo & binaural inputs).

Install

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)

Quickstart

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 carillon   <session-folder>   # which bells a carillon played: strike-note inventory [music]
ambiscape vision     <video-or-folder>  # per-frame visual features (multimodal companion)
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).

In notebooks

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.

Documentation

• 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.

Dependencies

• ambiviz renders rich spatial visuals from ambisonic files
• librosa

License

MIT — see LICENSE. Developed in the AMBIENT project at fourMs / RITMO, University of Oslo.