Translation files can control how midi messages should be sent/received and how the status should be displayed on the button. Translation files can be used for Fader buttons in Control Change actions and 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. When configuring a Stream Deck action, the available screen space 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) should be displayed when the value is sent or received?

• What image (if any) should be displayed when the value is sent or received?

• Whether or not a press on the button should affect the text/image displayed on the button.

In addition, you can control how the plugin should react to incoming midi messages not defined in the translation file; ignore them or locate/use the mathematically closest defined value. 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>

The Default tag (optional) defines the default values used if the individual Step tags do not have the corresponding attribute. Apart from the useclosestvalueonreceive attribute, all the attributes are available in both the Default and Step tags. 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 value is received.

While the button is pressed, commands are sent to signal V-pot rotation. This slider affects the frequency with which these commands are sent, thereby controlling the speed with which the V-pot is turned. Fast will move the V-pot the entire span (e.g., pan all left to all right) in about .5 seconds, while slow will do the same thing in about 10 seconds, giving you better control in small movements.

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 how to configure for different scenarios.

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>

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"

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).

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;"

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. For images defined in the file to be displayed, please ensure 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"

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 that 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 corresponding to the Midi value sent. If you move the fader itself, it might get a value that differs from what can be represented through Midi.

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

Since the configuration file for a cycle button most probably only defines a subset of the 128 possible Midi values, some special logic is 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 the message will be ignored. This will probably result in the button displaying a value other than what is present in the Daw (or other Midi device). However, that's unavoidable since not all Midi values have defined entries in the file.

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

When you select a file, it is immediately parsed and checked. A green check mark will be displayed if it has the correct format. 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.

• 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 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.