Skip to content

Image title Image title

Welcome to Soundscapy

PyPI version Documentation Status License

Soundscapy is a Python library for analysing and visualising soundscape assessments following the ISO 12913 standard. It is used by researchers and practitioners to process survey data, create publication-quality visualisations of soundscape perception, analyse binaural recordings, and compute Soundscape Perception Indices.

What can you do with it?

Process survey data — Load, validate, and transform PAQ questionnaire responses into ISO coordinates (ISOPleasant, ISOEventful) with a single function call. Supports custom value ranges, language-specific angle adjustments, and the ISD, ARAUS, and SATP datasets.

Visualise soundscapes — Create scatter plots, bivariate density plots, Likert plots, and radar plots of soundscape perception distributions. The ISOPlot class supports multi-panel and multi-layer figures suitable for publication.

Analyse audio recordings — Compute psychoacoustic metrics (loudness, sharpness, roughness, fluctuation strength) and environmental indices from binaural WAV files using the soundscapy[audio] extension.

Compute Soundscape Perception Indices — Fit multi-dimensional skewed normal distributions to perception data and score locations against target distributions using soundscapy[r]. Run CircE structural equation models via the SATP module.

Installation

pip install soundscapy

For audio analysis:

pip install "soundscapy[audio]"

For SPI and SATP (requires a local R installation):

pip install "soundscapy[r]"
R -q -e "install.packages('sn')"

Note

CircE is bundled with Soundscapy — no separate GitHub install needed. Only the sn R package is required externally.

To install everything at once:

pip install "soundscapy[all]"
R -q -e "install.packages('sn')"

Where to start

New to soundscape analysis? Read About Soundscape Analysis for a concise overview of PAQ attributes, the ISO circumplex model, and what ISOPleasant/ISOEventful mean.

Ready to write code? Go to the Quick Start.

Contributing

We welcome contributions from the community. Please get in touch or submit an issue on GitHub.

Citing Soundscapy

Note

If you use Soundscapy in your research, please include a citation to our accompanying paper:

Mitchell, A., Aletta, F., & Kang, J. (2022). How to analyse and represent quantitative soundscape data. _JASA Express Letters, 2_, 37201. [https://doi.org/10.1121/10.0009794](https://doi.org/10.1121/10.0009794) <!-- markdownlint-disable MD046 -->

License

This project is licensed under the BSD 3-Clause License. See the license page for details.