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

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.


Add new comment