# Pyroomacoustics for Indoor Audio Simulation and Beamforming

> Pyroomacoustics is a Python framework for simulating sound propagation in 2D and 3D rooms, generating room impulse responses, and prototyping array-processing algorithms. It is aimed at researchers and engineers working with beamforming, direction finding, adaptive filtering, source separation, and denoising.

**LCAV/pyroomacoustics** — Pyroomacoustics is a package for audio signal processing for indoor applications. It was developed as a fast prototyping platform for beamforming algorithms in indoor scenarios.

- Repository: https://github.com/LCAV/pyroomacoustics
- Website: https://pyroomacoustics.readthedocs.io
- Stars: 1,993 · Forks: 501
- Language: Python
- License: MIT
- Published: 2026-10-16 · Updated: 2026-10-16 · Language: en
- Canonical page: https://hysenlabs.com/projects/lcav-pyroomacoustics

## Pyroomacoustics Targets Indoor Array-Processing Experiments

Pyroomacoustics solves a specific engineering problem: reproducing the acoustic conditions around microphones and sound sources without recording every experiment in a physical room. It is for engineers, researchers, and Python developers who need to test audio algorithms in indoor scenarios before deployment. The package describes itself as a rapid development and testing framework for audio array processing, with particular emphasis on beamforming in rooms.

The supported workflow covers both simulation and algorithm evaluation. A project can define a room, place one or more sources and microphone arrays inside it, compute room impulse responses, and then process either synthetic signals or real audio samples. The same environment includes reference implementations for STFT, beamforming, direction-of-arrival estimation, adaptive filtering, blind source separation, and single-channel denoising. This makes the package useful when an algorithm needs repeatable acoustic conditions or when comparison across several propagation models is part of the task.

The intended users are not limited to acoustic simulation specialists. The object-oriented interface is designed to let a developer assemble an experiment from recognizable components. A microphone array can be connected to a beamformer, a room can compute the response between a source and receiver, and the resulting signal path can feed an STFT engine. The practical benefit is reduced implementation overhead during the evaluation stage. The package does not claim to replace hardware measurements, calibrated acoustic modeling, or production audio infrastructure.

## Image Sources, Ray Tracing, and Python Experiment Objects

The central propagation mechanism is a room impulse response generator based on the image source model. The documentation states that this model supports convex and non-convex rooms in both 2D and 3D. Image sources represent reflections generated by room boundaries, allowing the package to calculate propagation paths between sources and receivers rather than requiring every reflection to be recorded.

The core image source model and ray tracing modules are written in C++. That implementation choice matters for engineers who need repeated simulations involving multiple sources, receivers, or rooms, because the repository describes it as providing faster propagation computation than a purely Python implementation would. The Python layer exposes these mechanisms through object-oriented classes. The documented example creates a room object, adds a microphone array and a sound source, computes the RIR, and then passes microphone signals through a beamformer.

The processing path is modular. The `Room` class can compute the response between sources and receivers, and it can also process sound samples emitted by sources to simulate propagation toward microphones. An STFT engine then exposes short-time Fourier processing at the microphone inputs, allowing beamforming and other array algorithms to operate on the simulated signals. This separation is useful when the experiment needs to change the room geometry, source placement, or receiver configuration while keeping the processing algorithm conceptually separate.

There is a boundary to the claims. The README describes an image source model and ray tracing, but it does not specify every material, frequency-dependent absorption, diffraction, or measurement-calibration detail in the excerpt. Engineers should therefore inspect the documentation and source implementation for the exact assumptions behind a particular room model.

## Reference Algorithms Cover the Audio Processing Chain

Pyroomacoustics includes reference implementations rather than only a propagation simulator. The documented algorithm categories are short-time Fourier transforms, beamforming, direction-of-arrival finding, adaptive filtering, blind source separation, and single-channel denoising.

Within the STFT category, the package provides block and online implementations. Beamforming support includes delay-and-sum examples, while the adaptive filtering examples include NLMS and RLS. Blind source separation references include AuxIVA, Trinicon, ILRMA, SparseAuxIVA, FastMNMF, and FastMNMF2. Single-channel denoising includes Spectral Subtraction, Subspace, and Iterative Wiener methods.

These implementations have two distinct uses. First, they provide a baseline against which a new algorithm can be compared. Second, they can be used as components in an indoor experiment. For example, a simulated or recorded multichannel signal can enter an STFT implementation, pass through a beamformer, and produce a processed output that can be inspected with the package's example code. The repository includes examples for delay-and-sum beamforming, time-domain beamforming, adaptive filters, BSS, DOA algorithms, spectral subtraction, subspace processing, and Wiener filtering.

The README says that optional tuning parameters are provided and that default values generally aim for reasonable results. That is a convenience, not a guarantee of production quality. Algorithm parameters still need to be selected for the array geometry, signal type, room response, and evaluation criteria. A reference implementation is most useful when its assumptions and interfaces are understood before it becomes the basis of a deployed system.

## Installation and a First Room Simulation

The README gives the primary installation command for Python users. The project supports Python 3.9 through Python 3.14 according to `pyproject.toml`, and its runtime dependencies include Cython, NumPy, and SciPy. A release install should use the package name shown by the project.

The following command installs Pyroomacoustics into the current Python environment. The reader should confirm that the installation completes in the intended environment and that the package can be imported afterward.

```bash
pip install pyroomacoustics
```

The README also points to a Cookiecutter template for generating a working 2D or 3D simulation script. Cookiecutter must be installed first if it is not already available.

```bash
pip install cookiecutter
cookiecutter gh:fakufaku/cookiecutter-pyroomacoustics-sim
```

After the template is created, the README instructs the user to run the generated script. The placeholder script name is part of the documented workflow, so it must be replaced with the actual file produced by Cookiecutter.

```bash
python <chosen_script_name>.py
```

For users who prefer a container, the repository includes a minimal `Dockerfile`. Its documented build and entry commands use the repository as the build context. The file notes that the container may require increased memory for building the C++ code.

```bash
docker build -t pyroom_container .
```

The container is then started with an interactive Bash shell.

```bash
docker run -it pyroom_container:latest /bin/bash
```

A first practical use should begin with a small room, one source, and a small microphone array. The package's own README describes this delay-and-sum scenario. The examples directory also contains `beamforming_delay_and_sum.py` and `beamforming_time_domain.py`, which are more concrete starting points than building every component from scratch.

## Datasets and Audio I/O Support Common Experiment Paths

Pyroomacoustics includes wrappers for several speech corpora to reduce the setup work around experimental data. The README names CMU ARCTIC, TIMIT, and the Google Speech Commands Dataset. The corresponding examples are present in the repository as `cmu_arctic_corpus.py`, `datasets.py`, and `google_speech_commands_corpus.py`.

These wrappers do not replace a dataset's access or usage requirements. They provide a project-level way to load and sort through supported speech corpora. For example, a developer can use a corpus as input to an adaptive-filtering, BSS, or denoising example instead of manually arranging every file before testing the algorithm.

The package's broader audio stack also appears in `requirements.txt`, which lists `matplotlib`, `sounddevice`, `samplerate`, `mir_eval`, `python-sofa`, and `soxr` alongside the core build dependencies. The runtime package metadata in `pyproject.toml` identifies Cython, NumPy, and SciPy as dependencies, while the example requirements add tools for plotting, audio input and output, resampling, evaluation, and SOFA data. This distinction matters during installation: a clean environment that installs the package may not include every package needed by a particular example.

The repository also includes `input_samples`, `output_samples`, and `directivities` under `examples`. Those directories indicate that the examples are designed to run with or inspect concrete audio material. They do not establish a guarantee that every example works in every operating system or audio backend. A developer selecting a dataset-driven experiment should check the relevant example and its dependencies first.

## Pyroomacoustics Is a Prototyping Framework, Not a Complete Audio Product

The package is a good fit for researchers who need repeatable indoor audio scenarios, especially when the alternative is building an image source model, microphone geometry, beamformer, and evaluation pipeline independently. It is also useful for comparing algorithm implementations under a common simulation environment. Its Python interface and example scripts reduce the amount of boilerplate required to connect these pieces.

It is the wrong tool when the requirement is a complete production audio application rather than an experiment framework. Pyroomacoustics does not present itself as a microphone driver, live conferencing stack, hardware control system, or deployment framework. The `sounddevice` dependency supports audio-related examples, but dependency availability should not be confused with a complete real-time service.

It is also a poor substitute for calibrated room measurement. A simulation depends on the geometry and assumptions supplied by the user. The README identifies the image source model and ray tracing as the core propagation components, but it does not establish that arbitrary real rooms, furnishings, complex materials, or diffraction effects will be reproduced accurately. An algorithm tested against a synthetic response can still behave differently in a real room.

The build introduces another constraint. `setup.py` uses CMake for extensions and explicitly checks that CMake is installed. `pyproject.toml` also requires Cython, cmake, setuptools, and setuptools-scm in the build environment. Installing from a wheel may avoid some source-build work, while building from source requires the toolchain described by the project.

## A Practical Alternative Is a Separate Algorithm-and-Array Pipeline

A real alternative is to build the propagation model and audio-processing stack separately. For example, an application could use a dedicated room-acoustics simulator to generate impulse responses and a separate Python audio stack to perform STFT, beamforming, and adaptive filtering. That approach requires more assembly work, but it gives the engineer explicit control over each dependency and data format.

Pyroomacoustics takes a different approach by placing the simulator, Python experiment objects, and reference algorithms in one package. Its object-oriented model lets a room own or relate to sources and receivers while the processing classes consume the resulting signals. That integrated path is convenient when the goal is rapid comparison of algorithms against one or more room scenarios.

The trade-off is coupling and scope. A separate pipeline can be easier to adapt when the acoustic simulator, microphone array interface, or production signal path needs to be replaced. Pyroomacoustics is more appropriate when the simulation environment and the algorithm evaluation are intended to work together. It is less attractive if you need a minimal library with only one algorithm, or if your production architecture cannot accommodate its simulation and experimentation dependencies.

The repository includes a `CHANGELOG.rst`, a `CONTRIBUTING.rst`, tests, examples, and a default branch named `master`. These files provide concrete places to inspect release changes, development conventions, and expected behavior. The project is not archived, and the last push was on 2026-07-17. The most recent listed release is v0.10.1 from 2026-05-01, so upgrades should be checked against the changelog rather than assumed to be API-compatible.

## Pyroomacoustics License and Upgrade Boundaries

Pyroomacoustics is distributed under the MIT license. The package metadata identifies the license through the repository's `LICENSE` file. That is a permissive licensing choice, but it does not answer questions about the licenses of optional dependencies, datasets, audio files, or external components. Anyone incorporating package code or bundled examples into a product should review the relevant license files rather than treating the top-level identifier as a complete dependency review.

The project requires Python 3.9 or newer according to `pyproject.toml`, with classifiers covering Python 3.9 through 3.14. The declared package dependencies are Cython, NumPy with version 1.13.0 or newer, and SciPy with version 0.18.0 or newer. The broader requirements file includes additional packages used by examples or related functionality. This means an upgrade can involve both Python compatibility and the native extension build toolchain.

The repository contains a `CMakeLists.txt`, `setup.py`, C++ source under the package structure, and a `Dockerfile`. The build configuration indicates that compiling extensions is part of the project design. Users who cannot install a prebuilt wheel should expect to provide a working compiler environment and CMake. The Docker example also explicitly warns that the build may need 4 GB of memory, while noting that less may sometimes suffice.

Before changing a pinned environment, inspect `CHANGELOG.rst`, the release metadata, and the documentation for the relevant version. The listed releases show v0.7.7 and v0.7.6 in September 2024, followed by v0.10.1 in May 2026. The version gap is a reason to review migration notes, not evidence that every older example remains compatible.

## Conclusion

Adopt Pyroomacoustics when you need a Python environment for indoor audio experiments, synthetic room impulse responses, or reference audio-processing implementations. Do not treat it as a calibrated prediction of every real room without checking the geometry, material assumptions, and algorithm configuration. Verify first that your Python version is supported, that the C++ extensions build, and that your simulation scenario reflects the propagation effects you need.

## FAQ

### How do I install Pyroomacoustics?

The README's primary installation command is `pip install pyroomacoustics`. The project metadata requires Python 3.9 or newer and lists Cython, NumPy, and SciPy as dependencies.

### Can Pyroomacoustics simulate both 2D and 3D rooms?

Yes. The README states that the image source model supports convex and non-convex rooms in 2D and 3D, with the core propagation modules written in C++.

### Which audio-processing algorithms does Pyroomacoustics include?

The README lists block and online STFT, beamforming, direction-of-arrival finding, NLMS and RLS adaptive filtering, several blind source separation methods, and Spectral Subtraction, Subspace, and Iterative Wiener denoising.

### Does Pyroomacoustics replace real room measurements?

The project documentation describes a simulation and prototyping framework, not a calibrated measurement system. The README does not claim that a synthetic room response will reproduce every real-room effect, so geometry and acoustic assumptions should be checked against the intended use.

### What is required to build Pyroomacoustics from source?

The build configuration requires CMake for the extensions, while `pyproject.toml` lists setuptools, setuptools-scm, Cython, cmake, wheel, and NumPy as build requirements. The README also provides a Dockerfile example for containerized installation.

### Which speech datasets can the dataset wrappers load?

The README names CMU ARCTIC, TIMIT, and the Google Speech Commands Dataset. It also links to dataset examples for these corpora, but access and usage terms remain properties of the datasets themselves.

## Sources

- [LCAV/pyroomacoustics on GitHub](https://github.com/LCAV/pyroomacoustics)
- [License: MIT](https://github.com/LCAV/pyroomacoustics/blob/master/LICENSE)
- [Project website](https://pyroomacoustics.readthedocs.io)
- [README](https://github.com/LCAV/pyroomacoustics/blob/master/README.md)
- [Releases](https://github.com/LCAV/pyroomacoustics/releases)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/lcav-pyroomacoustics