VSD_Config_File_Definition

This page attempts to describe the structure and content of the VSD File's "config.xml" configuration file, the key to creating sounds through the Virtual Sound Decoder.

The VSD Config File is in standard XML, and the corresponding XML Schema is included with the JMRI package (in xml/schema/vsdecoder/vsdecoder-config.xsd).

This page describes Version 1.0 of the file. Additional features may be added under the 1.x class, so long as it remains backward compatible. If I need to change something that breaks backward compatibility, I will increment the major version number.

The following is a top-down breakdown of the elements within the config file.

• Config File Top Level
• Profiles
  • Sound Events
    • Triggers

Config File Top Level

The top level contains an optional JMRI version information block, followed by one or more Profiles.

<vsdecoder-config>

    <jmriversion>
        ...
    </jmriversion>

    <profile name="Profile A">
        ...
    </profile>

    <profile name="Profile b">
        ...
    </profile>

    ...

</vsdecoder-config>

Profiles

A VSDecoder Profile describes a specific locomotive model's sounds. For example, there might be a Profile for an EMD GP7, another profile for any EMD 567-engined Diesel, a third profile for a 2-cylinder light steam engine, and so on. The model defined by the Profile may be as generic or as specific as the designer chooses, and the designer may include as many or as few Profiles as he likes. Profiles are independent of each other, and may share common WAV files (even if they use them differently).

A Profile has the following attributes:

name
Name of the profile. Used to fill out the combo-box in the user interface.

A Profile has the following elements (described in detail later):

default
if present, indicates that this is the default Profile for this VSD file. Should be specified for exactly one Profile within the file.
sound-event
A "user-touchable" sound event - "bell", "horn", "coupler connect", "air brake release", etc. Including engine sound. Specifies what user actions cause the sound to happen, but not what audio to play in response.
sound
A specific collection of WAV files that produces the desired sound. A "sound" is triggered by a "sound-event".

    <profile name="profile-name">

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

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

    ...

    <sound name="sound-X">
        ...
    </sound>

    <sound name="sound-Y">
        ...
    </sound>

    ...

    </profile>

Sound Events

The Sound Event describes how the outside system (throttles, GUI buttons, etc.) causes each sound effect to happen. It contains the following parts:

• A Button - a (possibly complex) GUI element that allows the user to directly control the sound effects
• One or more Triggers - rules that define what external events cause the sound effect to happen.

A Sound Event has the following attributes:

name
Name of the sound event.
label
Text label for the Sounds pane button
buttontype
Type of the Sounds pane button to implement

The buttontype attribute has three available types:

• MOMENTARY - a momentary button (press-on, release-off... useful for horns or whistles)
• TOGGLE - a toggle button (press-on, press-off... useful for bells)
• ENGINE - a special complex type for use with Diesel or Steam engine sounds.

  <sound-event name="sound-event-name">
  
  <trigger name="Trigger X">
      ...
  </trigger>
  
  <trigger name="Trigger X">
      ...
  </trigger>
  
  ...
  
  </sound-event>
  

Triggers

Triggers are the real heart of the action. The Trigger maps an external event (e.g. throttle button press or speed change) to a specific sound. Each sound event can have any number of Triggers, mapping multiple (and complex) events to the corresponding sound.