SofaMyRoom

SofaMyRoom is a fast, accurate, and flexible “shoebox” room acoustics simulator that supports both specular and diffuse reflections. The simulator extends the work released by Schimmel et al., called Roomsim, by adding the rendering of Binaural Room Impulse Responses (BRIR) using arbitrary Head Related Transfer Functions (HRTFs) stored with the AES Spatially Oriented Format for Acoustics (SOFA) file format. Moreover, SofaMyRoom can be launched directly from your console of choice.

The SOFA support is possible thanks to MySofa library (hereinafter referred as libmysofa) and it can export the results of the simulation to a WAVE file.

Thanks to the Virtual Acoustic Space Traveling (VAST) framework [1], we added the possibility to systematically generate labeled datasets to train and test machine learning algorithms.

For any question or request of help please write to: roberto(at)robaru(dot)com

Installing SofaMyRoom

This repository includes the binary files and, if in case of need, the CMake scripts allow a customized compilation. Only 64-bit platforms are supported. SofaMyRoom binaries are available for Windows 10, Ubuntu Linux 20.04 and MacOS Catalina.

Installation on Windows

No futher steps are required to run SofaMyRoom on Windows.

Installation on Ubuntu Linux

libmysofa requires the zlib library in order to work properly. To install it, open a terminal and enter the following command:

sudo apt-get install zlib1g

Installation on macOS

No further steps are required to run SofaMyRoom on macOS.

Usage

To use SofaMyRoom, type this command in a Command Prompt or a Terminal:

./sofamyroom setup.txt

setup.txt is the name of the text file containing all the SofaMyRoom setup parameters structure. A sample of it can be found in sampleroomsetup.txt.

Usage with MATLAB

A MEX-file for 64-bit MATLAB is available. To run it, type these commands in the Command Window:

setup = readsetup('sampleroomsetup.txt');
output = sofamyroom(setup);

Notes about the setup file

This file stores all the information needed by SofaMyRoom to perform the simulation.

Notes about the options

Besides those related to the simulation, there are two options related to the output file:

options.outputname = 'output';
options.mex_saveaswav  =  true; % only for MATLAB MEX

options.outputname is the first part of the name given to the output file that stores the result of the simulation. The name must not contain the extension of the file, because SofaMyRoom takes care of that. options.mex_saveaswav tells SofaMyRoom to export the results to a Windows WAVE (.wav) file (options.mex_saveaswav = true;) or to return a MATALB numerical array. Note that there is one WAVE file for every source-receiver couple.

Notes about the receiver

The format of the field receiver(<i>).description is the following:

'RECEIVER_ID PATH_TO_HRTF_FILE interp=interp_value norm=norm_value resampling=resampling_value'

RECEIVER_ID must be SOFA in order to read a .sofa file. PATH_TO_HRTF_FILE is the relative or absolute path to your .sofa file. The other values are:

  • interp: SofaMyRoom can look up the HRTF that is closest to the given coordinates or it can interpolate the neighboring HRTFs to obtain the desired HRTF. interp_value can be T[RUE], t[rue], 1 (interpolation is active), or F[ALSE], f[alse], 0 (interpolation is not performed). Words in square brackets are optional, SofaMyRoom just looks for the first character.

  • norm: SofaMyRoom can normalize HRTF data. norm_value behaves just like interp_value, described above.

  • resampling: SofaMyRoom can resample the HRTF data according to the sampling frequency defined in options.fs. resampling_value behaves just like interp_value and norm_value, described above.

All the options described above are optional. If not set, interpolation, normalization and resampling are not performed. Unrecognized options are skipped. If options are repeated, only the last one is used.

Examples

All the examples proposed below are valid:

'SOFA ./mySofaFile.sofa'
'SOFA ./mySofaFile.sofa interp=TRUE norm=0 resampling=t'
'SOFA ./mySofaFile.sofa interp=1 norm=f'
'SOFA ./mySofaFile.sofa resampling=0 norm=F interp=0'

Building SofaMyRoom

These instructions will guide you through the steps to build SofaMyRoom on your local machine. CMake is required.

Building on Windows

You can use CMake to generate a Visual Studio solution that can be used to build SofaMyRoom. Open a new Command Prompt window and type the following commands:

> cd build
> cmake ../src -G"Visual Studio 16 2019"

To know how to generate solutions for other versions of Visual Studio, type cmake --help.

Building on Ubuntu Linux

You can use CMake to generate a Makefile for SofaMyRoom. Open a new Terminal window and type the following commands:

cd build
cmake ../src -G"Unix Makefiles" -DCMAKE_BUILD_TYPE=BUILD_TYPE
make

CMAKE_BUILD_TYPE can be Debug, Release or Unittest. If CMAKE_BUILD_TYPE is not set, the default build type is Release. Before building the project, the following libraries may be needed:

sudo apt-get install libfftw3-dev
sudo apt-get install zlib1g-dev
sudo apt-get install libcunit1-dev

Building on MacOS

You can use CMake to generate a XCode project. Open a new Terminal window and type the following commands:

cd sofamyroom/build
cmake ../src -G"XCode"

The cunit library may be required. You can install it with a package manager for MacOS, i.e. Homebrew.

Building with MATLAB

You can use MATLAB to generate a MEX-file. Type the following command in the Command Window:

cd src
make

You can build the MEX-file in Debug mode. Type the following command:

make debug

You can also build it in Unittest mode, to check the validity of SofaMyRoom functions. Type the following command:

make test

Building the documentation

You can optionally build the documentation files from the source code. Documentation files are built using Doxygen, Sphinx and Breathe. First of all, you need to install all of the required software. Please refer to the installation guides of each software in order to know the steps to install them on your machine. For MS Windows, we recommend to use the package manager pip3 to install Sphinx and Breathe (ref) while with Ubuntu is suggested to run:

# IMPORTANT: recommonmark version 0.5.0 or later
sudo apt install doxygen
pip3 install sphinx sphinx_rtd_theme recommonmark breathe

When the installation is complete, you need to enable the building of the documentation files. When using CMake, you need to add the following to the CMake command:

cd build
cmake ../src -DBUILD_DOCS=True

The documentation will be saved into the docs folder.

For example, if you are using CMake to generate a Visual Studio solution, the complete command is:

cmake ../src -G"Visual Studio 16 2019" -DBUILD_DOCS=True

If the option is not specified, documentation generation is skipped when building SofaMyRoom. Please note that if you don’t need to build the documentation files, you don’t need to install the aforementioned software.

A useful tutorial on how to use Doxygen in combination with Sphinx and CMAKE is available here.

Known issues

  • When using the MEX library, MATLAB can crash since the memory allocation performed by libmysofa is not persistent.

License

SofaMyRoom is licensed under the EUPL-1.2.

Credits

References

[1] C. Gaultier, S. Kataria, and A. Deleforge. “VAST: The virtual acoustic space traveler dataset.” International Conference on Latent Variable Analysis and Signal Separation. Springer, Cham, 2017.