Audio how-to

From JReality Wiki
Jump to: navigation, search

jReality currently uses two outlets for audio, Java Sound and JACK, the JACK Audio Connection Kit. As a rule of thumb, the Java Sound components work right out of the box on most systems but are limited to stereo or 5.1 surround speaker configurations, while the JACK components may require some initial configuration but offer better performance as well as support for fully isotropic 3D audio and arbitrary speaker configurations through Ambisonics.

The Java Sound stereo backend is enabled by default. If this is sufficient for your purposes, then you can skip this document. The remainder of this document covers advanced setup and performance tweaks.

Audio Preferences

In order to configure sound for a jReality application, open the audio preferences (Help->Preferences->Audio), choose the audio backend you want (stereo or 5.1 surround through Java Sound, or first or second-order Ambisonics through JACK), select the desired configuration options, and click on Apply. You will only need to do this once per application; a properly written jReality application will remember the settings and automatically launch the audio backend in the future.

A common configuration option for all audio backends is the choice of interpolation. This option determines the interpolation scheme used throughout the audio backend, including sample rate conversion and sound propagation. Cubic interpolation is the default, and there will be no need to change this unless audio performance is a serious consideration. If you feel the need to save CPU cycles, you can trade quality for performance and choose a simpler interpolation scheme, such as linear interpolation or no interpolation at all (i.e., sample and hold).

Java Sound

The Java Sound backends should work right out of the box on most systems. They have two basic configuration options, the buffer size and the sample rate. The default values should work in most cases, but there are certain situations where you may want to try different values.

  • If you hear audio artefacts such as clicks or dropouts, try a larger buffer size.
  • If you want to reduce audio latency, try a smaller buffer size.
  • If you want to reduce processor load, try a smaller sample rate.

Finally, you can choose whether to connect to the first available mixer. On most systems, you want to leave this option checked, but if you have several audio cards and want to choose one that's not the default, you can uncheck this option.

Ambisonics and JACK

The JACK components of jReality have only been tested on Mac OS X and Linux (a Windows port is available, but we haven't yet had an opportunity to evaluate it). They may require some initial setup but are worth the effort, especially if you have a 3D speaker rig that goes beyond mere surround sound.

Ambisonics Basics

Ambisonics is a multichannel replay technique that is capable of producing an isotropic 3D sound field. An Ambisonics setup consists of an encoder that generates the so-called B-signal (a four-channel signal that carries both audio and spatial information) and an Ambisonics decoder that reads the B-signal and converts it into signals for the speaker rig. The B-signal is independent of the speaker configuration, and the decoder only depends on the speaker configuration.

The JACK components of jReality render the B-signal, and they need to plug into an Ambisonics decoder that is configured for the local speaker rig. This configuration only needs to be done once, and will remain the same across all Ambisonics applications.

jReality comes with a simple JACK stereo decoder, mostly for testing purposes. For serious applications, you probably want to use Fons Adriaensen's ambdec. Any Ambisonics decoder needs to be calibrated for your specific speaker setup. Doing this well takes a some work, but you only have to do this once, and your reward will be a 3D isotropic sound sphere.

JACK Basics

JACK is a professional-grade system for handling real-time, low latency audio, similar to ReWire but free. It has many appealing features; the most important one from our point of view is that it provides a simple and powerful way of connecting various different bits of audio hardware and software. In particular, it allows us to route the B-signal generated by jReality to a decoder like ambdec. Please refer to the JACK documentation for your operating system for details on how to install and configure JACK.

Starting the JACK Components

Make sure that the JACK server and an Ambisonics decoder are running. Open the audio preferences and choose either 3D first-order or 2D second-order Ambisonics. Under JACK Options, you can choose the client name under which the out ports of your application will appear; the default name is an acceptable choice in almost all cases. In addition, you can specify a target, i.e., a regular expression that specifies the name and ports of the JACK client that belongs to your Ambisonics decoder (for ambdec, the target string should be ambdec.*in). If you specify a target, jReality will attempt to automatically connect its output ports to the input ports of the target. The remaining parameter, the number of retries after zombification, plays no role on most modern systems; you will only need to change it if your computer has trouble launching the audio backend within the time constraints imposed by JACK.

When you click on Apply, your jReality application will launch the JACK backend you selected, and will automatically do so in the future.


  • When autoconnecting JACK output ports and an Ambisonics decoder for the first time, make sure that the output ports are connected to the correct input ports, and in the correct order.
  • The target string is actually a regular expression. In particular, if you want to autoconnect to ambdec, your target string should be ambdec.*in (without the quotes), to make sure that you'll only hit the input ports but not the testing port.
  • If you see a lot of zombifications of your JACK client, especially upon startup, try increasing the buffer size of JACK.