README

Xtor - an extensable Gtk based MIDI editor
===========================================
For Xtor 1.4
RW 140223,150217

Xtor (formerly Midiedit) is an editor for MIDI synthesizers (or indeed any
MIDI device), currently configured (solely) for the Waldorf Blofeld. If offers
two way communication of both single parameter changes as well as complete
patch dumps, thus both operating as a visualization as well as graphical
editor.  It is also possible to save and load individual patches to the
computer, although Xtor is not intended to be a fully fledged librarian
application.

A control surface is also supported for more hands-on editing. As of version
1.4, Xtor supports the Arturia Beatstep and the Novation Nocturn.

1. Background
-------------

Looking for an MIDI sysex-based editor for the Waldorf Blofeld, the choice
narrowed down to the iPad TB MIDI Stuff app, and the cross-platform
Monstrum Ctrlr-based editor. However, in neither case was the source available
(as far as I could tell), so I would not be able to add any functionality
I wanted. Therefore I opted for writing a Gtk based lightweight editor
which would be fairly easy to work on as well as define a GUI for.

While GUI's with beautiful graphics are impressive, I feel it is more
purposeful to have a simple graphic interface, such as the Gtk toolkit.
Especially for machines which do not have a full front panel, there are is
no graphics concept to copy, and having sliders for parameters is much more
visibly practical than knobs. Knobs are great when it comes to hardware, but
for easy overview on a computer screen, sliders are much easier to read and
their manipulation using a scroll wheel or mouse more intuitive.

In addition to the GUI, using physical knobs makes editing much more intuitive
and direct. Xtor 1.4 therefore allows the use of an external control
surface which is mapped onto the currently selected parameter group.

2. Build and installation
-------------------------

Xtor was initially written on a machine running Debian Squeeze. The
libgtk2.0-dev and libglade2-dev packages are required as well as the
libasound2-dev package which contains ALSA support.

Type 'make' in the Xtor source directory, followed by 'make install' as
root in order to install the package. Uninstallation can be performed using
'make uninstall'.

3. User perspective
-------------------

Quick start: Plug synth (and control surface if so desired) into computer using
USB. Connection with the synth will be automatically established when Get is
clicked (or G pressed). Connection with the control surface will be
automatically established when Xtor starts.

By default, the control surface is assumed to be a Beatstep, connected via
USB. Using the --controller option to the application, it is possible to
select another control surface instead; for version 1.4 the only choices are
beatstep and nocturn.

Use arrow keys to navigate between parameters. Forward, Back,
Page Up, Page Down, + or - change the currently selected parameter value,
as does the mouse scroll wheel. Pressing shift or middle mouse button
(scroll wheel button) causes parameter values to change faster.

The mouse can of course also be used for navigation and to drag the sliders
in order to set values.

Press G or click Get to fetch the current parameter from the synth, 
requesting the Part specified under Part if the synth is in Multi Mode.

The currently selected module (i.e. a module on the screen where one of the
parameters has been selected for focus) will be automaticaly mapped to the
control surface. The top row of buttons/knobs will be mapped to as many
sliders as there are in the module, with the bottom row of buttons/knobs
being mapped to the combo boxes on the lower row in each module.

In order to not have to move between control surface and computer keyboard,
it is also possible to select which module is in focus using buttons on the
control surface, as well as jump between the editor pages.

3.1 Basics
----------

Starting Xtor brings up more or less full screen window with the
synthesiser controls grouped in tabs. Moving the controls sends
parameter updates to the synth, conversely, changing parameters on the synth
cause the parameters on the screen to update in real time.

For the Blofeld, the synth is intended to be connected via USB. By default,
Xtor tries to connect to a MIDI device whose name starts with 'Waldorf
Blofeld', but any MIDI device can be set up in the Patch and Settings tab.

The Blofeld UI in Xtor is designed to run on a screen 1280 (or more)
pixels wide (the machine on which it was developed has a screen resolution of
1280x800).

3.2 Navigation and editing
--------------------------

Apart from the mouse, navigation can be performed using the keyboard.
By default, Xtor uses it's native mode, where the arrow keys move
between the parameters, as does the TAB key. Changing the parameter values
can be accomplished using the Forward and Back, Page Up and Page Down, or
+ and - keys. It's also possible to use the scroll wheel (or corresponding
zone on a laptop touch pad). Holding SHIFT or the middle mouse button while
incrementing or decrementing the values causes them to change at ten times
the rate.

When the current parameter is a name, such as the Patch Name, the left and
right arrow keys move the cursor within the name, although the up and
down keys still perform navigation.

It's also possible to use the standard Gtk naviagation mode, which solely uses
the TAB key for moving between parameters, with the arrow keys changing the
values. I find this mode to be less intuitive for a synth editor, hence
the introduction of the aforementioned Xtor native mode.

The navigation mode can be selected using the right-hand mouse key popup menu.

3.2.1 Hotkeys
-------------

In both navigation modes, Xtor also supports hotkey navigation, where for
instance the parameter tabs can be reached by pressing the underlined letter in
the tab heading, and parameter groups in each tab reached by pressing the
underlined character in each group. Normally it is the first letter, although
for the case of multiple, numbered modules of the same type, for instance the
oscillators the digit keys 1, 2, 3, etc move between the different instances.

3.2.2 Control surface
---------------------

Changing focus to the different modules on the screen can be accomplished by
using 'jump keys' on the control surface. For the Beatstep, the pads function
as jump keys, with SHIFT on the Beatstep being used as a prefix key for page
jumps (and certain module jumps when there are more than 16 modules on a page).
For the Nocturn, any one of the upper buttons functions as a shift key for
module jumps, with any of the lower buttons function as a shift key for page
jumps. 

3.2.3 Scroll mode
-----------------

By default in Xtor, the scroll wheel on the mouse changes the value
of the currently focussed parameter. This is the most natural when navigating
between parameters using the arrow keys. However, normally in Gtk the scroll
wheel changes the value of the parameter the mouse cursor is on. Using the
right-hand mouse key popup menu it is possible to disable the Xtor
scroll mode thus reverting to the default Gtk method.

3.3 Tabs
--------

If, as in the case of the Blofeld, there are too many parameters to fit on
a single page, the parameters are split into several pages, accessible
using tabs. For the Blofeld the tabs are as follows:

- Sound tab. Sound chain (oscillators, mixer, filters, amplifier) as well
  as some of the modulators: the filter and amplifier envelopes, as well
  as two selected modulation routings. The patch name can also be found
  here.
- Modulation tab. Envelopes, LFO:s, Modulation matrix and Modifiers.
  Note that the amplifier and filter envelopes are duplicated in this tab.
- Arpeggiator and Effects tab.
- Patch and configuration tab. Send parameter dump to Blofeld, Copy / Paste
  to and from Clipboard, and Save / Load file. Note that the patch name
  and category parameters are duplicated in the tab. This page also
  holds the MIDI configuration: synth Device ID as well as the name of the
  MIDI interface. The default MIDI interface name is 'Waldorf Blofeld'; if the
  MIDI Device Name field is emptied, the name is reverted to the default.

Some parameters can appear in multiple tabs, in order to make editing related
parameters easier. For instance, in the main Sound tab, the filter envelope
is available, and it is also available in the Modulation tab. Another example
are the two configurable modulation routings which makes it easier to editing
a modulation amount while keeping an eye on the corresponding destination
parameter, there not being space for the full 16 modulation routings in the
Blofeld in the Sound tab.

Tabs can be reached by using 'page jumps' on the control surface. For the
Beatstep, the SHIFT key works as a prefix key for page jumps, with the
four pages being on the lower row of buttons. For the Nocturn, holding any
key on the bottom row while pressing one of the for leftmost keys on the
buttom row will jump to the corresponding page.

3.4 Multiple parts
------------------

The user interface supports multiple 'parts' in the synth. The currently
selected part is listed on the left of the main window, as well as in the
main window title. Selecting a different part automatically performs a
'Get' operation to load the current patch for the selected part into Xtor.

3.5 Getting a patch from the synth
----------------------------------

The Get button to the left in the main window fetches the current
patch from the synth to the editor. When the synth is in multi mode, the
corresponding multi part is shown in the radio buttons below. When the
synth is not in multi mode, part 1 is used.

3.6 Xtor preferences
------------------------

Xtor has a couple of preference settings which are set in a popup
menu which is activated by the right hand mouse key or the Menu key on the
keyboard.

The settings include the aformenetioned navigation preferences, as well
as a Debug mode which emits copious debug texts on stdout during operation.

3.7 Special features and quirks
-------------------------------

3.7.1 LFO Speed and Clock
-------------------------

The LFO Speed and Clock parameters are actually the same parameter, the
interpretation of which is controlled using the LFO Clocked parameter.
Currently both Speed and Clock are shown at all times, and changing one
updates the other. Another solution would be to hide the parameter not
currently in used, however, that would not really save any space in the
display, and so has not been implemented.

3.7.2 Effects parameters
------------------------

The effects units also have a couple of parameters with different
interpretations depending on the effect selected. Also, certain parameters
are not used for certain effects. Currently the implementation shows
all parameters at all times. A future improvement would be to only display
those parameters which are valid for the effect currently selected.

3.7.3 Arpeggiator clipboard
---------------------------

The arpeggiator features a cliboard, allowing arpeggiator parameters
(including the User Pattern) to be copied from one patch to another.

3.7.4 Arpegiator User Pattern All column
----------------------------------------

The Arpeggiator User Pattern box includes an All column at the far right.
Changing any parameter in this column sets the corresponding parameter
for all steps to the same value; it is intended for quickly setting up 
the arpeggiator when all steps are to have the same (or mostly the same)
value.

3.7.5 Blofeld Multi Mode parameters
-----------------------------------

While Xtor supports multi mode in the sense that it can easily switch
between the 16 available parts, the multi mode parameters such as MIDI
channel, volume, pan, etc for the different parts are not supported, for
the simple reason that Waldorf has not (yet) implemented sysex support
for editing these parameters individually.

3.8 Starring
------------

Pressing the * key causes Xtor to remember the currently selected
parameter. After navigating to another parameter, the remembered parameter can
be jumped to by pressing the space bar. Doing so causes Xtor to remember
the other parameter instead, meaning that it's possible to quickly jump back
and forth betwen two parameters using the space bar, once one of them has been
'starred'.

Furthermore, if the CTRL key is held while adjusting the value of the
parameter, the starred parameter is updated as well. This is very useful for
instance if the two Blofeld filters are working in parallel, feeding separate
output channels, and one wants to adjust the cutoff frequency of both filters
at the same time.

3.9 Control surface mapping
---------------------------

The control surface is automatically mapped to the module where a parameter
has focus. For the Blofeld, normally, the upper row of knobs map to the
sliders, whereas the lower row of knobs (or the buttons if there's only one
row of knobs as on the Nocturn) map to the combo boxes.

In order to support this, most modules have at the most 8 sliders.

For modules that have more than 8 sliders, for example the modulation matrix,
all the sliders in the module are mapped to the knobs, if the control surface
has more than 8 knobs, as is the case with the Beatstep. Conversely, if
there are no sliders in a module, for instance the arpeggiator User Pattern,
all the knobs are mapped to the top line of combo boxes, again assuming the
control surface has more than 8 knobs.

Some control surfaces have a knob which is not part of the main control array;
the Nocturn has the Speed Dial knob and the Beatstep has the Volume knob.
This knob is then always mapped to the currently focused parameter, and may
thus be used instead of the scroll wheel in conjunction with hotkey or arrow
navigation.

The mapping of control surface controls to parameters is automatic, and takes
place in a left-to-right manner, individually for the slider and combo box
rows in a module. Thus, parameters which line up vertically in the UI do
not necessarily end up on knobs/buttons that are in line.

4. Developer perspective
------------------------

Xtor is written entirely in C, although the user interface definition
is written in XML using the Glade user interface editor. An object oriented
approach is largely adopted, making it possible to cleanly support more
synths and control surfaces in the future.

glib is heavily utilized for list processing, and Gtk2+ is used for the graphic
environment.

4.1 Glade files
---------------

The editing user interface is defined in glade file for the synth in question,
blofeld.glade at the time of writing. Principally there is a window
called 'main_window' defined in this file which contains the complete editor
interface. Common infrastructure UI definitions are held in a file called
xtor.glade .

Xtor uses two glade files, one for the synth itself (e.g. blofeld.glade),
specifying the parameter layout in the main_wondow, and one for Xtor
properties (xtor.glade), which basically specifies a popup menu activated
using the right mouse key or the Menu key on the keyboard.

4.2 Parameter names and widget types
------------------------------------

The names of each parameter widget are mapped by the Xtor core to the
names of the parameters in the parameter list. Since it's not possible to
have two widgets with the same name, the Xtor core disregards any trailing
digits in the widget names. This is handy, because by default the Glade
interface editor appends a number to a widget name if it detects a duplicate.
However, this must be considered when giving names to parameters, as they
may not end with a digit or they won't be recognized during the mapping.

The following widget types may be used for synth parameters:
- Horizontal and vertical sliders (GtkRange)
- Combo boxes (GtkComboBox)
- Tick boxes (GtkToggleButton)
(Radio buttons are not supported at this time).

It is not necessary to add GtkAdjustments (specifying min and max values,
as well as step sizes etc) in the glade file, as this is done automatically
by the Xtor core when scanning the available UI parameters, based on the
min and max values in the parameter list definition.

4.3 Hotkeys
-----------

Hotkeys are specified using the KeyMapping liststore in the synth glade file.
The liststore has six columns: the actual hot key value ('Key'), a parameter
name to focus on ('ParamName'), an optional argument ('ParamArg') (more about
this later), a conditional focus parent name ('FocusParent'), an optional
focus parent argument ('ParentArg'), and finally a jump button specifier
('JumpButton').

Basically, the idea is that when the key corresponding to the 'Key' is
pressed, the user interface sets the focus on the 'ParamName' parameter, if
that parameter is an individual parameter widget (such as filter 1 cutoff). In
this case the 'ParamArg' is not used (and is normally set to -1).

If the 'ParamName' refers to a GtkNotepad, the tab specified in the
'ParamArg' column is selected. This is intended for quick jumping between
the tabs in the UI.

If the 'ParamName' refers to a GtkButton, the corresponding button is
activated. This is used for instance for the 'Get' button for getting
the current patch from the synth, which can be activated by pressing the 'G'
key.

The 'FocusParent' can be used as a conditional if the 'Key' in question should
only work on a given tab, or when a given widget is in focus (the widgets
are not limited to parameter widgets, but are rather usually containers
for groups of parameters, e.g. Osc 1; in that case, the conditional becomes
true if any child of the container is in focus.)

If the 'FocusParent' string is empty, then that conditional is always true.

If 'FocusParent' refers to a GtkNotebook, the 'ParentArg' specified
the tab that must be active for the conditional to be true. For all
other widget types, the currently focused widget must be either the
widget itself or a child of the 'FocusParent'. In this case, the
'ParentArg' is not used (and is normally set to -1).

The 'JumpButton' specifies a control surface jump key that will perform
the same duty as the 'Key'. Jump buttons are specified using a string of the
form 'J<row><column>', where row is the row number of a conceptual 4x8 matrix
of buttons, starting at 1 from the top. Column is the column number, again
starting at 1. Normally module jumps are on rows 1 and 2, with page jumps
being on row 4. For control surfaces that have fewer than 4x8 buttons, some
form of shift mechanism is used to access the lower two rows (rows 3 and 4).
The shift mechanism is different for different control surfaces, depending
on their capabilities.

The KeyMappings liststore is scanned in order from top to bottom, and the first
line with a matching 'Key' or 'JumpButton', and a valid 'FocusParent' (and
'ParentArg' when applicable (i.e. for GtkNotebooks)) causes the required action
to take place. The order of the rows in the list store is thus significant,
especially when the same 'Key' occurs on several rows.

4.4 Hiding parameters
---------------------

There is no infrastructure for hiding parameters depending on other parameters.
For the Modulation Selection boxes in the Sound tab, a signal handler
connected to the Select combo box hides/unhides the relevant modulation
parameters in the same box.

4.5 Parameters
--------------

The parameter definitions are held in the synth specific parameter handling
file. For the Blofeld this is blofeld_params.c .

4.5.1 Blofeld parameters
------------------------

For the Blofeld there are a number of parameters which are implemented as
bitfields in the same byte in the parameter dump. In order to handle these
as separate parameters, the parameter list handling supports so-called
'bitmap' parameters ("bm_param"). Bitmap parameters are located after the
ordinary parameters, and they specify the bitfield location in the parent
parameter. For each parent parameter, there are one or more bitmap parameters
for the individual bit fields. The bit fields may overlap; this used for
instance for the LFO frequency which can be represented either as a frequency
0..127 as well 64 different clock divisors, depending on the the LFO 'Clocked'
parameter.

The patch name parameters are handled in a similar way. In this case however,
there is one child parameter with several parent parameters, one parent
for each character in the patch name.

4.6 Control surfaces
--------------------

Control surfaces are managed using two concepts: knob mappers and controllers.

A knob mapper maps controls from a generalized control surface having two
rows of controls to the parameters in a module. Since technically the graphic
appearance of modules can vary depending on the synth being controlled,
the knob mapper must be written with the specific synth in mind, although
given enough similarity between the graphic appearance of different synth UI's,
it's conceivable that a knob mapper may be shared between several synths.

A controller receives control surface data and calls callbacks in Xtor
to inform it of knobs or button activation. Xtor then consults the current
knob mapper on how to map the controls to parameters in the current module.
A controller may also initialize the control surface; for instance, the
beatstep.c sends sysex strings to the Beatstep during startup in order to
configure the controls to generate the messages expected by Xtor
(various MIDI Control Change messages on channel 1).

Currently, only relative controls are supported by the Xtor framework,
i.e. controls that emit increment or decrement messages. Controls that
emit absolut values (i.e. potentiometers) are not supported.

4.6.1 Beatstep
--------------

The Beatstep control surface is configured by Xtor so that the knobs
emit relative CC values when turned, and the pads emit CC messages when
pressed and released. For simplicity, the CC number is the same as the buttons
reference id in the setup data, and the MIDI channel is 1.

The SHIFT key on the Beatstep is used as a prefix key for accessing jump
button rows 3 and 4. It may be held prior to pressing a pad, or pressed
momentarily before pressing the pad.

4.6.2 Nocturn
-------------

The Nocturn does not per se register itself as a MIDI USB device. Since a
while back, the Linux kernel contains built-in support for the Nocturn
nevertheless; prior to that, a special application had to be run which
converted the Nocturn USB data to MIDI. As it turns out, the actual data sent
from the Nocturn is actually MIDI and consists of various control change
messages, some with control change numbers that would not be used in
orderinary MIDI communication (for instance 127, which is one of the mode
messages).

The 16 buttons on the Nocturn are mapped as two rows of increment and
decrement buttons, respectively. Normally the buttons are mapped to the
combo boxes in modules in Xtor. To access the module jump function,
any button in the top row can be used as a shift key, this 16 buttons are
available for the jump destination. To access the page jump function,
any button in the bottom row can be used as the shift key.

4.7 File structure
------------------

The file structure of Xtor is as follows:

xtor.c: Main program, signal handlers for all general signals (parameter
        change, parameter hide), key and mouse event processing.
dialog.c, .h: Some useful dialog boxes: Yes/No questions, alert boxes, etc.
blofeld_params.c, .h: Parameter list definition for the Blofeld, conversion
                      functions between user interface representation and
                      actual parameter values. Send/receive of sysex data.
blofeld_knobs.c: Implementation of the knob mapper class for the Blofeld.
                 Sets up mapping between generalized control surface knobs
                 and Blofeld parameters.
blofeld_ui.c: Blofeld-specific signal handlers.
beatstep.c: Implementation of the controller class for the Arturia Beatstep
nocturn.c: Implementation of the controller class for the Novation Nocturn.
controller.h: Represents a controller class which represents a control
              surface.
knob_mapper.h: Represents a knob mapper class for mapping between controls on
               a control surface and parameters.
knob_mapper.c: Helper functions for knob mappers.
param.h: General parameter structure. Represents a param handler class.
         Embryo for multiple synth support.
midi.c, .h: Interface to MIDI layer. Receive and send sysex. Currently
            assumes underlying MIDI layer is ALSA.
debug.c, .h: Debug printout and control.
blofeld.glade: User interface definition for main window.
xtor.glade: Common user interface widgets: Popup menu and About box.

The idea is that when implementing support for a new synth, files
corresponding to blofeld_params.[ch], blofeld_ui.c and blofeld.glade need
to be written, but that the infrastructure defined in xtor.c should no
require adaptation. There is currently no support for switching between
multiple synth defintions, that will have to be added when the need arises. Of
course, since only support for one synth has been implemented, the
infrastructure will most likely need updating in order to support features
needed by new synth definitions, but the resulting changes should be
general and not specifically support a certain machine.

Similarily, when implementing support for a new control surface, a file
similar to beatstep.c or nocturn.c must be written. Note that the controller
class only handles the reception of knob and button data from the control
surface (and possible set up of it as well); the mapping of controls to
parameters is handled by the knob_mapper class.

4.6.1 Development
-----------------

By default, Xtor searches for its UI (glade) files in
/usr/local/share/xtor, however, during develpoment it is practical to keep
all files in the development directory so that it is not necessary to run the
'install' target every time a glade file is changed. This is accomplished by
uncommenting the '#UI_DIR=.' line in the Makefile.

The global Debug variable enables all printouts using dprintf(). Printouts
using eprintf() are printed to stderr at all times, this is inteded for
error and warning printouts.

4.7 Graphic philosophy
----------------------

The basic graphic philosophy when designing the Blofeld UI has been to have
modules as horizontal boxes of parameters. A lot of boxes have two rows,
the top row being a number of sliders, and the bottom row a number of
combo boxes, often selecting modulation sources etc whose amount is set by
the slider just above the combo box. To ease integration with control surfaces,
which in most cases have controls grouped in horizontal rows of 8, modules
should generally not have more than 8 parameters across.

Vertical sliders are mostly used, as they permit more parameters to be placed
in the horizontal direction (i.e. side by side). In some cases (Modulation
amounts in the Modulation matrix, and in the Arpeggiator) horizontal
sliders fit better with the rest of the graphics.

Parameters have been grouped on the tabs as being the ones most likely
to be edited together, to minimize switching between tabs. In some cases
the same parameters have been put on multiple pages for this reason.