midizap/example.midizaprc

318 lines
13 KiB
Plaintext

# 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