CCRMA Documentation links: index contents overview rooms account staff about
(contents of this file: links to each section)
JACK, the “JACK Audio Connection Kit” (jackaudio.org, wikipedia page), is an audio system allowing multiple programs running at the same time on a single computer to send and receive audio channels to and from each other and the computer’s audio hardware.
JACK’s developers conceive of it primarily as an API that software developers can use to make their programs able to join the JACK ecosystem.
JACK’s users conceive of it as a program that has to be configured and started so that other programs can flexibly send and receive audio channels, tending to focus their attention on connecting and disconnecting sources and destinations between both hardware and software.
The JACK package includes the programs jackd and QjackCtl (plus JackPilot for OSX up to 10.14), as well as the header files, shared libraries, and other software-developer-facing files of the JACK API.
After installing JACK, you must start JACK before it will make any audio connections. This means launching the program jackd; most people do this graphically using QjackCtl. When you start JACK you determine JACK’s settings.
JACK determines the following settings (aka “preferences”) when it starts on your computer:
Audio Sample rate, e.g., 48000 samples/second.
Buffer size (aka Frames/Period, often abbreviated FPP), i.e., how large are the “blocks” of audio that all JACK programs will process, e.g., 512 samples.
Connected audio Interface hardware that JACK will access (as your “system” “capture” and “playback” channels), e.g., your computer’s built-in sound and/or external audio interface, perhaps just a USB microphone with a built-in headphone output.
How many of your audio system’s Input Channels and Output Channels you want JACK to access.
On some operating systems you may also need to specify which audio Driver JACK uses to connect to your audio hardware (e.g., Windows ASIO or OSX Core Audio).
Changing any of these requires stopping JACK (thereby stopping every program currently using JACK), then restarting it with the new options.
A computer running JACK is simultaneously running some number of JACK-enabled audio programs, and also JACK itself is connected to (some of) the computer’s connected audio hardware. JACK’s key feature is the ability to make and break any connection from an audio output channel to an audio input channel, and the key thing most JACK users have to think about is making exactly all the right connections.
Usually you use qjackctl’s Connect window to view and modify JACK connections (and that section of documentation shows several examples).
When multiple outputs are connected to the same input, JACK mixes the signals together just by adding them in the simplest possible way. Therefore the resulting gain might be too high when you “mix” like this. (The result of the mix could go into gain-limiting software; in general if you want to do something more sophisticated you use a piece of software to do the mixing, and use JACK just to route all the independent signals in and out of the “mixer”.)
There are many many ways to accidentally create bad feedback loops by making “wrong” JACK connections depending on the specific context.
Break whatever connection you made just before it started squealing, remembering that sometimes some programs make their own JACK connections. Review your connections knowing that there’s at least one too many. Is there another audio path outside of JACK that’s affecting the overall system?
A major pitfall is that an unfortunately large number of programs that use JACK (arguably improperly) sometimes can’t participate in JACK connections. The program will display the number of audio inputs and outputs that it aspires to process, but none of them can be connected until the program actually starts processing audio. Anthropomorphizing this category of bug we might say that the program has to “really start working” to “prove” to JACK that it’s “serious” about processing audio before JACK will “trust” it with any connections, e.g.:
jacktrip must be currently streaming audio over the network with an active connection to a remote sitejackd, the “JACK daemon”Technically when “JACK is running” on a given computer, that means that the program jackd (“JACK Daemon”) is running as a background process on that computer. jackd connects to your audio hardware and is the program that all the other JACK programs communicate with and through. In JACK terminology, jackd is the JACK “server”, where the “service” is letting other programs on the computer (the JACK clients) send and receive audio to each other and to whatever audio hardware JACK is connected to. (Not to be confused with jacktrip or any other “services” your computer might also be participating in.)
Only one jackd can run at a time; it expects to have “complete control” over your computer’s audio. If jackd is already running then attempting to launch it a second time should fail, perhaps with a message such as `default' server already active / Failed to open server. When another program such as qjackctl “starts JACK”, it does so by launching jackd behind the scenes.
When jackd launches it determines all of JACK’s settings via a specific list of command-line arguments. For example, the following command launches jackd using the ALSA backend (-dalsa), an audio interface named US2x2 (-dhw:US2x2), sample rate of 48000 (-r48000), buffer size 256 (-p256), and two audio channels (-n2):
jackd -dalsa -dhw:US2x2 -r48000 -p256 -n2Most users start jackd from the qjackctl graphical user interface (described in the next section). Advanced users may want to launch jackd directly from the command-line (or from within a shell script.
Location of jackd the executable file:
/usr/local/bin/jackd (may be a link to /usr/local/bin/jackdmp)/usr/bin/jackdOne way to check whether a Linux or OSX system currently has JACK installed is to try launching jackd from the terminal:
jackdIf it prints version, copyright, and usage information then you’re good so far; if instead you see something like “command not found” then either you still need to install JACK and/or you have a problem with your search path.
One way to check whether a Linux or OSX system currently has JACK running (and if so how it’s configured) is to open a terminal and search for any currently running processes whose name includes “jackd”:
ps -ef | grep jackdIf the computer where you run this command is currently running jackd then the result will include a line that looks something like this:
matt 28625 28624 0 May04 ? 00:01:35 /usr/bin/jackd -dalsa -dhw:US2x2 -r48000 -p1024 -n2Everything after “jackd” on this line is the currently active JACK settings expressed in the language of jackd’s command-line argument) syntax.
XXX how to do something like this in Windows?
QjackCtl: a friendly graphical interface to JACKQjackCtl (pronounced “cue jack control”, qjackctl.sourceforge.io) is a graphical user interface to JACK. It can configure, start, and stop jackd as well as display and modify all of JACK’s audio connections.
Its main window is (confusingly) titled “JACK Audio Connection Kit” (which is the full name of JACK, but not the name of the qjackctl program). It looks like this:
In the above image three things tell you that JACK is currently stopped (as far as qjackctl understands):
Compare to this screenshot taken when JACK was running:
.
Next to the yellow word “Active” (sometimes instead “Started” - XXX not sure what the difference means) is a blinking “RT” (showing that JACK is running “realtime”?), the percentage of the CPU being used for JACK itself (here 0.024%), and JACK’s current sample rate (here 48000 Hz).
You can ignore the green “Stopped”, which has to do with MIDI, not audio.
There are three main buttons at the top:
jackd with the current settings of the Setup window (if qjackctl understands that jackd is not already running)
jackd that qjackctl is aware of (if any)
qjackctl application itself, as you would quit any other user program in your operating system, without necessarily stopping jackd.
There are three useful additional windows of QjackCtl that you can display by clicking the corresponding button on the main window:
Setup..., where you operate qjackctl’s way of controlling JACK’s settings. The parameters in this window take effect when you attempt to start JACK by clicking qjackctl’s “Start” button. (They do not necessarily display the state of the jackd currently running on your computer.) You must click “Cancel” to close this window, or “OK” to save any changed setting(s). “Wrong” settings may lead to future failure the next time you click qjackctl’s “Start”; if so then you almost certainly want to look at the Messages window to try and see what the problem is, and/or revert to your previous working settings.
Messages, the verbose log of all the errors, warnings, and notifications that are printed by QjackCtl and any jackd it starts. If qjackctl can’t start JACK then usually there is a message somewhere in this log that will tell you exactly what the problem is. If qjackctl can start JACK then this “Messages” window will contain the exact invocation of jackd corresponding to the options you selected in the Setup window. You can copy text out of this window (though it may require selecting a region then dragging it to another program). This is the complete log of all QjackCtl’s activity since it was launched (up to the default 1000 “Messages limit” in Setup/Display); to clear the list quit and restart QjackCtl. Clicking the button again hides the window.
Connect, where you can see the “system” audio hardware and all the programs currently running through JACK as well as connect any audio outputs to any audio inputs. Clicking the button again hides the window.
Graph: Newer versions of qjackctl have (and default to) an alternate view of the JACK audio connections called Graph, but we recommend you set it back to use the “classic” Connect interface: Go to “setup” window, click on the rightmost tab “misc”, then under “Buttons” deselect “Replace Connections with Graph button”.
Patchbay would be an obvious name for where you manipulate JACK connections, but no, you want Connect for that. Although the Patchbay may sometimes be useful we don’t recommend it.
Location of qjackctl the executable file:
/Applications/Jack/qjackctl.app/usr/bin/qjackctlQjackCtl relates to jackdMost users should use jackd exclusively through QjackCtl, with QjackCtl never crashing or being killed/force-quit. If that applies to you then you don’t need to worry about anything in this section.
There are other programs besides QjackCtl that can start, stop, and restart jackd, including JackPilot and jackd itself. Doing any of this outside QjackCtl can make things confusing if you’re also using QjackCtl at the same time.
QjackCtl is aware of any jackd that it starts (in response to your pressing the “Start” button). QjackCtl also checks to see if there is already a jackd running, but only when QjackCtl launches. So that can lead to this kind of scenario:
Start jackd outside of QjackCtl (or from a QjackCtl that crashed without stopping jackd - see below)
Next launch QjackCtl: QjackCtl will “notice” jackd already running, immediately show that it’s “Active” (including the option to “Stop” it), and display all the current connections. So far so good; that’s what you want.
Unfortunately, the settings in QjackCtl’s “Setup” window will be whatever you last selected in QjackCtl, not necessarily the settings of the jackd that is currently running.
If the jackd that QjackCtl “knows about” then stops (perhaps via killall), then QjackCtl will “notice” that it stopped and update the display accordingly. That’s good.
However if you then restart jackd outside of QjackCtl (such as by calling jackd from the command line), then QjackCtl will still (wrongly) display that JACK is inactive.
Any time (you suspect any possibility that) QjackCtl “doesn’t know” jackd is running, the solution is to quit and restart QjackCtl; when QJackCtl newly launches then it will “see” the jackd.
If you quit QjackCtl while JACK is running, then you may receive a dialog box “JACK is currently running. Do you want to terminate the JACK audio server?” (XXX this happens on OSX but maybe not Linux?) Selecting “OK” will cause QjackCtl to kill its jackd, but if QjackCtl stops abruptly (e.g., with “Force Quit” or killall qjackctl, or if it didn’t give you that dialog box when quitting normally) then the jackd that it started will keep running even after QjackCtl quits (and then if you restart QjackCtl it will “see” the still-running jackd as described above).
JackPilotJackPilot is OSX only, and only Mojave (10.14) and earlier; it does not work in OSX 10.15 “Catalina” and is not currently supported
It’s largely redundant with and inferior to qjackctl. Not recommended to use both together.
tl;dr The only good thing about it is that it lets you configure JackRouter’s number of virtual inputs and outputs.
JackPilot is an OSX appliction. It’s main window “JackPilot” is tiny, with just a single “Start”/“Stop” button, a “Routing” button (that opens a not-very-usable “Connections Manager”) and simple “CPU Load” meter. But (if JACK is not running), the “Preferences” window has not only the usual JACK settings, but also a section for JackRouter where you can set the number of “Virtual Input Channels” and “Virtual Output Channels”.
JackRouter was amazing. Sadly it no longer works under Catalina and may never again. It perfectly bridged Apple’s Core Audio system with “the JACK way of doing things”, making every OSX application with audio inputs and/or outputs (e.g., Max, any DAW, iTunes, any web browser…) see “JackRouter” as a legimate selectable Core Audio device giving the application a private set of audio connections to the rest of JACK.
qjackctl’s Connections window/Applications/Jack/JackPilot.appThere are (too) many ways to start JACK. Here is one relatively friendly method:
Setup...
OK (or Cancel if these are the same settings as last time)Start JACK
Messages and good luck troubleshooting.Is your audio hardware functional?
Is your audio hardware properly connected to your computer? Does your computer’s “sound preferences” (or equivalent) “see” the audio interface? Can non-JACK software use this audio interface? Is any non-JACK software already accessing the audio interface, perhaps in an overly possessive way?
What was printed while JACK was attempting to start? Look in QjackCtl’s Messages window.
Is JACK set to the correct driver?
Is JACK set to the correct audio interface?
As soon as you’re able to start JACK using any of the above methods, you should do an audio test to make sure that your sound hardware is correctly working and connected to JACK, and that no other software is interfering:
system/capture on the left and your speakers or headphones as system/playback on the right. If you see neither then there was a problem starting JACK. If you see the wrong number of inputs and/or outputs (especially including none) then you need to change JACK’s settings to select your audio hardware properly.Disconnectqjackctl that’s created the connection; most likely there’s an unintended direct sound monitoring path in your audio hardware or via other audio software currently running on your computer).The whole point of JACK is that you get to choose all the JACK audio connections among the sound hardware and all the JACK-aware software. You will need to inspect the current connections as well as make or break new connections (especially when setting up or troubleshooting).
The only slightly sane tool for inspecting JACK connections is QjackCtl’s Connect window. Every audio source appears on the left, every potential audio destination appears on the right, and between them can quickly grow an intimidatingly unwieldy tangle of connections depending on what you’re trying to do. The next section shows a series of examples in order of increasing complexity.
Most JACK users use QjackCtl’s visual interface to make and break connections:
Select one source from the left and one destination from the right, then click the Connect or Disconnect to make or break their connection.
Click and drag one source channel from the left onto one destination channel on the right.
Do either of the above with an entire group of channels (a multi-output-channel program or multi-channel “system” audio) instead of one channel at a time
The Disconnect All button breaks all connections. It prints a misleading warning message “This will suspend sound processing from all client applications. Are you sure?” but don’t worry: all JACK client applications will keep running even after they have no JACK connections, and then you can start over from scratch (making exactly the correct connections).
JMess - A utility to save your audio connections (mess). jmess can save and recall the entire state of all JACK connections. It’s also useful with the -D option to disconnect all JACK connections.
jack_connect (normally installed as part of the JACK package) can establish individual connections by naming the source and destination. Likewise jack_disconnect breaks individual connections.
jacktrip by default makes automatic JACK connections when it launches (can disable with --nojackportsconnect), so that your mic signal goes out to the network and anything received from the network goes to your speakers.
A jacktrip server in “hub mode” has a “hub patching mode” that will clear and reset all JACK connections every time any client connects or disconnects.
Ardour makes and breaks huge numbers of JACK connections, for example Ardour’s virtual mixing board uses JACK connections for all of its direct outputs, effects sends, etc.
You’re going to want to see the activity on all the various channels of even a slightly complex JACK setup. We strongly recommend Meterbridge for JACK debugging and monitoring.
Start meterbridge from the command line. You will want to use -t to set the “type” (visual style) of the meters. Also meterbridge takes one argument for each meter, e.g., if you want 4 meters you pass four arguments. These can be the names of specific JACK clients’ output signals (in which case each source automatically connects to the corresponding meter), or a dummy argument such as “x” (to get a meter you will connect to later).
Example: launch meterbridge with 8 “Digital peak meter” style meters:
meterbridge -t dpm x x x x x x x xExample: launch meterbridge with 8 “Digital peak meter” style meters, where the first two are connected to this computer’s first hardware audio inputs:
meterbridge -t dpm system:capture_1 system:capture_2 x x x x x x
It turns out there’s an OSX port of meterbridge that still works (at least on Mojave… XXX what about Catalina?).
The only tricky part is that it “Needs libsdl and libsdl_image”. These are two libraries that must be installed on your computer before the program will work. The best way to handle this is with a package manager. The developers recommend installing those libraries via MacPorts. Matt instead uses homebrew; brew install sdl sdl_image was successful.
sudo dnf install jack-audio-connection-kit)brew install jack but it currently only provides the uselessly out of date version 0.125.0 of JACK.)XXX specify exactly what comes from each of these sources; is it the full “JACK package” as described at the top of this page?
XXX maybe all this gets folded into the above and/or moved to separate pages?
You may need to change QjackCtl’s “Server Path” to the full /usr/local/bin/jackd instead of just jackd (XXX apparently always in Mojave or Catalina) as shown in JackTrip for OSX documentation.
If you’re on OSX 10.14 or earlier and want to run JackPilot (e.g., to configure JackRouter) on a modern Mac, you may have to set it to low resolution, so that “Get Info” looks like this:
This page of CCRMA documentation last committed on Mon Aug 30 11:03:06 2021 -0700 by Matthew James Wright.