Appendix B: The <binding> element
Adding a binding to a UI control, MIDI handler, or modulator tells the DecentSampler engine that it should take input from a source and use it to change values in another part of the engine. An example of this would be a knob which controls the volume of a group, a CC controller that changes an effect parameter, or an LFO that modulates an effect parameter.
In order to set up a binding for a specific source, create a <binding>
element within the source element.
In this example, a labeled knob is controlling the volume of the first group of samples (group 0):
<DecentSampler>
<ui>
<tab>
<labeled-knob x="420" y="100" label="RT" type="float" minValue="0" maxValue="1" value="0.3" textSize="20">
<binding type="amp" level="group" position="0" parameter="AMP_VOLUME" translation="linear" translationOutputMin="0" translationOutputMax="1.0" />
</labeled-knob>
</tab>
</ui>
</DecentSampler>
Here’s a full list of parameters for the <binding>
element:
Attribute |
Description |
|
---|---|---|
|
This tells the engine what type of parameter this is. Valid values are: “amp”, “effect”, “control”. |
Required |
|
Valid values are |
Required |
|
The specific 0-based index of the element to be modified by this binding. If you are targeting a group, for example, the first group would be 0, the second group would be 1, etc. |
Required |
|
When a binding is targeting a control, this is the same thing as the |
Optional |
|
When a binding is targeting a group, this is the same thing as the |
Optional |
|
When a binding is targeting an effect, this is the same thing as the |
Optional |
|
When a binding is targeting a modulator, this is the same thing as the |
Optional |
|
A comma-separated list of tags to be modified by this binding. This allows you to set values for multiple groups at once by targeting a tag that is assigned to the groups. |
Optional |
|
A value that turns the binding on and off. Valid values are: |
Optional |
|
A string identifying the specific parameter that you wish to change. If you are modulating based on tags, you would put the tag you are targeting here. See Appendix D for example. |
Required |
|
A token describing the specific kind of parameter that you wish to change. A list of controller parameters are below. |
Required |
|
Valid values are |
Optional |
|
This is the min value this binding should send to the target parameter. This is only looked at if translation is set to |
Optional |
|
This is the max value this binding should send to the target parameter. This is only looked at if translation is set to |
Optional |
|
Valid values are |
Optional |
|
A list of input-output pairs that make up the translation table. The input and output are separated by commas. The groups of coordinates themselves are separated by semi-colons. Default: |
Optional |
|
The value that should be passed along when |
Optional |
Binding Parameters for Targeting Note Sequences
A special set of binding attributes exist for targeting note sequences:
Attribute |
Description |
Default |
Required |
---|---|---|---|
|
A 0-based index of a sequence underneath the |
None |
Required |
|
What the binding should do with the sequence in question. Valid values are |
|
Optional |
|
An identifier used for tracking the state of a sequence. This value can be any sequence of numbers or letters. |
None |
Required when |
|
Whether or not the sequence should respect the velocity of the incoming MIDI note. This can only be used when the sequence is being triggered by a MIDI note binding. Value should be a floating point number from 0.0 to 1. |
Optional |
|
|
Transpose the notes in the sequence by an arbitrary number of half steps. Value should be a floating point number from -36 to 36. |
Any sequence of numbers of letters |
Optional |
|
Transpose the notes in the sequence relative to the pitch of the incoming MIDI note. This can only be used when the sequence is being triggered by a MIDI note binding. Value should be a floating point number from 0 to 127. |
Any sequence of numbers of letters |
Optional |
|
The speed of playback. Value should be a floating point number from 0.001 to 10000. |
1.0 |
Optional |
|
Valid values are: |
|
Optional |
Controllable Parameters
This is a list of parameters that can be used in conjunction with the <binding>
element above. NOTE: The table below scrolls to the right.
Description |
|
|
|
Valid Range |
Modulatable |
Additional required parameters |
---|---|---|---|---|---|---|
Global Volume |
|
|
|
0.0 - 16.0 |
No |
N/A |
Global Tuning |
|
|
|
-36.0 - 36.0 |
No |
N/A |
Global Pan |
|
|
|
-100 - 100 |
No |
N/A |
Sample Start (see note 2 below) |
|
|
|
0 - last sample |
No |
This value will be in number of raw samples where 0 is the beginning. See note 2 below. |
Sample End (see note 2 below) |
|
|
|
0 - last sample |
No |
This value will be in number of raw samples where 0 is the beginning. See note 2 below. |
Loop Start (see note 2 below) |
|
|
|
0 - last sample |
No |
This value will be in number of raw samples where 0 is the beginning. See note 2 below. |
Loop End (see note 2 below) |
|
|
|
0 - last sample |
No |
This value will be in number of raw samples where 0 is the beginning. See note 2 below. |
Amplitude Velocity Tracking |
|
|
|
0.0 - 1.0 |
No |
N/A |
Global Amp Envelope Attack |
|
|
|
0.0 - 10.0 |
No |
N/A |
Global Amp Envelope Attack Curve Shape |
|
|
|
-100 - 100 |
No |
N/A |
Global Amp Envelope Decay |
|
|
|
0.0 - 25.0 |
No |
N/A |
Global Amp Envelope Decay Curve Shape |
|
|
|
-100 - 100 |
No |
N/A |
Global Amp Envelope Sustain |
|
|
|
0.0 - 1.0 |
No |
N/A |
Global Amp Envelope Release |
|
|
|
0.0 - 25.0 |
No |
N/A |
Global Amp Envelope Release Curve Shape |
|
|
|
-100 - 100 |
No |
N/A |
Glide/Portamento Time |
|
|
|
0.0 - 10.0 |
No |
N/A |
Effect Enabled (all effects) |
|
|
|
false, true |
Yes |
|
Convolution Mix Level |
|
|
|
0.0 - 1.0 |
Yes |
|
Convolution IR File |
|
|
|
Text |
No |
|
Filter Frequency (for several filters) |
|
|
|
0.0 - 22000.0 |
Yes |
|
Peak or Notch Filter Q |
|
|
|
0.01 - 18.0 |
Yes |
|
Peak or Notch Filter Gain |
|
|
|
0.0 - 10.0 |
Yes |
|
Low-pass or High-pass Filter Resonance |
|
|
|
0.0 - 5.0 |
Yes |
|
Reverb Wet Level |
|
|
|
0.0 - 1.0 |
Yes |
|
Reverb Room Size |
|
|
|
0.0 - 1.0 |
Yes |
|
Reverb Damping |
|
|
|
0.0 - 1.0 |
Yes |
|
Chorus/Phaser/Convolution Mix Level |
|
|
|
0.0 - 1.0 |
Yes |
|
Chorus/Phaser Mod Depth |
|
|
|
0.0 - 1.0 |
Yes |
|
Chorus/Phaser Mod Rate |
|
|
|
0.0 - 10.0 |
Yes |
|
Phaser Center Frequency |
|
|
|
0.0 - 22000.0 |
Yes |
|
Phaser/Delay Feedback |
|
|
|
0.0 - 1.0 |
Yes |
|
Delay Time |
|
|
|
0.0 - 1.0 |
Yes |
|
Delay Time Format |
|
|
|
seconds, musical_time |
Yes |
|
Delay Stereo Offset |
|
|
|
0.0 - 1.0 |
Yes |
|
Delay Wet Level |
|
|
|
0.0 - 1.0 |
Yes |
|
Gain Level |
|
|
|
0.0 - 8.0 |
Yes |
|
Wave Folder Drive Level |
|
|
|
1 - 100 |
Yes |
|
Wave Folder Threshold |
|
|
|
1 - 100 |
Yes |
|
Wave Shaper Drive Level |
|
|
|
0.0 - 1000.0 |
Yes |
|
Wave Shaper Output Level |
|
|
|
0.0 - 8.0 |
Yes |
|
Wave Shaper Drive Boost |
|
|
|
0.0 - 1.0 |
Yes |
|
Group Enabled / Disabled |
|
|
|
true, false |
|
|
Group Volume |
|
|
|
0.0 - 16.0 |
Yes |
|
Group Tuning |
|
|
|
-36.0 - 36.0 |
Yes |
|
Pan |
|
|
|
-100 - 100 |
Yes |
|
Amplitude Velocity Tracking |
|
|
|
0.0 - 1.0 |
|
|
Group Amp Envelope Attack |
|
|
|
0.0 - 10.0 |
|
|
Group Amp Envelope Decay |
|
|
|
0.0 - 25.0 |
|
|
Group Amp Envelope Sustain |
|
|
|
0.0 - 1.0 |
|
|
Group Amp Envelope Release |
|
|
|
0.0 - 25.0 |
|
|
Group Glide/Portamento Time |
|
|
|
0.0 - 10.0 |
|
|
Tag Enabled |
|
|
|
true, false |
|
|
Tag Volume |
|
|
|
0.0 - 16.0 |
|
|
MIDI Note Mapping Enabled |
|
|
|
Any number |
|
|
MIDI Note Binding Enabled |
|
|
|
Any number |
|
|
MIDI Note Binding Change |
|
|
|
Any whole number |
|
|
MIDI Note Binding Change |
|
|
|
|
|
|
MIDI Note Binding Change |
|
|
|
0 - 128 |
|
|
MIDI Note Binding Change |
|
|
|
0.001 - 10000 |
|
|
MIDI Note Binding Change |
|
|
|
0.0 - 1.0 |
|
|
MIDI Note Binding Change |
|
|
|
-36 - 36 |
|
|
MIDI Velocity Binding Enabled |
|
|
|
Any number |
|
|
UI Button State Binding Enabled |
|
|
|
true, false |
|
|
UI Control Enabled |
|
|
|
true, false |
|
|
UI Control Visibile |
|
|
|
true, false |
|
|
UI Control Value |
|
|
|
Any number |
|
|
UI Control Text |
|
|
|
Text |
|
|
UI Control Minimum Value |
|
|
|
Any number |
|
|
UI Control Maximum Value |
|
|
|
Any number |
|
|
UI Control Value Type |
|
|
|
float, integer, musical_time |
|
|
UI Image Control Path |
|
|
|
Text |
|
|
UI Keyboard Coloring Enable / Disable |
|
|
|
true, false |
|
|
Modulator Amount (Depth) |
|
|
|
0.0 - 1.0 |
|
|
LFO Modulator Rate (or Frequency) |
|
|
|
0.0 - 22000.0 |
|
|
Envelope Modulator Attack |
|
|
|
0.0 - 10.0 |
|
|
Envelope Modulator Attack Curve Shape |
|
|
|
-100 - 100 |
|
|
Envelope Modulator Decay |
|
|
|
0.0 - 25.0 |
|
|
Envelope Modulator Decay Curve Shape |
|
|
|
-100 - 100 |
|
|
Envelope Modulator Sustain |
|
|
|
0.0 - 1.0 |
|
|
Envelope Modulator Release |
|
|
|
0.0 - 25.0 |
|
|
Envelope Modulator Release Curve Shape |
|
|
|
-100 - 100 |
|
|
Sequence Rate |
|
|
|
0.01 - 100 |
|
|
All Notes Off |
|
|
|
true |
NOTE: The indexes of the parameter list also include UI controls that are not editable, such as
<label>
UI controls, so you’ll want to account for that when calculating your positions.Here’s a quick example:
If your UI’s
<tab>
section has the following elements under it:<label>
,<control>
,<label>
,<control>
. Theposition
indexes of the four elements will be 0, 1, 2, 3. Therefore, the indexes of the two<control>
elements will be 1 and 3, respectively.NOTE: If your sample library manipulates
start
,end
,loopStart
, orloopEnd
after a sample library’s initial load, the sample playback engine must be in RAM/Memory mode (not disk streaming) or you will get very unpredictable results. In order to enforce this, sample creators should use theplaybackEngine
attribute.
Translation Modes
There are currently three binding translation modes: linear
, table
, fixed_value
Mode #1: linear
linear mode allows values that come in to be scaled up or down before they get passed along to the binding’s target. If you set your translation mode to linear
you should also translationOutputMin
and translationOutputMax
.
Example usage:
<binding level="ui" type="control" position="0" parameter="value" translation="linear"
translationOutputMin="0" translationOutputMax="1"/>
Mode #2: table
table mode allows you to transform the binding’s input in a more complex fashion before it gets passed along to the binding’s target. If you set your translation mode to table
you must define the translationTable
parameter as well. This consists of a series of input-output pairs, separated by semi-colons.
Mode #3: fixed_value
fixed_value mode allows you to completely disregard the input of a binding and instead always use a supplied value. In order to use this translation mode, you must also specify a translationValue
. This can be very useful when trying to have menu options enable and disable groups. An example usage:
<binding type="general" level="group" position="1" parameter="ENABLED" translation="fixed_value" translationValue="true" />