SDF Sound File Editor

Digitrax sound decoders are loaded with "sound projects", stored in "Sound Project" (.spj) files. Those contain a number of "sound fragments" in .wav format, plus a small program that tells the decoder when to play the various sounds, and controls the use of functions and CVs. That program is stored in a "Sound Definition" (SDF) format.

The SDF Sound File Editor allows you to make certain kinds of changes to the SDF information in a sound project. It's used with the SPJ editor because the SDF information is stored in a Digitrax SPJ sound project file. After you edit the SDF information, you can save it to a file from the SPJ editor, and the download it to a Digitrax sound decoder with a Digitrax PR2 or PR3 and the JMRI sound downloader tool or the Digitrax SoundLoader program.

Digitrax provides sample sound project files at their Sound Depot (http://www.digitrax.com/sounddepot.php) web site. You can also find links to documentation and additional tools there.

When you open the SDF editor by clicking the "Edit" button in the SPJ editor, a new window opens that has two parts:

On the left is a view of the entire SDF information as a tree of nested elements. On the right is a window that shows additional information on the element that's selected on the left.

The right hand window has the "assembly" format for the selected element at the top, then an explanation of what the element does in the middle. If an editor for that particular type of element has been defined, the section at the bottom will have checkboxes and selection boxes for modifying the content of the element.

SDF Structure

Sound definitions define a series of layers that together control the decoder. By opening and closing the icons on the left side of the editor window, you can explore the structure of a sound definition. Feel free to explore! Until you save the file, you can't actually hurt anything.

Scheme

At the top level are "schemes", which are like programs for the decoder. A decoder can only be using one scheme at a time, although there can be several present in memory at once. The schemes are numbered, starting with 0, and the active scheme is selected via the contents of CV. Scheme 31 marks the end of the file.

There are no options to the scheme itself for you to edit, but you can open the scheme to work with its contents.

The first element of a scheme is a version number tag. These defines the format used to store the scheme's contents. Currently, only version 1 is a defined format.

After the version tag, one or more "channels" are defined.

Channel

The decoder hardware is capable of handling several things at once. These are called "channels", and one or more of them make up each scheme. How many there can be depends on the specific decoder hardware, but it's quite common to see four channels within a scheme.

Although all the channels can be playing sounds simultaneously, each channel can only play one sound (one .wav fragment) at a time. The purpose of the commands within the channel is to define which sounds it should play, and when they should start and end.

The channel element itself has no options for you to edit, but you can open it and work with its contents.

Sequence

Within each channel, there can be one or more sequences. Each one has a condition under which it starts, and then a series of operations to take then it's started.

The operations can be things like starting to play a particular sound, or modifying how a sound is played, or changing various information internal to the decoder. When the sequence is started, it runs right to the end, leaving behind things for the decoder to do in the future. For example, it can define which sound fragment to play next when the current one is done, or stop the sound that's currently being played by the channel and start a new one.

The sequence starts when a trigger condition becomes true. You can examine and change the trigger condition using the lower-right part of the editor frame. Some examples include:

Trigger when a function becomes true, e.g. when the user sets F1 on.
Trigger on how the decoder is controlling the locomotive, for example:
- when the motor speed increases
- when the motor direction changes
- when the motor starts moving
Trigger on other events from the outside, such as:
- when the chuff cam goes active
- when a CV is written in ops mode
- when an input connection goes active

There are a lot of possibilities, which are listed in the selection box and (partially) documented on a separate page.

There are also four options that can be selected to change when the sequense is started:

Zap
Run while triggered
No preemptive trigger
Not triggered: The sequence starts when the opposite condition happens. For example, if the trigger is "When F1 goes active", and this option is selected, the sequence will start when F1 goes inactive.

Each sequence contains one or more instructions, the last of which has to be an "End Sequence" instruction.

Instructions

Within each sequence are instructions that tell the decoder what to do as it's processing the sequence. We describe the most important ones here.

Play Fragment

Set Modifier

Examples

(Provide some fragments of code here as examples)

Status and Future Work

This editor tool is still very much a work in progress. It's good at browsing the content of the file, but it needs a lot more explanatory text added. Also, it currently only provides a way to make small changes to the contents of an SDF file, but doesn't (yet) allow you to make larger changes to structure of the file. For example, if you selected an "Initiate Sound" element, which tells the decoder to start playing a sound under certain conditions, you can change those conditions. But the editor (at present) doesn't provide a way to add new "Initiate Sound" elements.

The editor is meant to be a beginner's tool, and we need a lot of explanatory text on each window so people know what the options do.