Project

General

Profile

The SoundScape Renderer has moved to http://spatialaudio.net/ssr/

NOTE: This page does not replace the SSR Manual - it just points out things that are different on OS X as the Manual right now is targeted at the Linux SSR.
Get the Manual at https://dev.qu.tu-berlin.de/projects/ssr/files.

Running the SSR on Mac OS X

This assumes you are using the precompiled SSR App for OS X. If you want to build the SSR yourself, have a look at the next section.

Installation

The installation should be straightforward. Just double-click on the .dmg file and drag the SoundScapeRenderer-x.x.x folder to your Applications folder. Done.

The .app bundle can be placed anywhere, but spaces in path names might cause trouble, so it's better to avoid them.
Another thing is that OS X sort of adds apps placed in the /Applications folder to the environment, so lets assume you put the SSR there.

You'll also need JACK (http://jackosx.com/, be sure to get the 64 bit version).

Starting the SSR

Run JackPilot and hit Start.
Then double-click the SoundScapeRenderer.app icon, select the renderer type, and off you go!

When the SSR is started, a Terminal window displaying the standard SSR output is automatically opened, too. If the SSR closes with an error, it remains open for you to inspect the error messages.

Config Files

After double-clicking on the SSR icon you can only select the renderer type, to specify more options (and there are many more!) you should use a config file.

As a starting point, we're providing an example configuration file in Extras/ssr.conf.example, you can copy this to any of the locations given below and change the relevant settings.

The SSR looks for ssr.conf files in these places in the given order:

  • Global:
    • /Library/SoundScapeRenderer/ssr.conf
    • /etc/ssr.conf
  • User:
    • ~/Library/SoundScapeRenderer/ssr.conf
    • ~/.ssr/ssr.conf

You can choose any of these locations, but be aware that settings in config files that are loaded later take precedence over settings in config files loaded earlier.

Running via Command Line (Terminal)

The .app bundle is more convenient, but brings limitations when using the command line. The included start script changes the working directory to the directory that includes the SSR .app bundle, so only absolute paths should be used on the command line.

What can be done using config files, should be done using config files.

To start the SSR on the command line do:

open -a SoundScapeRenderer

If the SSR is placed in /Applications and was run several times already, OS X should find it.
If not you would have to specify the full path, i.e.:

open /Applications/SoundScapeRenderer-0.3.1/SoundScapeRenderer.app

To start the SSR using the binaural renderer module do:

open -a SoundScapeRenderer --args "--binaural" 

The renderer selection prompt is skipped automatically if a renderer is given as argument.

To also load a scene do:

open -a SoundScapeRenderer --args "--binaural /absolute/path/to/scene" 

Notice that the arguments have to be enclosed in ""!

To load a scene that has spaces in its path name do:

open -a SoundScapeRenderer --args "/path/to/file\ with\ spaces" 

Spaces have to be escaped using backslashes!

In addition to the config files in standard locations mentioned above, you can also specify a config file on the command line:

open -a SoundScapeRenderer --args "--config=my_config_file.conf" 

To learn about other command line parameters, have a look at the Manual: https://dev.qu.tu-berlin.de/projects/ssr/files.

Using a head-tracker

Running with InterSense tracker support

Due to copyright reasons the SSR does not come with InterSense tracker support built in. So first you have to build the SSR with InterSense tracker support yourself or ask someone to do it for you.

If you are using an USB-to-Serial interface with your tracker, you need to install drivers for that.
These seem to work fine for the interface made by InterSense: http://www.ftdichip.com/Drivers/VCP.htm

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:

1) Using the command line (only one port can be specified):

open -a SoundScapeRenderer --args "--tracker=intersense --tracker-port=/dev/tty.usbserial-XXXXXXXX" 

2) Using config files:

Add these lines to a config file (multiple ports can be specified):

TRACKER = intersense
TRACKER_PORTS = /dev/tty.usbserial-XXXXXXXX /dev/tty.usbserial-YYYYYYYY

It's recommended to use the config file aproach - best use a global config file.

Running with Razor AHRS tracker support

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.

If you have Arduino installed on you machine, FTDI drivers will be there too. Otherwise get the driver from http://www.ftdichip.com/Drivers/VCP.htm

To check if the system sees the tracker do:

ls -l /dev/tty.usb*

This should give you something like /dev/tty.usbserial-A700eEhN.

To make the SSR use these Razor AHRS tracker, you have two options:

1) Using the command line:

open -a SoundScapeRenderer --args "--tracker=razor --tracker-port=/dev/tty.usbserial-XXXXXXXX" 

2) Using config files:

Add these lines to a config file:

TRACKER = intersense
TRACKER_PORTS = /dev/tty.usbserial-XXXXXXXX

It's recommended to use the config file aproach - best use a global config file.


Building the SSR on Mac OS X

Instructions how and what to set up to build the SSR on Mac OS X.

Currently building is only supported on OS X Snow Leopard (10.6.x).

Tested with 10.6.6 and 10.6.7

What to install first?

XCode

Tested with version 3.2.6

Can be downloaded from http://developer.apple.com/, but you have to register as developer first. It's maybe easier to install an older XCode from an OS X install DVD (there is something called "Optional Installs") and run an update afterwards.

MacPorts

Tested with version 1.9.2

Download here: http://www.macports.org/

Then open a terminal and do an initial ports tree update

sudo port selfupdate

If that is not working it's most likely because the router won't let you use rsync. So we switch to http:

sudo nano /opt/local/etc/macports/sources.conf

Comment out the rsync entry

#rsync://rsync.macports.org/release/ports/ [default]

And add a line

http://www.macports.org/files/ports.tar.gz [default]

Now save the file and try the selfupdate again.

MacPorts ports

These ports have to be installed (dependencies are installed automatically)
  • autoconf
  • automake
  • pkgconfig
  • libsndfile
  • fftw-3-single
  • qt4-mac
  • boost
  • libxml2

Ports are installed using

sudo port install <portname>

Because ports are compiled locally it may take several hours to install all ports. Issuing one command to install all ports might be more convenient:

sudo sh -c "port install autoconf && port install automake && port install pkgconfig && port install libsndfile && port install fftw-3-single && port install qt4-mac && port install boost && port install libxml2" 

Ecasound

Tested with version 2.7.2

Download from http://www.eca.cx/ecasound/

In Terminal go into the unpacked ecasound folder and do:

./configure
make
sudo make install

JackOSX

Tested with version 0.87 (64 bit) which includes:
  • Jackdmp 1.9.6
  • JackRouter 0.9.3
  • JackPilot 1.7.0

Download at http://www.jackosx.com/ and be sure to get the 64 bit version.

How to build from scratch?

Standard build

Get the SSR Source tarball and unpack it where ever you wish, then open a Terminal window and cd into the newly created folder.

You now have two options:

1) If you want to build local binaries - i.e. for local developing/testing - you can build and run the SSR Linux-style:

./configure JACK_LIBS="-L/usr/local/lib -ljack" JACK_CFLAGS=-I/usr/local/include/jack
make

And run the SSR using the start script that comes with it:

./data/ssr.sh

The binaries do not get wrapped in an .app bundle and nothing will be installed.
You can pass arguments to the SSR the same way you would do it on Linux, have a look at the Manual: https://dev.qu.tu-berlin.de/projects/ssr/files.

2) If you want to build a clickable .app bundle and wrap it into a .dmg image, you can build the SSR OSX-style:

./configure JACK_LIBS="-L/usr/local/lib -ljack" JACK_CFLAGS=-I/usr/local/include/jack --enable-app-bundle
make dmg

You can also name the .dmg:

./configure JACK_LIBS="-L/usr/local/lib -ljack" JACK_CFLAGS=-I/usr/local/include/jack --enable-app-bundle="SoundScapeRenderer-0.3.1-MacOSX-10.6-64bit.dmg" 
make dmg

The resulting .dmg is output to the SSR source root folder. The .app bundle inside contains all non-system dynamic libraries needed by the SSR, except the Jack libs. So it should run on every OS X 10.6.x with Jack installed.

Build with InterSense tracker support

Tested with IntertiaCube3, software version 4.17

Get the SDK from http://www.intersense.com/. It should contain a dynamic library called libisense.dylib and two header files called isense.h and types.h.

Put libisense.dylib into /usr/local/lib
Put InterSense header files into /usr/local/include/intersense

Then build like described above, but add CPPFLAGS=-I/usr/local/include/intersense to the configure parameters. So to build locally you would do:

./configure JACK_LIBS="-L/usr/local/lib -ljack" JACK_CFLAGS=-I/usr/local/include/jack CPPFLAGS=-I/usr/local/include/intersense
make

For some strange reason the full path of libisense.dylib is not written to the header of the binary. So if you configure with --enable-app-bundle and then do make dmg to build an .app bundle, a tool called dylibbundler will ask you to enter its path (/usr/local/lib) several times.