Option files

Program Change and Control Change commands send a single number in the range 0-127. To select which number to send, the actions have dropdowns with "standard" lists:

  • The Program Change action displays a list based on General Midi programs.

  • The Control Change action displays a CC list maintained by the MIDI Association.

When you select an entry in a dropdown, the name displayed is irrelevant to the plugin and the target system. What you select is just the number that should be sent; the names in the dropdown are there to make it easier for you to pick the correct number. The default lists presented in the dropdowns may not make any real sense in your environment, and to enable dropdowns that more accurately reflect your environment, you can define your own dropdown lists.

Another situation when custom dropdown content is helpful is when using the Note On/Off action to control articulation. You can use the normal note values in the Key dropdown to select a specific articulation (depending on the settings in the target VST), but that isn't very intuitive. It is possible to prepare a custom list of articulation names to be used instead to simplify selection.

Custom dropdown lists for the Program Change, Control Change and articulation commands are defined in xml files. Template files are present in the plugin folder, and these files must be copied to the subfolder Trevliga Spel in your Documents folder before making changes to them (do not edit the files in the plugin folder):

  1. If you haven't done so, please create the folder Trevliga Spel (case sensitive) in your Documents folder.

  2. Copy the files you want to use/change (ControlChangeOptions.xml, ProgramChangeOptions.xml and ArticulationOptions.xml) from the plugin folder (Extras/OptionFiles) to the Trevliga Spel folder. The file names must be kept unchanged and reference the action that will use the file.

  3. Edit the files as appropriate according to the guidelines below

The files have the same syntax with the following format:

<?xml version="1.0" encoding="utf-8" ?>
<options>
    <option value="0" name="[0] Acoustic grand piano"></option>
    <option value="1" name="[1] Bright acoustic piano"></option>
    <option value="2" name="[2] Electric grand piano"></option>
    <option value="3" name="[3] Honky tonk piano"></option>
    .
    .
    .
    <option value="125" name="[125] Helicopter"></option>
    <option value="126" name="[126] Applause"></option>
    <option value="127" name="[127] Gunshot"></option>
</options>

Behavior

If an xml file (with correct syntax) is present in the Trevliga Spel folder, the content of that file will be used in the Command/Program/Note dropdown in the corresponding action. All buttons of the type (Control Change, Program Change or Note On/Off in articulation mode) will use the same dropdown content.

Each option row defines one entry in the dropdown:

Attribute

Description

value

This value (in the range 0 - 127) will be sent by the plugin when the button is used, optionally with an extension string to get the value attribute unique. There must be no duplicates, i.e., multiple option rows with the same content in the value attribute.

  • In its simplest form, the value attribute should contain a single integer value (e.g., "10").

  • If multiple options with the same number are needed (very likely when controlling articulations), you must add extensions to make the value attribute unique. The extension is a dot followed by any text that makes this value attribute unique (e.g., "10.brass", "10.strings"). The text after the dot has no meaning to the plugin other than making this attribute unique.

name

The text to be displayed in the dropdown (please see formatting guidelines below). There is no requirement that the texts be unique, but if you have the same text on multiple entries, it is hard to know exactly what you have selected.

The option rows can be sorted any way you like. All 128 numbers are not required to be defined in the file; if you need only a subset of the available commands, you can define a file with those entries only.

Advanced configuration

The file format, as defined above, will create a continuous list of entries. There is an advanced option to create dropdown lists with grouped entries. The trick is to enclose a group of option rows in optiongroup tags:

The grouping is for display only - you cannot select the header of a group.

<?xml version="1.0" encoding="utf-8" ?>
<options>
  <optiongroup name="Group 1">
    <option value="0" name="[0] Bank select (coarse)"></option>
    <option value="1" name="[1] Modulation wheel (coarse)"></option>
    <option value="2" name="[2] Breath controller (coarse)"></option>
  </optiongroup>
  <optiongroup name="Group 2">
    <option value="125" name="[125] Omni mode on"></option>
    <option value="126" name="[126] Mono operation and all notes off"></option>
    <option value="127" name="[127] Poly operation and all notes off"></option>
  </optiongroup>
</options>

A comment on articulation

Each DAW configuration is unique regarding which VSTs and articulations you use, and it is impossible to deliver a file that is valid for every (...or any...) configuration. The template file ArticulationOptions.xml is just an example of the recommended way of structuring the file and will give you several groups with default articulations for some VST instruments. It is very likely that you must edit this file to get a list of articulations relevant to your configuration.

The value attribute must contain the actual midi value to send regardless of the Middle C configuration of the VST. If the VST has "C0" assigned to a specific articulation, you must enter either 0, 12 or 24 in the value attribute (with an optional extension) depending on whether the VST uses C5, C4 or C3 as Middle C. If you are uncertain what value to use, configure a Note On/Off button with a normal key dropdown that triggers the articulation, and check the value for the selected key (the number before the key name in brackets).

When using the articulation file, the value attribute is used to identify the selection (i.e., the plugin "remembers" your selection using the value attribute). The attribute is used to select the correct articulation the next time you open the button in the editor, which is why it must be unique. If you have configured the file in one way and later choose to change extensions for several options, please remember that all buttons referencing these options will lose their selection. (If you have several attributes with a ".strings" extension and later add a second string VST, you may be tempted to change the initial ".strings" to something else to get a better distinction between the extensions. Please don't :-) )

From a strict Midi point of view, there is no difference between, e.g., "10.Strings" and "10.Brass" - both will cause the Midi value 10 to be sent to the active track on the connected Midi channel. If the selected track in your DAW listens on that channel and has a VST with an articulation associated with midi value 10, it will trigger when you press the button regardless of which selection you have made. The purpose of having different selections is to have each selection associated with its VST (=the group header in the dropdown list) and to enable different articulation names in the dropdown depending on VST.

Formatting guidelines

In an xml file, some characters are reserved for the xml structure itself, and you must not use those characters when defining texts. If you want to have any of the following characters displayed in the dropdowns, 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;"