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