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 loop       <session-folder>   # seamlessly loopable prototype segment (typical, not just calm)
ambiscape resynth    <session-folder>   # recreate the soundscape from basic synthesis models (Web Audio page)
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 calibrate  <session-folder>   # store dBFS->dB SPL offset from a field SPL reading
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.

Related toolboxes

These four toolboxes come out of the fourMs lab at the University of Oslo. They are separate packages with separate release cycles, but they are built to be used together and share several implementations, so a measure computed in one agrees with the same measure computed in another.

• Musical Gestures Toolbox (musicalgestures) — video and audio: motiongrams, videograms, and motion analysis from ordinary video files
• musiscape — music collections: comparing many tracks and albums held as audio files in folders
• micromotion — human micromotion: quantity of motion from optical markers, accelerometers, respiration belts and force plates