Ratón

Open source Linux MIDI controller

Ratón Home

Documentation

Get the source:

Current v0.22



ChangeLog


Author

Ratón was written by Doug Garmon

Documentation

Building Ratón

Ratón is a GTK+ project, designed with Glade-2. It uses:

  • GTK+ libraries (anything >=2.4)
  • The ALSA library
Development files (includes) for both are also required.

Automake >= 1.4 & autoconf >= 2.52 are also needed to build the code.

Read the documentation packaged with the source code for instructions on building and installing.


Running Ratón

The Ratón executable is named simply "raton", so international users can type the name with ease. As with any *nix program, run by typeing "./raton" in the shell, if the executable is in the current dir. Elsewhere, type "raton" and it will launch.

Ratón doesn't need to be run from the shell and will execute fine from any icon or menu, in Gnome or KDE for instance. (However, if run via a shell, Ratón can output a stream of mouse feedback messages.)


Using Ratón

This section is rather sparse, currently. Sorry.

General usage

Ratón is simple. Once executed, mouse movements will be converted to MIDI Continuous Controller messages.

The Ratón mouse area shows the two characteristic curves which control the translation of mouse moves into controller messages. They are displayed as lines. As expected, the X dimension controller varies on left-to-right movements, while the Y responds to up-and-down motion. The curves are used as lookup tables and will modify the actual mouse location (and the corresponding controller value.)

MIDI channel assignments, Controller values are easily changed. And the curve map lookup tables can be inverted or reversed.

Connect to a MIDI client

Ratón uses the ALSA sequencer API. This in effect creates a software MIDI port which can be connected to other MIDI clients. See the Screenshot of Ratón connected via 'qjackctl'.

Mouse buttons

Mouse buttons have the following assigned tasks:

  1. Left button:
    While pressed, controller messages are suppressed. The mouse can be freely moved and no messages are output.
  2. Middle button:
    Sets the 'freeze' point (see right button.) The point is displayed as a small square.
  3. Right button:
    Sends a controller message with the 'freeze point' value. Suppresses all other controller messages until a left button click-and-release.

Saving and loading

Project files are saved and opened via the 'File' menu. A project file includes the current interface state (all the widgets on the main window) and both the controller curves. Suggested file suffix -- '.raton'

Curve files are saved and loaded directly from the 'Edit curve' windows. A curve file saved from the 'Edit X curve' window may be opened as a 'Y' curve, and vice-versa. Curve files save only the characteristic curve. Suggested file suffix -- '.rcurve'

Preference info is NOT saved in a project or curve file. Prefs are saved in 'homedir/.ratonrc', a file automatically created the first time you change the prefs from the default values.


Misc.

Project (.raton) and curve (.rcurve) files are in simple text format and can edited directly in any text editor. The format should be obvious:

axis  index  value
x       1     24.5

Axis can be 'x', 'y' or 'n' (neutral, for curve files.) The index variable has a value of 0 to 127. Value (controller data) is also 0 to 127 (There are range checks for both.) Index values do NOT need to be in sequential order.

Colors

(Some) colors can be changed, but not via the inteface. You can edit the .ratonrc file directly. The X and Y curve colors are 8-bit RGB values.

The 'consolecolor' variables control the mouse feedback when Ratón is run from the shell. These are well known shell escape sequences in the following format.

	<ESC>[{attr};{fg};{bg}m

Ratón writes the first two char itself:

<ESC>[

You supply the rest. A good tutorial on Linux Gazette.


Known problems, etc.

Version 0.2

Unfortunately, I chose the GtkCurve widget as the basis of the curve edit function in Ratón. However, GtkCurve has severe limitations--control points cannot be explicitly defined, and therefore cannot be restored. For this reason (and others), the widget is now tagged as depreciated (in the GTK+ API.)

When reediting a complex curve, some accuracy will be lost (how much depends on the original curve.) However, the initial edit will be accurate, and can be saved as a project file or a curve file.

Also, a work-around is possible--Free curves are always accurate. A bug exists in Ratón which has been left in as a 'feature'. When faced with an inaccurate curve in a reedit, click the 'Free' button and then 'Cancel'. Conceptually, 'Cancel' should abort the curve type change, but this 'bug' allows a type change without altering the curve. When edited again the curve will be a free-hand type, and will retain it's original shape. Of course, the 'spline' and 'linear' types are the most useful, so this is a compromise at best.

Eventually, the edit curve function will have to be rewritten, and replaced with a custom widget.


Kudos

Thanks to:

Alexander König's aseqjoy, joystick-to-MIDI converter. I stole the ALSA seq code from this project.

Bob Ham's JACK-rack, LADSPA plugin effects box. The MIDI controller ports on this were my main motivation for creating Ratón.

The creators of Glade-2, the best little gui generator for the GTK+.