CCRMA Documentation links:   index   contents   overview   rooms   account   staff   about


The JACK Audio Connection Kit (JACK)

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.

JACK’s settings

JACK determines the following settings (aka “preferences”) when it starts on your computer:

Changing any of these requires stopping JACK (thereby stopping every program currently using JACK), then restarting it with the new options.

JACK’s connections

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”.)

Troubleshooting: Horrible Squealing Feedback

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?

Troubleshooting: Why Can’t I Connect this Application?

A major pitfall is that JACK-connected software will display some 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. 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.:

JACK itself: jackd, 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 -n2

Most 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:

Troubleshooting: Is JACK installed on this computer?

One way to check whether a Linux or OSX system currently has JACK installed is to try launching jackd from the terminal:

    jackd

If 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.

Troubleshooting: Is this computer already running JACK?

One way to check whether a Linux or OSX system currently has JACK running (and if so how it’s configured) is to search for any currently running processes whose name includes “jackd”:

    ps -ef | grep jackd

If 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 -n2

Everything 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 JACK

QjackCtl (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:

Screenshot of QjackCtl’s main window with JACK stopped

In the above image three things tell you that JACK is currently stopped (as far as qjackctl understands):

  1. The word “Stopped” in the title bar
  2. The green “Start” button looks normal but the red “Stop” button is greyed-out
  3. The yellow word “Stopped” at the top left of the black-background rectangle.

Compare to this screenshot taken when JACK was running:

Screenshot of QjackCtl’s main window with JACK active.

Next to the yellow word “Active” (sometimes instead “Started” - XXX not sure what the difference means) is a blinking “RT” (also showing that JACK is running?), 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:

Start
Launch jackd with the current settings of the Setup window (if qjackctl understands that jackd is not already running)
Stop
Stop (aka “kill”) the jackd that qjackctl is aware of (if any)
Quit
Quit the 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:

Location of qjackctl the executable file:

How QjackCtl relates to jackd

Most users should use jackd exclusively through QjackCtl; if you do that 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, as well as make and break jack connections, including JackPilot and various command-line programs including 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 if you start jackd outside of QjackCtl and then launch QjackCtl, then QjackCtl will “notice” jackd already running, immediately show that it’s “Active” (including the option to “Stop” it), and display all the current connections, but the settings in the “Setup” window will be whatever you last selected in QjackCtl, not necessarily the settings of the jackd that is currently running. QjackCtl will “notice” the stopping of the jackd that it’s aware of, but if you restart jackd outside of QjackCtl, then QjackCtl will still (wrongly) display that JACK is inactive (until you quit+restart, at which point QjackCtl will “see” the jackd).

If you quit QjackCtl while JACK is running you may receive a dialog box “JACK is currently running. Do you want to terminate the JACK audio server?” (XXX Apparently this happens on OSX but 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).

JackPilot

JackPilot 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.

Recipe for Starting JACK

There are (too) many ways to start JACK. Here is one relatively friendly method:

Troubleshooting: Why won’t JACK start?

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?

Troubleshooting: Is JACK Working?

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:

Making and Breaking JACK Connections

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).

Viewing and Changing JACK Connections from QjackCtl

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. Here are some examples in increasing complexity:

Screenshot of QjackCtl’s Connect window with JACK stopped or not connected to any audio hardware (which you can see because there is no System audio)
Screenshot of QjackCtl’s Connect window with JACK running but no audio connections made, and we can’t see how many input or output channels JACK is using because of not having clicked the disclosure triangle next to each system
Screenshot of QjackCtl’s Connect window with JACK running and connected to two channels each of audio hardware input (“capture”) and output (“playback”).
Screenshot of QjackCtl’s Connect window with a single connection from audio input (mic) 1 to audio output 1 (possibly the left speaker or headphone ear)
Screenshot of QjackCtl’s Connect window with a connection from each audio input (e.g., two mics) to the corresponding audio output (e.g., mic 1 in the left speaker and mic 2 in the right speaker)
Screenshot of QjackCtl’s Connect window with audio input (mic) 1 connected to both audio outputs, e.g., a mic appearing equally in both ears of a pair of headphones.
Screenshot of QjackCtl’s Connect window with both audio inputs connected to both audio outputs, e.g., two mics both appearing equally in both ears of a pair of headphones.
Screenshot of QjackCtl’s Connect window for a jacktrip server in hub patching mode 2, where each of the three connected clients hears the audio from the other two but not herself.
Screenshot of QjackCtl’s Connect window for a jacktrip client sending two mics to server computer cmn16, playing sound received back from the server on the local audio hardware, and also using meterbridge to monitor the two local mic signals and the two signals being sent from the jacktrip server.

Most JACK users use QjackCtl’s visual interface to make and break connections:

Changing JACK Connections from Command Line and Scripts

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 can establish individual connections by naming the source and destination.

Some Programs Make Their Own JACK 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 JACK connections.

JACK Utilities

Meterbridge

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 x

Example: 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
meterbridge on OSX

It turns out there’s an OSX port of meterbridge that still works (at least on Mojave XXX Catalina?); the only tricky part is that it “Needs libsdl and libsdl_image”. They recommend installing those libraries via MacPorts; it worked via homebrew with brew install sdl sdl_image for Matt.

Installation

XXX specify exactly what comes from each of these sources; is it the full “JACK package” as described at the top of this page?

Operating-System-Specific aspects of JACK

XXX maybe all this gets folded into the above and/or moved to separate pages?

JACK on Windows

JACK on Linux

JACK on Macintosh OSX

QjackCtl Server Path

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.

JackPilot Low Resolution

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:

OSX “Get Info” window for JackPilot, shopwing “Open in Low Resolution” checked.

This page of CCRMA documentation updated Fri Jul 10 18:24:51 PDT 2020 by matt.