The Basics of LokProgrammer

Next step we can take, is double click on Sound Slot 4 (1-3 are kinda "Special" and are made specifically for Prime mover 1, 2 and the Horn, I will get into that at a later time.)

Sound Slot 4 should now be open, and you should be in the empty tab, and see nothing but Mute. (Mute doesn't mean Mute, it basically means Off)

Look over to the left, you should see the following:

State: A State holds information and sound, it can control lighting and motor functions as well.

Transition: This holds information on the prerequisites that are required to move throughout the "Flowgraph", it can also set global and local conditions (we will get into that later)

Container: This is a box, that can hold states, transitions and comments, used to make your project look cleaner. 

Steam Chuff Container: This is strictly used for the steam sounds on a steam project

Comment: This is a super handy little thing, you can use it to add a comment to the sound slot, or add it inside containers, use it like a sticky note, or a readme so you can keep track of what everything does. It no way effects the operation of the decoder.

Lets begin making our first sound slot! (Also, if you would like things to snap to a grid, select Edit-Align To Grid, Very useful for keeping everything organized)

1. Select "State", It should now pop up a box that says "State" on it, Click and drag it anywhere you want, maybe like 15 "dots" from Mute
   Note: locations of states do not effect the operation of the sound slot

With "State" selected, you should now see this on the left panel

Lets take a pause here to go over everything here Note: If you don't see this whole screen above, don't worry, use the scrollbar.

1. Name: Names the State Note: State names, and Container names, cannot be repeated on the main flowgraph or a container

2. Sample: When you add a sound to the project, you use this to select what sound this state will play

3. Cylinder and Speed: used on steam files for chuffs depending on where the cam sensor or decoder is currently at during the rotation of a wheel

4. Loop: Loops a state (THIS IS A VERY IMPORTANT CHECKBOX! THIS CAN MAKE OR BREAK A SOUND SLOT We will cover the use later.)

5. Min/Max: If loop is not selected, this defines the min or max amount of times a state will be looped before transitioning to the next state

6. Volume (Min/Max/Delay) These values effect the volume of a sound slot depending on speed. Delay is the amount of time it takes before the volume is changed. 

7. Pitch Range (Min/Max/Steps/Filter) Changes the pitch of a state depending on speed, sets the minimum pitch and maximum pitch. Steps and Filter are still a mystery to me. If you know exactly what they do, please let me know.

8. ESU Smoke (Preset/Fan/Filter/Temp/Steam Chuff) Used on both steam and diesel sound slots to control smoke output when the state is active

9. ESU Fan Control (Reverse/Fan/Filter) Used on Steam and Diesel sound slots to control fan speed on a smoke unit.

10. Flags
    Restore: Check this if the decoder was currently in that state, and experienced a loss of power, it will resume at that state
    DriveLock: When the state is active, the motor will be locked at whatever speed the locomotive was moving (Similar to the Drive Hold function)
    DriveStop: When the state is active, the locomotive will come to a stop, and not be able to move until deactivated (Similar to a brake function)
    Abort: When the state is active, it instantly mutes the sound slot, regardless if there is a transition from it to mute.
    DriveSlow: Does not allow the motor to stop when the state is active

11. Mapping
    Output: Enables physical outputs, regardless of their mapping in the function map table (Lights, and anything connected to aux) when this state is active, Commonly used to control multi color class lights on one function (Scaletrains, Rapido etc)
    Logical: Enables a logical function when the state is active, you can click on this and read through the list if you want.
    Sound: This will make the state activate another sound slot while the state is active. Can be utilized where, lets say if you have emergency brake active, it will also trigger the sand sound slot. 

Okay, so now you have a rundown of the different State Properties. For this demonstration download this ZIP, unless you already have some sounds in mind. (These are ESUs Civil Defense Siren sounds) Also note, This process is similar to how you also add and set up custom horns.

So, first thing you want to do is extract the sound files from that ZIP to somewhere handy, like your desktop. There are multiple ways to add these sounds to your project, you can click and drag them to the lower right pane, or at the top left of the window where it says "Sound" between "Programmer" and "Tools" press that, and select "Add Sound Files" and browse to it.

NOTE: Ideally sound files must be of .WAV format, Mono, 16 bit and around 31.250 kHz. If not, LokProgrammer will automatically convert, but you may loose audio quality

1. Once you have added the sounds, click on the State, and on the left side, name it "up" under the "Sample" dropdown select the sound "up.wav"

2. Create another state, name it "loop" and select the sample "loop.wav" place it about 15 dots from "up"

3. Create the last state, name it "down" add "down.wav" to it, and put this 15 dots Below "loop"

It should look something like this, all the states should turn a pale yellow color

Next step, is a very important one, adding "Transitions" These are the most crucial part of any sound slot. They contain very important information, telling the decoder what step to make next. Think of the state saying "Alright I'm done now what?" and the transition tells it where to go, or gives it multiple options to go depending on certain prerequisites. You can only activate one state at a time, multiple states cannot be activated, but you can activate another sound slot.

Click on "Transition", and draw a line from "mute" to "up" . Direction matters! Its telling the decoder which way to go after the transition.
You should now have a new little line between Mute and up, with the arrow pointing towards up. it should say 1: [true] above the line near mute, by default, it just means that regardless if the function is active or not, it will transition to up, you dont want this, because it will just play the sound slot with no control, if you click the "transition" line, or still have it selected, it will be blue, and pop this box up on the left

From top to bottom
1. Mode: There are 3 select able modes, normal means when the condition is met to transition to the next state, it will play the sound on the last state all the way through then transition, as long as the conditions are still set. Immediate means that as soon as the condition is met, it will immediately stop the sound, and move to the next state, the last one, which you wont see here, instead it goes in a container, is "exit" and that tells the decoder to completely stop the sound slot once the state meets the condition specified by the transition.

2. Order: This tells the decoder which transition is the most important in order, this is particularly important if there are multiple outgoing transitions, you typically have the most restrictive transition numbered lowest, and the lest restrictive last. This also is very important when you get the error that says "Last transition must be unconditioned" 

3. Conditions: These are requisites that must be met before the transition can take place. There are MANY to choose from. For more info visit Transitions Glossary

4.  Actions: This will set a action in the sound slot, depending on what you set in the Modifty action box. For more info visit Transitions Glossary

For now, it will be kept simple

1. Click the transition

2. Press the green + button under "Conditions"

3. In the box that comes up, under Register, find "Function" Operation will autofill to = and it should automatically select true. Click OK.
   
   

Next step is to link "Up" to "loop"

Follow the last steps outlined, except adding a condition. If you add a condition, once the sound plays through, and for whatever reason Function is no longer on, it will get stuck in up, it will also throw the warning "Last Condition must be Unconditioned" when you hit Validate. More on validate later.

And now draw a transition between "Loop" and "Down" and "Down" to Mute. Should now look like this:

Now we will test the sound slot, go ahead and do this.
1. Press Validate

2. Press Simulator

3. A bar should pop up on the bottom, press "Function" (warning: its loud, turn your sound down) and play with it a bit. You can watch the flow graph move about. You should notice a couple issues off the bat.

Here are the issues you will run into.

1. Sound wont loop

2. Sound doesn't stop if you turn the function off, it just plays through

So, Lets fix that

1. Press Simulator to stop the simulation (important step because you cant edit if its on)

2. Click on  the state "Loop" and select the box "Loop" under "Repeat Playback.

3. Stop here a moment, and select Validate, You will now have an error on loop, if you hover over the red X, it will say "Unreachable Loop" The reason for this, is because there is no instruction on what to do to exit the loop, think of it this way: You've been told to Stand up, spin in circles, and you cannot stop spinning until, I say "_____" and after that, sit down And your thinking I cant stop until you say what? How do I know when to sit down?  (Setting "Min and Max" without loop selected, will basically tell the sound to loop x amount of times then you can transition, we aren't dealing with that now, but just wanted to clarify that). 

4. Now we need to tell the sound when it can stop looping, so select the transition between "Loop to Down" and add the condition Function = False (Select the box that says true under "Value", select "False"

5. Click Validate, the red X should now go away, because now its like saying: "Stand up, Spin in circles, until I say "False", then sit down"

6. Makes sense right? Go ahead and test the function. As long as Function=True, loop will loop, and when you select "Function=False" (Or Function on/off) , and it will wind down and stop.

CONGRATS! YOU NOW HAVE A USABLE SOUND SLOT THAT CAN BE SAVED AS A TEMPLATE! 

And this is how very simple horn sounds are made.

We aren't done yet, lets get a little more involved in the project. Notice when its looping and you turn the function off, it doesn't stop? Instead it plays through, THEN stops? Lets work on the response time some.

1. Select the transition between "Loop" and Down

2. On the box on the left, to the right of "Mode" select "Immediate" it should look like this:

Go ahead and select Simulator again, and play with it, notice that now, the loop will instantly stop, and go to "Down" when you turn the function off.

Play with it some, you'll notice one thing, when you turn the function off, while it is "ramping up" it has to go through the loop state before it winds back down.

Lets fix that

1. Draw a transition, starting from "Up" and connect it to "Down" Add the Condition Function=False. 

2. Hit validate.

3. Oh no, the dreaded red X! But now it says "Unreachable Transition after 1, Last transition needs to be unconditioned"

Don't worry! This is an easy fix, remember when I said "order" is important when dealing with transitions? It can make or break a template, well you've found where they come into play, Remember this, the least restrictive always need to be the highest numbered. Basically your telling the decoder "Play "Up" and then continue to loop, unless I turn the function off" What you want to tell it is "Play "up" then if the function is off, go to "Down" if not, continue to "Loop" Just think of the decoder needing to have specific instructions on what to do, or its gonna get confused and not know what to do. Lets fix this.

1. Select the transition between "Up" and "Down"

2. Where it says "order" press the down arrow, so it now changes the order of the transition to "1", you will see this change above the transition line in the flowgraph

3. Test it, should now skip over the loop if you turn the function off, and go straight to "down" once it plays through

There you go, there's a simple sound slot to start with, When I have time, we will go over timers, users, shares and other variables that can add functionality to the sound slot!

If you found this handy, if something is wrong, you have a suggestion, or something needs clarification, let me know as well! 

Consider donating if you found this helpful so I can keep the site online!