JMRI: Audio

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

The Audio Table

The Audio Table lets you see what audio objects have been defined, and what information they currently contain. From the table, you can create a new audio object.

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 modifed by changing 'Meters per unit', all distance and velocity units are measured in real-world meters.

Only one Audio Listener can exist.

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.

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.

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 behaviour is for the volume of an Audio Source to be altered by the distance from the Audio Listener. This behaviour 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 utilise 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

A Logix can be defined to control audio objects. Currently, it is possible to play, pause, stop, rewind, fade-in and fade-out audio sources.

Using Audio Objects with Scripts

You can 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.

Technical details

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 system.

Mac OS X

Those versions of Mac OS X that are suitable for JMRI already have a suitable version 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 Creative Labs 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.

---