Getting started

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

PyPI has wheels with the compiled core inside 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. Every GitHub release has the same wheels, to pip install with the extras after the file name, such as pip install "acoustic_spaces-4.2.1-cp312-cp312-win_amd64.whl[viz,gui]". Between releases, install from source.

Extras

The extras in brackets add the optional parts:

Extra

Adds

For

viz

matplotlib, PyVista, imageio, imageio-ffmpeg

plots of responses and coverage maps (--plot), the 3D view (view, --screenshot), sound particles and walks as GIF or MP4 videos

gui

PySide6, pyvistaqt, PyVista, matplotlib

the graphical editor

measure

sounddevice

the sound card: measuring a room with sweeps (measure, devices) and real-time playback (play, the editor’s Listen)

sofa

h5py

HRTFs and source directivities from SOFA files

gpu

wgpu

the late stage’s rays, the wave solver and tune on a GPU, through Vulkan, Metal or Direct3D 12

ifc

IfcOpenShell, mapbox-earcut

BIM models: IFC files

sketchup

openskp

SketchUp files (experimental)

test

pytest, h5py

running the tests

dev

pytest, h5py, ruff, mypy, types-PyYAML

the tests, the linter and the type checks (CONTRIBUTING.md)

docs

Sphinx, Furo, MyST-Parser, pypdf

building this documentation and its PDF

A command or function that needs an extra that is not installed says which one to install.

The documentation (these pages, the validation report and an API reference generated from the docstrings) builds with Sphinx; see CONTRIBUTING.md.

Install from source

Requirements: Python 3.10+, a C++17 compiler and CMake 3.18+.

git clone https://github.com/naelolaiz/acoustic-spaces
cd acoustic-spaces

With uv, uv sync builds the package into .venv together with the dev tools (pytest, h5py, ruff, mypy), and --extra adds the extras:

uv sync --extra viz --extra gui        # the 3D view and the editor
uv sync --all-extras                   # every extra in the table, docs included

uv sync installs exactly what it is asked for, so name every extra each time. It rebuilds the compiled core when the C++ sources change.

With pip, in a virtual environment, the extras go in brackets after the .:

python -m pip install -e ".[dev,viz,gui]"   # the development tools, the 3D view and the editor

Check the installation and look at the example scene. The commands run in the environment you installed into: activate it (source .venv/bin/activate, or .venv\Scripts\activate on Windows), or with uv put uv run in front of each.

acoustic-spaces info
acoustic-spaces validate examples/shoebox/scene.yaml   # errors exit with status 1
acoustic-spaces validate examples/leaky_classroom/scene.yaml --strict  # warnings too
acoustic-spaces validate examples/leaky_classroom/scene.yaml --leaks  # where rays escape
acoustic-spaces inspect examples/shoebox/scene.yaml    # geometry, materials, RT estimates
acoustic-spaces view examples/shoebox/scene.yaml       # 3D window; --screenshot out.png
acoustic-spaces view examples/shoebox/scene.yaml --paths --max-order 2  # reflection paths
acoustic-spaces view examples/gallery/scene.yaml --paths --listener "round the corner"  # diffraction
acoustic-spaces animate examples/lecture_hall/scene.yaml               # sound particles
acoustic-spaces export examples/concert_hall/scene.yaml hall.glb --paths --particles  # Blender
acoustic-spaces materials carpet                       # search the material database
acoustic-spaces directivity hypercardioid --plot polar.png  # a source directivity
acoustic-spaces simulate examples/shoebox/scene.yaml --out results --plot
acoustic-spaces map examples/lecture_hall/scene.yaml --plot sti.png --parameter sti
acoustic-spaces walkthrough examples/gallery/scene.yaml guide=speech.wav --out walk.wav  # a visitor walks
acoustic-spaces demo my_room/scene.yaml                # each source plays its signal: a video of every listener
acoustic-spaces examples                               # the bundled rooms, and where they are
acoustic-spaces hrtf                                   # free HRTF sets to download, with their licences
acoustic-spaces pack examples/hillside/scene.yaml hillside.zip  # one zip to run elsewhere
acoustic-spaces tune --default auto                    # with the gpu extra: run on the fastest device here
python -m pytest                                       # the test suite

pack puts a scene and every file it names in one zip, which every command that reads a scene takes in its place, to run on a server or a cloud job: see Running on another computer.

Errors start with error: and warnings with warning:, in red and yellow in a terminal (NO_COLOR=1 turns colours off).

animate shows sound particles leaving a source and spreading through the room, each reflecting off the walls (turned from the specular direction by as much as the surface scatters; see Scattering) and losing the absorbed share of its energy at every hit, coloured by level or by reflection order. It opens a window with a time slider, or saves a GIF (--out particles.gif) or an MP4 video (--out particles.mp4).

Sound particles leaving the soloist of the concert hall example, coloured by level at 1 kHz, over the first 90 ms

simulate writes impulse responses for every source and listener in each format the scene’s outputs list (results/talker__seat-a.wav in mono, .binaural.wav, .ambix3.wav, .5.0.wav and so on, 32-bit float, scaled by one gain to a -1 dBFS peak with --normalize, ir_gain in parameters.json; names that would give one file name, as A/B and A_B do, get -2, -3… after the later ones), parameters.json with the room acoustic parameters of every response per octave band, its STI and its echo criteria, and with --plot an echogram, decay curves and a map of arrival directions as PNG. The files go into the folder once all of them are written, parameters.json last, so a run that cannot write them all (a full disk, say) leaves the folder as it was; the editor’s Export does the same. A file where the folder should be stops simulate before its run. Files of an earlier run whose names this one does not write stay in the folder. --output ambisonics:3 (repeatable) picks formats on the command line. It prints the parameters as it goes:

talker -> seat-a: direct sound at 11.7 ms, 63 early paths
                 63 Hz  125 Hz  250 Hz  500 Hz   1 kHz   2 kHz   4 kHz   8 kHz
EDT (s)          0.680   0.519   0.703   0.764   0.921   1.004   0.942   0.605
T20 (s)          0.712   0.781   0.876   1.173   1.353   1.369   1.169   0.764
T30 (s)          0.708   0.841   0.925   1.292   1.378   1.359   1.174   0.778
C50 (dB)           2.7     5.8     2.8     3.1     3.1     2.7     3.0     5.3
C80 (dB)           6.1     8.7     6.1     6.1     5.7     5.3     5.6     8.6
D50              0.652   0.793   0.655   0.670   0.669   0.650   0.664   0.771
Ts (s)           0.049   0.037   0.050   0.052   0.056   0.058   0.054   0.036
G (dB)            22.0    24.1    20.6    19.8    18.5    17.8    17.0    15.6
LF               0.170   0.093   0.300   0.304   0.330   0.343   0.345   0.328
LFC              0.254   0.138   0.433   0.432   0.446   0.454   0.451   0.430
LJ (dB)           10.4    10.7     9.5     9.4     8.9     8.6     7.4     3.7
IACC_E           0.998   0.989   0.817   0.586   0.495   0.739   0.604   0.611
IACC_L           0.973   0.947   0.577   0.183   0.298   0.122   0.078   0.067
T30_X (s)        0.707   0.787   0.927   1.265   1.363   1.341   1.146   0.775
T30_Y (s)        0.708   0.952   0.940   1.341   1.398   1.372   1.209   0.784
T30_Z (s)        0.707   0.821   0.895   1.083   1.279   1.265   1.154   0.753
ξ_T20 (‰)          0.0     0.9     2.7     5.5     3.8     1.8     0.6     0.9
ξ_T30 (‰)          0.0     2.9     2.2     6.5     2.1     1.4     0.8     0.5
Curvature (%)     -0.6     7.7     5.7    10.1     1.9    -0.8     0.4     1.7
standard errors from 10 batches of rays: at most 1.58 JND from 125 Hz to 4 kHz (T30 at 500 Hz); more rays (simulation.late.rays) would change the parameters less from seed to seed
uncertainty from the absorption and the rays (10 batches), 400 draws: at most 5.23 JND from 125 Hz to 4 kHz (T20 at 1 kHz: u = 0.354 s (absorption 0.34, rays 0.097), 95 % within 0.678 to 1.71 s, 95 % at least 0.707 s and 95 % at most 1.67 s); built-in materials of unknown source taken at plus or minus 0.1 (simulation.uncertainty.presets): painted_concrete, carpet_on_concrete, acoustic_ceiling
SPL 60.0 dB(A) (u = 0.7, 95 % within 58.4 to 61.0, 95 % at most 60.8); per octave band, dB: 52.8 66.9 63.4 58.9 51.6 44.9 38.1 30.7
STI 0.66 (u = 0.041, 95 % within 0.63 to 0.74, 95 % at least 0.63), STIPA 0.66, echo criterion 0.65 for speech (echo above 1.0), 0.69 for music (echo above 1.8)

Unless the scene sets simulation.seed, its rays and the noise of its rendered late part are drawn anew on each run, so these numbers move from run to run: IACC most, as it is read from one rendered response, and the others about as much as the standard errors say.

With --plot, each response gets an echogram (the late energy per millisecond and the early paths by order) with the decay curves of every band, and a map of where the sound comes from:

Echogram and decay curves of a seat in the middle of the concert hall's stalls

Arrival directions at the same seat: early reflections by delay and level, and the late energy per direction

From 500 Hz up, T30 comes out two to more than four times the Sabine and Eyring estimates that inspect prints, and that is the room, not a fault. Its absorption sits on the ceiling and the carpet while the walls are hard and smooth (scattering 0.05), so sound running between the walls meets little absorption and dies away slowly. Sabine and Eyring assume a diffuse field, where sound meets every surface alike; inspect says when a room is far from that and adds the Arau-Puchades estimate, which allows for absorption that faces one way. With every surface fully diffusing, the same room decays in Eyring’s 0.37 s at 1 kHz; with every surface scattering 0.3, in about 0.53 s. The validation report checks both kinds of room.

From Python:

from acoustic_spaces import Room, simulate
from acoustic_spaces.audio import write_wav
from acoustic_spaces.engine import early_paths, trace_particles
from acoustic_spaces.spatial import Ambisonics, Binaural, Loudspeakers
from acoustic_spaces.viz import animate_particles, plot_directions, plot_response, show_room

room = Room.from_yaml("examples/shoebox/scene.yaml")
print(room.report.summary())
print(room.problems(), room.warnings())
print(room.reverberation_time("eyring"))  # per octave band, seconds
show_room(room, paths=early_paths(room, max_order=2))
animate_particles(room, trace_particles(room, duration=0.1), "particles.gif")

result = simulate(room)
response = result["talker", "seat-a"]
print(response.parameters().table())
write_wav("talker__seat-a.wav", response.impulse_response(48_000), 48_000)
plot_response(response, "talker__seat-a.png")

binaural = response.spatial_impulse_response(Binaural(), 48_000)  # (samples, 2)
ambix = response.spatial_impulse_response(Ambisonics(order=3), 48_000)  # 16 channels
surround = response.spatial_impulse_response(Loudspeakers.layout("5.0"), 48_000)
plot_directions(response, "talker__seat-a.directions.png")

Where the results go

A simulation gives one response for each source and listener in use, all side by side: none of them is the result until a mix or the editor’s results panel picks a listener. Sources and listeners left out of simulations (enabled: false) get none.

  • acoustic-spaces simulate scene.yaml --out DIR (--out has no default) writes every pair into DIR, as above: SOURCE__LISTENER.wav for the mono output, SOURCE__LISTENER.binaural.wav, .ambix3.wav, .5.0.wav… for the others, and parameters.json with the parameters of every pair. The stadium concert, with 19 sources and 12 listeners in use and a mono output, gives 228 WAV files; ls DIR/*__mix_position.wav lists one listener’s. A listener with a microphone (pattern) has its mono files picked up through it, which parameters.json names (microphone).

  • The editor’s Simulation > Run (F5) keeps the results in memory: the results panel shows one source and one listener at a time, picked above it or by selecting them in the scene. Export… there, or File > Export results…, writes them all into a folder you pick, as simulate does.

  • acoustic-spaces auralize DIR SOURCE=WAV... --out mix.wav mixes the sources as heard at one listener, which --listener names when the results have more than one; acoustic-spaces walkthrough --all --out walk.wav writes one file per listener, walk_LISTENER.wav.

  • acoustic-spaces demo scene.yaml (This scene in the editor’s Simulation > Run demo…) writes into demo/ beside the scene (--work elsewhere): the simulation in results/, one mix per listener in seats/ (moving/ when something walks), named LISTENER.binaural.wav, and tour.wav, the stills in stills/, thumbnail.png and tour.mp4, which visits every listener in use in the scene’s order (--listeners picks them). An example’s own demo writes its scene and simulation beside its script (the stadium’s scene_band.yaml and results_band/) and the rest into demo/ there (Demos).

  • The editor runs a demo in the open scene’s folder, where the command line runs it, but for the examples of an installed copy (opened from File > Open example) and a folder it cannot write: those run in a folder of the same name in ~/acoustic-spaces/ (This scene in its demo/), so that nothing goes among the package’s files, which an upgrade replaces. The Run demo window says where (Runs in …).

Language

The editor and the command line show their text in English, Spanish, Catalan, Italian, German or Dutch, following the computer’s language unless told otherwise:

  • View > Language in the editor picks one for this user, or System to follow the computer again. It applies from the next start of the editor and of the command line.

  • ACOUSTIC_SPACES_LANG=nl (or de, it, ca, es or en) in the environment sets it over both, for one shell or one script. In the editor, choose Nederlands for Dutch, Deutsch for German, Italiano for Italian or Català for Catalan.

acoustic-spaces info says which language is in use and what chose it. Scene files, command and option names and the files the commands write stay in English whatever the language, so scripts keep working. The editor writes numbers as the computer’s regional settings do (0,85 in Spain, 0.85 in Mexico) and reads them typed either way; the command line keeps the decimal point. The Spanish, Catalan, Italian, German and Dutch translations come in steps: the editor is translated, with its plots and the examples’ descriptions; the command line and the library’s messages (which the editor shows too, such as the room’s checks) come next (see the roadmap); text not yet translated shows in English. Translating explains how the catalogs work and the terms the translations use.