example.midizaprc

# Copyright 2013 Eric Messick (FixedImagePhoto.com/Contact)
# Copyright 2018 Albert Graef <aggraef@gmail.com>
#
# 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:<note>: key pressure (aftertouch)
# <A..G><#b><num>: 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