Skip to main content

Auto-connect new JACK ports.

Project description

Auto-connect JACK ports as they appear and when they match the port patterns given on the command line or read from a file.

Latest version Project status GNU General Public License 2 Python versions Wheel available


jack-matchmaker is 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-matchmaker never disconnects any ports.

The port name patterns are specified as pairs of positional arguments or read from a file (see below) and by default are always interpreted as Python regular expressions, where the first pattern of a pair is matched against output (readable) ports and the second pattern of a pair is matched against input (writeable) ports. As many pattern pairs as needed can be given.

Patterns are matched against:

  • normal port names
  • port aliases
  • pretty-names set in the port meta data

You can run jack-matchmaker -oian to list all available output and input ports with their aliases and pretty-names.


Before you install the software, please refer to the section “Requirements”.

Then simply do:

pip install jack-matchmaker

There is also an AUR package available for Arch Linux users.


Run jack-matchmaker -h (or --help) to show help on the available command line options.


Automatically connect the first two ports of Fluidsynth to the audio outs using exact matching mode:

jack-matchmaker -e \
    "fluidsynth:l_01" "system:playback_1" \
    "fluidsynth:r_01" "system:playback_2"

Both 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 to all input 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}"

Regular expression and exact matching

By default port name patterns are always interpreted as Python regular expressions and 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 pattern client:out_\d matches client:out_1, client:out_2 etc. and also client:out_10 (even though the trailing zero is not included in the pattern), but does not match otherclient: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.g client:out_[12]$ will match client:out_1 and client:out_2, but not client:out_10`, client:out_21 etc.

To use exact string matching instead of regular expression matching, use the -e resp. --exact-matching command 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 pattern given as positional command line arguments and to patterns listed in a pattern file (see below).

Pattern match group substitution

An output port pattern can contain one or more named groups with 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 the Python string formatting syntax.


jack-matchmaker \
    'mysynth:out_(?P<channel>[lr])_\d+$' 'myfx:in_{channel}$'

This would connect all ports named mysynth:out_l_1, mysynth:out_l_2 and so on to myfx:in_l and all ports named mysynth:out_r_1, mysynth:out_r_2 and so on to myfx:in_r.

Pattern files

In addition to or instead of listing port patterns as as positional arguments on the command line, port patterns can also be put in a text file.

The -p/--pattern-file option 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 or 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'

# Right channel
# This will match output ports of any client named
# 'out_2', 'out_r', 'output_2' or 'output_r'

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

.*:Out R

When you send a HUP signal to a running jack-matchmaker process, the file that was specified on the command line when the process was started is re-read and the resulting patterns replace all previously 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.

JACK server connection

jack-matchmaker needs 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 to 0 (i.e. infinite attempts or until interrupted). jack-matchmaker waits for 3 seconds between each connection attempt by default. Change this interval with the option -I/--connect-interval.

When jack-matchmaker is connected and the JACK server is stopped, the shutdown event is signalled to jack-matchmaker, which then enters the connection loop described above again.

To disconnect from the JACK server and stop jack-matchmaker, send an INT signal to the process, usually done by pressing Control-C in the terminal wher jack-matchmaker is running.


  • A version of Python 3 with a ctypes module (i.e. PyPy 3 works too).
  • JACK version 1 or 2.
  • Linux, OS X (untested) or Windows (untested, no signal handling).


jack-matchmaker is licensed under the GNU Public License Version v2.

Please see the file LICENSE for more information.


jack-matchmaker was written by Christopher Arndt 2016 - 2019.


jack-matchmaker is written in Python and incorporates the jacklib module taken from falkTX’s Cadence application (but it was heavily modified and extended since).

It was inspired by jack-autoconnect, which also auto-connects JACK ports, but doesn’t support port aliases or meta dat 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” by aj-snapshot.

There is also a similar tool called jack-plumbing, part of the jack-tools package on popular Linux distributions.

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Files for jack-matchmaker, version 0.7.0rc1
Filename, size File type Python version Upload date Hashes
Filename, size jack_matchmaker-0.7.0rc1-py3-none-any.whl (26.7 kB) File type Wheel Python version py3 Upload date Hashes View
Filename, size jack-matchmaker-0.7.0rc1.tar.gz (26.1 kB) File type Source Python version None Upload date Hashes View

Supported by

Pingdom Pingdom Monitoring Google Google Object Storage and Download Analytics Sentry Sentry Error logging AWS AWS Cloud computing DataDog DataDog Monitoring Fastly Fastly CDN DigiCert DigiCert EV certificate StatusPage StatusPage Status page