Building the SSR from Source#

Tarball#

The so-called tarball – a file named like ssr-x.y.z.tar.gz – can be downloaded from http://spatialaudio.net/ssr/download/.

After downloading the tarball, unpack it and change to the newly created directory:

tar xvzf ssr-*.tar.gz
cd ssr-*

The tarball has the advantage that it already contains a few auto-generated files and therefore needs fewer dependencies. However, if you want to use the latest development version, you should get the code from the git repository:

Git Repository#

The source code repository of the SSR is located at https://github.com/SoundScapeRenderer/ssr/.

You can clone it and change to the newly created directory like this:

git clone https://github.com/SoundScapeRenderer/ssr.git --recursive
cd ssr

Note

The SSR repository uses multiple Git submodules. If you use the --recursive flag as shown above, they will be automatically downloaded. If you didn’t use the --recursive flag, you can get them by running the command:

git submodule update --init

When switching branches or when pulling changes from the server, the local submodules might get outdated. In such a case they can be updated with:

git submodule update

To generate the configure script (which is already contained in the tarball), run the command:

./autogen.sh

For this step, you’ll need those extra dependencies (see below for how to install them for both Linux and macOS):

  • libtool

  • automake

  • autoconf

If you want to generate the man pages (which are also contained in the tarball), you’ll need:

  • help2man

Dependencies#

To enable support for the newest ASDF version 0.4, the C-bindings of the asdf-rust library have to be installed before compiling the SSR.

Linux#

The following list of packages needs to be installed on your system to be able to build the SSR. The recommended way of installing those packages is to use your distribution’s package manager. On Debian/Ubuntu you can use apt-get, aptitude, synaptic etc. However, if you prefer, you can of course also download everything as source code and compile each program yourself.

Note

The package names may vary slightly depending on your distribution or might not be shipped in separate lib or dev packages!

  • make

  • g++ or clang

  • pkg-config

  • libxml2-dev

  • libfftw3-dev

  • libsndfile1-dev

  • libjack-jackd2-dev

  • jackd2

For playing/recording audio files:

  • ecasound

  • libecasoundc-dev

For the GUI:

  • libqt5-opengl-dev

For all network interfaces:

  • libasio-dev

For the WebSocket interface:

  • libwebsocketpp-dev

For the FUDI network interface:

  • libfmt-dev

For SOFA support:

  • libmysofa-dev

For VRPN tracker support:

  • vrpn on Homebrew (has to be compiled from source on Linux)

For support of the InterSense IntertiaCube3 head tracker:

For a concrete list of Ubuntu and Homebrew packages, see the CI configuration file .github/workflows/main.yml.

If the Qt5 library cannot be found during configuration, try using

export QT_SELECT=qt5

If there are problems with Qt5’s moc during the build, you might need to add the corresponding folder (like /usr/local/opt/qt/bin) to your PATH. It might also help to install the package qt5-default to select Qt5 as default Qt version.

On Linux, it may be necessary to run ldconfig after installing new libraries. Ensure that /etc/ld.so.conf or LD_LIBRARY_PATH are set properly and run this after any changes:

sudo ldconfig

macOS#

We recommend installing all dependencies from Homebrew:

brew install make automake libtool pkg-config help2man fftw asio fmt vrpn freeglut yarn node ecasound jack libsndfile websocketpp qt@5 SoundScapeRenderer/ssr/libmysofa llvm

You might be able to skip installing llvm if you have Xcode installed.

And then temporarily link the keg-only Qt5 according to homebrew info (this is neccesary if you already have a newer version of Qt installed, for example if you installed the very useful package qjackctl):

export PATH="/usr/local/opt/qt@5/bin:$PATH"
export LDFLAGS="-L/usr/local/opt/qt@5/lib"
export CPPFLAGS="-I/usr/local/opt/qt@5/include"
export PKG_CONFIG_PATH="/usr/local/opt/qt@5/lib/pkgconfig"

If you want to use help2man on macOS, you have to install a Perl package:

cpan Locale::gettext

Configuring#

Once all dependencies are installed, the SSR can be configured by running:

./configure

This script will check your system for dependencies and prepare the Makefile required for compilation. If any of the required software, mentioned in section Dependencies is missing, the configure script will signal that.

At successful termination of the configure script a summary will show up and you are ready to compile.

The configure script accepts many parameters and options, all of which can be listed with:

./configure --help

For example, certain feature can be disabled like this:

./configure --disable-ip-interface
./configure --disable-websocket-interface --disable-gui

The configure script also recognizes many environment variables. For example, to use a different compiler, you can specify it with CXX:

./configure CXX=clang++

If a header is not installed in the standard paths of your system you can pass its location to the configure script using

./configure CPPFLAGS=-Iyourpath

If you are using an arm64 CPU (i.e. M1, M2 or newer) on macOS (without Rosetta emulation), you might have to explicitly add some paths to be able to find the libraries installed with brew:

./configure CPPFLAGS=-I/opt/homebrew/include LDFLAGS=-L/opt/homebrew/lib

Building#

If everything went smoothly so far, you can continue with the next step:

make

This will take some time (maybe a few minutes). If you have a multi-core or multi-processor computer you can speed things up by specifying the number of processes you want to use with make -j8 (or any other number that you choose).

If there are errors, double-check whether all Dependencies are installed and whether the configuration options are correct.

Installing#

Until now, everything was happening in the source directory. To be able to use the SSR system-wide, it has to be installed like this:

make install

Note

To execute this step, you might need superuser privileges. Depending on your system setup, these might be acquired with the help of sudo.

Alternatively, you can give your own user account the right to install programs. For example, on Debian and Ubuntu this can be done by adding your user to the staff group like this (assuming your user name is myuser):

sudo adduser myuser staff

For the change to take effect, you might have to log out and log in again.

Uninstalling#

If the SSR didn’t meet your expectations, we are very sorry, but of course you can easily remove it from your system again using:

make uninstall