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

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.


Add new comment