JMRI® is...
Tools
JMRI tools for working with your layout:
Layout Automation
Use JMRI to automate parts of your layout and operations:
Supported Hardware
JMRI supports a wide range of DCC systems, command stations and protocols.
Applications
By the community of JMRI.org:

JMRI Help:

Contents Index
Glossary FAQ

Donate to JMRI.org

Virtual Sound Decoder


VSD File and Configuration

The VSD File is a ZIP archive containing all of the source audio files, plus a Configuration File that tells the Virtual Sound Decoder when and how to use the sound files, plus a License information file license.txt.

An example VSD file is included with the package, more examples are available for download on the web and you can make (and share!) your own.

To open a VSD File you may have to rename the file extension "vsd" to "zip" first.

A general overview of the VSD file and its components can be found here.

Configuration File

The config.xml file can be created or edited using a standard text editor or a XML editor.

A value in XML is described as a tag, e.g. <gain>0.8</gain>.

The following sections present important required elements and some optional elements. Most are documented as tags, so you can copy and paste it into your config.xml file, if desired.

Required configuration elements

Structure of config.xml for all locomotive types:

      <vsdecoder-config>

          <profile name="...">

              <sound-event name="ENGINE" ...>
               ...
              </sound-event>

              <sound name="ENGINE" type="...">
               ...
              </sound>

          </profile>

      </vsdecoder-config>
      

Note: the config.xml file can contain one or more profiles

Remarks:

Top-speed is the prototype maximum speed in mph.
Driver-diameter is the diameter of the prototype driver wheel in inches.

Optional configuration elements

Auto-Start Engine

Description:
Beside the "Auto Start Engine" option in VSD Preferences you may want to use this advanced option in your config.xml. Since this option is allowed per Engine, you could have auto-start-engines and non-auto-start-engines side by side.
Optional. Must be declared in the tag sound name="ENGINE". Default value: "no"
Since JMRI 4.11.3

Example:

      <auto-start>yes</auto-start>
      
Engine Start and Stop by a throttle key

Description:
If desired, you may define a throttle button to start and to stop the engine sound.
Optional. Must be declared in the tag sound-event name="ENGINE".
Since JMRI 4.11.4

Example:

      <trigger name="ENGINE_STARTSTOP" type="THROTTLE">
          <event-name>F4</event-name>
          <target-name>ENGINE</target-name>
          <action>NOTHING</action>
      </trigger>
      

Action "STOP_AT_ZERO":
With the example above you can stop the engine at any speed. Using the action "STOP_AT_ZERO" instead of "NOTHING" prevents the engine from stopping if the speed is not zero.
Since JMRI 4.19.2

More throttle key functions: Brake-Key, Half-Speed-Key and Coast-Key

Description:
Trigger name for Brake-Key: BRAKE_KEY
Trigger name for Half-Speed: HALF_SPEED
Trigger name for Coast-Key: COAST
All these Triggers are intended for Engine type "steam1".
Optional. Must be declared in the tag sound-event name="ENGINE".
Since JMRI 4.13.3

Important note on Brake-Key and Half-speed: Please setup those keys in Virtual Sound Decoder only, if your DCC decoder supports such features and can be set likewise.
Using a Brake-Key depends on the specification of your DCC decoder. Some DCC decoder support a brake time, which is an optional deceleration-rate and lower than the original one. I recommend to use a throttle key with momentum behavior as the Brake-Key. Don't forget to set the deceleration-rate (both in VSD and in your DCC decoder) to a high value, e.g. 250. If you want to define a brake time in VSD, please do declare (e.g.):

      <brake-time>30</brake-time>
      
Acceleration-Rate and Deceleration-Rate

Description:
Allows to set an acceleration-rate and a deceleration-rate for Engine type "steam1". Please note that it is necessary to set the accel-/decel-rates for your DCC-Decoder likewise.
Optional. Must be declared in the tag sound name="ENGINE" type="steam1". Default value: 35 / 18
Since JMRI 4.13.3

Example:

      <accel-rate>35</accel-rate>
      <decel-rate>18</decel-rate>
      
Reference Distance

Description:
It's recommended to setup this value for each sound tag. The reason for this is the sound attenuation model of OpenAL. Sounds with distance to listener position lower than reference-distance will not have any attenuation and the volume of the Audio Source will be as defined by the gain setting.
Optional. Must be declared in the tag sound previous to a gain value. Default value: 1.0
Since JMRI 4.11.4

Example:

      <reference-distance>3.0</reference-distance>
      
Engine Gain

Description:
This element allows to adjust the engine gain for steam1 and diesel3 engine types.
For engine type steam1 the gain value must be in the range of 0.4 and 1.0.
Optional. Must be declared in the tag sound name="ENGINE". Default value: 0.8
Since JMRI 4.11.7

Example:

      <engine-gain>0.6</engine-gain>
      
Dynamic Gain

Description:
This element allows to activate an option for steam1 engine types.
The engine volume is raised a bit when accelerating and lowered a bit when decelerating.
Optional. The declaration should be made in the tag sound name="ENGINE" right after element engine-gain.
Default value: no
Since JMRI 4.23.6

Example:

      <dynamic-gain>yes</dynamic-gain>
      
Chuff Fade Out

Description:
This element allows to activate an option for steam1 engine types.
If active and when coasting is triggered (by a function key or by a strong deceleration) the chuffs are faded out.
This function is limited to 16-bit sounds (e.g. Class64.vsd).
For 8-bit sounds (like in Class94.vsd) please consider to resample your sound files. With Audacity, a free audio editor, this can be done by import the 8-bit sound and export as 16-bit sound.
The declaration should be made in the tag sound name="ENGINE" right after element dynamic-gain.
Default value: no
Since JMRI 5.5.5

Example:

      <chuff-fade-out>yes</chuff-fade-out>
      
Top Speed Reverse

Description:
There are steam locomotives where the maximum speed differs between forward and reverse, e.g. the German BR 38 (P8).
You can declare a maximum speed for reverse for engine type steam1.
Optional. Must be declared in the tag sound name="ENGINE" right after top-speed.
Default value: value from "top-speed"
Since JMRI 4.13.5

Example:

      <top-speed-reverse>31</top-speed-reverse>
      
Sleep Interval

Description:
Depending on the speed of the computer hardware, the timing of the loop-player (sleep-interval) can be adjusted.
E.g. I use 40 for my new computer and 55 for my Raspberry Pi 3 B+. This may help to avoid sound-restarts.
You can declare a sleep-interval for engine type diesel3 and steam1.
The value must be in the range of 38 and 55. The unit is milliseconds.
Optional. Must be declared in the tag sound name="ENGINE" before decel-trigger-rpms.
Default value: 50
Since JMRI 4.19.4

Example:

      <sleep-interval>40</sleep-interval>
      
Create XY coordinates output in console for a VSDecoder

Description:
Helpfull option to verify the setup of your VSDGeoData.xml file (see Advanced Location Following).
The JMRI System Console output can be copied and edited for printing a route curve. I have tested this with "LibreOffice Calc" and "Gnuplot".
Optional. Must be declared right after the <profile> tag.
Default value: "no"
Since JMRI 4.13.2

Example:

      <create-xy-series>yes</create-xy-series>
      

Console output:

       vsdecoder.VSDecoder      INFO  - 3(S): -1.5     1.1 [AWT-EventQueue-0]
       vsdecoder.VSDecoder      INFO  - 3(S): -1.489   1.1 [AWT-EventQueue-0]
       vsdecoder.VSDecoder      INFO  - 3(S): -1.4173  1.1 [AWT-EventQueue-0]
       vsdecoder.VSDecoder      INFO  - 3(S): -1.3456  1.1 [AWT-EventQueue-0]
       ...