XML Configuration System
This same information can be found in your ~/.fweelin/config-help.txt file when FreeWheeling is installed and also in the ./src/ dir of the Freewheeling source code.
Each binding has two parts:
- 1) Which input event and conditions trigger the binding?
- 2) Which output event(s) are generated and what parameters are set for those events?
binding: input="key" conditions="key=escape and keydown=1"
output="exit-freewheeling"
The name after 'key=' must match one of the valid keysyms in the 'PC Keyboard Keysyms' table.
The number after 'keydown=' indicates whether to trigger when the key is either: pressed (1), or released (0).
The output event generated under these conditions is 'exit-freewheeling'; and the end result will be that the FreeWheeling program will stop and exit whenever the escape key is pressed.
Output events can accept or require extra parameters via the 'parameters=' attribute; though the 'exit-freewheeling' output event is one that does not.
In the table of input events, you can see that there are different input types that can trigger events. It's possible to use simple expressions in your bindings to dynamically check conditions and assign parameters.
For example: This binding is for a MIDI keyboard with volume faders that transmit on different MIDI channels. Here, the volume faders are being used to fade loop levels:
binding input="midicontroller" conditions="controlnum=7 and midichannel=0>15"
output="set-loop-amplifier"
parameters="loopid=midichannel+36 and amp=controlval/127*2"
This binding is triggered when MIDI controller 7 (volume) changes are received on channels 0-15. Event "set-loop-amplifier" is generated (to change the volume of a given loop). The loop given is "midichannel+36". The volume to set the loop to is "controlval/127*2". So, a MIDI controller 7 input on channel 2 with controller value 127 will set loop #38 to volume 2.0 (200%).
The example shows how input parameters, such as MIDI channel and controller value, can be referenced in your bindings along with simple algebra (+ - / *).
When entering algebraic expressions, note that FreeWheeling does not evaluate with standard order of operations. The order of evaluation is always left to right. So:
- amp="3+3/6" will evaluate to 1 and not 3 and not 3.5.
- amp="1/2" will evaluate to 0 and not 0.5.
- amp="1.0/2" which evaluates to 0.5.
- value="0>12 + 10" evaluates to "10>22"
- value="0>5 + 1>5" evaluates to "1>10"
- value="0.5>1.5 + 0.5>1.5" evaluates to "0>2"
It is also possible to create your own user variables. These can then be referenced in your bindings, or changed during runtime, for a much more dynamic user interface.
For example, the binding below will set trigger volume for loops across a range of notes. The binding checks to see that the MIDI note number matches the user variable "VAR_noterange". Since "VAR_noterange" is a range variable, this means that the binding will only trigger event "set-trigger-volume" if the note number is within the range specified by "VAR_noterange".
binding input="midikey" conditions="VAR_cutmode=1 and notenum=VAR_noterange and keydown=1"
output="set-trigger-volume"
parameters="loopid=notenum and vol=velocity/127"
- Note that as of version 0.5pre3, FreeWheeling automatically indexes your bindings based on a hash key, so there is no need to specify wildcard cases (previously done with midikey="*").
binding input="midikey" conditions="VAR_xferloop=1 and notenum=VAR_noterange and keydown=1"
output="move-loop"
parameters="oldloopid=VAR_xferidx and newloopid=notenum+VAR_loopid_pianostart"
Checks these conditions:
- Input event is a MIDI Key
- Variable 'VAR_xferloop' equals 1?
- Input parameter notenum is within range of variable 'VAR_noterange' (When comparing against a range, a condition is true when the value is within the bounds of the range)
- Input parameter keydown equals 1
Using a combination of user variables and careful configuration of bindings, a highly tailored user interface can be created.
The order in which we declare bindings in this file is important. Bindings are checked from top to bottom, so you will need to put special case bindings first. For example, if you want to modify the behavior of a binding when a certain variable is set or key is held, you will have to put the special case before the general case.
The first matching binding is the only binding that is triggered. For an example, look under comment -Erase Loops-, and see that holding space while pressing a loop trigger key erases a loop, whereas if space is not held, it triggers the loop.
You can set up one event input to trigger many output events. To do this, specify your output events and parameters for each in a list. Have a look at the binding for input="start-freewheeling", which triggers a bunch of events when FreeWheeling is first started.
- Note that as of version 0.5pre3, this new syntax replaces the old start="1" and continued="1" syntax for startup and multiple output events.
FreeWheeling echos incoming MIDI events to MIDI output. However, events that trigger a binding are not echoed. This allows you to connect a softsynth or other MIDI device to one of FreeWheeling's MIDI outputs. Then MIDI inputs which trigger your event bindings, such as triggering loops, will not go to your synth.
