midizap/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 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
# 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# 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, 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, channel and key
# pressure messages (here any non-zero 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, channel and key pressure, and pitch bend
# messages 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 "-".  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.  The same
# applies to channel and key pressure as well as pitch bend messages.
# 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.

# 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

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

 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