audiblelight 0.1.2

A controllable, end-to-end API for soundscape synthesis across ray-traced & real-world measured acoustics

AudibleLight

A Controllable, End-to-End API for Soundscape Synthesis Across Ray-Traced & Real-World Measured Acoustics

⚠️ WARNING: This project is currently under heavy development. We have done our due diligence to ensure that it works as expected. However, if you encounter any errors, please open an issue and let us know.

Contents

• Installation
• Usage
• Contributions
• Roadmap

What is AudibleLight?

AudibleLight is a unified API for audio-visual soundscape synthesis supporting ray-traced, real-world, and parametric RIR generation. It enables flexible microphone array modeling and dynamic, fully annotated source trajectories within a single workflow. It is built upon SpatialScaper, SoundSpaces, Pyroomacoustics, and SELDVisualSynth for scalable soundscape generation with unprecedented acoustic diversity.

AudibleLight is developed by researchers at the Centre for Digital Music, Queen Mary University of London in collaboration with Meta Reality Labs.

Installation:

Prerequisites

• python3.10 or above (tested up to python3.12)
• A modern Linux distro: current versions of Ubuntu and Red Hat have been tested and confirmed to work.
  • Using another OS? Let us know so we can add it here!

If you're looking to develop AudibleLight, you'll also need to install:

• git
• poetry
• make

Install via pypi

For non-development installs, the simplest way to install AudibleLight is via pypi:

sudo apt update
sudo apt install -y libsox-dev libsox-fmt-all freeglut3-dev pandoc
pip install audiblelight

Install via the command line

git clone https://github.com/AudibleLight/AudibleLight.git
cd AudibleLight
make install

Download data

We provide several helper scripts to download and prepare data (3D meshes, sofa files, audio files, images) that may be useful in AudibleLight.

You can run these scripts directly from the Python interpreter:

from audiblelight.download_data import download_fsd

download_fsd(path="path/to/save/fsd", cleanup=True)

Alternatively, for a development install, you can run them from the command line:

poetry run python scripts/download_data/download_fsd.py --path path/to/save/fsd --cleanup

From a development install, you can also run all download scripts at once using the Makefile:

make download

For further information, see scripts/download_data/README.md.

Usage

See the quickstart guide for help getting started with dataset generation in AudibleLight

Script

We include scripts to generate large datasets for common tasks relating to spatial soundscape synthesis.

To generate a dataset for sound event localization and detection (SELD) that conforms with the DCASE2023 task 3 format, run:

poetry run python scripts/seld/generate_dataset.py

To see the available arguments that this script takes, add the --help argument

If you want to generate custom datasets (or want to implement AudibleLight in a larger pipeline), please see the quickstart, tutorials, and API documentation.

Contributions

... are welcome! Please make a PR or take a look at the open issues.

Running the tests

Before making a PR, ensure that you run the pre-commit hooks and tests:

make fix
make tests

Roadmap

• Spatial audio augmentations (from https://arxiv.org/abs/2101.02919)
• HRTF support
• Directional microphone capsules support

Citation

If you refer to any aspect of this work, please cite the following paper:

View citation

@inproceedings{cheston2025audiblelight,
    title={AudibleLight (RC): A Controllable, End-to-End API for Soundscape Synthesis Across Ray-Traced & Real-World Measured Acoustics}, 
    author={Cheston, Huw and Stepien, Adrian, and Azcarreta, Juan and Roman, Adrian S. and Chen, Chuyang and Bilen, Çağdaş and Roman, Iran R.},
    year={2025},
    booktitle={DMRN+ 20: Digital Music Research Network One-Day Workshop 2025}
}