After installing the SSR, each renderer (see The Renderers)
is available as a separate binary:
ssr-binaural,
ssr-brs,
ssr-vbap,
ssr-wfs,
ssr-aap,
ssr-dca (the renderer formerly known as ssr-nfc-hoa)
and
ssr-generic.
The following examples use ssr-binaural,
but you can of course you any renderer you want!
Note that the SSR renderers are also available as externals for
Pure Data. Refer to SSR in Pure
Data.
The easiest way to get a signal out of the
SSR is by passing a sound-file directly:
ssr-binauralYOUR_AUDIO_FILE
Make sure that your amplifiers are not turned too loud…
To stop the SSR use either the options provided by the GUI (Section
Graphical User Interface) or type Crtl+c in the shell in which you started the SSR.
There are a lot of options that are available for all renderers
and only a few that are only available for certain renderers.
Type ssr-binaural--help to get
an overview of the command line options
(the help text is the same for all renderers):
Usage: ssr-binaural [OPTIONS] <scene-file>
The SoundScape Renderer (SSR) is a tool for real-time spatial audio reproduction
providing a variety of rendering algorithms.
Options:
Renderer-specific options:
--hrirs=FILE Load HRIRs for binaural renderer from FILE
--hrir-size=N Truncate HRIRs to length N
--prefilter=FILE
Load WFS prefilter from FILE
-o, --ambisonics-order=VALUE
Ambisonics order to use for AAP (default: maximum)
--in-phase-rendering
Use in-phase rendering for AAP renderer
JACK options:
-n, --name=NAME Set JACK client name to NAME
--input-prefix=PREFIX
Input port prefix (default: "system:capture_")
--output-prefix=PREFIX
Output port prefix (default: "system:playback_")
-f, --freewheel Use JACK in freewheeling mode
General options:
-c, --config=FILE Read configuration from FILE
-s, --setup=FILE Load reproduction setup from FILE
--threads=N Number of audio threads (default: auto)
-r, --record=FILE Record the audio output of the renderer to FILE
--decay-exponent=VALUE
Exponent that determines the amplitude decay (default: 1)
--loop Loop all audio files
--master-volume-correction=VALUE
Correction of the master volume in dB (default: 0 dB)
--auto-rotation Auto-rotate sound sources' orientation toward the
reference
--no-auto-rotation
Don't auto-rotate sound sources' orientation toward the
reference
-i, --ip-server[=PORT]
Start IP server (default off),
a port number can be specified (default 4711)
-I, --no-ip-server Don't start IP server (default)
--end-of-message-character=VALUE
ASCII code for character to end messages with
(default 0 = binary zero)
--websocket-server[=PORT]
Start WebSocket server (default on),
a port number can be specified (default 9422)
--no-websocket-server
Don't start WebSocket server
--fudi-server[=PORT]
Start FUDI server (default off),
a port number can be specified (default 1174)
--no-fudi-server
Don't start FUDI server (default)
--follow Wait for another SSR instance to connect
--no-follow Don't follow another SSR instance (default)
-g, --gui Start GUI (default)
-G, --no-gui Don't start GUI
-t, --tracker=TYPE Select head tracker, possible value(s):
fastrak patriot vrpn intersense razor
--tracker-port=PORT
Port name/number of head tracker, e.g. /dev/ttyS1
-T, --no-tracker Don't use a head tracker (default)
-h, --help Show help and exit
-v, --verbose Increase verbosity level (up to -vvv)
-V, --version Show version information and exit
Use $HOME to refer to your home directory in the case that SSR does not
resolve the tilde ~.
The general configuration of the SSR (whether GUI is enabled, which tracker
to use, and most other command line arguments) can be specified in a
configuration file (e.g.
ssr.conf). By specifying your settings in such a file, you avoid
having to give explicit command line options every time you start the
SSR. We have added the example
data/ssr.conf.example,
which mentions
all possible parameters. Take a look inside, it is rather
self-explanatory.
Configuration files are loaded in the following order, if certain options are
specified more than once, the last occurrence counts. This means that it is
not the last file that is loaded that counts but rather the last occurrence at
which a given setting is specified.
/Library/SoundScapeRenderer/ssr.conf
/etc/ssr.conf
$HOME/Library/SoundScapeRenderer/ssr.conf
$HOME/.ssr/ssr.conf
the path(s) specified with the --config/-c option(s) (e.g.,
ssr-binaural-cmy_config.file)
We explicitly mention one parameter here that might be of immediate
interest for you: MASTER_VOLUME_CORRECTION. This a correction in
dB (!) that is applied – as you might guess – to the master volume. The
motivation is to have means to adopt the general perceived loudness of
the reproduction of a given system. Factors like the distance of the
loudspeakers to the listener or the typical distance of virtual sound
sources influence the resulting loudness, which can be adjusted to the
desired level by means of the MASTER_VOLUME_CORRECTION. Of course,
there’s also a command line alternative (--master-volume-correction).
If you start SSR without GUI (option --no-gui), it starts
automatically replaying the scene that you have loaded. You can have some
interaction via the shell. Currently implemented actions are (all
followed by Return):
c: calibrate tracker (if available)
p: start playback
q: quit application
r: “rewind”; go back to the beginning of the current scene
s: stop (pause) playback
Note that in non-GUI mode, audio processing is always taking place. Live
inputs are processed even if you pause playback.
You can record the audio output of the SSR using the
--record=FILE command line option. All output signals
(i.e. the loudspeaker signals) will be recorded to a multichannel wav-file
named FILE. The order of channels corresponds to the order of loudspeakers
specifed in the reproduction setup (see Sections
Reproduction Setups and
ASDF). The recording can then be used to analyze the SSR output or
to replay it without the SSR using a software player like ecaplay
(http://nosignal.fi/ecasound/).
We provide integration of the InterSense InertiaCube3 tracking sensor,
the Polhemus Fastrak and the Polhemus Patriot as well as all trackers
supported by VRPN. The Supperware head tracker is supported indirectly via
the Pd patch pd/supperware_head_tracker_to_ssr.pd. The head trackers are
used to update the orientation of the reference (in binaural reproduction this
is the listener) in real-time.
See Dependencies for how to compile the SSR with head tracking support.
Note that on startup, the SSR tries to find the tracker. If it fails, it
continues without it. If you use a tracker, make sure that you have the
appropriate rights to read from the respective port.
You can calibrate the tracker while the SSR is running by pressing
Return. The instantaneous orientation will then be interpreted as
straight forward, i.e. upwards on the screen (\(\alpha = 90^\circ\)).
SSR is progressively (and silently) moving from 2D scenes to 3D scenes. The
binaural renderer can handle head tracking about all
three axes of rotation if the HRIRs are provided in SOFA. We recommend using
the browser-based GUI to monitor the tracking as the
built-in GUI only visualizes tracking along the azimuth.
Make sure that you have the required access rights to the tracker before
starting SSR. For you are using the USB connection type
sudochmoda+rw/dev/ttyUSBX
whereby X can be any digit or number. If you are not sure which port is
the tracker then unplug the tracker, type
ls/dev/ttyUSB*
replug the tracker, execute above command again and see which port was added.
That one is the tracker. It’s likely that it is the one whose name contains
the highest number.
Make sure that
you have the required access rights to the tracker before starting SSR by
typing something like
sudochmoda+rw/dev/ttyS0
or
sudochmoda+rw/dev/ttyS1
or so.
If you want to disable this tracker, use ./configure--disable-polhemus
and recompile.
If you are using head tracking about all three axes of rotation, make sure
that the tracking sensor is mounted on the headphones such that the cable
leaves the sensor towards the left relative to the look direction of the user.
In order to use Virtual Reality Peripheral Network (VRPN) compatible
trackers create a config file vrpn.cfg with one of the following lines (or
similar)
If the tracker runs on a different computer, use its hostname (or IP address)
instead of localhost. You can of course select your head tracker settings by
means of Configuration Files.
As stated before, the SSR is currently not able to dynamically replay
audio files (refer to Section ASDF). If your audio scenes are
complex, you might want to consider using the SSR together with a
digital audio work station (DAW). To do so, you simply have to create as
many sources in the SSR as you have audio tracks in your respective DAW
project and assign live inputs to the sources. Amongst the ASDF examples
we provide on SSR website http://spatialaudio.net/ssr/ you’ll find an scene
description that does exactly this.
DAWs like Ardour (https://ardour.org) support JACK and their use is therefore
straightforward. DAWs which do not run on Linux or do not support JACK
can be connected via the input of the sound card.
In the future we will provide a VST plug-in which will allow you to
dynamically operate all virtual source’s properties (like e.g. a
source’s position or level etc.). You will then be able to have the full
SSR functionality controlled from your DAW.
How to connect the SSR in binaural playback mode with the own audio library
using Jack and VLC Media Player:
After installing Jack and the SSR (with all needed components: see
Configuring) it is necessary to install the VLC
Media Player with its Jack plugin (for example UBUNTU):
sudoapt-getinstallvlcvlc-plugin-jack
(or use the packet manager of your choice instead of the command line and
install: vlc and vlc-plugin-jack)
2. After installing open VLC Media Player and navigate to Tools->Preferences
Select “All” on the bottom left corner In the appearing menu on the left
navigate to “Audio”->”Output Module” and extend it by using “+”
3. In the submenu of “Output Module” select “JACK” and replace “system” by ”
Binaural-Renderer” in the “Connect to clients matching”-box. Do not forget to
enable “Automatically connect to writable clients” above. (Otherwise you have
to connect the audio output of vlc with the SSR input after every played audio
file using jack.)
(Note: If you want to use another Renderer, e.g. for WFS, you have to
enter “WFS-Renderer” in the box)
Due to copyright reasons, the SSR does not come with a built-in InterSense
tracker support. So first you have to build the SSR with InterSense
tracker support yourself (see the CI configuration file
.github/workflows/main.yml
for instructions).
If you are using a USB-to-Serial interface with your tracker, you need to
install drivers for that. This seems to work fine for the interface made by
InterSense: https://ftdichip.com/drivers/vcp-drivers/
To check if the system sees the tracker do:
ls-l/dev/tty.usb*
On the MacBooks tested, the serial ports were called /dev/tty.usbserial-00001004 or /dev/tty.usbserial-00002006 depending on which USB port was
used.
To make the SSR use the InterSense tracker with these ports, you have two
options:
Using the command line (only one port can be specified):
If you happen not to own a Polhemus or InterSense tracker to do your head-
tracking, an alternative would be to use our DIY low-cost Razor AHRS tracker.
