ambiscape

ambiscape is a Python toolbox for analysing soundscapes—the sonic ambiences of rooms and other places. It reads mono, stereo, binaural, or first-order ambisonic recordings of any length and describes a place's sound as a whole: level, spectrum, space, rhythm, sources, and more. Several recorders spread through a building can be read together as one acoustic network.

Install

pip install ambiscape

Optional extras add psychoacoustic indicators, machine listening, music analysis, live capture, and spatial visuals. See the install guide.

Quickstart

Point analyze at a session—a folder of WAV files from one recording occasion:

ambiscape analyze my-session/

This streams the audio in constant memory, however long it is. It extracts features, computes descriptors (Leq, LAeq, percentile levels, event statistics, diffuseness, and more), renders overview figures, and writes a README.md summarising the session. Start by reading that README and looking at analysis/overview.png:

Session overview figure: level timeline, spectrogram, anglegram, and diffuseness lane on one clock. The quickstart guide continues from there, on the command line and in Python.

Commands

analyze is one of nearly forty subcommands. The others cover taxonomy annotation, rhythm and tonality, room acoustics and impulse responses, ecological and source-domain indices, perceptual surveys, multi-recorder building networks (network), corpus aggregation, and privacy-aware publishing. The command overview lists them all; ambiscape --help prints the same list.

Documentation

User guide & API reference—the session model, feature and descriptor definitions, and a page per analysis module.
Wiki—field-recording protocol, recipes, worked case studies, design rationale, and research context.

ambiscape analyses sound; its sister toolbox MGT-python analyses video. The two meet at file boundaries—see Working with other packages.

Related toolboxes

These come out of the same lab, as separate packages with separate release cycles. 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.

micromotion—human micromotion: quantity of motion from optical markers, accelerometers, respiration belts and force plates
musiscape—music collections: comparing many tracks and albums held as audio files in folders; it reuses this package's circular statistics and Schaeffer typology machinery
Musical Gestures Toolbox (musicalgestures)—video and audio: motiongrams, videograms, and motion analysis from ordinary video files

The boundary with musiscape is the one worth stating: ambiscape is about a PLACE and its sonic ambience, musiscape about a COLLECTION of music. Music analysis moved out of ambiscape into musiscape on 2026-08-12, so an older release of either may still carry the other's functions.

Licence

MIT—see LICENSE.

Credits

ambiscape is developed as part of the AMBIENT project at fourMs / RITMO, University of Oslo, supported by the Research Council of Norway. It is the streaming companion to ambiviz, which renders rich spatial visuals from short ambisonic files.

Citing

Cite the concept DOI, which always resolves to the newest version:

Jensenius, A. R., & Guo, J. (2026). ambiscape: analysis of soundscapes from mono, stereo, binaural and ambisonic recordings [Computer software]. Zenodo. https://doi.org/10.5281/zenodo.21948997

Where the exact behaviour matters, add the version you ran. Every release has its own DOI, listed on the Zenodo record.

CITATION.cff in this repository carries the same information in machine-readable form.

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

ambiscape-0.43.0.tar.gz (364.8 kB view details)

Uploaded Aug 16, 2026 Source

Built Distribution

If you're not sure about the file name format, learn more about wheel file names.

The dropdown lists show the available interpreters, ABIs, and platforms. Enable javascript to be able to filter the list of wheel files.

ambiscape-0.43.0-py3-none-any.whl (296.0 kB view details)

Uploaded Aug 16, 2026 Python 3

File details

Details for the file ambiscape-0.43.0.tar.gz.

File metadata

Download URL: ambiscape-0.43.0.tar.gz
Upload date: Aug 16, 2026
Size: 364.8 kB
Tags: Source
Uploaded using Trusted Publishing? Yes
Uploaded via: twine/7.0.0 CPython/3.13.14

File hashes

Hashes for ambiscape-0.43.0.tar.gz
Algorithm	Hash digest
SHA256	`a87479cb5c599975e29dcdfef416f67217099651c74983f3f6e808c20a1df2a8`
MD5	`f210c4a5f50dffb1ede4fcf2475934f9`
BLAKE2b-256	`f23951297ec8bf7a082a02f7bac85e1129ee43ba699961c1a416cb1ca22755b1`

See more details on using hashes here.

Provenance

The following attestation bundles were made for ambiscape-0.43.0.tar.gz:

Publisher: python-publish.yml on fourMs/ambiscape

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

Statement:
- Statement type: https://in-toto.io/Statement/v1
- Predicate type: https://docs.pypi.org/attestations/publish/v1
- Subject name: ambiscape-0.43.0.tar.gz
- Subject digest: a87479cb5c599975e29dcdfef416f67217099651c74983f3f6e808c20a1df2a8
- Sigstore transparency entry: 2487065832
- Sigstore integration time: Aug 16, 2026
Source repository:
- Permalink: fourMs/ambiscape@ccefdefb3ac40f9ec943a4b3fe871685d0b4affb
- Branch / Tag: refs/tags/v0.43.0
- Owner: https://github.com/fourMs
- Access: public
Publication detail:
- Token Issuer: https://token.actions.githubusercontent.com
- Runner Environment: github-hosted
- Publication workflow: python-publish.yml@ccefdefb3ac40f9ec943a4b3fe871685d0b4affb
- Trigger Event: release