acoustic_spaces¶
Open-source room acoustics simulator and auralisation toolkit, in the spirit of CATT-Acoustic and ODEON: load a 3D model of a space, place sources and listeners, compute impulse responses, and listen to the result in binaural, Ambisonics or loudspeaker formats.

Status: 4.2 (see the roadmap and the known issues).
What it does¶
Rooms from CAD and BIM models (OBJ, DXF, glTF, STL, IFC, Collada, SketchUp), from their dimensions or from a floor plan, with a material database and the material libraries of CATT-Acoustic and ODEON, walls and doors between rooms, audience seating, and directional, line, surface and array sources; a leak finder shows where a model is open: scene files.
Simulation, in octave or third-octave bands: ray-traced early reflections with edge diffraction, added in pressure at low frequencies, a stochastic late tail and, for the lowest bands, a wave solver, both on the CPU or a GPU; ISO 3382-1 parameters with their standard errors, the STI and echo criteria for every source and listener, and the parameters’ uncertainty from the materials’ absorption and the rays by Monte Carlo (GUM Supplement 1): simulation, materials’ uncertainty.
Outdoors: the ground and its impedance, terrain, buildings from a map, barriers and trees, wind, temperature and turbulence, behind barriers and buildings too; road vehicles by CNOSSOS-EU, trains and trams by Schall 03, construction plant from Defra’s database, helicopters from their rotors, aircraft by ECAC Doc 29, ground-borne vibration by the US FTA’s manual and sound through a closed window by EN ISO 12354-3: outdoor scenes.
Coverage maps of the parameters and of the speech transmission index over the audience: coverage maps.
Listening: impulse responses in mono, binaural, Ambisonics (AmbiX) and loudspeaker formats, or through a listener’s microphone (first-order patterns, XY, Blumlein and MS pairs), as WAV files; dry recordings run through them offline or in real time on the sound card, head-tracked on headphones, or heard along a walk through the room: spatial audio and listening.
Demos, binaural for headphones: an orchestra in the concert hall, a choir and an organ in the church, a band in the stadium and across a lake, a walk through the gallery, road vehicles with sirens and horns, trains and a tram passing by, road works in a street, a helicopter over a meadow and over the stadium, and a jet taking off and landing; any scene makes a demo of its own: demos, and videos in one playlist.
Measuring real rooms with sine sweeps, comparing them with their model in just noticeable differences, and fitting the model’s absorption to them: measurements.
A graphical editor that does all of this in one window, starting from the bundled example rooms; reflection paths and sound particles in 3D, animated and exported to Blender: graphical editor.
Validation against theory, against pyroomacoustics and against measured rooms, with the numbers and the scripts to reproduce them: the validation report says how far the results can be trusted, and its known issues what is still wrong.
Install¶
pip install acoustic-spaces # simulation, rendering and the command line
pip install "acoustic-spaces[viz,gui]" # with the 3D view and the graphical editor
pip install "acoustic-spaces[viz,gui,measure,sofa,gpu,ifc,sketchup]" # every optional part
What each extra in brackets adds is listed in Getting started.
PyPI and every GitHub release have wheels for Linux (x86-64), macOS (Apple silicon and Intel) and Windows (x86-64), CPython 3.10 to 3.14; elsewhere pip builds the package from source, which needs a C++17 compiler. From a source checkout, with uv, a C++17 compiler and CMake:
git clone https://github.com/naelolaiz/acoustic-spaces
cd acoustic-spaces
uv sync --extra viz --extra gui
Getting started has the same with pip and a tour of the command line and the Python API.
Quick start¶
acoustic-spaces examples # the example rooms
acoustic-spaces simulate examples/shoebox/scene.yaml --out results --plot
acoustic-spaces view examples/gallery/scene.yaml --paths --listener "round the corner"
acoustic-spaces # alone: the graphical editor
from acoustic_spaces import Room, simulate
room = Room.from_yaml("examples/shoebox/scene.yaml")
response = simulate(room)["talker", "seat-a"]
print(response.parameters().table())
Documentation¶
User manual: a path through these pages, from a first simulation to the advanced workflows, with an example to try at each step.
Getting started: installing, the command line and the Python API.
Graphical editor: editing scenes, drawing rooms, results and listening, export to Blender.
Example scenes: the bundled rooms and what each shows.
Scene files: geometry, materials, walls and openings, audience seating, sources and directivity.
Outdoor scenes: the ground and the open sky, terrain, buildings, barriers and trees, wind and turbulence, passing vehicles, aircraft and vibration through the ground.
Simulation: early reflections, the late part, scattering, frequency bands, edge diffraction, low frequencies and the wave solver.
Coverage maps: parameters and the STI over the audience area.
Spatial audio and listening: binaural, Ambisonics and loudspeaker outputs, convolution, real-time playback and head tracking.
Demos: what each demo plays, its recordings and its options.
Measurements: measuring impulse responses, comparing them with simulations, and fitting materials to them.
Running on another computer: a scene and its files in one pack, and a container image to run it on a GPU server or a cloud job.
Validation report: how the results compare with theory, another simulator and measured rooms.
The same pages, with an API reference generated from the docstrings, are online at naelolaiz.github.io/acoustic-spaces, and the user manual and the reference make one PDF, also attached to every release (to build either, see CONTRIBUTING.md).
Design in one paragraph¶
Python is the main language; a C++ core (bound with nanobind) carries the parts that must be fast: the ray tracer, the wave solver and the real-time convolver. Every simulation runs in two stages with selectable methods: deterministic ray tracing (or image sources) for the early reflections and stochastic processing for the late reverberation. Both write a format-independent directional reflectogram, from which binaural, Ambisonics and loudspeaker impulse responses are encoded, so one simulation serves every output format. For the lowest bands a wave solver can take over; it records the pressure and its gradient, so the bass keeps its direction (to first order) in every format.
Contributing¶
Pull requests are welcome.
CONTRIBUTING.md
covers the development setup, the checks to run before opening one (ruff, mypy, the
translation catalogs and pytest -W error), the documentation, the validation scripts
and releases. CI runs the tests on all three platforms, and ruff and mypy on Linux.
License¶
GPL-3.0-or-later. See LICENSE.
The built-in material table comes from
pyroomacoustics (MIT, see
materials/data/LICENSE-pyroomacoustics.txt).
That table does not cite a source for most entries; check values that matter
against manufacturer data or a measured database.