# 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.  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).

# Other than the input being MIDI instead of the Shuttle's key and wheel
# events, the program works exactly the same. 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 more details).

# CC<0..127>: control change message for the given controller
# PC<0..127>: program change message
# PB: pitch bend message
# <A..G><#b><0..10> (MIDI notes): MIDI note (on or off)

# Note messages are specified using the cutomary notation (note name
# A..G, optionally followed by an accidental, # or b, followed by a MIDI
# octave number. Enharmonic spellings are equivalent, so, e.g., D# and
# Eb 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 (usually at 440 Hz), 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, e.g., 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.
# E.g., a "note on" message with non-zero velocity emulates a button
# press, while the corresponding "note off" emulates a button release,
# just as if the MIDI keys were just ordinary keys on a computer
# keyboard. The same holds true for control change messages (here any
# non-zero controller value means "on", zero "off"), and pitch bends
# (here the center value of the pitch wheel means "off", any other value
# means "on"). The program change messages play a somewhat special role
# in that they don't actually have any "off" messages associated with
# them, so to keep in line with the other kinds of MIDI messages we
# consider them as being "pressed" and then "released" immediately
# afterwards.

# In addition, control change and pitch bend messages can also be
# interpreted as incremental changes, and have associated key bindings
# which are executed each time the controller or pitch bend value
# increases or decreases, respectively. Such bindings are indicated with
# the suffixes "+" and "-". Thus, e.g., a key sequence bound to CC7+
# will be executed each time the value of controller 7 increases, and
# CC7- will be executed each time it decreases. PB+ and PB- do they same
# for pitch bends. 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 the 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.

# As already mentioned, translations can also contain other MIDI
# messages, in order to translate MIDI input to MIDI output to be passed
# on to to other MIDI devices and applications. In fact, X KeySyms and
# MIDI messages can be mixed freely in the output. To enable this,
# invoke the program with the '-o' option.  This creates a MIDI output
# port, which can then be hooked up to other Jack MIDI applications.
# (Otherwise, MIDI messages in the translations will just be ignored.)

# 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

# NOTE: The debugging options can also be specified on the command line
# using -d in conjunction with any of the letters r, s and k (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 and mouse emulation.

# These mostly assume a Mackie MCU-like DAW controller device. We use
# this as an example throughout, since devices of this kind are standard
# gear in many studios, and they offer an abundance of useful controls.
# If you don't have one of these lying around, there are inexpensive MCU
# emulations in software (such as the TouchDAW app on Android).

# On most MCU-style 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.


# Shotcut (WM_CLASS is "shotcut")
# see https://www.shotcut.org/howtos/keyboard-shortcuts/

[Shotcut] ^shotcut$

# Shotcut uses the customary J-K-L shortcuts, 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 your device may not have these, or they may be labeled
# differently, so we 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 single frames to the left or the right
 CC60< XK_Left    # Frame reverse
 CC60> XK_Right   # Frame forward


# Kdenlive (same bindings as above)

[Kdenlive] ^kdenlive$

# 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)
 D#7 "I"         # Set In
 E7  "O"         # Set Out

# alternate binding for set in/out (cursor up/down)
 C8  "I"         # Set In
 C#8 "O"         # Set Out

# cursor left/right
 D8  XK_Home     # Beginning
 D#8 XK_End      # End

# jog wheel
 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 translate midizap's MIDI
# input for use with other MIDI devices and applications. Here's a
# simple example for illustration purposes, which shows how to map both
# the MCU master fader and the jog wheel to CC7, so that they can be
# used as volume controls.

# Note that the MCU 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.

# This is the inverse of the translation in the [MIDI] section above,
# mapping CC7 back to PB-9 (the MCU master fader), appropriately scaled.
 CC7= PB[128]-9


# Default section (cursor and mouse emulation)

[Default]

# 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). Please note that most of these bindings, as well as the
# CC60 bindings above, will only be active when the [MIDI] default
# section above isn't used (invoke midizap without the -o option).

 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