Translation files can be used to control how midi messages should be sent/received and how status should be displayed on the button. Translation files can be used for Fader buttons in Control Change actions and for Cycle buttons in Control Change and Program Change actions.

Since a Midi value can range from 0 to 127, there is a need to define 128 mappings to define how each midi value should be sent, received and displayed. The available screen space when configuring a Stream Deck action is very limited so it would be awkward to edit all that information in the restricted space. To make things more manageable the only configuration required in the Stream Deck action is to reference a file that contains all the mappings. The file can be edited using the editor of your choice and once created, the same file can be used in multiple actions.

With a translation file you can define the following things for each midi value:

• If the value should be sent when the button is pressed.
• If the value should be received or ignored.
• What text (if any) to display when the value is sent or received.
• What image (if any) to display when the value is sent or received.
• Whether or not a press on the button should affect the text/image displayed on the button.

The file should be an xml file with the following format:

<?xml version="1.0" encoding="utf-8" ?>
<MidiSteps version="1.1">
  <Default send="yes" receive="yes" display="" image="" displayonsend="yes" useclosestvalueonreceive="yes"/>
  <StepValues>
    <Step value="0" display="-&#8734;" image="%documents%\MyImage.png"/> 
    <Step value="1" display="-80.4"/>
    .
    .
    .
    <Step value="126" display="5.86"/>
    <Step value="127" display="6.02"/>
  </StepValues>
</MidiSteps>

Behavior

The Default tag (which is optional) defines the default values that will be used if the individual Step tags does not have the corresponding attribute. Apart from the useclosestvalueonreceive attribute, all the attributes are available in both the Default tag and in each Step tag. An attribute in a Step tag always takes precedence; if the Step tag does not define a specific attribute, the corresponding attribute in the Default tag is used. The useclosestvalueonreceive attribute defines the generic plugin behavior whenever any midi vaule is received.

Attribute	Default value	Description
send	yes	yes/no. Defines if a value should be sent when the button is pressed. The default behavior is to send each Step value that is defined in the file. If you want to exclude a few values you can keep the default to yes and set send="no" on the values that should be ignored when the button is pressed. If most of the values should be ignored you should set the default value to no and set send="yes" on the steps that should be sent. A Cycle button cycles through only the values that are defined to be sent (when pressed) but can show state for additional values if they are defined to be received.
receive	yes	yes/no. Defines if a value should be handled when received on the midi in port. The default behavior is to handle every value that is defined in the file (see also useclosestvalueonreceive). If you want to exclude a few values you can keep the default to yes and set receive="no" on the values that should be ignored when received. If most of the values should be ignored you should set the default value to no and set receive="yes" on the steps that should be received.
display		The text to display when the value is sent or received. Text is displayed when the button is pressed if send="yes" and displayonsend="yes". The text is displayed when the value is received if receive="yes". (please see formatting guidelines below).
image		The path to the image to display when the value is sent or received. The image is displayed when the button is pressed if send="yes" and displayonsend="yes". The image is displayed when the value is received if receive="yes". (please see path guidelines below).
displayonsend	yes	yes/no. Defines if the button text/image should be affected when the button is pressed to send the value.
useclosestvalueonreceive	yes	yes/no. Defines how to handle the situation when a midi message is received with a value that is not defined to be received in the file. yes means that the step with the mathematically closest value in the file will be used instead. When calculating the closest step, only steps that explicitly or through the default attribute are set to receive="yes" are included. no means that the received value is ignored. Please note that this attribute is not available for the individual steps, it can only be defined in the Default tag and controls the overall logic when receiving midi data.
The following settings are used if no Default tag is defined in the file: <Default send="yes" receive="yes" display="" image="" displayonsend="yes" useclosestvalueonreceive="yes"/> Please see the Scenarios section below for description of how to configure for different scenarios.

Additional features for Cycle buttons

When used on a Cycle button, some additional attributes are available to control the behavior of the Cycle button. These attributes define if the button should jump or glide between values and if direction indicators should be superimposed on the button image.

<?xml version="1.0" encoding="utf-8" ?>
<MidiSteps version="1.1">
<Default send="yes"
       	receive="yes"
       	display=""
       	displayonsend="yes"
       	useclosestvalueonreceive="no"
       	directionupimage="%plugin%\Images\CycleDirections\Dark\Up_Top.png"
       	directiondownimage="%plugin%\Images\CycleDirections\Dark\Down_Bottom.png"
       	glideuptime="2000"
       	glidedowntime="2000"/>
  <StepValues>
	<Step value="0" display="0" image="%trevligaspel%\icons\Generic.png"/>  
	<Step value="64" display="64" image="%trevligaspel%\icons\Generic_Active_Green_Fade.png" glideuptime="200"/>
	<Step value="127" display="127" image="%trevligaspel%\icons\Generic_Active_Red_Fade.png" glidedowntime="200"/>
  </StepValues>
</MidiSteps>

Attribute	Default value	Description
directionupimage/ directiondownimage	None	(Control Change and Program Change buttons) Paths to images that will be superimposed on the background image to indicate the current direction of the button.
glidetime/ glideuptime/ glidedowntime	0	(Control Change buttons only) Time (in milliseconds) for the transition from the current value to the next. The default value (0) will cause an instant jump to the next value. Any value greater than 0 will cause the plugin to fade/glide gradually from the current value to the next over the period defined. glidetime is used when moving from the current value to the next or previous step in the list, depending on button direction. If the same time can be used in both directions, this parameter can be used. If different times are needed when moving up or down, you need to use the following parameters. glideuptime is used when moving from the current value to the next value in the list (in the direction from the first step and forward, button direction = up). glidedowntime is used when moving from the current value to the previous value in the list (in the direction from the last step and backwar, button direction = down). If these attributes are defined on individual steps, the values from the current step are used when determining how to get to the next step. For version 2.5.0, the documentation incorrectly stated that glideuptime was used to glide to a higher value and glidedowntime to a lower value. The correct statement is that glideuptime is used to glide to the next step in the list going up (in the direction from the first step and forward), while glidedowntime is used to glide to the previous step in the list going down (in the direction from the last step and backward).
The following settings are used if the attributes are not defined in the Default tag in the file: directionupimage="" directiondownimage="" glidetime="0" glideuptime="0" glidedowntime="0"

Step

Each Step represents one value on the Midi channel and 128 values are possible (0-127). The value attribute must contain the numerical midi value for which the defined attributes should be used. The remaining attributes are optional; if an attribute is defined in the Step that value is used for the step, if an attribute is omitted the value from the Default tag is used.

---

• For Fader buttons all 128 values are expected to be defined and if a step is missing in the file it is handled as if the step was defined with a display value equal to the midi value. The Steps may be defined in any order but I recommend defining them sequentially to make it easier to find an entry if you want to change it.
• For Cycle buttons, the Midi values you want to cycle through should be defined, in the order you want to cycle through them. In addition, you can optionally define the attributes described under "Additional features for Cycle buttons" above.
• For the Note On/Off action (where it isn't associated with a specific button type), only the Midi values you want to display a text/image for when received should be defined.

There must be no duplicates (i.e. multiple Step entries with the same value attribute).

Formatting guidelines

In an xml file some characters are reserved for the xml structure itself, and you must not use those characters when defining display attributes. If you want to have any of the following characters displayed on your buttons, please use the following replacement strings (without the quotes):

• To display the < character, please use "&lt;"
• To display the > character, please use "&gt;"
• To display the & character, please use "&amp;"
• To display the " (quote) character, please use "&quot;"
• To display a line feed, please use "&#xA;"

Image path definition

Please note that images defined in the Stream Deck editor (for the action) always take precedence. If you define an image in the editor, you will always see that image regardless of what you define in this file. In order for images defined in the file to be displayed, please make sure that no image is defined in the editor.
If you define images in the translation file you need to have an image defined for every step (explicitly or through the Default tag); the default Stream Deck image will be displayed for steps without images and you probably don't want that (and as stated above - you cannot change the default image since that image will then be used for all steps).

The full path to images must be defined. To simplify path definitions, replacement strings can be used enclosed by % characters.

• All environment variables defined on the computer can be used, e.g. %appdata%
• Use %trevligaspel% to get the path to the Trevliga Spel folder in your Documents folder
• Use %documents% to get the path to your Documents folder
• Use %music% to get the path to your Music folder
• Use %plugin% to get the path to your plugin folder

Examples:
Windows
image="%appdata%\Elgato\StreamDeck\Plugins\se.trevligaspel.midi.sdPlugin\Extras\Icons\Generic.png"
image="%plugin%\Extras\Icons\Generic.png"
image="%trevligaspel%\MyImage.png"
Mac
image="%plugin%/Extras/Icons/Generic.png"
image="%trevligaspel%/MyImage.png"

Step resolution, fader buttons

The target fader might have a higher resolution than what the Midi protocol can support, i.e. a fader can have many more intermediate values than the 128 levels than can be set through Midi. If you set the fader value with the Stream Deck button, the fader value will be set to exactly the value that correspond to the Midi value sent. If you move the fader itself, it might get a value that differ from what is possible to represent through Midi.

Example: A Cubase volume fader will show -2.36db if midi value 87 is sent, and will show -2.16db if midi value 88 is sent. It is fully possible to move the fader in Cubase to have a value in-betweeen those two values and in such a case you will have a slight difference between what the Stream Deck button display and what the actual fader display (Cubase will send midi value 87 or 88 and the plugin will display the associated value). This is not an error, it is just a consequence of the midi resolution.

Step resolution, cycle buttons

Since the configuration file for a cycle button most probably only defines a subset of the 128 possible Midi values, there is some special logic involved in handling incoming Midi messages. If the incoming Midi value is not defined in the configuration file, the useclosestvalueonreceive attribute will control whether the entry with the (numerically) closest value will be selected or if the message will be ignored. Most probably this will result in a situation where the button displays another value than what is present in the Daw (or other Midi device), but that's unavoidable since not all Midi values have defined entries in the file.

File selection

To select a translation file, click on Select file... (or the file name if you already have a file referenced).

When you have selected a file it is immediately parsed and checked. If it has the correct format a green check mark will be displayed. If there is something wrong with the file (e.g not being an xml file or if the file format is incorrect) there will be a warning icon. If you hover over the file name you will get a tooltip with a short note of the problem.

If you get an error for a file you have edited, try to open the file in a browser - if there is an xml format error in the file, the browser will tell you where that problem is. You can also check the plugin log file where more details about the problem can be found.

Once a file is attached to an action, the plugin will automatically keep track of changes made to the file. If you edit and save the file the changes will be applied immediately, there is no need to re-attach the file or refresh anything.

Where to store translation files

• Template and example files are installed with the plugin (at "%appdata%\Elgato\StreamDeck\Plugins\se.trevligaspel.midi.sdPlugin\Extras\TranslationFiles" or "~/Library/Application Support/com.elgato.StreamDeck/Plugins/se.trevligaspel.midi.sdPlugin/Extras/TranslationFiles"):
• An empty translation file template ("TranslationFileTemplate.xml").
• An example file showing db values for Cubase faders ("CubaseFader db.xml").
• An example file showing Program names for Program Change buttons ("ProgramTranslations.xml"). You might want to adjust the font and/or the font size if you use this.
• If you use these files unchanged you can reference them in the installed location.
• If you want to edit the example files or create your own files from the template files you should save them to a new location, otherwise your changed files will be replaced when a new version of the plugin is installed. I highly recommend storing everything related to the plugin in the Trevliga Spel folder in your Documents folder; create the folder if you don't have it yet.

Scenarios

I have translation files already configured for the previous version of the plugin, what do I need to change?

Nothing. The default values used are exactly the same as in the previous version so "old" translation files can be used unchanged.

I want a button that always send the same value but that shows different status based on incoming midi messages.

Create a translation file where a only a single Step tag has a send="yes" attribute.

• In the Default tag, define send="no" receive="yes". That way, all Step entries that not explicitly set send="yes" will be ignored when the button is pressed.
• In the Step tag for the value you want to send, define send="yes". A cycle button with a single Step entry available for send will act as a Push button.
• If you don't want the button press to change the button text/image, set displayonsend="no" for the Step.
• Configure the rest of the Step entries as required to show the texts/images you want for each incoming midi message.

I want a button that only shows status based on incoming midi (but does nothing when I press it).

Create a translation file where no Step tag has a send="yes" attribute.

• In the Default tag, define send="no" receive="yes".
• Configure all the Step entries as required to show the texts/images you want for each incoming midi message.

I have two buttons that should send/listen on the same midi port but should act/react within separate intervals of the midi value range. (could e.g. be to listen for Program Change messages to display articulations)

Create two translation files where the defined Steps cover the appropriate value interval and set send/receive attributes as required in each file.

• In the Default tag for both files, define useclosestvalueonreceive="no". This will force the plugin to ignore the incoming midi messages with values not defined in the used translation file for the button.
• Configure all the Step entries as required to show the texts/images you want for each incoming midi message and to send the values required when pressed.

I want to have a Program Change action that show specific images for some values but a generic image (like: just background for the text) for most incoming midi values.

In the Stream deck editor, Program Change actions has a single image only and the default image is not suitable as background for texts. You cannot change the image in the Stream Deck editor if you want to use other images for some values since a user defined image in the Stream Deck editor always take precedence.

• In the Stream Deck editor, keep the default image for the action (otherwise Stream Deck will ignore the attempts from the plugin to set images based on the settings in the file).
• In the Default tag, set image="path to image" where you define the image for steps that not explictly define an image (i.e. that has no image attribute at all).
• For steps that should use the default image, remove the image attribute (i.e. remove the complete image="" declaration).
• For steps that require a different image, define the image attribute and set the path to the appropriate image file.

I want to have two buttons where one glide from A to B, and the other glide from B to A (e.g., to fade between two distinct volume levels).

There are a couple of ways you can do that, and I recommend using a single translation file like this:

• Reference a translation file like the one below from two buttons.
• Temporarily enable manual direction switch on the button that should glide down.
• Switch the direction on that button.
• Disable the manual direction switch on the button.
• Done.

<?xml version="1.0" encoding="utf-8" ?>
<MidiSteps version="1.1">
  <Default send="yes" receive="yes" display="" glidetime="8000" displayonsend="yes" useclosestvalueonreceive="no"/>
  <StepValues>
    <Step value="0" display="0" />
    <Step value="108" display="108"/>
  </StepValues>
</MidiSteps>

• trevligaspel@gmail.com
• User forum
• Youtube