nixo
/
midizap
1
0
Fork 0
Code Issues Pull Requests Releases Wiki Activity

Update the manual.

master 0.6
Albert Graef 2018-10-15 06:23:23 +02:00
parent b39484c0ac
commit 15b8b574b3
2 changed files with 108 additions and 81 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

50
README.md
View File

@ -6,7 +6,7 @@ midizap -- control your multimedia applications with MIDI
# Synopsis
midizap [-hkn] [-d[rskmj]] [-j *name*] [-ost[*n*]] [-P[*prio*]] [-r *rcfile*]
midizap [-hkn] [-d[rskmj]] [-j *name*] [-ost[*n*]] [-P[*prio*]] [[-r] *rcfile*]
# Options
@ -31,8 +31,8 @@ midizap [-hkn] [-d[rskmj]] [-j *name*] [-ost[*n*]] [-P[*prio*]] [-r *rcfile*]
-P[*prio*]
: Run with the given real-time priority (default: 90). See Section *Jack-Related Options*.
-r *rcfile*
: Set the configuration file name. Default: taken from the MIDIZAP_CONFIG_FILE environment variable if it exists, or ~/.midizaprc if it exists, /etc/midizaprc otherwise. See Section *Configuration File*.
[-r] *rcfile*
: Set the configuration file name. The `-r` is optional, but still supported for backward compatibility. Default: taken from the MIDIZAP_CONFIG_FILE environment variable if it exists, or ~/.midizaprc if it exists, /etc/midizaprc otherwise. See Section *Configuration File*.
-s[*n*]
: Pass through system messages from MIDI input to output; *n* optionally specifies the port (0 = none, 1 = first, 2 = second port only), default is pass-through on both ports (if available). This overrides the corresponding directive in the configuration file. See Section *Jack-Related Options*.
@ -42,13 +42,11 @@ midizap [-hkn] [-d[rskmj]] [-j *name*] [-ost[*n*]] [-P[*prio*]] [-r *rcfile*]
# Description
midizap lets you control your multimedia applications using [MIDI][], the Musical Instrument Digital Interface. Modern MIDI controllers are often USB class devices which can be connected to computers without any ado. midizap makes it possible to use this gear with just about any X11-based application. To these ends, it translates Jack MIDI input into X keyboard and mouse events, and optionally MIDI output. It does this by matching the `WM_CLASS` and `WM_NAME` properties of the window that has the keyboard focus against the regular expressions for each application section in its configuration (midizaprc) file. If a regex matches, the corresponding set of translations is used. If a matching section cannot be found, or if it doesn't define a suitable translation, the program falls back to a set of translations in a default section at the end of the file, if available.
midizap lets you control your multimedia applications using [MIDI][], the venerable "Musical Instrument Digital Interface" protocol which has been around since the 1980s. Modern MIDI controllers are usually USB class devices which don't require any special interface or driver, and they are often much cheaper than more specialized gear. With midizap you can leverage these devices to control just about any X11-based application. To these ends, it translates Jack MIDI input into X keyboard and mouse events, and optionally MIDI output. It does this by matching the class and title of the focused window against the regular expressions for each application section in its configuration (midizaprc) file. If a regex matches, the corresponding set of translations is used. If a matching section cannot be found, or if it doesn't define a suitable translation, the program falls back to a set of default translations.
The midizaprc file is just an ordinary text file which you can edit to configure the program. The configuration language is fairly straightforward, basically the file is just a list of MIDI messages (denoted with familiar human-readable mnemonics, no hex numbers!) and their translations, which is divided into sections for different applications. An example.midizaprc file is included in the sources to get you started, and you can find some more examples of configuration files for various purposes in the examples directory.
The midizaprc file is just an ordinary text file which you can edit to configure the program. The configuration language is fairly straightforward, basically the file is just a list of MIDI messages (denoted with familiar human-readable mnemonics, no hex numbers!) and their translations. An example.midizaprc file is included in the sources to get you started, and you can find more examples of configuration files for various purposes in the examples subdirectory.
midizap provides you with a way to hook up just about any MIDI controller to your applications. Even if your target application already supports MIDI, midizap's MIDI output option will be useful if your controller can't work directly with the application because of protocol incompatibilities. In particular, you can use midizap to turn pretty much any MIDI controller with enough faders and buttons into a Mackie-compatible mixing console ready to be used with most DAW (digital audio workstation) programs. Another common use case is video editing software, which rarely offers built-in MIDI support. midizap allows you to map the faders, encoders and buttons of your MIDI controller to keyboard commands of your video editor for cutting, marking, playback, scrolling, zooming, etc.
In other words, as long as the target application can be controlled with simple keyboard shortcuts and/or MIDI commands, chances are that midizap can make it work (at least to some extent) with your controller.
Even if your target application already supports MIDI, midizap's MIDI output option will be useful if your controller can't work directly with the application because of protocol incompatibilities. In particular, you can use midizap to turn any MIDI controller with enough faders and buttons into a Mackie-compatible device ready to be used with most DAW (digital audio workstation) programs. Another common use case is photo and video editing software. This kind of software often lacks built-in MIDI support, and midizap can then be used to map the faders, encoders and buttons of your MIDI controller to keyboard commands for adjusting colors, cutting, marking, playback, scrolling, zooming, etc. In other words, as long as the target application can be controlled with simple keyboard shortcuts and/or MIDI commands, chances are that midizap can make it work (at least to some extent) with your controller.
# Installation
@ -66,7 +64,11 @@ After installation the system-wide default configuration file will be in /etc/mi
The ~/.midizaprc file, if it exists, takes priority over /etc/midizaprc, so it becomes your personal default midizap configuration. The midizaprc file included in the distribution is really just an example; you're expected to edit this file to adjust the bindings for the MIDI controllers and the applications that you use.
It is also possible to specify the configuration file to be used, by invoking midizap with the `-r` option followed by the name of the midizaprc file on the command line. This is often used with more specialized configurations dealing with specific applications or MIDI controllers. E.g., to try one of sample configurations in the sources: `midizap -r examples/MPKmini2.midizaprc`
It is also possible to specify the configuration file to be used, by invoking midizap with the name of the midizaprc file on the command line. This is often used with more specialized configurations dealing with specific applications or MIDI controllers. E.g., to try one of sample configurations in the sources:
~~~
midizap examples/APCmini.midizaprc
~~~
The program automatically reloads the midizaprc file whenever it notices that the file has been changed. Thus you can edit the file while the program keeps running, and have the changes take effect immediately without having to restart the program. When working on new translations, you may want to run the program in a terminal, and employ some or all of the debugging options explained below to see exactly how your translations are being processed.
@ -76,7 +78,7 @@ The midizap program is a command line application, so you typically run it from
Try `midizap -h` for a brief summary of the available options with which the program can be invoked.
midizap uses [Jack][] for doing all its MIDI input and output, so you need to be able to run Jack and connect the Jack MIDI inputs and outputs of the program. We recommend using a Jack front-end and patchbay program like [QjackCtl][] for this purpose. In QjackCtl's setup, make sure that you have selected `seq` as the MIDI driver. This exposes the ALSA sequencer ports of your MIDI hardware and other non-Jack ALSA MIDI applications as Jack MIDI ports, so that they can easily be connected to midizap. As an alternative, you can also run [a2jmidid][] as a separate ALSA-Jack MIDI bridge. (The latter method works well with both Jack1 and Jack2. Jack's built-in ALSA-Jack MIDI bridge also works very well in Jack1, but in Jack2 it doesn't list the ALSA ports by their name, which makes it rather unusable there because you'll have to guess which port represents which device or application.)
midizap uses [Jack][] for doing all its MIDI input and output, so you need to be able to run Jack and connect the Jack MIDI inputs and outputs of the program. We recommend using a Jack front-end and patchbay program like [QjackCtl][] for this purpose. In QjackCtl's setup, make sure that you have selected `seq` as the MIDI driver. This exposes the ALSA sequencer ports of your MIDI hardware and other non-Jack ALSA MIDI applications as Jack MIDI ports, so that they can easily be connected to midizap. As an alternative, you can also run [a2jmidid][] as a separate ALSA-Jack MIDI bridge. The latter method works well with both Jack1 and Jack2. Jack's built-in bridge also does the job in Jack1, but in Jack2 it doesn't list the ALSA ports by their name, so it's better to use a2jmidid in that case. When in doubt, just use a2jmidid. You can have QJackCtl autostart a2jmidid by placing the command `a2jmidid -e &` into the "Execute script after Startup" field which can be found under "Options" in QJackctl's Setup dialog.
Having that set up, start Jack, make sure that your MIDI controller is connected, and try running `midizap` from the command line (without any arguments). In QjackCtl, open the Connections dialog and activate the second tab named "MIDI", which shows all available Jack MIDI inputs and outputs. On the right side of the MIDI tab, you should now see a client named `midizap` with one MIDI input port named `midi_in`. That's the one you need to connect to your MIDI controller, whose output port should be visible under the `alsa_midi` client on the left side of the dialog (or the `a2j` client, if you're using a2jmidid).
@ -143,9 +145,7 @@ Besides MIDI notes and control change (`CC`) messages, the midizap program also
# Jack-Related Options
There are some additional directives (and corresponding command line options) to configure midizap's Jack setup in various ways. We take a look at these in the following. If both the command line options and directives in the midizaprc file are used, the former take priority, so that it's possible to override the configuration settings from the command line.
Note that all these options can only be set at program startup. If you later edit the corresponding directives in the configuration file, the changes won't take effect until you restart the program.
There are some additional directives (and corresponding command line options) to configure midizap's Jack setup in various ways. If both the command line options and directives in the midizaprc file are used, the former take priority, so that it's possible to override the configuration settings from the command line. Note that all these options can only be set at program startup. If you later edit the corresponding directives in the configuration file, the changes won't take effect until you restart the program.
## Jack Client Name and MIDI Port Setup
@ -169,9 +169,11 @@ Not very surprisingly, at least one output port is needed if you want to output
## MIDI Connections
Setting up all the required connections for the Jack MIDI ports can be a tedious and error-prone task, especially if you have to deal with complex setups involving feedback and/or multiple midizap instances. It's all to easy to mess this up when doing it manually, and either end up with a dysfunctional setup or, even worse, MIDI feedback loops crashing your Jack MIDI clients. While it's possible to automatize the MIDI connections, e.g., with QjackCtl's persistent MIDI patchbay facility, this is often inconvenient if you need to accommodate multiple midizap configurations and you already have a complicated studio setup which you don't want to mess with.
Setting up all the required connections for the Jack MIDI ports can be a tedious and error-prone task, especially if you have to deal with complex setups involving feedback and/or multiple midizap instances. It's all to easy to mess this up when doing it manually, and end up with a dysfunctional setup or, even worse, MIDI feedback loops crashing your Jack MIDI clients. While it's possible to automatize the MIDI connections, e.g., with QjackCtl's persistent MIDI patchbay facility, this is often inconvenient if you need to accommodate multiple midizap configurations and you already have a complicated studio setup which you don't want to mess with.
As a remedy, midizap offers its own built-in patchbay functionality using the `JACK_IN` and `JACK_OUT` directives, which let you specify the required connections in the configuration itself and be done with it. The port number is tacked on to the directive, so, e.g., `JACK_IN2` connects the second input port (if the port number is omitted then the first port is assumed). The directive is followed by an (extended) regular expression (see the regex(7) manual page) to be matched against the Jack MIDI ports of your devices and applications. A connection will be established automatically by midizap whenever a Jack MIDI port matches the regular expression, as well as the port type and I/O direction. This also works dynamically, as new devices get added and new applications are launched at runtime.
As a remedy, midizap offers its own built-in patchbay functionality using the `JACK_IN` and `JACK_OUT` directives, which let you specify the required connections in the configuration itself and be done with it. The port number is tacked on to the directive, so, e.g., `JACK_IN2` connects the second input port. If the port number is omitted then it defaults to 1, so both `JACK_OUT1` and just `JACK_OUT` connect the first output port. The directive is followed by a regular expression to be matched against the Jack MIDI ports of your devices and applications. Please see the regex(7) manual page for a discussion of the syntax and meaning of regular expressions. Note that regular expressions come in two different flavors, "basic" and "extended"; midizap uses the latter kind.
A connection will be established automatically by midizap whenever a MIDI port belonging to another Jack client matches the regular expression, as well as the port type and I/O direction. This also works dynamically, as new devices get added and new applications are launched at runtime.
For instance, the following lines (from the XTouchONE.midizaprc example) connect midizap to an X-Touch One device on one side and Ardour's Mackie control port on the other:
@ -184,12 +186,18 @@ JACK_OUT2 X-Touch One MIDI 1
To break this down, the X-Touch One device will be connected to midizap's first input port, midizap's first output port to Ardour's Mackie control input, Ardour's Mackie control output to midizap's second input port, and midizap's second output port back to the device. This is a typical setup for bidirectional communication between controller and application as described in the *MIDI Feedback* section. The sample configurations in the examples folder in the sources have all been set up in this manner, so that they will create the required connections automatically.
Please note that at this time, the built-in patchbay is only available through these directives, there are no corresponding command line options. Also, only one directive can be specified for each port, but since midizap will connect to all ports matching the given regular expression, you can connect to more than one application or device by just listing all the alternatives. For instance, to have midizap's output connected to both Ardour and Pd, you might use a directive like:
Please note that in the present implementation, the built-in patchbay is only available through these directives, there are no corresponding command line options. Also, only one directive can be specified for each port, but since midizap will connect to all ports matching the given regular expression, you can connect to more than one application or device by just listing all the alternatives. For instance, to have midizap's output connected to both Ardour and Pd, you might use a directive like:
~~~
JACK_OUT1 ardour:MIDI control in|Pure Data Midi-In 1
~~~
All matches are done against full port names including the *client-name*`:` prefix, so you can specify exactly which ports of which clients should be connected. However, note that in contrast to the QJackCtl patchbay, midizap does substring matches by default, so that, e.g., `MIDI control` will match *any* Ardour MIDI control port, in any instance of the program (and also ports with the same name in other programs). If you want to specify an exact match, you need to use the `^` and `$` anchors as follows:
~~~
JACK_OUT1 ^ardour:MIDI control in$
~~~
## Pass-Through
If at least one output port is available then it also becomes possible to pass through MIDI messages from input to output unchanged. Two options are available for this: `-t` which passes through any ordinary (non-system) message for which there are no translations (not even in the default section), and `-s` which passes through all system messages. The former is convenient if the incoming MIDI data only needs to be modified in a few places to deal with slight variations in the protocol. The latter may be needed when the input data may contain system messages; midizap cannot translate these, but it can pass them on unchanged when necessary. You can find examples for both use cases in the examples folder in the sources.
@ -848,7 +856,7 @@ CC1[128] $CC0 # don't do this!
midizap *will* catch such mishaps after a few iterations, but it's better to avoid them in the first place. We mention in passing that in theory, recursive macro calls in conjunction with value lists and change detection make the configuration language Turing-complete. However, there's a quite stringent limit on the number of recursive calls, and there are no variables and no iteration constructs, so these facilities aren't really suitable for general-purpose programming.
But there's still a lot of fun to be had with macros despite their limitations. Here's another instructive example which spits out the individual bits of a controller value, using the approach that we discussed earlier in the context of nibble extraction. Input comes from `CC7` in the example, and bit #*i* of the controller value becomes `CC`*i* in the output, where *i* runs from 0 to 6. Note that each of these rules uses a successively smaller power of 2 as modulus and passes on the remainder to the next rule, while transposition is used to extract and output the topmost bit in the quotient.
But there's still a lot of fun to be had with macros despite their limitations. Here's another instructive example which spits out the individual bits of a controller value, using the approach that we discussed earlier in the context of nibble extraction. Input comes from `CC7` in the example, and bit #*i* of the controller value becomes `CC`*i* in the output, where *i* runs from 0 to 6. Note that each of these rules uses a successively smaller power of 2 as modulus and passes on the remainder to the next rule, while transposition is used to extract and output the topmost bit in the quotient. (You may want to run this example with debugging enabled to see what exactly is going on there.)
~~~
CC7[64]{0} $CC6 CC6'
@ -859,9 +867,7 @@ CC3[4]{0} $CC2 CC2'
CC2[2]{0} CC0 CC1'
~~~
You may want to run this example with debugging enabled to see what exactly is going on there.
The "naming" of macros is another issue worth discussing here. In principle, any message which can occur on the left-hand side of a mod translation (i.e., everything but `PC`) can also be used as a macro. Unfortunately, in general you can't be sure which messages might show up in *real* MIDI input. For instance, in the example above the macro translations for `CC2` to `CC6` might also be triggered by real MIDI input instead of macro calls. While this may be useful at times, e.g., for testing purposes, it is most likely going to confuse unsuspecting end users. As a remedy, midizap also provides a special kind of *macro event*, denoted `M0` to `M127`. These "synthetic" messages work exactly like `CC` messages, but they are guaranteed to never occur as real input, and they can *only* be used in macro calls and on the left-hand side of mod translations. We can rewrite the previous example using macro events as follows:
In principle, any message which can occur on the left-hand side of a mod translation (i.e., everything but `PC`) can also be used as a macro. Unfortunately, in general you can't be sure which messages might show up in *real* MIDI input. For instance, in the example above the macro translations for `CC2` to `CC6` might also be triggered by real MIDI input instead of macro calls. While this may be useful at times, e.g., for testing purposes, it is most likely going to confuse unsuspecting end users. As a remedy, midizap also provides a special kind of *macro event*, denoted `M0` to `M127`. These "synthetic" messages work exactly like `CC` messages, but they are guaranteed to never occur as real input, and they can *only* be used in macro calls and on the left-hand side of mod translations. We can rewrite the previous example using macro events as follows:
~~~
CC7[64]{0} $M6 CC6'
@ -911,9 +917,7 @@ translation ::= midi-token { key-token | midi-token }
directive ::= "DEBUG_REGEX" | "DEBUG_STROKES" | "DEBUG_KEYS" |
"DEBUG_MIDI" | "MIDI_OCTAVE" number |
"JACK_NAME" string | "JACK_PORTS" number |
"JACK_IN" regex | "JACK_OUT" regex |
"JACK_IN1" regex | "JACK_OUT1" regex |
"JACK_IN2" regex | "JACK_OUT2" regex |
"JACK_IN" [number] regex | "JACK_OUT" [number] regex |
"PASSTHROUGH" [ number ] |
"SYSTEM_PASSTHROUGH" [ number ]

139
midizap.1
View File

@ -8,7 +8,7 @@ midizap \[en] control your multimedia applications with MIDI
.SH Synopsis
.PP
midizap [\-hkn] [\-d[rskmj]] [\-j \f[I]name\f[]] [\-ost[\f[I]n\f[]]]
[\-P[\f[I]prio\f[]]] [\-r \f[I]rcfile\f[]]
[\-P[\f[I]prio\f[]]] [[\-r] \f[I]rcfile\f[]]
.SH Options
.TP
.B \-h
@ -69,8 +69,10 @@ See Section \f[I]Jack\-Related Options\f[].
.RS
.RE
.TP
.B \-r \f[I]rcfile\f[]
.B [\-r] \f[I]rcfile\f[]
Set the configuration file name.
The \f[C]\-r\f[] is optional, but still supported for backward
compatibility.
Default: taken from the MIDIZAP_CONFIG_FILE environment variable if it
exists, or ~/.midizaprc if it exists, /etc/midizaprc otherwise.
See Section \f[I]Configuration File\f[].
@ -97,47 +99,43 @@ See Section \f[I]Jack\-Related Options\f[].
.SH Description
.PP
midizap lets you control your multimedia applications using
MIDI (https://www.midi.org/), the Musical Instrument Digital Interface.
Modern MIDI controllers are often USB class devices which can be
connected to computers without any ado.
midizap makes it possible to use this gear with just about any
MIDI (https://www.midi.org/), the venerable \[lq]Musical Instrument
Digital Interface\[rq] protocol which has been around since the 1980s.
Modern MIDI controllers are usually USB class devices which don't
require any special interface or driver, and they are often much cheaper
than more specialized gear.
With midizap you can leverage these devices to control just about any
X11\-based application.
To these ends, it translates Jack MIDI input into X keyboard and mouse
events, and optionally MIDI output.
It does this by matching the \f[C]WM_CLASS\f[] and \f[C]WM_NAME\f[]
properties of the window that has the keyboard focus against the regular
expressions for each application section in its configuration
(midizaprc) file.
It does this by matching the class and title of the focused window
against the regular expressions for each application section in its
configuration (midizaprc) file.
If a regex matches, the corresponding set of translations is used.
If a matching section cannot be found, or if it doesn't define a
suitable translation, the program falls back to a set of translations in
a default section at the end of the file, if available.
suitable translation, the program falls back to a set of default
translations.
.PP
The midizaprc file is just an ordinary text file which you can edit to
configure the program.
The configuration language is fairly straightforward, basically the file
is just a list of MIDI messages (denoted with familiar human\-readable
mnemonics, no hex numbers!) and their translations, which is divided
into sections for different applications.
mnemonics, no hex numbers!) and their translations.
An example.midizaprc file is included in the sources to get you started,
and you can find some more examples of configuration files for various
purposes in the examples directory.
and you can find more examples of configuration files for various
purposes in the examples subdirectory.
.PP
midizap provides you with a way to hook up just about any MIDI
controller to your applications.
Even if your target application already supports MIDI, midizap's MIDI
output option will be useful if your controller can't work directly with
the application because of protocol incompatibilities.
In particular, you can use midizap to turn pretty much any MIDI
controller with enough faders and buttons into a Mackie\-compatible
mixing console ready to be used with most DAW (digital audio
workstation) programs.
Another common use case is video editing software, which rarely offers
built\-in MIDI support.
midizap allows you to map the faders, encoders and buttons of your MIDI
controller to keyboard commands of your video editor for cutting,
marking, playback, scrolling, zooming, etc.
.PP
In particular, you can use midizap to turn any MIDI controller with
enough faders and buttons into a Mackie\-compatible device ready to be
used with most DAW (digital audio workstation) programs.
Another common use case is photo and video editing software.
This kind of software often lacks built\-in MIDI support, and midizap
can then be used to map the faders, encoders and buttons of your MIDI
controller to keyboard commands for adjusting colors, cutting, marking,
playback, scrolling, zooming, etc.
In other words, as long as the target application can be controlled with
simple keyboard shortcuts and/or MIDI commands, chances are that midizap
can make it work (at least to some extent) with your controller.
@ -182,12 +180,17 @@ example; you're expected to edit this file to adjust the bindings for
the MIDI controllers and the applications that you use.
.PP
It is also possible to specify the configuration file to be used, by
invoking midizap with the \f[C]\-r\f[] option followed by the name of
the midizaprc file on the command line.
invoking midizap with the name of the midizaprc file on the command
line.
This is often used with more specialized configurations dealing with
specific applications or MIDI controllers.
E.g., to try one of sample configurations in the sources:
\f[C]midizap\ \-r\ examples/MPKmini2.midizaprc\f[]
.IP
.nf
\f[C]
midizap\ examples/APCmini.midizaprc
\f[]
.fi
.PP
The program automatically reloads the midizaprc file whenever it notices
that the file has been changed.
@ -221,11 +224,15 @@ easily be connected to midizap.
As an alternative, you can also run
a2jmidid (http://repo.or.cz/a2jmidid.git) as a separate ALSA\-Jack MIDI
bridge.
(The latter method works well with both Jack1 and Jack2.
Jack's built\-in ALSA\-Jack MIDI bridge also works very well in Jack1,
but in Jack2 it doesn't list the ALSA ports by their name, which makes
it rather unusable there because you'll have to guess which port
represents which device or application.)
The latter method works well with both Jack1 and Jack2.
Jack's built\-in bridge also does the job in Jack1, but in Jack2 it
doesn't list the ALSA ports by their name, so it's better to use
a2jmidid in that case.
When in doubt, just use a2jmidid.
You can have QJackCtl autostart a2jmidid by placing the command
\f[C]a2jmidid\ \-e\ &\f[] into the \[lq]Execute script after
Startup\[rq] field which can be found under \[lq]Options\[rq] in
QJackctl's Setup dialog.
.PP
Having that set up, start Jack, make sure that your MIDI controller is
connected, and try running \f[C]midizap\f[] from the command line
@ -399,11 +406,9 @@ option, see the following section for details.
.PP
There are some additional directives (and corresponding command line
options) to configure midizap's Jack setup in various ways.
We take a look at these in the following.
If both the command line options and directives in the midizaprc file
are used, the former take priority, so that it's possible to override
the configuration settings from the command line.
.PP
Note that all these options can only be set at program startup.
If you later edit the corresponding directives in the configuration
file, the changes won't take effect until you restart the program.
@ -457,9 +462,9 @@ of translations will be silently ignored.
Setting up all the required connections for the Jack MIDI ports can be a
tedious and error\-prone task, especially if you have to deal with
complex setups involving feedback and/or multiple midizap instances.
It's all to easy to mess this up when doing it manually, and either end
up with a dysfunctional setup or, even worse, MIDI feedback loops
crashing your Jack MIDI clients.
It's all to easy to mess this up when doing it manually, and end up with
a dysfunctional setup or, even worse, MIDI feedback loops crashing your
Jack MIDI clients.
While it's possible to automatize the MIDI connections, e.g., with
QjackCtl's persistent MIDI patchbay facility, this is often inconvenient
if you need to accommodate multiple midizap configurations and you
@ -471,14 +476,20 @@ using the \f[C]JACK_IN\f[] and \f[C]JACK_OUT\f[] directives, which let
you specify the required connections in the configuration itself and be
done with it.
The port number is tacked on to the directive, so, e.g.,
\f[C]JACK_IN2\f[] connects the second input port (if the port number is
omitted then the first port is assumed).
The directive is followed by an (extended) regular expression (see the
regex(7) manual page) to be matched against the Jack MIDI ports of your
devices and applications.
\f[C]JACK_IN2\f[] connects the second input port.
If the port number is omitted then it defaults to 1, so both
\f[C]JACK_OUT1\f[] and just \f[C]JACK_OUT\f[] connect the first output
port.
The directive is followed by a regular expression to be matched against
the Jack MIDI ports of your devices and applications.
Please see the regex(7) manual page for a discussion of the syntax and
meaning of regular expressions.
Note that regular expressions come in two different flavors,
\[lq]basic\[rq] and \[lq]extended\[rq]; midizap uses the latter kind.
.PP
A connection will be established automatically by midizap whenever a
Jack MIDI port matches the regular expression, as well as the port type
and I/O direction.
MIDI port belonging to another Jack client matches the regular
expression, as well as the port type and I/O direction.
This also works dynamically, as new devices get added and new
applications are launched at runtime.
.PP
@ -506,9 +517,9 @@ The sample configurations in the examples folder in the sources have all
been set up in this manner, so that they will create the required
connections automatically.
.PP
Please note that at this time, the built\-in patchbay is only available
through these directives, there are no corresponding command line
options.
Please note that in the present implementation, the built\-in patchbay
is only available through these directives, there are no corresponding
command line options.
Also, only one directive can be specified for each port, but since
midizap will connect to all ports matching the given regular expression,
you can connect to more than one application or device by just listing
@ -521,6 +532,22 @@ you might use a directive like:
JACK_OUT1\ ardour:MIDI\ control\ in|Pure\ Data\ Midi\-In\ 1
\f[]
.fi
.PP
All matches are done against full port names including the
\f[I]client\-name\f[]\f[C]:\f[] prefix, so you can specify exactly which
ports of which clients should be connected.
However, note that in contrast to the QJackCtl patchbay, midizap does
substring matches by default, so that, e.g., \f[C]MIDI\ control\f[] will
match \f[I]any\f[] Ardour MIDI control port, in any instance of the
program (and also ports with the same name in other programs).
If you want to specify an exact match, you need to use the \f[C]^\f[]
and \f[C]$\f[] anchors as follows:
.IP
.nf
\f[C]
JACK_OUT1\ ^ardour:MIDI\ control\ in$
\f[]
.fi
.SS Pass\-Through
.PP
If at least one output port is available then it also becomes possible
@ -2243,6 +2270,8 @@ Note that each of these rules uses a successively smaller power of 2 as
modulus and passes on the remainder to the next rule, while
transposition is used to extract and output the topmost bit in the
quotient.
(You may want to run this example with debugging enabled to see what
exactly is going on there.)
.IP
.nf
\f[C]
@ -2255,10 +2284,6 @@ CC2[2]{0}\ \ CC0\ \ CC1\[aq]
\f[]
.fi
.PP
You may want to run this example with debugging enabled to see what
exactly is going on there.
.PP
The \[lq]naming\[rq] of macros is another issue worth discussing here.
In principle, any message which can occur on the left\-hand side of a
mod translation (i.e., everything but \f[C]PC\f[]) can also be used as a
macro.
@ -2367,9 +2392,7 @@ translation\ ::=\ midi\-token\ {\ key\-token\ |\ midi\-token\ }
directive\ \ \ ::=\ "DEBUG_REGEX"\ |\ "DEBUG_STROKES"\ |\ "DEBUG_KEYS"\ |
\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ "DEBUG_MIDI"\ |\ "MIDI_OCTAVE"\ number\ |
\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ "JACK_NAME"\ string\ |\ "JACK_PORTS"\ number\ |
\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ "JACK_IN"\ regex\ |\ "JACK_OUT"\ regex\ |
\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ "JACK_IN1"\ regex\ |\ "JACK_OUT1"\ regex\ |
\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ "JACK_IN2"\ regex\ |\ "JACK_OUT2"\ regex\ |
\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ "JACK_IN"\ [number]\ regex\ |\ "JACK_OUT"\ [number]\ regex\ |
\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ "PASSTHROUGH"\ [\ number\ ]\ |
\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ "SYSTEM_PASSTHROUGH"\ [\ number\ ]