JMRI: Audio DocumentationJMRI Audio objects hold information about sounds that can be played-back by the computer. 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).
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)
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.
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.
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.
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.
- 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
OpenAL may already be included with your operating system:
macOSThose versions of macOS (aka Mac OS X) that are suitable for JMRI already have a suitable version of OpenAL installed.
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.
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.