You are here

QjackCtl and the Patchbay

Simon W. Fielding writes that after quite some time, and reading between the lines of various posts on the linuxaudio-user mail list, he has finally understood how the QjackCtl Patchbay works and what it is for. Because of that, he has written a brief guide to using the patchbay and the document is here first released into the wild, hoping it will turn out to be useful to someone in the quest to make amusing noises at home.

Thanks Simon, for this excellent piece of work. You've done, in just a few paragraphs, what I've failed to do in all those four years QjackCtl's Patchbay has been around ;) Cheers.

What is this document for?

When I started using qjackctl I couldn't understand the difference between the patchbay and the connections window. They both seemed to show the same information and the patchbay was not very useful. Now, thanks to various hints on the linuxaudio mailing list, I think I understand how it should work and how useful it could really be. This document is my attempt to share that understanding with those in the same position as I was.

It is not an explanation of how to setup jack, qjackctl or any other tools and assumes that you can already do that but I hope it will be useful to somebody nevertheless.

What is the patchbay for?

When it is setup correctly, the patchbay provides automatic connection setup for jack-aware applications, maintains connections persistently through application stops (or crashes) and restarts, and allows for easy switching between different setups (eg from one instrument setup to another between songs in a live performance).

What shall we do today?

Since I am far too shy to stand up and perform live in front of an audience, I will attempt to describe how to use the patchbay to implement a simple studio rig which I can use to record drums, keyboard track and a single vocal.

I will use ardour, hydrogen and whysynth as the tools to be connected. Since I am writing this away from my studio, I will use vkeybd to stand in for my real midi controller keyboard. The final jack connection setup which we are aiming for is shown in the images below.

Screenshot of the audio connections to be achieved using the patchbay

Screenshot of the midi connections to be achieved using the patchbay

How do we do it?

  1. Start all your applications
  2. Disconnect all audio in qjackctl Connections windows
  3. Disconnect all midi in qjackctl Connections windows
  4. Open the Patchbay

    QjackCtl Patchbay button

    An empty patchbay

At this point, if this is your first set of patchbay connections, the system is ready for us to start adding plug definitions. However, when you have finished and wish to create another patchbay definition for the next song/overdub/band in your studio, you will need to click on the "New" button. This is where all my confusion and problems started because I assumed that you needed to start by clicking "New" so I will explain what not to do. When you see the dialog box which asks if you wish to take a snapshot :-

The snapshot dialog box

do NOT click "Yes". This will give you one plug per application which will almost certainly not do what you want if you connect them. Either click "No" to get an empty patchbay, or "Cancel" to give up and do something else instead.

Assuming you didn't give up, you now have an empty patchbay, split into Input and Output sections. This is where we start the real, interesting part. It can be a bit tedious but we should only have to do this once so it is worth persevering and getting it right.

What I want for my setup is to have one socket for each end of each connection I want to be able to make. These sockets will be mostly stereo (ie with two plugs in qjackctl terminology) or mono ( ie one plug). There is no need to restrict yourself however and you could connect as many plugs to each socket as you wish (caveat - I don't actually know if there is a limit or what it is but it's more than is likely to be needed in any manageable audio setup).

What now?

On each side of the patchbay window, you will see a button labelled "Add". Click one of them and you will see the window below. It is best to be methodical about this stage. I tend to add all output sockets and then all input sockets but you may prefer to setup all sockets for a single application and then move on to the next. Just do what works for you but try to be consistent.

New socket window

Now select Audio or Midi using the radio buttons, select your client from the drop down list, then select the plugs you want to add and click "Add Plug". Finally, give the socket a name that will mean something to you when you come to use the patchbay later on. If it's a general purpose patchbay, you might want to use something like "ardour: Audio 1/out" for example. If the patch bay is for a specific task however, as this one is, then you might want to give it a more user-friendly name eg "Ardour: Drum track/out". The name can be anything you want it to be. Use "exclusive" and/or "forward" on the socket if you wish. Finally, click "OK" and your patchbay should look like this :-

Patchbay with one socket defined

Now repeat this process for each input and output socket you wish to create until you have something like this :-

Patchbay with full set of sockets

Now we can make the connections that we need. Simply select an input socket and an output socket and click the Connect button to connect them together. Repeat until all connections are made and your patchbay looks something like this :-

Full patchbay with all sockets connected

Now, save the patchbay definition, give a memorable name, and click the activate button.

When you have done all this, go back to the qjackctl connections window and we should see all the applications connected as we have specified. To test the patchbay, click "Disconnect All" in the connections window and watch all the connections disappear and then automagically reappear.

What does the patchbay NOT do?

The patchbay does not disconnect audio or midi connections. If you disconnect one, or all, sockets in the patchbay, all the audio and midi connections will still be there. The audio/midi connections will still automagically reappear if you disconnect them until you save the (now disconnected) patchbay and subsequently disconnect the audio/midi connection in the connection window.

Simon W. Fielding
s.fielding at wmcce dot org


rncbc's picture

The following verbosity intends to be one's formal sidenote regarding the distinction between QjackCtl Connections and Patchbay widgets, while quite similar in their aspect, aren't at all fitting the same purpose nor functionality. Let's just hope this makes it a bit more bearable ;)

QjackCtl Connections

All audio and MIDI connections and routing are controlled under the QjackCtl Connections window. These are flexible but imperative connections that can be made between all the Audio/MIDI software application programs (clients) that run in the system, establishing an actual signal path from source to destination ports.

In the Connections window you will see all Audio/MIDI signal sources on the left pane (Readable Clients/Output Ports) and all possible Audio/MIDI signal destinations in the right pane (Writable Clients/Input Ports).

Actual connections are established between source (Output Ports) and destination (Input Ports) by selecting one item in either side and pressing the [Connect] button at the bottom-left of the Connections window.

It is also possible to establish a connection by dragging an item and dropping it over the other side (Note: it doesn't matter from either side you start dragging).

To disconnect a currently established connection you proceed in a similar manner: select each item in either side and press the [Disconnect] button.

Actual and established connections are shown as color directed lines in the middle pane of the Connections window. Each color indicates a single and distinct source module (client) that is currently connected.

It is possible to route every audio and MIDI from and to where you see fit, provided that JACK and ALSA sequencer services and client applications are up and running.

QjackCtl Patchbay

All connections made in the Connections interface are kept as long you don't power-cycle the JACK server (jackd). That is, all connections will be lost when the JACK server or any of the client application programs are closed or terminated. Those connections just don't get setup whenever the server and any of its client applications get started later again.

To maintain a custom and persistent connection configuration layout, you'll have to edit and activate a patchbay definition profile. Patchbay definition profiles are connection models that are edited and created in the Patchbay window, which is accessed via the [Patchbay] button on the main QjackCtl panel.

The Patchbay window is very similar to the Connections one. However, it is here where you prepare and set your intentional and persistent connections, not the actual connections. When activated, this patchbay definition profile will keep all declared connections automatically, as long as QjackCtl is kept alive.

Following the Patchbay model, you declare connections between sockets (clients). When two sockets are said connected, it is implied that each one of its plugs (ports) are declared about to be connected in turn, one by one, in a one-to-one basis.

Take special note on the plug/port order in the socket plug list, as each plug of each other socket is about to be connected in the precise order those are listed on either end.

The Patchbay handles both Audio and MIDI connections. However you can only instruct to connect between sockets of the same type.

Each actual Audio/MIDI client program is mapped into one or more items in a patchbay definition, here called sockets. Thus far, a socket is just one representation to a specific subset of all the ports (plugs) of a given client.

For example, you can have a stereo socket on to which only two of the ports from a given client are listed. When you refer to this socket you are actually referring only to those ports. Take special care that you'll have to agree to yourself to always list the ports in the very same and logical order, e.g. Left always followed by Right channel, which is the most common.

You can set a socket as being in Exclusive mode, meaning that the patchbay routine will enforce that no connections are to be held at any one time, other than the ones explicitly declared by the active patchbay definition.

As an additional feature, you can also set one socket to Forward and therefore replicate all its connections to yet another one. This option feature may be found useful, for instance, when you wish to replicate all connections made onto the main audio outputs to some aux or cue (eg. phones) outputs.

Hope it helps a little bit.
rncbc aka Rui Nuno Capela

This is a great article. But my connection saver does not seem to save connections between my control
surface , and I still need to manually connect other things. The patchbay definitions load fine, and I get no error messages.

rncbc's picture

And what "connections saver" are you using? Certainly not the one provided by QjackCtl, because there's none :)

As the article implies, the snapshot feature you opt when creating a new patchbay definition profile is not quite an accurate connections saver as you might expect. It's just a convenience helper in populating an initial patchbay definition from scratch with something that might resemble your current JACK/ALSA graph. As said, it's just a starting point, not an end in itself. You'll most certainly need to rearrange the resulting snapshot model quite for sure, to fit your actual client/port graph.

OTOH, one thing I've forgot to mention, there's no support for JACK-MIDI yet on the QjackCtl Patchbay, although that's already a reality in the Connections widget.

rncbc aka Rui Nuno Capela

rncbc's picture

...there's no support for JACK-MIDI yet on the QjackCtl Patchbay,
Not anymore, as just committed to CVS HEAD (qjackctl

- Finally, full JACK MIDI support sneaks into the patchbay; socket
types now differ in Audio, MIDI and ALSA, following the very same
nomenclature as found on the Connections widget tabs.

rncbc aka Rui Nuno Capela

rncbc's picture

...the snapshot feature you opt when creating a new patchbay definition profile is not quite an accurate connections saver as you might expect.

Aha, the world is round and ever changing: as of QjackCtl, CVS commit-log:

- At last, after years of retarded procrastination, the old infamous patchbay snapshot feature has been the subject of a almost complete rewrite and it does try to give a way better mapping of all actual and current running client/port connections, both JACK (audio, MIDI) and ALSA MIDI, of course ;)


Currently on Ubuntu 22.04/server running headless with xvfb and vnc, and snapshots of current session map out like a charm. Thanks!

The patchbay really comes into its own when you use regexps in the rules.

Example: In rosegarden one can name inputs and outputs but cannot define the output number yourself, which can come back to haunt you especially when you have multiple rosegarden files you want connecting in the same manner. A number of other applications have similar quirks.

Perhaps one case gives you
out 1 - Roland D10
out 2 - Alesis DM5

and another gives
out 3 - Alesis DM5
out 4 - Roland D10

Using Perl style regexps (all the metasymbols seem to work) the following pair of regexps will always match the above names regardless of number
out \d* - Alesis DM5$
out \d* - Roland D10$

See if you need a translation of perl's extensive regexp capabilities

AutoStatic's picture

Just came across this functionality too as I am currently trying to fully grasp the Patchbay's functionality. I've also taken the liberty to convert the above article to a downloadable PDF.



What about situations where a mono source is expected to connect to a stereo source? Is there a method to connect one output plug with more than one plugs in a single input socket?

rncbc's picture

I'm afraid not. You can however duplicate the output socket (client), having the same mono output plug (port) and connect to two separated input sockets on same client but different input plugs (ports) each one for left and right.

output socket 1 (client 1) / plug 1 (port) ---> input socket L (client 2) / plug L (port L)
output socket 2 (client 1) / plug 1 (port) ---> input socket R (client 2) / plug R (port R)


Ok, I connect one output port with two input ports and save patchbay. Now when I am restarting jack, this patchbay is activated but only one input port is connected. How to fix this?

rncbc's picture

kind of similar to the previous problem (Re: One-to-many connections?)


  1. duplicate the target input socket (client), having each its separated input plug (port).
  2. connect the output socket (client) to the two separated input sockets for same client but different input plugs (ports).

(warn. ascii art follows)

output socket 1 (client 1) / plug 1 (port) --.--> input socket 1 (client 2) / plug 1 (port 1)
                                             `--> input socket 2 (client 2) / plug 2 (port 2)


Actually it could work but it needed some workaround for the moment.

I'll explain first how sockets and plugs work (to my understanding)
Basically, each socket connect to others sequentially.
for example we connect Socket A -> Socket B
if socket A has 1 plug, and socket B has 2 or more plugs, then only A:1 -> B:1 is connected. Notice the 'Click track from ardour' connection to 'PA Audio' in the screenshot from the article.
if socket A has more then 1 plug (for example 4) while socket B has less plugs than A (for example only 2) then the connections are A:1->B:1, A:2->B:2, while A:3 and A:4 is unconnected.

Now for your need to connect a mono output port to a stereo input ports you need to have
Socket A:
+plug 1 = mono_synth_out
+plug 2 = mono_synth_out
Socket B:
+plug 1 = stereo_input_L
+plug 2 = stereo_input_R

if you connect A->B, then mono_synth_out will be connected to stereo_input_L and stereo_input_R, just like you wanted.

The problem is that QJackCtl's Patchbay interface actually removed the ports from the list of available plugs to add if you already add the port.

Take a look at this screenshot

It produces this XML code in the patchbay save file.
<socket exclusive="off" client="zita-mu1" type="jack-audio" name="Output Socket 4">

In order to achieve that, I add two plugs, sel_out.L and sel_out.R, and then renamed sel_out.L into sel_out.R.
But for a monosynth it's impossible to achieve that because once the port is added as a plug then the list of ports is empty.
There might be a workaround though.
For example you have these clients 'MonoSynth' ('mono_out') and 'system' ('capture_1' and 'capture_2').
Create Output Socket Stereo_Synth.
Choose 'system' as the client, add capture_1 as the first plug.
Change client into 'MonoSynth' and add mono_out as the second plug.
Rename the first plug into mono_out.

Now, Rui's suggestion to make two Mono Input Sockets also work, but it means having two connections MonoSynth->Input_L and MonoSynth->Input_R.
if you have a lot of stereo clients or already make stereo sockets, then that means having duplicate sockets for the mono connections.

This actually means that it depends on your workflow.
if you work with stereo connections then the majority of your sockets would be stereo.
I find that using QJackCtl's Patchbay simplifies connecting the ports by grouping the ports into stereo sockets.

So, I have two suggestions for Rui regarding this workflow.
1, make the list of ports in the Socket window to always shows all available ports in the system. (the connection already works, it's just the UI does not let the user to add them)
2, if it's possible to make that each socket can have plugs from multiple clients (I think this would be harder, from the patchbay xml format it seems that you coded each socket to be tied to a certain client.)
Perhaps something like this
<socket exclusive="off" type="jack-audio" name="Output Socket 4">
<socket exclusive="off" type="jack-audio" name="Output Socket 4">
<client name="zita_mu1">
<client name="system">

Perhaps I'll take a look at the source code sometime later if I could hack on them (but probably will take a looong time, I'm still learning how to code, and QJackCtl's code is pretty big -- wc shows >30K lines)

This works, but I have different problem now.

I connect output of application to jack mixer input. When i do what you suggested i must uncheck "Exclusive" in output socket in patchbay. When i did this i got three connections in "connect tab" in QjackCtl. Two of them connect to jack mixer in right way (1 -> 2 ), and one connection to system input. How to disable direct connection to system input?

Here is a pic:

It's about mplayer (in this case).

rncbc's picture

ah. the dreaded auto-connection feature of mplayer et al. :)

if you don't want anything else (auto-)connected to system/playback_1 and 2 ports but jack_mixer/MAIN L and R, please add a patchbay rule for exactly that, setting the exclusive flag on system (client) input socket side:

jack_mixer/MAIN L, R -----> system/playback_0, 1 (exclusive)


Awesome, it's really work :)

Thanks. Very useful.

I thought one could edit the names of the ports. But don’t do it in the patchbay. None of the connectioms will activate as it seems to be based on that name of the port and not some internal ID.

Greetings !!
I merged two sound cards in one virtual one called "ldfsoundcard".
How can I do to make this virtual device visible from the system or at least Ardour5 or jack ?

When addind this virtual soundcard with alsa_in when jackd is running I got no errors but there is no way to use this virtual device in Ardour5: it lists the alsa detected soundcards but not the device called "ldfsoundcard"

I can not check if /root/.asoundrc is correctly formatted... loaded and added in the soundcard list.
I guess not because /proc/asound/cards doesn't list nothing more than the hw cards

Thanks Simon, it was your comment that solved my issues. It was just not taking over my patchbay to the connections !! Don't rename the plugs, you can rename the sockets, but not the plugs .... A bit pitty but at least it works now !

The above posts are very helpful. It would be great if they could be incorporated into some comprehensive documentation and made available on the project page, and/or in the source distribution. I first started trying to use Jack and QjackCtl a few weeks ago, and I've been quite mystified by most of the QjackCtl GUI. I've gradually gleaned some information from google searches, but much of it is still quite opaque to me. Why is there no documentation?? Of course I know, it's because this is a volunteer project (for which I'm grateful!), and no one has taken the time to produce said documentation; and if I want it, I should write it :) And I would indeed volunteer to do that, if I knew enough. If someone who knows the ins and outs of QjackCtl is willing to work with me to answer all my questions, I am willing to take a stab at it.

rncbc's picture

hi, many thanks for your kind words and welcome aboard!

as you might know already, I'm not so keen to produce documentation to my own things: I'm way more inclined to produce lots of code than anything else, yes the dang old developer stance, I'm sure you recognize...

but by all means, you're all green lights from here and thanks a lot for volunteering to help on this daunting matter :) Be sure that I'll help you back with all the answers you need. Thanks a gain.


May I send you my Jack connections, patchbay, and advanced settings .png? I have followed your Qjackctl plan but Reaper 6.15 tells me in the Input section of tracks, that nothing is connected. I am at a loss.
I run a fresh install of Ubuntu Studio with a Behringer UMC404HD usb interface, which shows up in Jack. I run both mics and 2 keyboards into the Behringer, usb to this laptop, and out to my mixer and into two powered speakers. Sounds fine through the speakers, but no recording signal.
Thank you,

I'm trying to get rid of the (for my scenario annoying) auto-connections created when the JACK audio Connection is restarted.

So far the only "hack" I've been able to come up with is to set the output that goes to the input that I want to get rid of to exclusive and then map it somewhere else. It works, but is hurts my eyes. There must be a better way? :-)

Is there no way to config Patchbay to override or suppress such annoying auto-populated connections?

rncbc's picture

hi, you may well try with the, relatively recent, qjackctl (advanced) setting "Self connect mode"...

be advised that it works on JACK2 (v1.9.x) and/or on a JACK D-BUS enabled service only.


Thumps up for the quick response.

As far as I can see this would be version qjackctl-0.9.2. Excuse my ignorance, but I'm only able to locate the source code. Is there somewhere I can download the binaries for Windows 10. Just thought I'd ask before spending a lot of time figuring out how to compile this :-)

rncbc's picture

I am sorry to tell but, as you might well know, in that regard, I'm not keen to any other platform than GNU/Linux ... :(

however you may try hack the server prefix; from jackd --help output:

     --autoconnect OR -a <modechar>
       where <modechar> is one of:
         ' ' - Don't restrict self connect requests (default)
         'E' - Fail self connect requests to external ports only
         'e' - Ignore self connect requests to external ports only
         'A' - Fail all self connect requests
         'a' - Ignore all self connect requests



I added:

-a a that the server prefix now looks like this:
jackd -S -a a

That did the trick! Thanks again.

From this article and it's comments I get answers to all my questions and could make everything works as I need (entry level, nothing complicated)! Awesome! Thanks to all of you a lot!
But what about Sessions? Could you point me to the description or write some words about this part of the program.
I understand that it is a place where I could add some commands to a specific program/connection, but what commands and when they executes I did not understand. When I load previously saved config it duplicates some clients/ports.
What is it for and when I should use it? Maybe you have some useful examples? Write it please.

rncbc's picture

Don't use it, period. [JACK Session Management] It's been deprecated by the By far, you'll be better using NSM in either of its original or newer flavor.


Add new comment