Developer section

How to build and extend VA


VA is based on C++11 source code and will compile on any modern architecture with a current C/C++ compiler set.
If you plan to build VA expect to spent a significant amount of time to prepare the required dependencies (see tables below). For Windows users no package manager is available to pull in software packages, hence manual configuration and compiling is required (which can be hard work).

VA uses CMake to configure the project. It allows to activate and deactivate rendering and reproduction modules and and offers options to control implementation details of the core.


C++ code documentation

Virtual Acoustics is entirely written in C++. However some bindings for other languages like Python and Matlab exist. They have been brought into existence in the spirit of making VA available for a broader user base that is not familiar with C++ programming. For those who are not familiar with C++, see getting started section). If you want to embrace VA in your software (instead of only controlling it from the outside), here is what you need to know:

C++ API documentation (generated with Doxygen)



Third party dependencies

VA makes extensive use of third party libraries. Parts of the framework can be build with a minimal set of external libs, however the core and applications all require the full dependency tree to be solved. Table 1 below lists the internal and external dependencies (for a description of the projects, see overview and documentation section).

Project name Internal dependencies (components) External dependencies (components)
VABase none none
VANet VABase VistaCoreLibs (Aspects, Base, InterProcComm)
VALua VABase
VistaCoreLibs (Aspects, Base, InterProcComm)
Lua C++ headers and libs
VAMatlab VABase
VistaCoreLibs (Aspects, Base, InterProcComm)
Matlab C++ headers and libs
NaturalPoint OptiTrack C++ headers and libs [optional]
VACS (C#) VABase
VistaCoreLibs (Aspects, Base, InterProcComm)
VAPython VABase
VistaCoreLibs (Aspects, Base, InterProcComm)
Python C++ headers and libs, Python's distutils
VACore VABase ITACoreLibs (all components)
ITAGeometricalAcoustics (all components) [optional]
RAVEN [optional]
VistaCoreLibs (Aspects, Base, InterProcComm)
OpenDAFF C++ headers and libs
VAServer VABase
ncurses (POSIX only)
Redstart VABase
Table 1: VA dependency tree

The ITA projects ITACoreLibs, ITAGeometricalAcoustics and ITAAcousticVisualization are open source projects (see below), RAVEN (Room Acoustics for Virtual ENvironments) however is not available to the public. It is only required as a backend for the room acoustics audio renderer, which is disabled by default.
These projects have a lot of dependencies to smaller projects, which are pulled in if you want to build the VACore of any application using it (cmp. Table 2).

Project name Internal dependencies (components) External dependencies (components)
(ITACoreLibs component)
none libsamplerate
pcre and pcrecpp
IPP [optional, problematic license]
SimpleINI (in source)
pthreads (POSIX only)
(ITACoreLibs component)
ITABase FFTW3 [optional, but recommended, though forces VA into GPL]
MKL [optional]
FFTS [optional]
(ITACoreLibs component)
ITABase VistaCoreLibs (Aspects, Base, InterProcComm)
ASIO [optional, but recommended]
Portaudio [optional]
JACK [optional]
(ITACoreLibs component)
(ITACoreLibs component)
(ITACoreLibs component)
(ITAGeometricalAcoustics component)
ITABase VistaCoreLibs (Base, Math)
OpenMesh [optional, recommended]
SketchUp / slapi [optional, recommended]
libcitygml [optional]
IfcOpenShell [optional]
(ITAGeometricalAcoustics component)
(ITAAcousticVisualization component)
ITAGeo [optional]
VTK [recommended with Qt5 support]
(ITAAcousticVisualization component)
ITAGeo [optional]
ITADiffraction [optional]
ITAVTK [optional]
VTK with Qt5 support
Table 2: ITA projects dependency tree


Build configurations

VA configuration options

VA can be configured by a variety of options to meet the needs for different purposes. This is usually required if not all of the dependency tree is available and only some features (like rendering or reproduction modules) should be compiled and linked to the core. Also, if you only want to build the network support to control a remote core or want to build a binding for an uncommon platform, you will find this section helpful.

All CMake configuration options will have an ITA_ prefix. If "Grouped" mode is activated in CMake GUI, the group name is ITA and all relevant options will be listed there.

VA (general)

Option Description
ITA_VA_BUILD_STATIC Activate, if you want to build static VA libraries. Also, uncheck BUILD_SHARED_LIBS in this case.
ITA_VA_GENERATE_DOCUMENTATION Generates the documentation using Doxygen
ITA_VA_INSTALL_WITH_DLLS Will copy all dependent shared libraries (DLLs in Windows) to the bin folder when deploying / installing.
ITA_VA_WITH_BENCHMARKS Includes benchmarks for all subprojects
ITA_VA_WITH_TESTS Includes tests for all subprojects
ITA_VA_WITH_SERVER_APPS Includes server application (VAServer)
ITA_VA_WITH_UNITY_SCRIPTS Will also deploy Unity extension C# scripts
ITA_VA_WITH_CORE Includes the core (VACore)
ITA_VA_WITH_BINDING_CS Includes the C# binding (VACS)
ITA_VA_WITH_BINDING_LUA Includes the Lua binding (VALua)
ITA_VA_WITH_BINDING_MATLAB Includes the Matlab binding (VAMatlab)
ITA_VA_WITH_BINDING_PYTHON Includes the Python binding (VAPython)
Table 3: General VA CMake configuration
VANet (network library settings)

Option Description
ITA_VANET_DEFAULT_PORT Changes default port (usually 12340)
ITA_VANET_VERSION_MAJOR VANet version major part, e.g. v2018
ITA_VANET_VERSION_MINOR VANet version minor part, e.g. a,b,c,d ...
ITA_VANET_WITH_NETAUDIO_STREAM_SERVER_EXTENSION Includes a network streaming server extension for custom signal sources
Table 4: VANet specific CMake configuration
VAMatlab (Matlab binding)

Option Description
ITA_VAMATLAB_SHOW_BANNER Includes VA banner on first creation in Matlab
ITA_VAMATLAB_VERSION_MAJOR VAMatlab version major part, e.g. v2018
ITA_VAMATLAB_VERSION_MINOR VAMatlab version minor part, e.g. a,b,c,d ...
ITA_VAMATLAB_DEPLOY_MATLAB_EXECUTABLE Additionally deploy matlab executable to bin folder
ITA_VAMATLAB_BUILD_WITH_OPTITRACK_TRACKING_SUPPORT Include OptiTrack tracking support to enable integrated update of sound receivers and sound sources
ITA_VAMATLAB_BUILD_WITH_INTEGRATED_CORE Link core into Matlab executable (no server application required, but VA behaviour can not be monitored, anymore)
ITA_VAMATLAB_POSTBUILD_CREATE_MATLAB_CLASS Auto-create Matlab convenience class after build [for future use]
Table 5: VAMatlab specific CMake configuration
VAPython (Python binding)

Option Description
ITA_VAPYTHON_VERSION_MAJOR VAPython version major part, e.g. v2018
ITA_VAPYTHON_VERSION_MINOR VAPython version minor part, e.g. a,b,c,d ...
Table 6: VAPython specific CMake configuration
VACore (core functionality)

Option Description
ITA_VACORE_DEPLOY_WITH_COMMON_CONFIGS Copies configuration files along when deploying / installing
ITA_VACORE_DEPLOY_WITH_COMMON_DATA Copies data files along when deploying / installing
ITA_VACORE_DEPLOY_WITH_COMMON_SCRIPTS Copies scripts along when deploying / installing
ITA_VACORE_WITH_TESTS Includes tests for core only
ITA_VACORE_VERSION_MAJOR VACore version major part, e.g. v2018
ITA_VACORE_VERSION_MINOR VACore version minor part, e.g. a,b,c,d ...
ITA_VACORE_DEFAULT_CONFIG_FILE_NAME Default VACore configuration file name (INI file)
ITA_VACORE_DEFAULT_DEBUG_LEVEL Default VACore debug level (0-5)
ITA_VACORE_MODULE_INTERFACE_ENABLED Build VACore with module interface
ITA_VACORE_NO_MODULE_INTERFACE_THROW_EXCEPTION Throw exception during module call attempt if VACore was build without module interface
ITA_VACORE_MAX_NUM_SOUND_SOURCES VACore maximum number of sound sources ( 0 = unlimited )
ITA_VACORE_MAX_NUM_SOUND_RECEIVERS VACore maximum number of sound receivers ( 0 = unlimited )
ITA_VACORE_WITH_TTS_SIGNAL_SOURCE VACore with text-to-speech signal source support (requires TTSReleay)
ITA_VACORE_BIG_DATA_DIR VACore big data dir with more files for auralization (will be added to search path)
INSIDE_SCENE_DATA InsideSceneData folder for Inside scenes
ITA_RAVEN_DATA_PATH RAVEN data base path (where to find models, HRTFs, materials etc. ...)
ITA_VACORE_WITH_AUDIO_BACKEND_ASIO Build VACore with ASIO audio backend support
ITA_VACORE_WITH_AUDIO_BACKEND_PORTAUDIO Build VACore with Portaudio audio backend support
ITA_VACORE_WITH_AUDIO_BACKEND_DUMMY Build VACore with dummy audio backend support
ITA_VACORE_WITH_RENDERER_AMBIENT_MIXER Build VACore with rendering module: ambient mixer
ITA_VACORE_WITH_RENDERER_AMBISONICS_FREE_FIELD Build VACore with rendering module: ambisonics free-field
ITA_VACORE_WITH_RENDERER_BINAURAL_FREE_FIELD Build VACore with rendering module: binaural free-field
ITA_VACORE_WITH_RENDERER_BINAURAL_ARTIFICIAL_REVERB Build VACore with rendering module: artificial reverb
ITA_VACORE_WITH_RENDERER_BINAURAL_ROOM_ACOUSTICS Build VACore with rendering module: room acoustics
ITA_VACORE_WITH_RENDERER_BINAURAL_AIR_TRAFFIC_NOISE Build VACore with rendering module: air traffic noise (VATSS project)
ITA_VACORE_WITH_RENDERER_PROTOTYPE_FREE_FIELD Build VACore with rendering module: prototype free-field
ITA_VACORE_WITH_RENDERER_PROTOTYPE_DUMMY Build VACore with rendering module: prototype dummy
ITA_VACORE_WITH_RENDERER_PROTOTYPE_HEARING_AID Build VACore with rendering module: prototype hearing aid (iCARE project)
ITA_VACORE_WITH_RENDERER_PROTOTYPE_GENERIC_PATH Build VACore with rendering module: prototype generic path
ITA_VACORE_WITH_RENDERER_VBAP_FREE_FIELD Build VACore with rendering module: vector-base amplitude panning free-field
ITA_VACORE_WITH_REPRODUCTION_TALKTHROUGH Build VACore with reproduction module: talkthrough
ITA_VACORE_WITH_REPRODUCTION_HEADPHONES Build VACore with reproduction module: headphones (equalization)
ITA_VACORE_WITH_REPRODUCTION_AMBISONICS Build VACore with reproduction module: ambisonics (B-format decoder)
ITA_VACORE_WITH_REPRODUCTION_BINAURAL_NCTC Build VACore with reproduction module: binaural N-CTC
ITA_VACORE_WITH_REPRODUCTION_BINAURAL_MIXDOWN Build VACore with reproduction module: binaural mixdown
ITA_VACORE_WITH_REPRODUCTION_AMBISONICS_BINAURAL_MIXDOWN Build VACore with reproduction module: ambisonics binaural mixdown (B-format decoder)
ITA_VACORE_WITH_REPRODUCTION_MIXER_LOW_FREQUENCY Build VACore with reproduction module: low frequency (subwoofer) mixer
ITA_VACORE_REPRODUCTION_NCTC_WITH_SWEET_SPOT_WIDENING Cross-talk cancellation sweet spot widening
Table 7: VACore specific CMake configuration
VAServer (CLI server application)

Option Description
ITA_VASERVER_DEFAULT_SERVER_ADDRESS Default address for scripts and when running out of dev env (e.g. Visual Studio)
ITA_VASERVER_DEFAULT_SERVER_PORT Default port for scripts and when running out of dev env (e.g. Visual Studio)
ITA_VASERVER_DEPLOY_WITH_COMMON_SCRIPTS Include start scripts when installing / deploying
ITA_VASERVER_VC_COMMAND_LINE_ARGUMENTS Command line arguments when starting server from within Visual Studio
Table 8: VAServer specific CMake configuration
Redstart (Qt GUI server application)

Option Description
ITA_REDSTART_DEFAULT_SERVER_ADDRESS Default address for scripts and when running out of dev env (e.g. Visual Studio)
ITA_REDSTART_DEFAULT_SERVER_PORT Default port for scripts and when running out of dev env (e.g. Visual Studio)
ITA_REDSTART_DEPLOY_WITH_COMMON_SCRIPTS Include start scripts when installing / deploying
ITA_REDSTART_VC_COMMAND_LINE_ARGUMENTS Command line arguments when starting Redstart from within Visual Studio
Table 9: Redstart specific CMake configuration


Build guide


VA relies on CMake to generate project files of your choice that will let you build the project in your preferred development environment. At least in theory. So far, we have only build VA using diverse Microsoft Visual Studio versions and MS compiler versions on Windows platforms, and on Linux platforms using Makefiles and GCC.
CMake is fine, but the Vista VR Toolkit practically improves it by its VistaCMakeCommon scripts. VA uses a lot of ViSTA functionality, and we have also adopted the build methods. It takes a little effort to set some paths to the environment, but it pays off especially of you want to add tests, benchmarks and your own applications that require the VA libraries (and its dependencies).

Where to start

Start with installing CMake, GIT and your development environment. Create an empty folder, let's call it dev, and let's assuming the absolute path is C:/dev or /home/username/dev. Switch to this folder, and clone ViSTA here using
git clone

Now, clone VistaCMakeCommon, the CMake extensions to ease finding dependencies and ViSTA-compatible projects.
git clone

Additionally, add a folder that will contain all your dependencies and call it ExternalLibs. Your folder structure should look like this

- dev
  - ExternalLibs
  + ViSTA
  + VistaCMakeCommon

Finally, we have to add environment variables to point to the VistaCMakeCommon and ExternalLibs folder (otherwise CMake will not find these paths). For further information see the ViSTA documentation.
For Windows, edit the environment variables for this user (google it) and add the following variables (adjust for deviating paths and test if they are valid, otherwise nothing will work)

VISTA_CMAKE_COMMON = C:/dev/VistaCMakeCommon
VISTA_EXTERNAL_LIBS = C:/dev/ExternalLibs

For Linux, add the export VAR lines e.g. to your ~/.bashrc or find other ways using Google.

export VISTA_CMAKE_COMMON = ~/dev/VistaCMakeCommon
export VISTA_EXTERNAL_LIBS = ~/dev/ExternalLibs
Now follow the ViSTA way to build ViSTA, or more precisely the VistaCoreLibs, the libraries we need for VA. By default, ViSTA has no additional dependencies, and VA only requires those libraries and not - for example - the entire rendering kernel and the device drivers.
You build ViSTA by opening the CMake GUI and put in the source code path and the build directory. There is no strict rule how to name the build folder, but as good practice use build prefix followed by win32-x64 for a Windows 64bit build, and add .vc14 for the Visual C Compiler Version 14. Adopt for diverging version. For Linux, use LINUX.X64, and if preferred, use the cmake command line tool instead.

As an example for a Windows machine with Visual Studio 2015 (using Visual Studio 14 compiler), this is the CMake setup

Source: C:/dev/VistaCoreLibs
Build:  C:/dev/VistaCoreLibs/build_win32-x64.vc14

If you now configure and generate the project files, you can open the project solution and build the VistaCoreLibs (or run make on Linux). CMake will automatically find VistaCMakeCommon and from now on also knows where to look for VistaCoreLibs libraries, if you want to add a dependency to it in your project (like VA does).

Notes on building static libraries: disable the BUILD_SHARED_LIBS flag and disable ViSTA drivers and demos (they are not required for VA).
In the process of building VA, activate ITA_VISTA_BUILD_STATIC, ITA_VA_BUILD_STATIC, ITA_CORE_LIBS_BUILD_STATIC and so on.

Compiling VA base and network library

Now that you have set up ViSTA, we can proceed with building VA. Clone VA into the dev folder above, and use the --recursive flag to also clone the submodules:
git clone --recursive

Run CMake with the following parameters:

Source: C:/dev/VA
Build:  C:/dev/VA/build_win32-x64.vc14
Make sure, that no further settings are activated. For now we want to build VABase and VANet, which depend on VistaCoreLibs only. As usual in CMake: configure, generate and open the project to build it (or run make on Linux).

Compiling the binding(s)

The base libraries are ready, now continue with bindings for Matlab, Lua, C# and/or Python. C# has no further dependency, but for the others you will have to provide third party libraries. You can activate the respective binding in CMake (Linux users use ccmake) as described in the section above.


To build a Python 3.x extension using Windows, install Python and the Python build sets that come with Visual Studio. You can compile the VAPython project from within Visual Studio, but the resulting library will not be used - it is only to conveniently code in Visual Studio and refactor efficiently. Instead, the final Python VA extension will be generated by a call to distutils, that will generate the compatible library. It is highly recommended to use static linking to VA and further dependencies.


To build a Matlab executable (mex), you need a Matlab installation ad the corresponding headers and libraries. You can compile the Matlab extension directly out of your development environment, however currently only Visual Studio has been tested.
To generate the itaVA class to easy using the VAMatlab executable, currently a manual step is required because auto-generation calling Matlab out of the development environment is still under construction. To create the class, run the itaVA_build.m script in Matlab once. The class will be included into the deployment and can be found in the matlab folder (along with some examples).


The core of VA is the most challenging part. It requires the entire dependency tree and also pulls in the ITACoreLibs libraries. Please note the dependency table in the sections above. Provide the dependencies e.g. to fftw3, libsndfile, libsamplerate and others. Before starting, configure the ITACoreLibs as described below.


Obtain the source code using

git clone --recursive
Configure the ITACoreLibs using CMake. It is recommended to use static linking to avoid mix ups with other library versions (that potentially have the same name). Please activate the following switches:

ITA_BASE_WITH_OLD_ATOMICS (only required for RAVEN backend)
ITA_BASE_WITH_OLD_RAVEN_OPS (only required for RAVEN backend)
ITA_DATA_SOURCES_WITH_INTEGRATED_ASIO (optional, recommended for Windows users)
ITA_DATA_SOURCES_WITH_INTEGRATED_JACK (optional, for Linux users only)
ITA_FFT_WITH_FFTW3 (recommended)
Now generate and build the project to make it available for the next step.


Activate the core flag in CMake and configure VA.

Now, a lot of further configuration options will appear, which might have to be altered to fit your needs. However, the default setting should be sufficient to begin. It will include the most important rendering and reproduction modules that do not depend on further projects, like room acoustics and RAVEN or outdoor noise renderers using ITAGeometricalAcoustics. See section above for more details.
After generating, the VACore project appears in your development environment.


Activate the server app flag in CMake and configure VA.

After generating, the VAServer project appears in your development environment.

Redstart VA GUI

Redstart, the graphical user interface application for VA, uses Qt5. Obtain and install a current version first. Also, because the ITAAcousticVisualization project is required for some widgets, obtain the current VTK source code and build it with Qt5 support activated (it is also based on CMake).


Obtain the source code using

git clone --recursive
Configure, generate and build ITAAcousticVisualization using CMake.


Now, activate the Redstart app flag in CMake and configure VA.

After generating, the Redstart project appears in your development environment.

Special features

VA provides some special features.

Rendering module with room acoustics simulation backend

This module requires RAVEN, which is copyright protected and not available for the public. Please contact us if you are working for a university and want to use it for academic purposes, only. If you have been granted access, obtain the source code using

git clone --recursive
Configure, generate and build RAVEN using CMake.
Now you can activate the room acoustics rendering module


Rendering module with outdoor noise simulation

This module requires ITAGeometricalAcoustics. Obtain the source code using

git clone --recursive
Configure, generate and build ITAGeometricalAcoustics using CMake.
Now you can activate the outdoor noise acoustics rendering module (under construction)



VA provides C# scripts for Unity. You can connect Unity GameObjects with VA sound sources, sound receivers, signal sources, auralization modes, etc. Also, some basic interfaces to control the core (gains, muting) as well es special scripts for rendering and reproduction modules exist.

Either copy the entire scripts from VAUnity into your Assets folder or clone it directly there using

git clone
All unity scripts require the VA C# class, which uses a C++ wrapping library called VANetCSWrapper together with the C# class VACS.cs, which can be found in the VACS binding project. To create it activate the C# binding

Make the VANetCSWrapper shared library (.dll on Windows) available in your Assets folder. Unity usually expects external libraries under the Plugins folder. Note, that if you build shared VA and VistaCoreLibs libraries they have to be placed next to the VANetCSWrapper library. The list usually comprises VABase VANet VANetCSWrapper VistaAspects VistaBase VistaInterProcComm, which can be found in the deploy directory inside the bin folder after installing VA. For further details, see the corresponding README files of VAUnity.

VA also provides extensions for Unity that require additional assets like VRTK or SteamVR. They have been placed into VAUnityExtensions to strictly separate the VAUnity C# scripts, which only require VA. If you are planning to use Unity with HMDs and interactive input devices, check out the VA 3D menus for the Vive that lets you control VA in Virtual Reality. You will also find templates for multi-modal experiments that can be used for alternate forced choice tests (3-AFC tests), which are common for quality assessments and perceptional threshold evaluations.

Extending VA

You can extend VA to create modules for your purpose. Best practice is to derive a class or method from an existing implementation and modify it accordingly. Wherever possible, use generic methods (Set..Parameters() Get..Parameters() Create...FromParameters()) instead of extending the VA interface. It will make your life easier, because repercussions of new virtual interface methods are significant. Changes to the entire VA collection will be necessary, and a slight mistake will lead to a lot of trouble that is difficult to debug. Furthermore, choose a module that is closest to what you are planning and use refactoring tools to detect where and how to register your new class in the core as a signal source, a rendering module or a reproduction module. If you want to start from scratch, look out for dummy classes that only implement required virtual methods.

Wrap up

If you have come this far, your development environment folder structure will look similar to this:

- dev
  + ExternalLibs
  + ITAAcousticVisualization
    - ITAQtWidgets
  + ITAGeometricalAcoustics (optional)
    - ITAGeo
	- ITADiffraction
  + ITACoreLibs
    - ITABase
	- ITAConvolution
	- ITADataSources
	- ITA
  + RAVEN (optional, protected)
  + VA
    - Redstart
    - VABase
	- VACore
	- VAMatlab
	- VANet
	- VAPython
	- VAServer
	- VAUnity
	- VAUnityExtensions
  + ViSTA
    - VistaCoreLibs
  + VistaCMakeCommon

Get help

If you are stuck, get help from the community.


Code repositories

The ITA and VA repositories link to submodules. Use git clone --recursive URL to include submodule contents, too. Also, because the referenced submodules are detached from HEAD, it is recommended to use the foreach statement to switch branches and update code. Common calls are

git submodule foreach git status
git submodule foreach git checkout master
git submodule foreach git branch
git submodule foreach git pull
Name URL Webinterface
VA GitLab
ViSTA GitLab
VistaCMakeCommon GitLab
ITACoreLibs GitLab
ITAGeometricalAcoustics GitLab
ITAAcousticVisualization GitLab
RAVEN (non-public) GitLab
Table 1: open access GIT repositories

Get them all

git clone --recursive
git clone --recursive
git clone --recursive
git clone --recursive
git clone
git clone