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


Thank You! Now I have another little question.
In general, do the New Session Manager and WirePlumber (PipeWire session manager) made for the same purposes? The Agordejo that "uses the New-Session-Manager daemon and enhances it with some tricks of its own" looks pretty well in comparing with editing WirePlumber's config files. Maybe I just don't know yet that I need it ;)
Thank you in advance for your response, and especially for the incredible speed with which you respond.

rncbc's picture

you should ask the respective devs. as I'm not the author of those programs :)

cheers & thanks anyway.

ps. you may also find RaySession interesting.

I just discovered Simon's writeup - I have been struggling with qjackctl - his writeup - 14 years later - is still very helpful.

CarloWood's picture

Thank you! I have been wrestling with this for 4 hours and couldn't figure out that you have to *manually* select two outputs at a time (left and right).
Clearly this is a BUG in qjackctl's feature of "Create patchbay definition as a snapshot of all actual client connections?" Because that should create
whatever you get after doing it manually the way you described. I am flabbergasted that 14 years after this post this bug is still not fixed :/.

rncbc's picture

maybe you did not read the whole article ?
you seem to miss the point where Connections and Patchbay serves two different functions and models:

TL;DR what you do in the Patchbay (proposed connections) does not always imply an immediate action as you do in Connections (actual connections), unless the patchbay definition file is properly named, saved and activated.


I've been doing pro audio in Linux/Reaper/ALSA for a couple years now and my setup has been very simple, but two things made me want to finally move to Jack - using an external waveform editor in Reaper and using the amazing samplv1 app!

This tutorial and your apps, samplv1 & QjackCtl, have literally changed my life! :D


PS. Damn, that captcha is hard!


Add new comment