search JMRI:

Common Tools

JMRI provides powerful tools for working with your layout.

• Turnouts
• Lights
• Sensors
• Throttles
• Consisting
• Signaling
• Blocks
• Reporters
• Memory Variables
• Routes
• LRoutes
• Sections
• Transits
• Logix
• Fast Clocks
• Speedometer
• Audio
• ID Tags
• LogixNG
• Timetable

System-specific Tools

• Acela (CTI)
• C/MRI
• CAN
• MERG CBUS
• DCC++
• EasyDCC
• ESU ECoS
• Grapevine
• LocoNet (Digitrax)
• Märklin
• NCE
• OpenLCB
• RPS
• SPROG
• XBee
• XPressNet (Lenz)

Layout Automation

JMRI can be used to automate parts of your layout, from simply controlling a crossing gate to running trains in the background.

• Signaling
• Entry Exit (NX)
• Warrants
• Dispatcher
• Routes
• Fast Clocks
• Scripting

JMRI: Audio Documentation

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.

Audio Table controls

Below the Audio Table are two buttons, named "Add Source..." and "Add Buffer..." to create new Audio objects.

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.

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

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.

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:

Mac OS X

Those versions of 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.

---