Ambiscape

Ambiscape is a toolbox for analysing soundscapes, with a particular focus on the sonic ambiences of rooms. It takes a holistic view, bringing together measurements of level, spectral, spatial, temporal, ecological, and source-domain descriptors so a place's sound can be described as a whole rather than one metric at a time.

The toolbox works from many different types of recordings: mono, stereo, binaural, or first-order ambisonic, using whatever spatial information each format carries (see Mono, stereo & binaural inputs). It is built to be useful to different people: acousticians and soundscape ecologists, sound artists and composers, students, and anyone curious about the sound of a place.

Scope: ambiscape and MGT

ambiscape and MGT-python are sister toolboxes: ambiscape owns the samples, MGT owns the pixels. The built-in vision module extracts only lightweight per-frame features as a multimodal companion to the audio; for real video analysis (motion, pose, 360° stitching) use MGT, which can ingest ambiscape sessions directly via pip install "musicalgestures[soundscape]". ambiscape itself stays dependency-light and never imports MGT.

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 background <session-folder>   # background-only bed render, or --excerpt: a characteristic minute
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. From version 0.3 there has been 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.

Funding

Developed as part of the AMBIENT project at fourMs / RITMO, University of Oslo. Supported by the Research Council of Norway.