Metadata-Version: 2.4
Name: ambiscape
Version: 0.35.0
Summary: A holistic toolbox for analysing soundscapes (sonic ambiences) from mono, stereo, binaural, or ambisonic recordings
Author-email: Alexander Refsum Jensenius <a.r.jensenius@imv.uio.no>
License: MIT
Project-URL: Repository, https://github.com/fourMs/ambiscape
Project-URL: Issues, https://github.com/fourMs/ambiscape/issues
Project-URL: Author ORCID, https://orcid.org/0000-0001-6171-8743
Project-URL: Companion toolbox (ambiviz), https://github.com/fisheggg/ambiviz
Keywords: ambisonics,soundscape,field-recording,acoustics,spatial-audio,long-duration,ISO-12913
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Multimedia :: Sound/Audio :: Analysis
Classifier: Intended Audience :: Science/Research
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: numpy>=1.24
Requires-Dist: scipy>=1.10
Requires-Dist: soundfile>=0.12
Requires-Dist: matplotlib>=3.7
Provides-Extra: viz
Requires-Dist: ambiviz>=0.0.1; extra == "viz"
Provides-Extra: iso
Requires-Dist: mosqito>=1.2; extra == "iso"
Provides-Extra: music
Requires-Dist: librosa>=0.10; extra == "music"
Provides-Extra: capture
Requires-Dist: sounddevice>=0.4; extra == "capture"
Provides-Extra: ml
Requires-Dist: panns-inference>=0.1; extra == "ml"
Requires-Dist: silero-vad>=5.0; extra == "ml"
Requires-Dist: torch>=2.0; extra == "ml"
Requires-Dist: birdnetlib>=0.17; extra == "ml"
Provides-Extra: dev
Requires-Dist: pytest>=7.0; extra == "dev"
Dynamic: license-file

# Ambiscape

[![CI](https://github.com/fourMs/ambiscape/actions/workflows/ci.yml/badge.svg)](https://github.com/fourMs/ambiscape/actions/workflows/ci.yml)
[![docs](https://github.com/fourMs/ambiscape/actions/workflows/docs.yml/badge.svg)](https://fourms.github.io/ambiscape/)
[![PyPI version](https://img.shields.io/pypi/v/ambiscape)](https://pypi.org/project/ambiscape/)
[![Python](https://img.shields.io/pypi/pyversions/ambiscape.svg)](https://pypi.org/project/ambiscape/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)

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

```bash
pip install ambiscape
```

Optional extras add psychoacoustic indicators, machine listening, music analysis, live capture, and spatial visuals. See the [install guide](https://fourms.github.io/ambiscape/install/).

## Quickstart

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

```bash
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.](docs/img/overview.png) The [quickstart guide](https://fourms.github.io/ambiscape/quickstart/) 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](https://fourms.github.io/ambiscape/cli/) lists them all; `ambiscape --help` prints the same list.

## Documentation

- **[User guide & API reference](https://fourms.github.io/ambiscape/)**—the session model, feature and descriptor definitions, and a page per analysis module.
- **[Wiki](https://github.com/fourMs/ambiscape/wiki)**—field-recording protocol, recipes, worked case studies, design rationale, and research context.

Ambiscape analyses sound; its sister toolbox [MGT-python](https://github.com/fourMs/MGT-python) analyses video. The two meet at file boundaries—see [Working with other packages](https://fourms.github.io/ambiscape/interop/).

## Licence

MIT—see [LICENSE](LICENSE).

## Credits

Ambiscape is developed as part of the [AMBIENT project](https://www.uio.no/ritmo/english/projects/ambient/index.html) at [fourMs / RITMO](https://www.uio.no/ritmo/english/), University of Oslo, supported by the Research Council of Norway. It is the streaming companion to [ambiviz](https://github.com/fisheggg/ambiviz), which renders rich spatial visuals from short ambisonic files.
