Package: jack-matchmaker
jack-matchmakerAuto-connectJACKports as they appear and when they match the port patterns
given on the command line or read from a file.Descriptionjack-matchmakeris a small command line utility that listens to port
registrations by JACK clients and connects these ports when their names match
one of the port pattern pairs given on the command line at startup.jack-matchmakernever disconnects any ports.The port name patterns are specified as pairs of positional arguments or read
from a file (see below) andby defaultare always interpreted asPython regular expressions, where the first pattern of a pair is matched
against both output (readable) ports and input (writeable) ports, and the
second pattern of a pair is matched only against input ports. As many pattern
pairs as needed can be given.If the first pattern matches an input port, all output ports connected to that
input port will be connected to the input ports matching the second pattern.Patterns are matched against:normal port namesport aliasespretty-namesset in the port meta dataYou can runjack-matchmaker -oianto list all available output and input
ports with their aliases and pretty-names.InstallationBefore you install the software, please refer to the section
"Requirements".Then simply do:$ pip install jack-matchmakerThere is also anAUR packageavailable for Arch Linux users.UsageRunjack-matchmaker -h(or--help) to show help on the available command
line options.See also the section "Systemd service" below on how to usejack-matchmakeras
a systemd user service.ExamplesAutomatically connect the first two ports of Fluidsynth to the audio outs usingexact matchingmode:$ jack-matchmaker -e \
    fluidsynth:l_01 system:playback_1 \
    fluidsynth:r_01 system:playback_2Both the output port and the input port patterns can be regular expressions. If
a match is found on an output port, the matching port will be connected toallinput ports, which match the corresponding input port pattern:$ jack-matchmaker \
    'fluidsynth:l_\d+' 'system:playback_[13]' \
    'fluidsynth:r_\d+' 'system:playback_[24]'You can also use named regular expression groups in the output port pattern and
fill the port name sub-strings they match to into placeholders in the input
port pattern:$ jack-matchmaker \
    'system:midi_capture_(?P<num>\d+)$' 'mydaw:midi_in_track_{num}'Automatically connect all ports going to the system output to an FFmpeg
recording instance as well:$ jack-matchmaker \
    'system:playback_(?P<num>\d+)$' 'ffmpeg:input_{num}'Regular expression and exact matchingBy default port name patterns are always interpreted asPython regular expressionsand are matched against port names, aliases and
pretty-names using case-sensitive matching. They are anchored to the start of
the string they match, i.e. they must match the start of the port name, but
they still match, if the port name continues after the part the pattern matches.E.g. the patternclient:out_\dmatchesclient:out_1,client:out_2etc.
and alsoclient:out_10(even though the trailing zero is not included in the
pattern), but does not matchotherclient:out_1.You can still match port names with arbitrary prefixes by using.*at the
start of the pattern, e.g..*client:out_\d.To anchor the pattern to the end of the matched string as well, use a$at
the end of the pattern. E.gclient:out_[12]$will matchclient:out_1andclient:out_2, but notclient:out_10,client:out_21etc.To use exact string matching instead of regular expression matching, use the-e,--exact-matchingcommand line option. When this option is given,
patterns must match port names (or aliases or pretty-names) exactly. You can
still use regular expression patterns by enclosing a pattern in forward
slashes, e.g. like so:$ jack-matchmaker -e system:capture_1 '/myclient:in_l_\d+/'All this applies to patterns given as positional command line argumentsandto patterns listed in a pattern file (see below).Pattern match group substitutionAn output port pattern can contain one or morenamed groupswith the syntax(?P<name>...), where the three dots represent a sub regular expression. The
part of the port name matched by this sub regex, is available as a substitution
value for a placeholder corresponding to the name of group in the input port
pattern. Placeholders use thePython string formattingsyntax.Example:$ jack-matchmaker \
    'mysynth:out_(?P<channel>[lr])_\d+$' 'myfx:in_{channel}$'This would connect all ports namedmysynth:out_l_1,mysynth:out_l_2and so
on tomyfx:in_land all ports namedmysynth:out_r_1,mysynth:out_r_2and
so on tomyfx:in_r.Pattern filesIn addition to or instead of listing port patterns as as positional arguments
on the command line, port patterns can also be put in a textfile.The-p,--pattern-fileoption instructs the program to read the patterns
from the file path given as the option value. The file must list one port
pattern per line, where the first line of every pair of two lines specifies the
output port pattern, and the second specifies the input port pattern. Empty
lines and lines starting with a hash-sign (#) are ignored and whitespace at
the start of the end of each line is stripped.Example file:# Left channel
# This will match output ports of any client named
# 'out_1', 'out_l', 'output_1' or 'output_l'
.*:out(put)?_(1|l)$
    system:playback_1

# Right channel
# This will match output ports of any client named
# 'out_2', 'out_r', 'output_2' or 'output_r'
.*:out(put)?_(2|r)$
    system:playback_2

# Another common naming scheme for output ports:
.*:Out L
    system:playback_1

.*:Out R
    system:playback_2Easy pattern file creationSet up your JACK connections using GUI tools likeQJackCtlorCarlafirst.
Then usejack-matchmaker -c > patternsto save a the current JACK connections
in the filepatternsin apattern file compatibleformat. You may then edit
this file and and delete or add pattern pairs as needed.When using the-coption, you can also optionally give one or more regular
expression patterns as positional arguments on the command line. In that case
only connections, where any of the given patterns is matching (part of) either
the output or input port names, are listed. If the patterns contain any
uppercase letters, they will be matched in a case-sensitive fashion, if not,
they will be matched case-insensitively. The patterns are matched against the
full port name, including the client name. For example:$ jack-matchmaker -c JACKThis would list connections, where one of the connected ports contains "JACK"
in its name, but not if it contained only "jack" or "Jack" (unless matched by
another pattern).Reloading the pattern fileWhen you send a HUP signal to a runningjack-matchmakerprocess, the file
that was specified on the command line when the process was started is re-read
and the resulting patterns replaceallpreviously used patterns (including
those listed as positional command line arguments!). If there should be an
error reading the file, the pattern list will then be empty.On systemd you can usesystemctl --user reload jack-matchmakerto reload the
pattern file.JACK server connectionjack-matchmakerneeds a connection to a running JACK server to be notified
about new ports. On start-up it tries to connect to JACK until a connection can
be established or the maximum number of connection attempts is exceeded. This
number can be set with the command line option-m,--max-attempts, which
defaults to0(i.e. infinite attempts or until interrupted).jack-matchmakerwaits for 3 seconds between each connection attempt by
default. Change this interval with the option-I,--connect-interval.Whenjack-matchmakeris connected and the JACK server is stopped, the
shutdown event is signaled tojack-matchmaker, which then enters the
connection loop described above again.To disconnect from the JACK server and stopjack-matchmaker, send an INT
signal to the process, usually done by pressing Control-C in the terminal wherejack-matchmakeris running.Systemd serviceYou can optionally installjack-matchmakeras a systemd user service:$ install -Dm644 systemd/jack-matchmaker.conf /etc/conf.d/jack-matchmaker
$ install -Dm644 systemd/jack-matchmaker.service -t /usr/lib/systemd/userTo start the service, edit/etc/conf.d/jack-matchmakeraccording to your
needs (see section "Environment file" below) and then start the service with:$ systemctl --user start jack-matchmakerTo stop it again:$ systemctl --user stop jack-matchmakerTo reload the pattern file:$ systemctl --user reload jack-matchmakerEnvironment fileThejack-matchmakersystemd user service reads an environment file, which is
expected to be located at/etc/conf.d/jack-matchmaker. In this file, you can
set the following service startup settings as environment variables:PATTERN_FILE(default:"/etc/jack-matchmaker/patterns.txt")A file with port pattern pairs to read at startup as described above in section
"Pattern files".PATTERNSA space-separated list of port patterns in pairs of two. The default list is
empty and it is recommened to usePATTERN_FILEinstead when runningjack-matchmakeras a systemd service, unless the patterns should remain
static and never change.CLIENT_NAME(default:"jack-matchmaker")Set the JACK client name used byjack-matchnmakerto the given value.CONNECT_INTERVAL(default:3)Set the interval in seconds between attempts to connect to JACK server to the
given numeric value.EXACT_MATCHINGEnable literal matching mode. Patterns must match port names exactly. To still
use regular expressions, surround a port pattern with forward slashes, e.g."/system:out_\d+/".SetEXACT_MATCHINGto any value to enable it.MAX_ATTEMPTS(default:0)Set the maximum number of attempts to connect to JACK server before giving up.
The default value0means to keep on trying until interrupted.VERBOSITY(default:INFO)Set output verbosity level. Choices are:DEBUG,INFO,WARNING, andERROR.RequirementsA version of Python 3 with actypesmodule (i.e. PyPy 3 works too)pyjacklibcachetoolsJACKversion 1 or 2Linux, OS X (untested) or Windows (untested, no signal handling)Licensejack-matchmakeris licensed under the GNU Public License Version v2.Please see the fileLICENSEfor more information.Authorjack-matchmakerwas written by Christopher Arndt 2016 - 2023.Acknowledgementsjack-matchmakeris written in Python and depends on thepyjacklibmodule,
which was originally taken from falkTX'sCadenceapplication but now turned
into a stand-alone Python package and was heavily modified and extended in
the process.It was inspired byjack-autoconnect, which also auto-connects JACK ports, but
doesn't support port aliases or meta data pretty-names. jack-autoconnect is
also written in C++, and therefore probably faster and less memory hungry.The idea to read ports (patterns) from a file and re-read them on the HUP
signal was "inspired" byaj-snapshot.There is also a similar tool calledjack-plumbing, part of thejack-toolspackage on popular Linux distributions.