Posted by: bgtwindad | August 12, 2011

Virtual Sound Decoder for JMRI

Here’s a little software project I’ve been working on, alongside of my more “hard” modeling work.  I made a video demo, as it can be hard to express how this is all supposed to work in words.

This is the result of a confluence of several factors.

I have long wanted to have sound on my layout, but I was balking at the expense and the lack of sound quality from N scale sound decoders (this has more to do with physics and tiny speakers than the quality of the available products).  SoundTraxx had been pre-announcing their SurroundTraxx product for a while, and a couple of online friends of mine have been toying with under-the-table sound systems being driven by hardware sound decoders and larger speakers.  And I had been playing with the JMRI Java Model Railroad Interface project.

It occurred to me that I could write a software program that would emulate (or simulate, if you prefer) the function of a hardware sound decoder, listening to the layout interface for throttle commands and responding to them  just as a hardware decoder installed in a locomotive would.  And most PCs these days come with surround sound audio systems!  JMRI already provided much of the foundation for this, including the layout interface, a nice abstraction of the throttle, and integration with the OpenAL 3D audio system, so it seemed a good match.

I’ve been working on this for a few months.  The basic idea follows very roughly the scheme of an add-on sound decoder.  For each engine you want to have sound, you launch a “Virtual Sound Decoder” (or “VSDecoder”) on the PC, select a “sound profile” from a “VSD File” and assign it a DCC address.  The virtual decoder then sits in the background and generates sounds in response to the throttle inputs.  Thanks to the way JMRI handles throttles, it will respond to any throttle on the system, whether a hardware or software throttle, or a wireless-attached throttle on a PDA or smart phone.  Buttons on the VSDecoder allow the user to directly trigger sounds, bypassing the throttle if desired.

The “VSD File is somewhat like a Digitrax SPJ file, though the two are completely incompatible.  The VSD file is a Zip archive containing all of the source audio files, plus a configuration file (written in XML) that tells the Virtual Sound Decoder when and how to use the sound files.  Each VSD File can contain one or more “Profiles”, each of which describes a specific configuration of a locomotive.  This could be multiple variants of a particular type of locomotive, or several completely different types of locomotives. For example, a VSD FIle might contain profiles for several different EMD engines based on the 567 Diesel prime mover, or an eclectic collection of engines belonging to the Pennsylvania Railroad.  VSD Files can be easily constructed by and shared among folks who are interested in doing so.

Work progresses steadily, and I hope to have a version of this included in the 2.13 development release of JMRI at some point.  In the meantime, if you are interested in developing or providing sound files, let me know!



  1. I love your vsd project! I watched the video, and eagerly wait to see it available. I wish I knew anything about coding so I could help, but sadly my skills are only good enough to use such software, not write it.

    I use Engine Driver to run Z Scale trains with the BAZ BoyZ at shows and at the TCSME N Scale layout, and would love to run sound using your VSD files through decoder pro.

    If you are looking for a windows Alpha tester, I would be overjoyed to help, alternately, if you want to trade skillsets, I would be happy to do custom laser cutting to help populate your layout in trade.

    -Robert Ray

    • Thanks, Robert!! I appreciate the compliments.

      We do have plans to port some portion of this function to EngineDriver, and possibly to the iPhone as well. Most likely you’ll be able to choose a VSD file that you’ve synced to your phone, and it’ll auto-key to the EngineDriver throttle (only) and play through the headphones. I suppose eventually we could stream the audio back to the phone over WiFi (so you get *all* the locos!) but that would be very bandwidth intensive for both the phone and the host PC.

      For the time being, the VSD tool should work just fine with EngineDriver as long as you are happy with the sound coming from your PC speakers.

      The basic code is now checked into JMRI, so it should be available in the next development release (2.13.2, most likely).

      As for supporting the project, I appreciate the offer. The best way to support it would be to donate directly to JMRI, either through testing, documenting, or financially.

  2. […] It’s a new development in JMRI, being coded by an N-scale modeller calling himself TwinDad. The Virtual Sound Decoder (or VSDecoder) runs on a PC and emulates (or simulates) the function of an actual sound decoder. It […]

  3. Hello,
    I am very interested in the vsd project. I haven’t tried it on my layout yet but I have been playing with it virtually. I am working on making my own sound package and I am getting an error about the file not containing config.xml even though it does. Is there a way I can contact you to ask about it? I am running 2.13.2 on Windows 7.

  4. Just a short note to say “thank you” for the time and effort you and others have put into the VSD project. It adds another dimension to my Z scale modeling. I have it running on both my iMac and a Dell lap top. I had a few false starts but was able it get them both running with just a couple of hours work (fun?). I understand it will NOT work with hard wired NCE throttles but it works successfully for me with the JMRI and WiThrottle using a dedicated router. I wish I were able to do some programming so that I could independently mute the sounds. I find the diesel sound a bit annoying after a few minutes but really love to play with the bell and horns. It is my plan to take the system to the December GTE show in Del Mar, CA.

    • Thanks for the compliment! I’m glad it is (mostly) working for you. I’ll see what I can do about the engine mute in a future release. That should be fairly easy to implement.

      • I had a Ralph Simpson moment. All you have to do is NOT start the engine. The bell and horn work just fine. DUH!!!!

  5. I have successfully modified a profile to include a crossing gate sound using F4. I changed a copy of the example.vsd file to a new name of I used WinZip to unzip the file, modified the config.xml file, saved it, used WinZip to compress the files and saved as I then changed the file extension from .zip to .vsd. The file worked fine.
    I used an evaluation copy of WinZip as I am too cheap to buy the software. I found a free Mac utility called iZip. iZip unzips just fine but when I compress the modified files using iZip and change the extension from .zip to .vsd, the file will not load.
    Any thoughts?
    I think you used iZip based on the icon in your demo.
    I have an iMac running OS X 10.6.8
    Thanks for the help.
    Lindley Ruddick

  6. I just stumbled about this project and this is exactly what I was looking for!
    Is there an ETA when this program might be available? I can’t find any reference to it on the JMRI site.
    Great job!


    • Virtual Sound Decoder is included in version 2.14 of JMRI, though it doesn’t have much mention on the web page yet. You’ll find it under the “debug” menu when you run either DecoderPro or PanelPro. It is still considered very much in “Beta” test, and frankly I haven’t been able to do much with it for a while. So don’t expect it to stand up to a SurroundTraxx or anything.

      • Thanks for the info!
        I just installed JMRI last night after finally plugging in my LocoBuffer II that I had bought many years ago and never used. What a rush!
        I will take a look tonight and give it a shot. The SurroundTraxx is tempting as a stand-alone unit, but the price tag is way too hefty for my taste. And buying multiple sound decoders at $70 a piece isn’t cheap either.
        Your approach is just what I had in mind. I have some coding experience and, once I get more familiar with JMRI and your implementation, maybe I can help out.


  7. TwinDad

    I have been reading about VSD with great interest and have a few questions.
    – Where are the VSD files located in the JMRI files? Searched for *.vsd without results.
    – Do I understand correctly that I could edit the config file and save it for each loco with loco specific wave files specified?
    – Can the same wave files used in SPJ be used with VSD?
    – How does VSD follow the loco around the layout?
    – I have detection and transponding but have not used Operations at this point. If Operations is required what are the minimum elements of Ops needed?
    – I have a 5.1 sound card with four speakers currently attached. What is the next step to get the sound to ‘move’ around the layout?
    – Should a 5.1 speaker system be used for the best effect?
    – Using Engine Driver how is the VSD activated?

    Any suggestions you might offer or thoughts you could share would be appreciated.

    Thank you,

    • Dave, thank you for your interest! I will try to answer your questions in turn.

      – Where are the VSD files located in the JMRI files? Searched for *.vsd without results.

      The VSD files (including the… included… example.vsd) are in the program resources directory. On a PC, this should be C:\Program Files\JMRI\resources\vsdecoder\example.vsd. On a Mac, it will be /Applications/JMRI/resources/vsdecoder/example.vsd

      – Do I understand correctly that I could edit the config file and save it for each loco with loco specific wave files specified?

      Yes. You can edit the config file, change the sounds to customize them, and save a different file for each loco, if you choose. The intended design is for the VSD to contain one or more “profiles” describing a *type* of locomotive (say, an EMD GP9), and that all of the GP9s in your roster could share that same profile. Multiple locomotives sharing a VSD profile will still have independent control of the actual sounds played (e.g. several GP9s can be at different speeds, play the horn at different times, etc.)

      – Can the same wave files used in SPJ be used with VSD?

      VSD files use standard WAV type sound files. If you have a SPJ file that contains WAV files you wish to use AND THAT YOU HAVE LICENSE TO USE, you can. You will have to create your own config.xml file to describe how to use the sounds, though. SPJ files cannot be directly translated into VSD. NOTE: You must still have PERMISSION to use the contents of the SPJ file, to create the VSD. While I cannot take responsibility for what anyone else does on their own time, I cannot and do not condone use of other people’s sounds without proper license. This especially includes reverse engineering Digitrax SPJ files. That would be a definite No-No.

      – How does VSD follow the loco around the layout?

      The plan is for the locomotive’s position on the layout to be tracked by any of a number of means, including Digitrax Transponding, regular track sensors, and user-indication of arrival at JMRI Operations Locations. At this time, only the JMRI Operations Locations support has been coded. The way this will work is that each transponding zone will be given a physical position in the X/Y/Z axes, relative to the listener position at (0,0,0) — the underlying audio framework does not yet support moving listeners — and as the locomotive “reports in” at a new transponding location, the sound will move to the new apparent source location. If possible, I would also like to add velocity and track-map following to interpolate the train’s physical location in between transponding reports. This will be a long way off, though.

      – I have detection and transponding but have not used Operations at this point. If Operations is required what are the minimum elements of Ops needed?

      Note that Operations is only required because I have not yet developed the Transponding support. Once I’ve developed the Transponding support, it will work independent of Operations.

      You will need to enable VSD support in the Operations Settings. Then you will need to define a set of Locations, and assign each a physical position on the layout. You will then need to define some Routes and Trains that follow those Routes. Then when you activate a Train, and Move the train to its next Location, the sound will (unfortunately) “jump” to that apparent location. This is obviously a VERY crude method of sound following, but it is intended only as a proof-of-concept, or for those people who do not have “better” locomotive tracking means.

      Note that you do not have to build up the car inventory or do any of the “train building” that Operations does. Merely set up the Locations, Routes, and Trains, and then move the Trains.

      – I have a 5.1 sound card with four speakers currently attached. What is the next step to get the sound to ‘move’ around the layout?

      The audio subsystem in JMRI should automatically take advantage of your 5.1 sound to position the sounds, assuming the above steps are taken to tell the software where the train is (using Operations for now, Transponding or other, better methods later). All you should need to do is properly position your speakers for best effect.

      You will then need to set up the Operations code as described above, and “Move” your “Trains”.

      – Should a 5.1 speaker system be used for the best effect?

      Actually, headphones probably give the best effect. 5.1 would be a very close second. Surprisingly decent effect can be provided with a simple pair of “computer speakers”, though.

      – Using Engine Driver how is the VSD activated?

      EngineDriver and WiThrottle appear to VSD as “just another throttle”. Once you assign a locomotive address to the VSD decoder, it should respond to EngineDriver throttle input (speed, function buttons) the same as a Digitrax hardware throttle. You cannot (yet) “launch” a VSD from any throttle, though (coming soon, I hope!). For now, you must launch the VSD decoder from the JMRI Debug menu.

      VSD sound output to your smart phone is not yet supported, but is high on the priority list.

  8. Thank you for your very detailed and complete answers. I plan to do some experimenting with it over the next few weeks.

    I appreciate all that you have put into this project and look forward to following along as it develops. And it is good to know that development is still continuing.

    Thanks so much again,

  9. General comment for all comers:

    Y’all please do keep in mind that the current implementation of VSD (as of JMRI 3.1) is little more than a “proof of concept”. It barely works at all, let alone well. I do appreciate any and all constructive feedback, but don’t expect a polished commercial product out of it. Yet. 🙂

  10. Hi there would you mind letting me know which web
    host you’re using? I’ve loaded your blog in 3
    completely different browsers and I must say this blog loads a lot quicker then most.

    Can you recommend a good hosting provider at a fair price?
    Cheers, I appreciate it!

    • It’s I just use their free blogging service.

  11. Hi…
    I have been testing the use of Bluetooth Audio Streaming using VSD as the sound source….I have had very positive results.

    My progress is here:

    I have also been in contact with Bill Francis, who I know produced some sound projects for VSD, and who has been giving me encouragement.

    I would be extremely grateful if you would please get back in touch via email as I would love to know your thoughts on my videos.

    Randall Morris

Leave a Reply

Fill in your details below or click an icon to log in: Logo

You are commenting using your account. Log Out /  Change )

Twitter picture

You are commenting using your Twitter account. Log Out /  Change )

Facebook photo

You are commenting using your Facebook account. Log Out /  Change )

Connecting to %s


%d bloggers like this: