Configuration Basics
Changing the default configuration is done in the XML-based config file. If you know XML, you will have no problem editing ~/.fweelin/.fweelin.rc. Anyway, there's a lot of documentation inside this file. Pretty much everything about the program is controlled by it. It's very flexible.
Underlying the configuration system is a robust language. You can do things like map velocity of a MIDI note to a certain parameter in Freewheeling; Scale, map and transform MIDI events; Create your own toggles and modes; And trigger several events from one input. If you can learn how to configure Freewheeling, then you will have a robust performance controller at your fingertips.
XML is used for a lot of things. It's just a way to markup (describe) a structured document. In this case, it's being used to describe how Freewheeling is configured but it could as well describe your 8-track collection or the price of tea in china. You should start by reading any beginner tutorial on XML to learn the basic syntax. In short, properly formatted XML is a hierarchical configuration of nested 'tags' of this form:
<!-- this is a comment -->
<book title="Very Short Book">
<chapter title="Very Short Chapter 1">
<page>
<header text="Very Short Chapter 1" />
first page text
</page>
<page>second page text</page>
<chapter>
<chapter title="Very Short Chapter 2">
<page>
<header text="Very Short Chapter 2" />
first page text
</page>
<page>second page text</page>
<chapter>
</book>The Freewheeling XML Configuration System is event driven in nature. If you don't know what that means, you may not find configuring Freewheeling easy at first. Some rudimentary knowledge of general programming concepts and XML syntax will help tremendously. In short, this means that your config files can 'cause' certain Output Events to happen in the fweelin process (TODO:); but only in response to certain Input Events that happen in the fweelin process when certain things happen (TODO:). The Input Events may also be used as Output Events in your config files.
The quintessential example would be to demonstrate the differences in the start=freewheeling and exit-freewheeling events. The start-freewheeling event is triggered by the fweelin process on startup (and each time an interface is swapped in if i remember right); TODO: (do i remember right?) and the exit-freewheeling specifies that Freewheeling should be shutdown.
<interfaces>
<bindings>
<declare var="SHUTDOWN_AS_SOON_AS_WE_START" type="int" init="1" />
<binding input="start-freewheeling" conditions="SHUTDOWN_AS_SOON_AS_WE_START=1"
output="exit-freewheeling" />
</bindings>
</interfaces>
The example binding above would cause freewheeling to shutdown as soon as it is started but only if the variable has been declared and initialized to equal 1.
As you see, the Freewheeling XML Configuration System has the power to do many interesting things. For example:
- your config files could 'react' to the pressing of a key on your PC or MIDI keyboard by pressing one or more other MIDI or PC 'keys' for you
- using the key Input Events you can trigger a series of MIDI controller changes when a QWERTY key is pressed.
This is the default binding for the PC keyboard ESC key. This causes Freewheeling to shutdown in response to the key being pressed. You can change this to any other key by simply replacing the word escape with another from this table of PC Keyboard Keysyms.
<binding input="key" conditions="key=escape and keydown=1"
output="exit-freewheeling" />
- Input Events - These are events generated regularly by the fweelin process to which you can bind in your config files.
- Output Events - These are events that you can specify to occur in response to input events.
- System Variables - read-only variables which reflect the internal state of the fweelin process
- User Variables - read-write variables that you declare in your configs
The first time you run Freewheeling a ~/.fweelin.rc file will be created which can then be edited to add soundfonts and the like.
Here, you can set up Freewheeling to look and feel the way that is most intuitive for you. Freewheeling is especially configurable where it comes to different input controllers such as QWERTY and piano keyboards, MIDI footswitches, and pedalboards etc.
In the video section, you can define a graphical layout so that your control surfaces will appear onscreen as they do at your feet or fingertips. This is important, because you will be grabbing and controlling loops from different MIDI/keyboard controllers.
In the events section, you can tell Freewheeling how you want it to respond to the physical buttons and switches you press, sliders you move, and movements you make. Most of Freewheeling's important functions can be controlled from any input.
Inside your ~/.fweelin directory you'll find several XML-based config files that you can edit to change the appearance and behavior of freewheeling. You can create your own custom configs to utilize virtually any midi device or keyboard PC keyboard/mouse.
ls ~/.fweelin/
- Start by making some simple changes to basic options in ~/.fweelin/basics.xml using your favorite text editor.
cd ~/.fweelin nano basics.xml
- To test your changes launch Freewheeling from a terminal and hit Keypad ENTER to turn on debugging info. On the console, you will see a 'trace' of what events Freewheeling is generating (Input Events) and receiving (Output Events).
fweelin
- It is quite safe to experiment as these files can be restored to their original form from the files in /usr/local/share/fweelin/; for example:
cp /usr/local/share/fweelin/basics.xml ~/.fweelin/
- NOTE: Freewheeling must be restarted to reflect changes made to config files while it is running.
- NOTE: - Some interesting things could be done, however, if interfaces were reloaded upon swap. This would make a nice feature addition.
- Explore ~/.fweelin/coreinterface.xml as well. Don't be discouraged if it appears daunting at first. It is. :)
- The very top bits are concerned with initialization (things that only need to happen once at startup)
- The bulk of this file is the default 'global' binding that define the basic functions (the core interface) that are available to all other interfaces (MIDI and PC Keyboards, Drum Triggers, Dancemats, etc). The important thing to notice here is that this section is delimited by the opening <binding> tag and the closing </binding> tag.
- The bottom bits define some of the core visual elements that are visible in all layouts (the level indicators, the name of current synth patch, etc). The important thing to notice here is that this section is delimited by the opening <layout> tag and the closing </layout> tag.
- This entile file is encapsulated within the opening <interface> tag and the closing </interface> tag. This is what we will refer to as a complete working inteerface.
In the Configurations article you can find more ready-made complete interfaces that you can simply download to your ~./.fweelin dir to extend Freewheeling's functionality to specific midi devices that may not be included by default. You will also find there some useful snippets for specific hardware that you can include in the custom interfaces that you make. Once you have placed a new interface file in your ~/.fweelin dir, you need only add a single line to you ~/.fweelin/interfaces.xml file to activate it.
Once you feel that you get the gist of this, move on to the next article and we'll really get this fweel rolling.
Next Step: The Freewheeling XML Configuration System
