Acoular turns microphone array recordings into acoustic source maps

What acoustic source mapping actually produces

Acoular is a Python module for acoustic beamforming, distributed under the BSD 3-clause license, and it is aimed at, though not limited to, applications in acoustic testing.

The task it performs is specific. Multichannel data recorded by microphone arrays can be processed and analysed to generate mappings of sound source distributions. The README calls these maps acoustic photographs, and they are used to locate sources of interest and to characterise them using their spectra.

That is a different job from locating a single source in a room, which is what a beamformer with a known geometry can do cleanly, and a different job again from noise mapping, where you integrate over a long measurement to build a sound pressure level grid. Source mapping aims at a picture of where energy is coming from in a band of frequency, at a resolution fine enough to pick out individual sources in a product or in a wind tunnel model, and the method you choose determines how well separated those sources appear.

The audience is stated plainly: engineers and researchers in acoustics, and the repository is maintained by a named group at the Technical University of Berlin, with maintainers including Adam Kujawski, Art Pelling, Ennes Sarradj, Gert Herold, Mikolaj Czuchaj and Simon Jekosch. The project publishes a paper for academic use, a Python framework for microphone array data processing in Applied Acoustics, and a Zenodo software DOI for citation.

The library is also honest about its centre of gravity. It is a beamforming library that happens to have a broad method catalogue, not a general purpose audio toolkit.

The method catalogue and what each family assumes

The highlights list in the README is organised by algorithm family, and reading it as a taxonomy tells you most of what you need to know about the library.

The frequency domain beamforming family covers delay and sum, Capon which is adaptive, MUSIC, and functional and eigenvalue beamforming. These are the classical array processing methods, and they differ in how they treat coherent sources, which matters because two sources at the same frequency in the same direction produce signals that a plain delay and sum beamformer cannot separate, and MUSIC is the one that will tell you there are two of them.

The deconvolution family is the more interesting one for acoustic testing. It includes DAMAS, DAMAS+, Clean, CleanSC and gridless orthogonal deconvolution. Deconvolution is where source mapping gets its name, because a conventional beamforming map shows the response of the array smeared by its own directivity, and deconvolution algorithms try to remove that so the map reads as an actual source distribution. The DAMAS family and the Clean family are the standard tools here, and the gridless variant addresses the fact that a deconvolution on a fixed grid is a constrained optimisation with an arbitrary discretisation baked in.

The inverse methods family covers CMF for covariance matrix fitting, general inverse beamforming and SODIX, and these are the most demanding of the three, with the strongest assumptions and the most to gain when those assumptions hold.

In the time domain, the list is much shorter: delay and sum beamforming and CleanT. The reason is structural, since time domain processing does not have the frequency domain's separation of the spatial and spectral parts.

The mapping grid works in 1D, 2D and 3D for all methods, which is what makes the library usable across very different problems, from a planar array in a 2D scan to a 3D grid for wind tunnel work.

Background flow, rotating sources and moving sources

Three extensions to the standard formulation are listed as separate highlights, and each of them addresses a case where textbook beamforming gives you the wrong picture.

Arbitrary stationary background flow can be considered for all methods. A uniform flow across the array, which is what you get in a wind tunnel or in front of a moving vehicle, is not the quiescent medium the steering vector assumes. Without accounting for it the source map is displaced, and with a strong enough flow it is displaced by an amount that makes the map useless. Being able to consider arbitrary stationary flow for every method, rather than only for some, is a meaningful piece of the library's value.

Frequency domain methods for rotating sources work via virtual array rotation for arbitrary arrays. A rotating source, such as an electric motor or a fan, is smeared over the measurement because its direction changes during the averaging, and the standard fix is to compensate the steering vectors for the rotation, which is a data problem rather than an algorithm problem and therefore applies across the frequency domain family.

All time domain methods can identify moving sources with arbitrary trajectory. The time domain methods do not rely on stationarity in the way the frequency domain ones do, so a source that moves during the measurement can still be located, provided you know the trajectory.

That last point deserves emphasis for anyone new to array acoustics. A stationary source that moves a little during a long averaging window also produces a smeared map, and the standard advice is to keep the averaging time short, which trades away statistical robustness. The trajectory-aware time domain methods give you another way out of that trade.

Caching and lazy evaluation are the practical difference

Two implementation details in the highlights list are what separate Acoular from a collection of scripts, and both are about how a long analysis session behaves.

The first is intelligent and transparent caching. Computed results are automatically saved and loaded on the next run, to avoid unnecessary re-computation. In acoustic testing this is not a nicety. A single source map at fine resolution across a wide frequency range can take a long time, and the usual workflow is to change one parameter and look at the result again, which is exactly the case where recomputing everything is most wasteful. The word transparent in the README means you get the caching without having to manage cache keys yourself, and the caching is described as intelligent, which suggests the library works out what has actually changed rather than invalidating everything.

The second is lazy evaluation. While processing blocks are set up at any time, expensive computations are only performed when needed. The example in the README shows the mechanism in comments, where the PowerSpectra object is constructed with a source, a block size and a window, and the comment says the actual computation, covering data intake, FFT, Welch cross spectral matrix and beamforming, starts later when a result is requested. So building the pipeline of objects is cheap, and the work happens when you ask for a number.

The third performance feature is efficient and parallel multithreaded computation with Numba for most algorithms. Numba compiles the inner loops of the numerical kernels, which for beamforming is where the time goes, and the parallelism is what makes a fine grid over a wide frequency range tractable on a workstation.

The signal processing layer is similarly broad, with n-th octave band filters, fast, slow and impulse weighting, A, C and Z weighting, a filter bank and linear phase filters. Third octave bands are the unit of the beamforming example, so the band filtering is directly usable.

Installing from PyPI or conda

Acoular can be installed from PyPI, and the README recommends using a virtual environment. Inside the environment you run:

    pip install acoular

The second option is conda, again into a dedicated environment, which the README also recommends:

    conda install -c acoular acoular

The pyproject.toml gives the constraints that matter. The package requires Python 3.11 or newer and below 3.15, with classifiers for 3.11 through 3.14. The runtime dependencies are numba, numpy, scikit-learn, scipy, tables and traits, and scipy is pinned with a version floor of 1.16.1 for Python versions above 3.10.

The tables dependency is the one to understand. It is the PyTables package, and it is what the .h5 file format in the examples depends on, so the ability to store large multichannel recordings in a compact, chunked, compressed format is part of the design rather than an optional extra. The traits dependency is what gives the library its configuration style, where processing objects are configured through declared traits rather than through constructor arguments alone.

There is an optional extra named full, which adds matplotlib, pylops and sounddevice. Those are the plotting and interactive elements, and the README's own example imports matplotlib, so the extra is what makes the documented example run as written.

The project is on PyPI with version and Python badges, and the documentation site is organised into a getting started section, a user guide, an API reference and a gallery of auto examples, which is a good structure to browse if you are deciding whether the library covers your problem.

The worked example shows the object graph you write

The README's example reads data from 64 microphone channels and computes a beamforming map for the 8kHz third octave band. It is worth reading as a whole because it shows the shape of every Acoular program.

from pathlib import Path

import acoular as ac
import matplotlib.pylab as plt

# this file contains the microphone coordinates
micgeofile = Path(ac.__file__).parent / 'xml' / 'array_64.xml'
# set up object managing the microphone coordinates
mg = ac.MicGeom(file=micgeofile)
# generate test data, in real life this would come from an array measurement
p = ac.demo.create_three_sources(mg, h5savefile='three_sources.h5')
# set up object managing the microphone array data (usually from measurement)
ts = ac.TimeSamples(file='three_sources.h5')
# set up object managing the cross spectral matrix computation
ps = ac.PowerSpectra(source=ts, block_size=128, window='Hanning')

Each object does one job and is connected to the next by being passed as a parameter, and that graph is the program. The microphone geometry comes from an XML file describing the array, the time samples come from a file, the power spectra are computed from the samples with a block size and a window, and a later object requests a result in a particular band.

The comment about generating test data is the practical hint. The demo call create_three_sources produces a synthetic three-source dataset, and the comment says that in real life this would come from an array measurement. So the same script runs against synthetic data while you develop, and against a real recording when you deploy it, and the only thing that changes is the source of the samples.

The final part of the example plots the map with imshow, with the extent taken from the grid object and the colour range clipped to the maximum minus 10, which is the standard way to display a source map when the dynamic range of the map is wide.

Where Acoular is the wrong tool

The boundaries come from the same place the strengths do, and it is worth being explicit about them.

The first is that Acoular needs an array with known geometry. The microphone positions are an input, not an output, and the whole computation depends on them being right. A single microphone, or a pair used for intensity measurements, is outside what this library is for, and if your measurement setup does not give you reliable positions for every channel, you cannot use the results regardless of how good the algorithm is.

The second is the choice of algorithm relative to the source. Conventional beamforming resolves two sources at the same frequency in different directions; it does not resolve two coherent sources, and the deconvolution family exists precisely because the naive map is a smeared version of the truth. If you are hunting for a single dominant source in a band, delay and sum is fast and adequate. If you are trying to find how many broadband sources there are, or to separate sources that are close together, you need MUSIC or the inverse methods, and you need to know their assumptions. The README lists the methods but does not choose for you, which is correct and also means the burden is on the user.

The third is that it is a library, not an application. There is no GUI for acquisition, array control or inspection. If your workflow needs to drive a measurement rig, trigger a scan and produce a report without writing Python, this is the wrong layer, and you would be writing the glue yourself.

The alternative approach is worth naming for contrast. Doing beamforming in a general numerical environment, with scipy and your own array handling, is entirely possible, and for a one-off measurement of a single source it may be less work than learning this API. The difference in approach is that Acoular supplies the things that are tedious to get right: consistent steering vector construction, the standard environment assumptions, the deconvolution implementations, the band filtering, and the caching and lazy evaluation that make parameter studies bearable. If you are doing a series of measurements and comparing methods, that framework is what you are buying, and the citation and documentation around it are part of the package.

Editorial conclusion

Adopt Acoular if you are doing acoustic testing with a microphone array and want a documented, cited, scriptable pipeline from raw multichannel measurements to source maps and spectra, since it covers beamforming, deconvolution and inverse methods in one consistent API with caching and lazy evaluation built in. Do not adopt it for general audio processing or for a single microphone, since the whole design assumes an array with known geometry, and do not expect a graphical front end, since it is a Python module driven from scripts or notebooks. Verify first that your Python version falls in the supported range of 3.11 to 3.14, that the microphone geometry file matches your array, that the algorithm you choose suits your array and the kind of source you are hunting, and that you read the documentation for the method rather than the summary, since delay and sum, Capon, MUSIC and the deconvolution family have quite different assumptions about coherent sources.

Frequently asked questions

Official sources

1. acoular/acoular on GitHub
2. License: BSD-3-Clause
3. Project website
4. README
5. Releases