# Copyright 2013 Eric Messick (FixedImagePhoto.com/Contact) # Copyright 2018 Albert Graef # # Lines in this file starting with # are comments. # This program works pretty much like Eric Messick's shuttlepro program, # but it translates MIDI input rather than input events from the Contour # Design Shuttle devices. By default, the program creates a Jack MIDI # client named "midizap" with a single input port, which you'll have to # connect to the MIDI controller that you want to use (e.g., using a # patchbay program like qjackctl; non-Jack ALSA MIDI inputs can be # accommodated using a2jmidid). # Both the Jack client name and the number of (input and output) ports # can be adjusted, either from the command line, using the -j and -o # options (these always take priority), or by employing the following # midizaprc directives. NOTE: These options only take effect # immediately after program start, when the Jack client is initialized. # If you edit them later, you need to restart the program, so that a new # Jack client is created. # The JACK_NAME directive is used to change the client name. # (Uncomment the line and edit the name as needed.) This is useful, # e.g., if you're running multiple instances of midizap using different # configurations for different controllers, and you want to have them # named appropriately so that they can be wired up more easily using the # qjackctl patchbay. #JACK_NAME "midizap" # The number of ports given with the JACK_PORTS directive must be # 1 or 2. It causes the given number of both input and output ports to # be created. This option is useful if you want to translate MIDI # messages, see the [MIDI] section below for details. Two input and # output ports can be employed, e.g., if you also need to provide # backward translations for controller feedback, see the [MIDI2] section # below for an example. #JACK_PORTS 2 # Other than the input being MIDI instead of the Shuttle's key and wheel # events, the program works like Eric Messick's original. Each section # in the file (starting with a name in brackets and a regex to be # matched against the window class and name) specifies the bindings for # one application. A section at the end without regex provides default # bindings if none of the other sections are matched. Within each # section, bindings are introduced with the name of the MIDI message # being assigned, followed by a sequence of X KeySyms and/or MIDI # messages to be output when the MIDI message is received. # Here is a brief rundown of the supported notation for MIDI messages # (please check the documentation for details). # CC<0..127>: control change message for the given controller # PC<0..127>: program change message # PB: pitch bend message # CP: channel pressure # KP:: key pressure (aftertouch) # <#b>: MIDI note (on or off) # Note messages are specified using the customary notation (note name # A..G, optionally followed by an accidental, # or b, followed by a MIDI # octave number). The same notation is also used with aftertouch (KP) # messages, which always apply to a specific note (in contrast, channel # pressure (CP) always applies to all notes on a single MIDI channel). # Enharmonic spellings are equivalent, so, e.g., D#5 and Eb5 denote # exactly the same MIDI note. All MIDI octaves start at the note C, so # B0 comes before C1. By default, octave numbers are zero-based, so C0 # is MIDI note 0, C5 denotes middle C, A5 is the chamber pitch, etc. # However, you can adjust this to your liking by specifying the offset # of the lowest MIDI octave. Two of the most common alternatives are # listed below (uncomment one of the following lines to use these): #MIDI_OCTAVE -1 # ASA (Acoustical Society of America; middle C is C4) #MIDI_OCTAVE -2 # alternate MIDI (various manufacturers; middle C is C3) # The program distinguishes between messages on different MIDI channels. # By default, messages are assumed to be on MIDI channel 1, but the MIDI # channel can be specified explicitly following a dash at the end of the # message token. E.g., a message on MIDI channel 10 would be denoted # CC7-10 or C#3-10. # Each of these messages can be either "on" or "off", and so they can # have different "press" and "release" keystrokes associated with them. # In addition, all messages except PC (which doesn't have a data value) # can also have their value changes translated, in which case they have # associated key bindings which are executed each time the value # increases or decreases, respectively. Such bindings are indicated # with the suffixes "+" and "-". You can also use the "=" suffix to # indicate that the same translation should be applied to both increases # and decreases of the controller or pitch bend value. Thus, e.g., CC7= # indicates that the same translation applies for both CC7+ and CC7-. # This is most commonly used with pure MIDI -> MIDI translations. # There is also another special mode for these incremental bindings, # incremental "bit-sign" mode. The suffixes "<", ">" and "~" can be # used in lieu of "+", "-" and "=" with the CC token to properly # interpret the control values of endless rotary encoders and jog wheels # on Mackie-like devices. These encoders send values < 64 for # increases, and > 64 for decreases, where the first 6 bits of the value # denote the actual amount of change relative to the current value. # Debugging options: You want to run the program in a terminal window to # see its output when using these. The following line, when # uncommented, prints the section recognized for the window in focus: #DEBUG_REGEX # This option prints the contents of the entire configuration file, as # parsed by the program, in a human-readable format: #DEBUG_STROKES # You can also use the following option to have the recognized # translations printed out as the program executes them, in the same # format as DEBUG_STROKES: #DEBUG_KEYS # Finally, the following option prints all MIDI input (with the input # port number in the first, and the actual data value in the last # column). This is useful as a simple MIDI monitor, especially if you # want to figure out which tokens to use in your translations. #DEBUG_MIDI # NOTE: The debugging options can also be specified on the command line # using -d in conjunction with any of the letters r, s, k and m (or the # letter j if you also want debugging output from Jack). Just -d # without any option letter turns on all debugging options. # Sample bindings for video editing. These assume a Mackie-compatible # device, which are available from various manufacturers. They are more # or less standardized, and offer an abundance of useful controls, # making it easier to provide bindings which just work. If you don't # have one of these lying around, there are inexpensive emulations in # software (such as the TouchDAW app on Android), or you can just edit # the rules below to make them work with your controller. # On most Mackie-like devices there are some playback controls and # cursor keys which generate various note events, and a jog wheel which # generates CC60 messages. We put all of these to good use here. Note # that the CC60 control requires use of the aforementioned special # incremental mode for endless rotary encoders. # Bindings for the Kdenlive and Shotcut video editors (matched by their # WM_CLASS). These have very similar key bindings, see e.g.: # https://www.shotcut.org/howtos/keyboard-shortcuts/ [Kdenlive/Shotcut] ^shotcut\|kdenlive$ # Both Kdenlive and Shotcut use the J-K-L shortcuts, where each # successive J or L key decrements or increments the playback speed. We # assign these to the MCU Rewind and Forward controls. # playback controls A#7 XK_space # Play/Pause A7 "K" # Stop G7 "J" # Rewind G#7 "L" # Forward # punch in/out (sets in and out points) # Note that these are labeled drop/replace on some devices. We also # provide an alternative binding below. D#7 "I" # Set In E7 "O" # Set Out # up/down cursor movement (alternate binding for set in/out) C8 "I" # Set In C#8 "O" # Set Out # left/right cursor movement D8 XK_Home # Beginning D#8 XK_End # End # the jog wheel moves left/right by single frames CC60< XK_Left # Frame reverse CC60> XK_Right # Frame forward [MIDI] # The special "MIDI" default section is only active when MIDI output is # enabled (midizap -o). This allows you to use midizap as a MIDI mapper # translating MIDI input to MIDI output. Here's a simple example for # illustration purposes, which shows how to map both the Mackie master # fader and the jog wheel to CC7, so that they can be used as volume # controls. # Note that the master fader is PB (on MIDI channel 9), which has 128 # times the range of a MIDI controller, so we scale it down accordingly # by specifying a step size of 128. PB[128]-9= CC7 CC60~ CC7 # Drumkit example. The following translations should work on most MIDI # keyboards. We assume that the keyboard is set to MIDI channel 1 (the # usual default). The first four white keys (C, D, E and F) in the # fourth MIDI octave are mapped to the notes of a little drumkit on MIDI # channel 10, and the volume controller (CC7) is bound to the volume # controller on the same channel, so that you can change the output # volume as you play the drumkit. Note that you need a GM-compatible # software synthesizer such as Fluidsynth/Qsynth to make this work. C4 C3-10 D4 C#3-10 E4 D3-10 F4 D#3-10 CC7= CC7-10 [MIDI2] # Auxiliary MIDI translations. This is only used when midizap is # invoked with the -o2 option, so that it creates a second pair of MIDI # input and output ports. Input for this section only comes from the # second input port, and output goes to the second output port. This is # typically used for feedback to controllers featuring motor faders, # LEDs and the like, in which case the translations are often the # inverse of what's in the [MIDI] section. # Here we only map CC7 back to PB-9 (the MCU master fader). Please # check examples/APCmini.midizaprc for a more comprehensive example. CC7= PB[128]-9 # Default section (cursor and mouse emulation) [Default] # First, some Mackie-compatible bindings. # cursor movement D8 XK_Left D#8 XK_Right C8 XK_Up C#8 XK_Down # stop/play/rec are assigned to the left/middle/right mouse buttons A7 XK_Button_1 A#7 XK_Button_2 B7 XK_Button_3 # the jog wheel emulates the scroll wheel of the mouse CC60< XK_Scroll_Up CC60> XK_Scroll_Down # The following bindings should work on any MIDI keyboard. The C, D and # E keys in the middle octave are bound to the three mouse buttons, and # the modulation wheel (CC1) emulates the mouse wheel. The F, G, A and # B keys in the middle octave are mapped to the cursor keys (Left, Up, # Down, Right). C5 XK_Button_1 D5 XK_Button_2 E5 XK_Button_3 F5 XK_Left G5 XK_Up A5 XK_Down B5 XK_Right CC1+ XK_Scroll_Up CC1- XK_Scroll_Down