JMRI: Audio

# JMRI: Audio Documentation

JMRI Audio objects hold information about sounds that can be played-back by the computer.

- Audio Table
- Audio Objects
- Using Audio Objects
- Playing Audio

## The Audio Table

The Audio Table lets you see what Audio objects (Audio Listeners, Audio Buffers, and Audio Sources) have been defined and what information they currently contain.

#### Audio Table controls

At the bottom of the Audio Table window are buttons "Add Source..." and "Add Buffer..." to create new Audio objects. At the current time, only a single listener can be defined through the table interface (IAL$ is defaulted).

## Audio Objects

The JMRI audio framework consists of three distinct types of object:

- Audio Listeners
- Audio Buffers
- Audio Sources

### Audio Listener

The Audio Listener defines where the person hearing the sounds is located.

The defined listener position is then used to calculate the actual pan and gain of each audio source when played back.

The orientation settings define the co-ordinate system in use. The default values transpose to:

- x - left-to-right (-ve to +ve)
- y - front-to-back (-ve to +ve)
- z - down-to-up (-ve to +ve)

With the default position, 'y' values would be positive, measured from the front-edge of the layout and 'x' values to be negative to the left of the layout centre-line and positive to the right of the layout centre-line. Positive 'z' values would be measured from layout level upwards.

Unless modified by changing 'Meters per unit', all distance and velocity units are measured in real-world meters.

Only one Audio Listener can exist, and it is already present in the Audio Table where it may be configured by clicking its Edit button.

### Audio Buffers

An Audio Buffer holds the actual sound sample data.

To load an Audio Buffer with sound data, click the 'Browse...' button and select the appropriate '.wav' file.

One Audio Buffer object can be used by many Audio Sources.

NOTE: Loop Points are not yet implemented. "End" is set when an audio file is loaded and the table saved but cannot be edited.

### Audio Sources

An Audio Source controls the playback of sound sample data and controls the position.

To actually play a sound, an Audio Source must be linked to an existing Audio Buffer - choose one from the drop-down list. Buffers are allowed to be shared between Audio Sources, in which case they will be played back independently.

As with the Audio Listener, an Audio Source should be positioned in 3d-space. If required to 'move' whilst playing, set the velocity in x, y and z directions. This will move the position of the Audio Source in the direction and speed specified by the velocity vector at the defined rate while the Audio Source is playing.

Example: An 'x' value of 2 will move the Audio Source 2 units (meters) per second towards the right whilst playing.

Note: The Audio Source position is only relevant when bound to a mono buffer - those holding multi-channel sounds (i.e. stereo) will not be affected by changes in position and played as-is.

If it is necessary to turn-down the volume of a specific Audio Source, this can be achieved by changing the 'Gain' setting. Similarly, the pitch can be modified by changing the 'Pitch' parameter.

Normal behavior is for the volume of an Audio Source to be altered by the distance from the Audio Listener. This behavior can be modified by altering the Reference Distance and Maximum Distance settings. The Reference Distance determines the distance at which the volume will start to decrease - at distances smaller than the reference distance, the volume of the Audio Source will be as defined by the gain setting. The Maximum Distance determines the distance at which the volume is zero. Roll-off Factor determines the rate-of-change of the gain with respect to distance - larger values denote a faster rate-of-change.

Finally, the fade-in and fade-out times of the Audio Source can be defined - these are specified in milli-seconds. Fading-in and out of an Audio Source is achieved by using the fadeIn and fadeOut methods of the Audio Source; play, stop and pause methods do not utilize fade times.

Unless modified by changing the 'Meters per unit' parameter of the Audio Listener, all distance and velocity units are measured in real-world meters.

## Using Audio Objects with Logix, LogixNG and Scripts

A Logix or LogixNG can be defined to control audio objects. Currently, it is possible to play, pause, stop, rewind, fade-in and fade-out audio sources.
You can also directly manipulate Audio Objects with scripts. There's an example script in the distribution, along with documentation for the AudioBuffer, AudioSource and AudioListener classes that control the audio processing.

## Playing Audio

The JMRI audio framework makes use of either of the following audio libraries:

- JavaSound - for basic audio functions (limited to stereo)
  JavaSound is normally available with a Sun Microsystems Java Runtime Environment; other vendors, such as OpenJDK, do not include JavaSound.
- OpenAL - for full-featured audio functions (including support for up-to 7.1 surround)
  OpenAL may already be included with your operating system:

#### macOS

Those versions of macOS (aka Mac OS X) that are suitable for JMRI already have a suitable version of OpenAL installed.

#### MS Windows

By default, OpenAL will require installing on your system. Certain sound cards, notably those manufactured by Creative Labs and NVidia, will normally already come with suitable OpenAL drivers. If OpenAL is not installed, it should be downloaded from OpenAL.org and then installed on your system.

#### Linux

Depending on the provider of your Linux distribution, OpenAL might already be included in the default package. If not, the 'libopenal-dev' package should be installed using the package manager on your system. For Debian-based distributions, this will typically be achieved by the command:

          $ sudo apt-get install libopenal-dev

For Ubuntu, the 'Universe' repository should be enabled.