Translation files

When using a Fader or Cycle button in a Control Change action, there is a possibility to display a value on the button. This value could be the simple Midi value sent/received or it could be a translated value (e.g. a db value for a volume fader).

Since a Midi Control Change value can range from 0 to 127, there is a need to define 128 mappings for how to translate Midi values to displayed values. 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. The file also enables each and every Midi value to have a unique icon on the button; without the file only two state icons can be defined.

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

<?xml version="1.0" encoding="utf-8" ?>
<MidiSteps version="1.0">
    <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"/>

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 display value should be used.
  • The display attribute contains whatever text information you want to have displayed for the associated midi value (please see formatting guidelines below).
  • The image defines the full path to an image file if you want a specific image to be displayed for this midi value.

  • 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, only the Midi values you want to cycle through should be defined, in the order you want to cycle through them.
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 have 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 - the default 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 %documents% to get the path to your Documents folder
  • Use %music% to get the path to your Music folder
Normally replacement strings do not end with a backslash so in order to get a correct path the rest of the path should start with a backslash, example:

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 entry with the (numerically) closest value will be selected. 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"):
    • 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 edit the example files or create your own files from the template file you should save them to a new location (e.g. your Documents folder), otherwise they will be deleted when a new version of the plugin is installed.