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,
# except that input comes from Jack MIDI.  It creates a Jack MIDI client
# named "midizap" with a single input port, which you'll have to connect
# to your MIDI controller (e.g., using a patchbay program like qjackctl;
# non-Jack ALSA MIDI inputs can be accommodated using a2jmidid).

# 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 other
# 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 names use
# the customary MIDI notation, with # and b denoting accidentals; the
# number at the end denotes the MIDI octave in the range 0..10 (C5 is
# middle C)

# 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 also 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 plays 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. (There are also some other special modes for the
# incremental bindings, please check the documentation for details. In
# particular, the suffixes "<" and ">" can be used in lieu of "+" and
# "-" to properly interpret the control values of endless rotary
# encoders, such as the jog wheels on Mackie-like devices.)

# As already mentioned, translations can also contain other MIDI
# messages, in order to translate MIDI input to other MIDI data.  In
# fact, X KeySyms and MIDI messages can be mixed freely in the output.
# To enable this, invoke the program with the '-t' 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.


# Some convenient bindings for video editing and mouse emulation. These
# assume a Mackie MCU-like device. We use this as an example throughout,
# since they are standard gear in many studios, and offer a bunch 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).

# MCU-like equipment usually offers an abundance of (more or less)
# standard controls which can be put to good use with many applications.
# On most MCU devices there are some playback controls and cursor keys
# which generate various note events, and a jog wheel which generates
# CC60 messages. The latter are in a somewhat peculiar form, encoding
# relative control changes in so-called "sign bit" format which is also
# understood by many DAW programs. The special CC60< and CC60>
# translations shown in the examples below will usually interpret these
# correctly, although you may have to swap the increment/decrement
# actions on some devices.


# 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 then
# increments the playback speed in the corresponding direction. 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 depending on your MCU device, you 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

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

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

# 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

# cursor movement
 D8  XK_Home     # Beginning
 D#8 XK_End      # End
# alternate binding for set in/out
 C8  "I"         # Set In
 C#8 "O"         # Set Out

# 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 -t). 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 the
# MCU jog wheel to CC7, so that it can be used as a volume control.

 CC60< CC7
 CC60> CC7


# 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 (note that these
# bindings will only be active when the [MIDI] default section above
# isn't used)
 CC60< XK_Scroll_Up
 CC60> XK_Scroll_Down