The <ui> element

The <ui> element is how you specify a user interface for your instrument. Each dspreset should have at most one <ui> element. There are several important attributes:

• coverArt (optional): A relative or absolutely path to a cover art image to use. After the first time this library is opened, this will get displayed on the “My Libraries” tab.

• bgImage (optional): A relative or absolutely path to a background image to use.

• bgColor (required): An eight digit hex value indicating the background color to be used for the background of the UI. This color will be drawn underneath any background image specified by bgimage.

• width (required): The width of your user interface. Recommended value: 812.

• height (required): The height of your user interface. Recommended value: 375.

Example:

<DecentSampler>
  <ui width="812" height="375">
    <tab name="main">
      <labeled-knob x="560" y="0" label="Tone" type="float" minValue="60" maxValue="22000"
                    textColor="FF000000" value="22000.0" uid="y8AA4uuURh3">
        <binding type="effect" level="instrument" position="0" parameter="FX_FILTER_FREQUENCY"/>
      </labeled-knob>
      <label x="360" y="0" width="50" height="30" text="Reverb"/>
      <control x="360" y="30" parameterName="Reverb" type="float" minValue="0" maxValue="1" textColor="FF000000" value="0.5">
      <!-- Your <binding /> elements should go here -->
      </control>
    </tab>
  </ui>
</DecentSampler>

The <tab> element

The <tab> element lives underneath the <ui> element. This architecture was chosen because we may, at some point, add support for multiple tabs. At present it is only possible to have a single tab within DecentSampler instruments. As such, every UI must have at most one <tab> element.

Attributes:

• name (optional): An optional name to be associated with this tab. This is currently not displayed anywhere.

The <button> element

The <button> element allows you to create a button within your UI. It lives underneath the <tab> element. There are two styles of buttons: text buttons and image buttons.

Attributes:

Attribute	Required	Description	Default
x	(required)	The x position of the menu	None
y	(required)	The y position of the menu	None
width	(required)	The width of the menu	None
height	(required)	The height of the menu	None
value	(optional)	The is the 0-based index of the button state that is currently selected. A value of 0 means that the first state is active.	0
style	(optional)	The type of button we want. There are two valid values: text, image.	text
mainImage	(required for image buttons)	For image buttons only. The path of the main image to display for this button. This can also be set at the state level so that it only applies to a specific state.	None
hoverImage	(optional)	For image buttons only. The path of the main image to display when the user hovers their mouse over this button. This can also be set at the state level so that it only applies to a specific state.	None
clickImage	(optional)	For image buttons only. The path of the main image to display when the user clicks down on this button. This can also be set at the state level so that it only applies to a specific state.	None
visible	(optional)	This controls whether or not this button is visible. There are two valid values: true, false.	true

Example:

<button x="10" y="40"  width="120" height="30" style="image" value="0" mainImage="samples/ButtonMainImage.png" hoverImage="samples/ButtonHoverImage.png" clickImage="samples/ButtonSelectedImage.png">
    <!-- Your button states go here -->
</button>

The <state> element

In order for your button to work, it must contain at least one <state> elements.

Attributes:

Attribute	Required	Description
name	(required for text buttons)	The text to display on a text button when this state is active
mainImage	(required for image buttons)	For image buttons only. The path of the main image to display for this button when the button is in the current state.
hoverImage	(optional)	For image buttons only. The path of the image to display when the user hovers their mouse over this button when the button is in the current state.
clickImage	(optional)	For image buttons only. The path of the image to display when the user clicks down on this button when the button is in the current state.

In order to have your <button> elements actually do something useful, you need to attach bindings to them. Here’s an example:

<button x="10" y="30"  width="70" height="50" style="image" value="0" >
    <state name="English" mainImage="samples/EFlag_MainImage.png" hoverImage="samples/EFlag_HoverImage.png" clickImage="samples/EFlag_SelectedImage.png">
        <!-- Turn on this group -->
        <binding type="general" level="group" position="0" parameter="ENABLED" translation="fixed_value" translationValue="true" />
        <!-- Turn off this group -->
        <binding type="general" level="group" position="1" parameter="ENABLED" translation="fixed_value" translationValue="false" />
    </state>
    <state name="French" mainImage="Samples/FFlag_MainImage.png" hoverImage="Samples/FFlag_HoverImage.png" clickImage="Samples/FFlag_SelectedImage.png">
        <!-- Turn off this group -->
        <binding type="general" level="group" position="0" parameter="ENABLED" translation="fixed_value" translationValue="false" />
        <!-- Turn on this group -->
        <binding type="general" level="group" position="1" parameter="ENABLED" translation="fixed_value" translationValue="true" />
    </state>
</button>

As you can see, this example uses a button to switch between two groups. You’ll note the liberal use of the fixed_value translation mode above. This means that when any of these options are selected, a fixed predetermined value is used for the value of that binding.

The <image> element

The <image> element allows you to place a static image into your user interface. It lives underneath the <tab> element. Attributes:

• x (required): The x position of your image where (0,0) is the top-left corner

• y (required): The y position of your image where (0,0) is the top-left corner

• width (required): The width in pixels of the image component

• height (required): The height in pixels of the image component

• path (required): The relative path of the image file to show in this component

• aspectRatioMode (required): Whether or not the engine should preserve the aspect ratio of the image. Note: regardless of these settings, you still need to specify a width and height for your image element. Valid values: preserve, stretch. Default value is preserve.

• visible (optional): This controls whether or not this image is visible. There are two valid values: true (default), false.

The <label> element

The <label> element allows you to place a static block of text into yoru user interface. It lives underneath the <tab> element. Attributes:

• x (required): The x position of your control where (0,0) is the top-left corner

• y (required): The y position of your control where (0,0) is the top-left corner

• text (required): The actual text that should be displayed as part of the label.

• textColor (optional): An 8 digit hex value indicating the text color to be used for the label. See Appendix A for an explanation on these hex values.

• textSize (optional): A font size for the text label. Default: 12

• width (required): The width in pixels of the label.

• height (required): The height in pixels of the label.

• vAlign (optional): The vertical alignment of the text within the box described by the width and height attributes. Valid values: top,bottom, center. Default is center.

• hAlign (optional): The horizontal alignment of the text within the box described by the width and height attributes. Valid values: left,right, center. Default is center.

• visible (optional): This controls whether or not this text label is visible. There are two valid values: true (default), false.

A label’s text can also be set dynamically using bindings using the TEXT binding parameter name.

The <labeled-knob> and <control> elements

The <labeled-knob> and <control> elements live underneath the <tab> element. These tags correspond to user controls (usually round radial dials) that can be used as part of a UI. These two element types are the same except that <labeled-knob> elements contain built-in labels, where as <control> elements do not. Every tab can have many <control> or <labeled-knob> elements underneath it.

For precise UI creation, it may be advisable to use a combination of <control> & <label> elements rather than <labeled-knob>.

Attributes:

• x (required): The x position of your control where (0,0) is the top-left corner

• y (required): The y position of your control where (0,0) is the top-left corner

• width (required): The width in pixels of the knob + label.

• height (required): The height in pixels of the knob + label.

• parameterName (required): In a situation where the sampler does not have enough room to display the full UI, a shrunken down version of the UI will be used. In such situations, this control will be labeled using the parameterName. It is good practice to always include a parameterName. If not parameterName is specified and a value label is specified, then that will be used instead.

• style (optional): The specific kind of control that is created. The following values are supported: linear_bar, linear_bar_vertical, linear_horizontal, linear_vertical, rotary, rotary_horizontal_drag, rotary_horizontal_vertical_drag, rotary_vertical_drag, custom_skin_vertical_drag, custom_skin_horizontal_drag. Default: rotary_vertical_drag.

• showLabel (optional): A true/false value dictating whether or not a built-in label should be displayed. Default: true for <labeled-knob> and false for <control> elements

• label (optional): If showLabel is true, the actual text that should be displayed above the control.

• parameterName (required): In a situation where the sampler does not have enough room to display the full UI, a shrunken down version of the UI will be used. In such situations, this control will be labeled using the parameterName. It is good practice to always include a parameterName.

• minValue (optional): The minimum value of your control. Default: 0

• maxValue (optional): The maximum value of your control. Default: 1

• value (optional): The initial value of your control. Default: 0

• defaultValue (optional): If a user double-clicks on the control, the control’s value will be set to this default value. If no default value is specified, then nothing will happen on double-click.

• valueType (optional): There are three possible values for this float which yields numbers with two decimal points, integer which yields whole numbers, and musical_time which yields musical time increments in beats and measures. This last option is for use with the built-in delay effect only. Default: float

• textColor (optional): An 8 digit hex value indicating the text color to be used for the label. See Appendix A for an explanation on these hex values.

• textSize (optional): A font size for the text label. Default: 12

• trackForegroundColor (optional): An 8 digit hex value indicating the foreground color to use for the knob track. See Appendix A for an explanation on these hex values.

• trackBackgroundColor (optional): An 8 digit hex value indicating the background color to use for the knob track. See Appendix A for an explanation on these hex values.

• visible (optional): This controls whether or not this control is visible. There are two valid values: true (default), false.

It is also possible to use custom control graphics using the following attributes:

• customSkinImage (optional): This is path to an image to use for the control. This is expected to be a JPEG or PNG in KnobMan format. A huge gallery of compatible knobs can be found here (https://www.g200kg.com/en/webknobman/gallery.php).

• customSkinNumFrames (optional): The number of animation frames contained in the KnobMan image pointed to by customSkinImage.

• customSkinImageOrientation (optional): The orientation of the frames within the KnobMan image pointed to by customSkinImage. Valid values: horizontal, vertical. Default: vertical.

• mouseDragSensitivity (optional): An integer number describing how sensitive the control should be to mouse drags. The higher the number, the less sensitive the control will be to mouse movements.

If you are using custom knobs, it’s important that you specify a style= value of either custom_skin_vertical_drag or custom_skin_horizontal_drag.

Example:

<DecentSampler>
  <ui>
    <tab>
      <labeled-knob x="560" y="0" label="Tone" type="float" minValue="60" maxValue="22000" textColor="FF000000" value="22000.0">
      <!-- Your <binding /> elements should go here -->
      </labeled-knob>
      <label x="360" y="0" width="50" height="30" text="Reverb"/>
      <control x="360" y="30" parameterName="Reverb" type="float" minValue="0" maxValue="1" textColor="FF000000" value="0.5" style="custom_skin_vertical_drag" customSkinImage="Samples/ENIGMA-nolight.png" customSkinNumFrames="31" customSkinImageOrientation="horizontal" mouseDragSensitivity="100">
      <!-- Your <binding /> elements should go here -->
      </control>
    </tab>
  </ui>
</DecentSampler>

To learn how to make knobs actually control parameters of your instrument, see “Appendix B: Bindings” section below.

The <menu> element

The <menu> element allows you to create a drop-down menu within your UI.

Attributes:

Attribute	Required	Description
x	(required)	The x position of the menu
y	(required)	The y position of the menu
width	(required)	The width of the menu
height	(required)	The height of the menu
value	(optional)	The is the 1-based index of the menu option that is currently selected. NOTE: Index numbers for menu items start at 1. A value of 0 means that no item is selected.
visible	(optional)	This controls whether or not this button is visible. There are two valid values: true, false.	true

Example:

<menu x="10" y="40"  width="120" height="30" value="2">
    <!-- Your menu options go here -->
</menu>

The <option> element

In order for your drop-down menu to have options, it must contain <option> elements.

Attributes:

Attribute	Required	Description
name	(required)	The name of this element

That’s right. The <option> element has only one attribute. In order to have your <option> elements actually do something useful, you need to attach bindings to them. Here’s an example:

<menu x="10" y="40"  width="120" height="30" requireSelection="true" placeholderText="Choose..." value="2">
    <option name="Menu Option 1">
        <!-- Set the text of a label element -->
        <binding type="control" level="ui" position="2" parameter="TEXT" translation="fixed_value" translationValue="You chose the first option." />
        <!-- Turn on this group -->
        <binding type="general" level="group" position="0" parameter="ENABLED" translation="fixed_value" translationValue="true" />
        <!-- Turn off this group -->
        <binding type="general" level="group" position="1" parameter="ENABLED" translation="fixed_value" translationValue="false" />
    </option>
    <option name="Menu Option 2">
        <!-- Set the text of a label element -->
        <binding type="control" level="ui" position="2" parameter="TEXT" translation="fixed_value" translationValue="You chose the second option." />
        <!-- Turn off this group -->
        <binding type="general" level="group" position="0" parameter="ENABLED" translation="fixed_value" translationValue="false" />
        <!-- Turn on this group -->
        <binding type="general" level="group" position="1" parameter="ENABLED" translation="fixed_value" translationValue="true" />
    </option>
  </menu>

As you can see, this example uses a menu to switch between two groups. It also sets the text of a text label. You’ll note the liberal use of the new fixed_value translation mode above. This means that when any of these options are selected, a fixed predetermined value is used for the value of that binding.

The <keyboard> element

The <keyboard> element lives underneath the <ui> element. This is where you specify settings relating to the on-screen keyboard. There should be only one <keyboard> element in your preset file. At this point, the only settings are color ranges which are specified using <color> sub-elements.

The <color> element

You can use <color> elements to change the color of portions of the on-screen keyboard. You can have as many <color> elements as you like. Only white keys are affected. It’s worth noting that colors specified in the <color> elements are overlayed on top of the white keys using a 75% transparency, so choose your colors accordingly. This is done to preserve the readability of the key labels.

<DecentSampler>
    <ui>
        <!-- Other stuff here -->
        <keyboard>
            <color loNote="36" hiNote="50" color="FF2C365E" />
            <color loNote="51" hiNote="57" color="FF6D9DC5" />
            <color loNote="58" hiNote="67" color="FFCCF3F5" />
            <color loNote="68" hiNote="73" color="FFE8DA9B" />
            <color loNote="74" hiNote="84" color="FFD19D61" />
        </keyboard>
    </ui>
    <!-- Other stuff here -->
</DecentSampler>

Attribute		Description
loNote	(required)	The bottom of the range for which this color should be displayed. Format: MIDI Note number.
hiNote	(required)	The top of the range for which this color should be displayed. Format: MIDI Note number.
color	(required)	A text representation of the color to be used for this key range. See Appendix A for an explanation on these hex values.