shuttlepro.1

.\" Automatically generated by Pandoc 2.2.3.2
.\"
.TH "shuttlepro" "1" "" "" ""
.hy
.SH Name
.PP
shuttlepro \[en] translate input from the Contour Design Shuttle devices
.SH Synopsis
.PP
shuttlepro [\-h] [\-o] [\-p] [\-j \f[I]name\f[]] [\-r \f[I]rcfile\f[]]
[\-d[rskj]] [\f[I]device\f[]]
.SH Options
.TP
.B \-h
Print a short help message.
.RS
.RE
.TP
.B \-o
Enable MIDI output.
.RS
.RE
.TP
.B \-p
Enable hotplugging support.
.RS
.RE
.TP
.B \-j \f[I]name\f[]
Set the Jack client name.
Default: \[lq]shuttlepro\[rq].
.RS
.RE
.TP
.B \-r \f[I]rcfile\f[]
Set the configuration file name.
Default: taken from the SHUTTLE_CONFIG_FILE environment variable if it
exists, or ~/.shuttlerc if it exists, /etc/shuttlerc otherwise.
.RS
.RE
.TP
.B \-d[rskj]
Enable various debugging options: r = regex (print matched translation
sections), s = strokes (print the parsed configuration file in a
human\-readable format), k = keys (print executed translations), j =
jack (additional Jack debugging output).
Just \f[C]\-d\f[] enables all debugging options.
.RS
.RE
.SH Description
.PP
The Contour Design Shuttle devices are specialized input devices mainly
used with audio and video editing software.
They offer three different kinds of controls: a jog wheel (an endless
rotary encoder), a shuttle wheel surrounding the jog wheel which
automatically snaps back into its center position, and a collection of
buttons arranged around the jog and shuttle wheels.
.PP
There are various versions of these devices.
The current line of products from Contour Design consists of the
ShuttlePRO v2 and the ShuttleXpress.
These and a few older versions should be recognized by the shuttlepro
program without any further ado.
However, there are also some rebranded versions which might not be
detected automatically, in which case you'll have to specify the device
name on the command line.
.PP
The shuttlepro program enables you to use these devices on Linux.
It will work with any application taking X11 keyboard and mouse or MIDI
input, without requiring any special support from the application.
The program translates input events (button presses, jog and shuttle
wheel movements) into X keystrokes, mouse button presses, scroll wheel
events, or, as an option, MIDI output.
It does this by matching the \f[C]WM_CLASS\f[] and \f[C]WM_NAME\f[]
properties of the window that has the keyboard focus against the regular
expressions for each application section in its configuration
(shuttlerc) file.
If a regex matches, the corresponding set of translations is used.
If a matching section cannot be found, or if it doesn't define a
suitable translation, the program falls back to a set of default
translations at the end of the file, if available.
.PP
The shuttlerc file is just an ordinary text file which you can edit to
configure the program for your applications.
A sample configuration file is included, see example.shuttlerc in the
sources.
This also gets installed as a system\-wide configuration file, so that
the program works out of the box with any of the preconfigured
applications.
At the time of this writing, there are ready\-to\-use translations for
some popular video editors and a basic Mackie emulation which should
work with most DAW (digital audio workstation) programs.
Your contributions are appreciated, so if you have any interesting
application configurations to share, please submit them at the project
page (https://github.com/agraef/ShuttlePRO)!
.SS Installation
.PP
First, make sure that you have the required dependencies installed.
The program needs a few X11 libraries and Jack (http://jackaudio.org/);
the latter is only required if you plan to utilize the MIDI support.
And of course you need GNU make and gcc (the GNU C compiler).
On Ubuntu and other Debian\-based systems you should be able to get
everything that's needed by running this command:
.IP
.nf
\f[C]
sudo\ apt\ install\ build\-essential\ libx11\-dev\ libxtst\-dev\ libjack\-dev
\f[]
.fi
.PP
Then just run \f[C]make\f[] and \f[C]sudo\ make\ install\f[].
This installs the example.shuttlerc file as /etc/shuttlerc, and the
shuttlepro program and the manual page in the default install location.
Usually this will be under /usr/local, but the installation prefix can
be changed with the \f[C]prefix\f[] variable in the Makefile.
Also, package maintainers can use the \f[C]DESTDIR\f[] variable as usual
to install into a staging directory for packaging purposes.
.PP
The program will automatically be built with Jack MIDI support if the
Jack development files are detected at compile time.
(If you do have Jack installed, but you still want to build a Jack\-less
version of the program for some reason, you can do that by running
\f[C]make\ JACK=\f[] instead of just \f[C]make\f[].)
.PP
Finally, if you also want hotplugging support, you can run
\f[C]sudo\ make\ install\-udev\f[] to have the corresponding udev rules
and helper script installed.
(If you specified the \f[C]prefix\f[] variable during
\f[C]make\ install\f[], the same value should be used here, so that the
proper absolute path to the shuttlepro program gets inserted into the
helper script.) However, we recommend that you first go without this,
until you have everything set up as needed, and even then you should
first read the \f[I]Hotplugging\f[] section at the end of this manual
and note the caveats concerning this feature.
.SH Configuration File
.PP
After installation the system\-wide default configuration file will be
in /etc/shuttlerc, where the program will be able to find it.
We recommend copying this file to your home directory, renaming it to
\&.shuttlerc:
.IP
.nf
\f[C]
cp\ /etc/shuttlerc\ ~/.shuttlerc
\f[]
.fi
.PP
The ~/.shuttlerc file, if it exists, takes priority over /etc/shuttlerc,
so it becomes your personal shuttlepro configuration.
You can edit this file as you see fit, in order to customize the
configuration for the applications that you use.
.PP
The program automatically reloads the configuration file whenever it
notices that the file has been changed.
Thus you can edit the file while the program keeps running, and have the
changes take effect immediately without having to restart the program.
The program also has a bunch of debugging options which let you to see
exactly how your translations are being processed, which is very helpful
when testing out new translations.
.SH Usage
.PP
The shuttlepro program is a command line application, so usually you run
it from the terminal.
However, once you've set up everything to your liking, you can also
launch it from your Jack session manager (see \f[I]MIDI Output\f[]
below), or from your desktop environment's startup files.
Hotplugging support using the Linux udev system is also available;
please check the \f[I]Hotplugging\f[] section below for details.
.PP
Before you can use the program, you have to make sure that you can
access the device.
On modern Linux systems, becoming a member of the \f[C]input\f[] group
should be all that is needed:
.IP
.nf
\f[C]
sudo\ usermod\ \-a\ \-G\ input\ username
\f[]
.fi
.PP
Log out and in again, and you should be set.
(Another possibility is to use the hotplugging feature which will set
the permissions of the device so that an ordinary user has access even
without being member of the \f[C]input\f[] group; please check the
\f[I]Hotplugging\f[] section for details.)
.PP
Now make sure that your Shuttle device is connected, and try running
\f[C]shuttlepro\f[] from the command line (without any arguments).
The program should hopefully detect your device and print something
like:
.IP
.nf
\f[C]
shuttlepro:\ found\ shuttle\ device:
/dev/input/by\-id/usb\-Contour_Design_ShuttleXpress\-event\-if00
\f[]
.fi
.PP
(The precise name of the device will differ, depending on the version of
the device that you have.
E.g., the output above indicates that a Shuttle Xpress was found.)
.PP
If the program fails to find your device, you'll have to locate it
yourself and specify the absolute pathname to it on the command line.
On modern Linux systems, there should be an entry under
/dev/input/by\-id for it, which is simply a symbolic link to some device
node under /dev/input.
Look for devices having \[lq]Contour_Design\[rq], \[lq]CAVS\[rq] or
\[lq]Shuttle\[rq] in their name.
.PP
Naming the device on the command line will also be necessary if you have
multiple Shuttle devices.
In this case you may want to run a separate instance of shuttlepro for
each of them (possibly with different configurations, using the
\f[C]\-r\f[] option).
.PP
If your device was found, you should be able to operate it now and have,
e.g., the terminal window in which you launched the program scroll and
execute mouse clicks if you move the jog wheel and press the three
center buttons on the device.
When you're finished, terminate the program by typing Ctrl+C in the
terminal window where you launched it.
.PP
Note that once up, the program will just keep running, even if the
device gets unplugged, in which case an error message will be printed
and the program will keep trying to reopen the device until you
interrupt it.
However, there is an alternative mode available with the \f[C]\-p\f[]
option, which makes sure that the program exits as soon as the device
becomes unavailable.
This is also used, in particular, when using the udev hotplugging
facility mentioned above.
.PP
The default \[lq]mouse emulation mode\[rq] is actually configured in the
\f[C][Default]\f[] section near the end of the distributed shuttlerc
file, which reads as follows:
.IP
.nf
\f[C]
[Default]
\ K6\ XK_Button_1
\ K7\ XK_Button_2
\ K8\ XK_Button_3
\ JL\ XK_Scroll_Up
\ JR\ XK_Scroll_Down
\f[]
.fi
.PP
As you can see, the buttons denoted \f[C]K6\f[], \f[C]K7\f[] and
\f[C]K8\f[] (which are the three buttons right above the jog wheel, see
the comments at the beginning of the shuttlerc file for a description of
the button layout) are mapped to the corresponding mouse buttons, and
rotating the jog wheel to the left (\f[C]JL\f[]) and right (\f[C]JR\f[])
emulates the scroll wheel, scrolling up and down, respectively.
(Besides these mouse actions, you can also bind input events to
arbitrary sequences of key strokes, so operating the functions of any
application that is well\-equipped with keyboard shortcuts should in
most cases be a piece of cake.
Have a look at the other configuration entries to see how this is done.)
.PP
One useful feature is that you can invoke the program with various
debugging options to get more verbose output as the program recognizes
events from the device and translates them to corresponding mouse
actions or key presses.
E.g., try running \f[C]shuttlepro\ \-drk\f[] to have the program print
the recognized configuration sections and translations as they are
executed.
For instance, here is what the program may print in the terminal if you
move the jog wheel one tick to the right (\f[C]JR\f[]), then left
(\f[C]JL\f[]), and finally press the leftmost of the three buttons
(\f[C]K6\f[]):
.IP
.nf
\f[C]
$\ shuttlepro\ \-drk
shuttlepro:\ found\ shuttle\ device:
/dev/input/by\-id/usb\-Contour_Design_ShuttleXpress\-event\-if00
Loading\ configuration:\ /home/foo/.shuttlerc
translation:\ Default\ for\ ShuttlePRO\ :\ bash\ (class\ konsole)
JR:\ XK_Scroll_Down/D\ XK_Scroll_Down/U\ 
JL:\ XK_Scroll_Up/D\ XK_Scroll_Up/U\ 
K5[D]:\ XK_Button_1/D\ 
K5[U]:\ XK_Button_1/U\ 
\f[]
.fi
.PP
We strongly recommend using the debugging options when editing the
translations, so that you can see exactly what's going on if your
translations don't appear to work correctly.
The \f[C]\-d\f[] option can be combined with various option characters
to choose exactly which kinds of debugging output you want; \f[C]r\f[]
(\[lq]regex\[rq]) prints the matched translation section (if any) along
with the window name and class of the focused window; \f[C]s\f[]
(\[lq]strokes\[rq]) prints the parsed contents of the configuration file
in a human\-readable form whenever the file is loaded; \f[C]k\f[]
(\[lq]keys\[rq]) shows the recognized translations as the program
executes them, in the same format as \f[C]s\f[]; and \f[C]j\f[] adds
some debugging output from the Jack driver.
You can also just use \f[C]\-d\f[] to enable all debugging output.
Most of these options are also available as directives in the shuttlerc
file; please check the distributed example.shuttlerc for details.
.SS MIDI Output
.PP
If the shuttlepro program was built with Jack MIDI support, it can also
be used to translate input from the Shuttle device to corresponding MIDI
messages rather than key presses.
This is useful if you want to hook up the device to any kind of
MIDI\-capable program, such as software synthesizers or digital audio
workstation (DAW) programs like Ardour (https://ardour.org/).
.PP
You need to run the program as \f[C]shuttlepro\ \-o\f[] to enable MIDI
output at run time.
This will start up Jack (if it is not already running) and create a Jack
client named \f[C]shuttlepro\f[] with a single MIDI output port which
can then be connected to the MIDI inputs of other programs.
The Jack client name can also be changed with the \f[C]\-j\f[] option,
which is useful if you're running multiple instances of the program with
different Shuttle devices (possibly using different configurations).
.PP
We recommend using a Jack front\-end and patchbay program like
QjackCtl (https://qjackctl.sourceforge.io/) to manage Jack and to set up
the MIDI connections.
In QjackCtl's setup, make sure that you have selected \f[C]seq\f[] as
the MIDI driver.
This exposes the ALSA sequencer ports of non\-Jack ALSA MIDI
applications as Jack MIDI ports, so that they can easily be connected to
shuttlepro.
(We're assuming that you're using Jack1 here.
Jack2 works in a very similar way, but may require some more fiddling;
in particular, you may have to use
a2jmidid (http://repo.or.cz/a2jmidid.git) as a separate ALSA\-Jack MIDI
bridge in order to have the ALSA MIDI devices show properly as Jack MIDI
devices.)
.PP
The shuttlepro program also supports Jack session management, which
makes it possible to record the options the program was invoked with
along with the MIDI connections.
This feature can be used with any Jack session management software.
Specifically, QjackCtl has its own built\-in Jack session manager which
is available in its Session dialog.
To use this, launch shuttlepro and any other Jack applications you want
to have in the session, use QjackCtl to set up all the connections as
needed, and then hit the \[lq]Save\[rq] button in the Session dialog to
have the session recorded.
Now, at any later time you can relaunch the same session with the
\[lq]Load\[rq] button in the same dialog.
.PP
The example.shuttlerc file comes with a sample configuration in the
\f[C][MIDI]\f[] section for illustration purposes.
This special default section is only active if the program is run with
the \f[C]\-o\f[] option.
It allows MIDI output to be sent to any connected applications, no
matter which window currently has the keyboard focus.
This is probably the most common way to use this feature, but of course
it is also possible to have application\-specific MIDI translations, in
the same way as with X11 key bindings.
In fact, you can freely mix mouse actions, key presses and MIDI messages
in all translations.
.PP
The sample \f[C][MIDI]\f[] section implements a simplistic DAW
controller which can be used as a (rather rudimentary) Mackie control
surface, e.g., with Ardour.
It maps some of the keys, as well as the shuttle and jog wheels to
playback controls and cursor movement commands.
The configuration entry looks as follows:
.IP
.nf
\f[C]
[MIDI]

\ K6\ A7\ \ #\ Stop
\ K7\ A#7\ #\ Play
\ K8\ B7\ \ #\ Record

\ K5\ D8\ \ #\ Left
\ K9\ D#8\ #\ Right

\ IL\ G7\ \ #\ Rewind
\ IR\ G#7\ #\ Fast\ Forward
\ S0\ A7\ \ #\ Stop

\ #\ Mackie\ jog\ wheel
\ JL\ CC60~
\ JR\ CC60~
\f[]
.fi
.PP
Note that the Mackie control protocol consists of various different MIDI
messages, mostly note and control change messages.
We'll discuss the syntax of these items in the \f[I]MIDI
Translations\f[] section below.
.PP
To try it, run \f[C]shuttlepro\ \-o\f[], fire up Ardour, and configure a
Mackie control surface in Ardour which takes input from the MIDI output
of the \f[C]shuttlepro\f[] client.
The playback controls and the jog wheel should then work exactly like a
real Mackie\-like MIDI controller connected directly to Ardour.
.SH Translation Syntax
.PP
The shuttlerc file consists of sections defining translation classes.
Each section generally looks like this, specifying the name of a
translation class, optionally a regular expression to be matched against
the window class or title, and a list of translations:
.IP
.nf
\f[C]
[name]\ regex
K<1..15>\ output\ #\ key
S<\-7..7>\ output\ #\ shuttle\ value
I<LR>\ \ \ \ output\ #\ shuttle\ rotation
J<LR>\ \ \ \ output\ #\ jog\ wheel\ rotation\ 
\f[]
.fi
.PP
The \f[C]#\f[] character at the beginning of a line and after whitespace
is special; it indicates that the rest of the line is a comment, which
is skipped by the parser.
Empty lines and lines containing nothing but whitespace are also
generally ignored.
(An exception is the section header which is taken verbatim, so that the
name and/or the regular expression of a translation class may contain
literal whitespace and \f[C]#\f[].)
.PP
Each \f[C][\f[]\f[I]name\f[]\f[C]]\f[] \f[I]regex\f[] line introduces
the list of translations for the named translation class.
The given \f[I]name\f[] is only used for debugging output, and needn't
be unique.
The \f[I]regex\f[] part can be any regular expression using the egrep
a.k.a.\ \[lq]extended\[rq] syntax, cf.\ regex(7).
When focus is on a window whose class or title matches \f[I]regex\f[],
the corresponding translations are in effect.
An empty \f[I]regex\f[] for the last class will always match, allowing
default translations.
Any output sequences not bound in a matched section will be loaded from
the default section if they are bound there.
.PP
The translations define what output should be produced for the given
input.
Each translation must be on a line by itself.
The first token of each translation denotes the key, shuttle or jog
wheel event to be translated:
.IP \[bu] 2
\f[C]K\f[] followed by the key number denotes one of the buttons on the
Shuttle device.
The PRO version of the device has 15 such buttons, the Xpress version
only five (\f[C]K5\f[] ..
\f[C]K9\f[]).
See the example.shuttlerc file for a picture showing how the buttons are
laid out.
.IP \[bu] 2
\f[C]S\f[] followed by any of the values \-7..7 denotes a specific
position of the shuttle wheel, with 0 denoting the center position.
.IP \[bu] 2
\f[C]IL\f[] denotes left (counter\-clockwise), \f[C]IR\f[] right
(clockwise) rotation of the shuttle wheel.
.IP \[bu] 2
\f[C]JL\f[] denotes left (counter\-clockwise), \f[C]JR\f[] right
(clockwise) rotation of the jog wheel.
.PP
The input event is followed by the output sequence consisting of one or
more key, mouse and MIDI events.
We'll describe these below.
In each translation section, the translations must be unique, i.e.,
there may be at most one translation for each kind of input event.
.SS Key and Mouse Translations
.PP
Input events can generate sequences of multiple keystrokes, including
the pressing and releasing of modifier keys.
The output sequence consists of one or more tokens described by the
following EBNF grammar:
.IP
.nf
\f[C]
token\ \ \ ::=\ "RELEASE"\ |\ keycode\ [\ "/"\ flag\ ]\ |\ string
keycode\ ::=\ "XK_Button_1"\ |\ "XK_Button_2"\ |\ "XK_Button_3"\ |
\ \ \ \ \ \ \ \ \ \ \ \ "XK_Scroll_Up"\ |\ "XK_Scroll_Down"\ |
\ \ \ \ \ \ \ \ \ \ \ \ "XK_..."\ (X\ keysyms,\ see\ /usr/include/X11/keysymdef.h)
flag\ \ \ \ ::=\ "U"\ |\ "D"\ |\ "H"
string\ \ ::=\ \[aq]"\[aq]\ {\ character\ }\ \[aq]"\[aq]
\f[]
.fi
.PP
Besides the key codes from the keysymdef.h file, there are also some
special additional key codes to denote mouse button
(\f[C]XK_Button_1\f[], \f[C]XK_Button_2\f[], \f[C]XK_Button_3\f[]) and
scroll wheel (\f[C]XK_Scroll_Up\f[], \f[C]XK_Scroll_Down\f[]) events.
.PP
Any keycode can be followed by an optional \f[C]/D\f[], \f[C]/U\f[], or
\f[C]/H\f[] flag, indicating that the key is just going down (without
being released), going up, or going down and being held until the
\[lq]off\[rq] event is received.
So, in general, modifier key codes will be followed by \f[C]/D\f[], and
precede the keycodes they are intended to modify.
If a sequence requires different sets of modifiers for different
keycodes, \f[C]/U\f[] can be used to release a modifier that was
previously pressed with \f[C]/D\f[].
Sequences may also have separate press and release sequences, separated
by the special word \f[C]RELEASE\f[].
Examples:
.IP
.nf
\f[C]
K5\ "qwer"
K6\ XK_Right
K7\ XK_Alt_L/D\ XK_Right
K8\ "V"\ XK_Left\ XK_Page_Up\ "v"
K9\ XK_Alt_L/D\ "v"\ XK_Alt_L/U\ "x"\ RELEASE\ "q"
\f[]
.fi
.PP
One pitfall here is that character strings in double quotes are just a
shorthand for the corresponding X key codes, ignoring case.
Thus, e.g., \f[C]"abc"\f[] actually denotes the keysym sequence
\f[C]XK_a\ XK_b\ XK_c\f[], as does \f[C]"ABC"\f[].
So in either case the \f[I]lowercase\f[] string \f[C]abc\f[] will be
output.
To output uppercase letters, it is always necessary to add one of the
shift modifiers to the output sequence.
E.g., \f[C]XK_Shift_L/D\ "abc"\f[] will output \f[C]ABC\f[] in
uppercase.
.PP
Translations are handled in slightly different ways depending on the
type of input event.
For key inputs (\f[C]K\f[]), there are separate separate press and
release sequences.
At the end of the press sequence, all down keys marked by \f[C]/D\f[]
will be released, and the last key not marked by \f[C]/D\f[],
\f[C]/U\f[], or \f[C]/H\f[] will remain pressed.
The release sequence will begin by releasing the last held key.
If keys are to be pressed as part of the release sequence, then any keys
marked with \f[C]/D\f[] will be repressed before continuing the
sequence.
Keycodes marked with \f[C]/H\f[] remain held between the press and
release sequences.
For instance, let's take a look at one of the more conspicuous
translations in the example above:
.IP
.nf
\f[C]
K9\ XK_Alt_L/D\ "v"\ XK_Alt_L/U\ "x"\ RELEASE\ "q"
\f[]
.fi
.PP
When the \f[C]K9\f[] key is pressed, the key sequence \f[C]Alt+v\ x\f[]
is initiated, keeping the \f[C]x\f[] key pressed (so it may start
auto\-repeating after a while).
The program then sits there waiting (possibly executing other
translations) until you release the \f[C]K9\f[] key again, at which
point the \f[C]x\f[] key is released and the \f[C]q\f[] key is pressed
(and released).
.PP
For the shuttle and jog wheel events there are no such separate press
and release sequences.
Only a single sequence is output in this case, and at the end of the
sequence, all down keys will be released.
For instance, the following translations move the cursor left or right
when the jog wheel is rotated left or right, respectively.
Also, the number of times one of the cursor keys is output corresponds
to the actual change in the value.
Thus, if in the example you move the jog wheel clockwise by 4 ticks,
say, the program will press (and release) \f[C]XK_Right\f[] four times,
moving the cursor 4 positions to the right.
.IP
.nf
\f[C]
JL\ XK_Left
JR\ XK_Right
\f[]
.fi
.PP
For the shuttle wheel with its 15 discrete positions (\-7..7), you have
two options.
You can treat it in the same fashion as the jog wheel, translating
incremental movements, by using \f[C]IL\f[] and \f[C]IR\f[] in lieu of
\f[C]JL\f[] and \f[C]JR\f[]:
.IP
.nf
\f[C]
IL\ XK_Left
IR\ XK_Right
\f[]
.fi
.PP
Or you can assign different output sequences to the 15 shuttle
positions, using the \f[C]S\-7\f[] ..
\f[C]S7\f[] input events.
For instance, you can use something like the following rules in order to
control playback speed (rewind and fast forward) with the shuttle in the
Kdenlive video editor:
.IP
.nf
\f[C]
S\-2\ "KJJ"\ \ #\ fast\ rewind
S\-1\ "KJ"\ \ \ #\ rewind
S0\ \ "K"\ \ \ \ #\ stop
S1\ \ "KL"\ \ \ #\ forward
S2\ \ "KLL"\ \ #\ fast\ forward
\f[]
.fi
.SS MIDI Translations
.PP
The output sequence can involve as many MIDI messages as you want, and
these can be combined freely with keyboard and mouse events in any
order.
There's no limitation on the type or number of MIDI messages that you
can put into a translation rule.
However, as already discussed in Section \f[I]MIDI Output\f[] above, you
need to invoke the shuttlepro program with the \f[C]\-o\f[] option to
make MIDI output work.
(Otherwise, MIDI messages in the output translations will just be
silently ignored.)
.PP
shuttlepro uses the following human\-readable notation for the various
kinds of MIDI messages (notes, program change, control change and pitch
bend; aftertouch and system messages are \f[I]not\f[] supported right
now, although they might be added in the future).
The syntax of these tokens is as follows:
.IP
.nf
\f[C]
token\ ::=\ (\ note\ |\ msg\ )\ [\ number\ ]\ [\ "\-"\ number]\ [\ "~"\ ]
note\ \ ::=\ (\ "A"\ |\ ...\ |\ "G"\ )\ [\ "#"\ |\ "b"\ ]
msg\ \ \ ::=\ "CH"\ |\ "PB"\ |\ "PC"\ |\ "CC"
\f[]
.fi
.PP
Case is ignored here, so \f[C]CC\f[], \f[C]cc\f[] or even \f[C]Cc\f[]
are considered to be exactly the same token by the parser, although by
convention we usually write them in uppercase.
Numbers are always integers in decimal.
.PP
MIDI messages are on channel 1 by default, but you can change this with
a dash followed by the desired channel number (1..16).
E.g., \f[C]C3\-10\f[] denotes note \f[C]C3\f[] on MIDI channel 10.
If multiple messages are output on the same MIDI channel, then you can
also use the special \f[C]CH\f[] token, which doesn't generate any
output by itself, but sets the default channel for subsequent MIDI
messages in the sequence.
For instance, the sequence \f[C]C5\-2\ E5\-2\ G5\-2\f[], which outputs a
C major chord on MIDI channel 2, can also be abbreviated as
\f[C]CH2\ C5\ E5\ G5\f[].
.PP
Note messages are specified using the customary notation (note name
\f[C]A..G\f[], optionally followed by an accidental, \f[C]#\f[] or
\f[C]b\f[], followed by the MIDI octave number).
Note that all MIDI octaves start at the note C, so \f[C]B0\f[] comes
before \f[C]C1\f[].
By default, \f[C]C5\f[] denotes middle C (see Section \f[I]Octave
Numbering\f[] below on how to change this).
Enharmonic spellings are equivalent, so, e.g., \f[C]D#\f[] and
\f[C]Eb\f[] denote exactly the same MIDI note.
.PP
Here is a quick rundown of the recognized MIDI messages, with an
explanation of how they work.
.PP
\f[B]CCn:\f[] Generates a MIDI control change message for controller
number \f[I]n\f[], where \f[I]n\f[] must be in the range 0..127.
In the case of jog or shuttle, the controller value will correspond to
the jog/shuttle position, clamped to the 0..127 (single data byte)
range.
For key input, the control change message will be sent once with a value
of 127 when the key is pressed, and then again with a value of 0 when
the key is released.
.PP
\f[B]Example:\f[] \f[C]CC7\f[] generates a MIDI message to change the
volume controller (controller #7), while \f[C]CC1\f[] changes the
modulation wheel (controller #1, usually some kind of vibrato effect).
You can bind these, e.g., to the jog wheel or a key as follows:
.IP
.nf
\f[C]
JL\ CC7
JR\ CC7
K5\ CC1
\f[]
.fi
.PP
When used with the jog wheel, you can also generate relative control
changes in a special \[lq]sign bit\[rq] format which is commonly used
for endless rotary controllers.
In this case, a +1 change is represented by the controller value 1, and
a \-1 change by 65 (a 1 with the sign in the 7th bit).
This special mode of operation is indicated with the \f[C]~\f[] suffix.
E.g., here's how to bind an Mackie\-style jog wheel (\f[C]CC60\f[])
event to the Shuttle's jog wheel:
.IP
.nf
\f[C]
JL\ CC60~
JR\ CC60~
\f[]
.fi
.PP
\f[B]PB:\f[] Generates a MIDI pitch bend message.
This works pretty much like a MIDI control change message, but with an
extended range of 0..16383, where 8192 denotes the center value.
Obviously, this message is best bound to the shuttle (albeit with a
resolution limited to 14 steps), but it also works with the jog wheel
(with each tick representing 1/128th of the full pitch bend range) and
even key input (in this case, 8192 is used as the \[lq]off\[rq] value,
so the pitch only bends up, never down).
.PP
\f[B]Example:\f[] Just \f[C]PB\f[] generates a pitch bend message.
You usually want to bind this to the incremental shuttle events, so the
corresponding translations would normally look like this:
.IP
.nf
\f[C]
IL\ PB
IR\ PB
\f[]
.fi
.PP
\f[B]PCn:\f[] This generates a MIDI program change message for the given
program number \f[I]n\f[], which must be in the 0..127 range.
This type of message is most useful with key input, where it is output
when the key is pressed (no output when the key is released, as there's
no on/off status for this message; to have another \f[C]PC\f[] message
generated at key release time, it must be put explicitly into the
\f[C]RELEASE\f[] part of the key binding).
In jog and shuttle assignments, this simply outputs the program change
message every time the wheel position changes (which probably isn't very
useful, although you could conceivably bind different \f[C]PC\f[]
messages to different shuttle wheel positions).
.PP
\f[B]Example:\f[] The following will output a change to program 5 when
\f[C]K5\f[] is pressed, and another change to program 0 when the key is
released (note that if you leave away the \f[C]RELEASE\ PC0\f[] part,
then only the \f[C]PC5\f[] will be output when pressing the key, nothing
happens when the key is released):
.IP
.nf
\f[C]
K5\ PC5\ RELEASE\ PC0
\f[]
.fi
.PP
\f[B]MIDI notes:\f[] Like \f[C]PC\f[] messages, these are most useful
when bound to key inputs.
The note starts (sending a note on MIDI message with maximum velocity)
when pressing the key, and finishes (sending the corresponding note off
message) when releasing the key.
In jog and shuttle assignments, a pair of note on/off messages is
generated.
.PP
\f[B]Example:\f[] The following binds key K6 to a C\-7 chord in the
middle octave:
.IP
.nf
\f[C]
K6\ C5\ E5\ G5\ Bb5
\f[]
.fi
.SS Octave Numbering
.PP
A note on the octave numbers in MIDI note designations is in order here.
There are various different standards for numbering octaves, and
different programs use different standards, which can be rather
confusing.
E.g., there's the ASA (Acoustical Society of America) standard where
middle C is C4, also known as \[lq]scientific\[rq] or \[lq]American
standard\[rq] pitch notation.
At least two other standards exist specifically for MIDI octave
numbering, one in which middle C is C3 (so the lowest MIDI octave starts
at C\-2), and zero\-based octave numbers, which start at C0 and have
middle C at C5.
There's not really a single \[lq]best\[rq] standard here, but the latter
tends to appeal to mathematically inclined and computer\-savvy people,
and is also what is used by default in the shuttlerc file.
.PP
However, you may want to change this, e.g., if you're working with
documentation or MIDI monitoring software which uses a different
numbering scheme.
To do this, just specify the desired offset for the lowest MIDI octave
with the special \f[C]MIDI_OCTAVE\f[] directive in the configuration
file.
For instance:
.IP
.nf
\f[C]
MIDI_OCTAVE\ \-1\ #\ ASA\ pitches\ (middle\ C\ is\ C4)
\f[]
.fi
.PP
Note that this transposes \f[I]all\f[] existing notes in translations
following the directive, so if you add this option to an existing
configuration, you probably have to edit the note messages in it
accordingly.
.SH Hotplugging
.PP
It is possible to use the Linux udev system to have the shuttlepro
program invoked automatically whenever a Shuttle device is plugged into
the computer.
However, before you do this please note the following caveats:
.IP \[bu] 2
The hotplugging feature interferes with regular use of the program
because shuttlepro needs exclusive access to the device.
In other words, once you've set up hotplugging, you won't be able to run
the program from the command line any more.
(Unless you manually kill the auto\-launched shuttlepro process first,
that is.
And it will keep coming back each time you plug in the device.)
.IP \[bu] 2
With hotplugging, there's no (easy) way to see the output from the
program, so you can't debug your translations any more.
Thus you want to make sure that you have your shuttlepro configuration
set up beforehand.
.IP \[bu] 2
Using hotplugging with MIDI output is \f[I]not\f[] recommended, because
shuttlepro will then also start up Jack for you, which you probably
don't want if you're using Jack for anything else.
If you need MIDI output, consider using Jack session management instead,
as discussed in the \f[I]MIDI Output\f[] section.
.PP
That said, of course the hotplugging feature \f[I]is\f[] very convenient
in many situations, and it can be installed and uninstalled very easily:
.IP \[bu] 2
Run \f[C]sudo\ make\ install\-udev\f[] in the source directory to enable
hotplugging.
Now, whenever you plug in the device, shuttlepro should be invoked
automatically, and exit as soon as the device is unplugged.
You can check that it works by looking for the shuttlepro process in
your process monitor (or by running \f[C]pgrep\ \-a\ shuttlepro\f[]).
.IP \[bu] 2
Run \f[C]sudo\ make\ uninstall\-udev\f[] to disable hotplugging again.
Unplug the device, and everything should be back to normal.
.PP
Note that the \f[C]install\-udev\f[] target just installs the necessary
udev rules and a little helper script to launch shuttlepro, and
\f[C]uninstall\-udev\f[] removes those files again, that's all.
Normally, udev should pick up the changes automatically.
(If not, a reboot might be in order.)
.PP
You can also edit the shuttle\-hotplug script (which will end up in
/usr/local/bin by default) if you need to add some options to the
shuttlepro command.
As shipped, the script just runs \f[C]shuttlepro\ \-p\f[], so there's no
MIDI output and the default configuration file will be used.
.SH Notes
.PP
ShuttlePRO is free and open source software licensed under the GPLv3,
please check the accompanying LICENSE file for details.
.PP
Copyright 2013 Eric Messick (FixedImagePhoto.com/Contact)
.PD 0
.P
.PD
Copyright 2018 Albert Graef (<aggraef@gmail.com>)
.PP
The sources of this program can be found on
Github (https://github.com/agraef/ShuttlePRO).
This is a fork of Eric Messick's original
version (https://github.com/nanosyzygy/ShuttlePRO) which doesn't seem to
be maintained any longer.
.PP
Eric Messick wrote the original ShuttlePRO version in 2013, based on
earlier code by Trammell Hudson and Arendt David.
The present version, by Albert Graef, offers some bug fixes and
improvements, such as additional command line options, automatic
detection of Shuttle devices, and, most notably, Jack MIDI support.
.PP
Note that while the original ShuttlePRO still uses basic regular
expressions which are considered largely obsolete these days, this
version uses modern (extended) regexes for matching translation sections
instead.
This introduces slight incompatibilities, but generally most
configurations written for Eric's original ShuttlePRO program should
also work with the present version.
In the worst case, you may have to escape some characters which have a
special meaning in extended regexes, see regex(7) for details.
.PP
Eric's original README along with some accompanying files can still be
found in the attic subdirectory in the sources.
You might want to consult these in order to get the program to work on
older Linux systems.
.PP
The udev hotplugging configuration contained in the udev subdirectory is
based on Shamanon's source (https://github.com/Shamanon/ShuttlePRO).
.PP
ShuttlePRO relies on the Linux kernel driver for the Shuttle devices,
and its keyboard and mouse support is tailored to X11, i.e., as far as I
can tell it's pretty much tied to Linux and X11 right now.
Hence there's no Mac or Windows version of the program; you'll have to
use Contour Design's own software offerings for these systems.