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. Stanford has a page for Digital Accessibility.