JACK faq

• How did JACK come to be?
• How does JACK compare to...?
• How can I make my app use JACK?
• What do I need to do to link to JACK?
• How do install JACK?
• Why are my clients unable to connect to the JACK server?
• How can I get the best performance out of JACK?
• How should I tune my hardware?
• How should I configure my Operating System?
• How do I configure Linux 2.6?
• How do I configure Linux 2.4?
• How do I configure Mac OS X?
• What about other Operating Systems?
• What other software tuning should I consider?
• JACK, jackd, libjack, jackit, wha?

How did JACK come to be?

People on the linux-audio-dev list saw the need for a server API that would allow high-bandwidth, low-latency communication between a number of audio applications. The proposal that was put forth was called "LAAGA", the Linux Audio Applications Glue API. JACK may be seen as an implementation of the goals of LAAGA. Another planned implementation of these goals is LADMEA, written by the author of the successful LADSPA plugin interface. LADMEA and JACK are somewhat orthogonal, and it is not impossible to imagine them interacting in a cooperative fashion.

How does JACK compare to...?

Please mail the jackit-devel mailing list if you have any concerns about the answers to these questions. Also, no disrespect to any effort is intended, only a recognition of different goals and design principles.

How does JACK compare to ...

• Other Linux-centered systems

  • ALSA: both a HAL and a user-space library for audio under Linux. ALSA is used to provide the default audio i/o driver for JACK. ALSA is a very powerful audio API, but it does not provide a callback-based API or offer any solutions for inter-application communication, though it has been discussed and is theoretically possible.

  • aRts, a streaming media architecture: aRts was not designed from the ground up with low-latency in mind. Not a fault, but a design decision. A jack output element could be written for aRts, though, as far as I can tell.

  • GStreamer, another streaming media architecture: GStreamer is designed for in-process construction of media pipelines, and is not used to link applications. JACK elements for GStreamer are under construction.

  • LADSPA: LADSPA is an internal plugin API for DSP routines, not a way of linking external applications together.

  • LADMEA, another LAAGA proposal: JACK is actually implemented. Also, see the thread on linux-audio-dev.

• Cross-platform systems

  • PortAudio: a "cross platform, open-source, audio I/O library" offering both callback- and blocking I/O-based APIs. PortAudio backends exist for various Windows, Mac, and Unix HALs. It is mainly focused on hardware I/O rather than a general concept of ports and connections, although a JACK backend to PortAudio is under construction that would allow PortAudio apps to connect to JACK ports. While the JACK API is portable, its current implementation is limited to POSIX-compliant systems; applications needing greater portability might consider PortAudio. In any case, the callback-style API used by both projects makes it easy to port between the two (no pun intended).

• MacOS- and/or Windows-centered systems

  • CoreAudio, the Mac OS X audio API: Very similar to JACK in concept, being centered on a synchronous-execution-via-callback API, but does not include inter-application audio routing. CoreAudio also includes a hardware-level abstraction layer, whereas JACK uses higher-level drivers for that purpose. The first JACK driver was based on ALSA, but others are available for the OSS and PortAudio interfaces.

  • ASIO: a HAL for both Windows and MacOS that replaces the native device driver model with something much cleaner. It supports hardware-level latencies, but it does not connect applications to each other. Also, it is subject to license restrictions, and does not exist for Linux (though it would not be impossible to implement it on top of ALSA).

  • ReWire, an inter-app communications API for Windows and MacOS from PropellerHeads and Steinberg, ReWire is similar in that it provides inter-application audio routing, but does not allow for fully independent processes, and has silly restrictions ("up to 64 channels", etc). JACK also comes without without silly license restrictions.

  • VST, DirectX, MAS, RTAS: these are all Windows/MacOS audio plugin APIs. None of them permit inter-application data sharing. Some plugin hosts can make this possible by using some other system such as ReWire. These APIs also require that the callback you write to process/generate data be executed in the context of the plugin host; JACK allows your callback to be executed within the context of your own application (if you wish to).

How can I make my app use JACK?

Your app must be callback-based. This means that you should not block on writes or reads from a PCM device; rather, you should have your app be "driven" by a function that gets called at regular intervals. This is a design decision. Then, take a look at the simple client code, and do your interesting stuff inside the process() function.

Note that code written for any callback API can generally be ported to any other callback API fairly easily. Code that is written around a "blocking I/O" model generally needs to completely redesigned to be used in any kind of callback API.

What do I need to do to link to JACK?

JACK uses pkg-config. Find a package for your favorite distribution and OS, or build it from source. To build your JACK program, try

$ gcc -o myprog `pkg-config --cflags --libs jack` myprog.c

This process can be integrated into your autoconf/automake build system with pkg.m4, included in the pkg-config package. Just add the line

PKG_CHECK_MODULES(JACK, jack, HAVE_JACK=true, HAVE_JACK=false)

to your configure.ac. In addition to HAVE_JACK, the variables JACK_LIBS and JACK_CFLAGS will be created. To substitute on them you will have to AC_SUBST both of them separately.

How do I install JACK?

Prerequisites

• 2.4, 2.5 or 2.6 series kernel with tmpfs turned on (CONFIG_TMPFS)
• Shared memory file system mounted on /dev/shm. add the following to /etc/fstab to get it mounted at boot:

  	shmfs       /dev/shm     shm    defaults        0       0
  

  (Note: you may have to make the /dev/shm directory)

Once you have the correct shmfs support, you should be able to build jack with the following sequence of commands:

sh ./autogen.sh
./configure
make
make install

Good luck!

Why are my clients unable to connect to the JACK server?

The most common reason is that the server was started using a different user ID.

How can I get the best performance out of JACK?

"Good performance" for JACK means operating at the lowest latency possible with no dropouts at any load. There are a number of factors which affect performance:

• How should I tune my hardware?

  Sound card

  Some sound cards are designed better than others. Many "consumer" sound cards use separate internal pointers for capture and playback, which can result in unreliable operation at low latencies. For example, my ens1370 does not operate very well in full-duplex mode. You can work around this by telling the ALSA driver to operate only in capture or playback mode.

  People have reported problems with ymfpci cards as well.

  General system configuration

  People from linux-audio-dev are quite familiar with what is necessary to build a low-latency system. There is no need to rehash all of that here, see the low-latency resource page for more information on getting your system in tune.

• How should I configure my Operating System?

  Real-time scheduling

  JACK requires real-time scheduling privileges for reliable, dropout-free operation. The server requests these privileges when running with the -R option. The standard Linux 2.4 kernel does not adequately support this, but can be modified to work very well. Unmodified 2.6 kernels work much better, but still require special configuration. The requirements for Mac OS X and other Operating Systems differ.

  The simplest, and least-secure way to provide real-time privileges is running jackd as root. This has the disadvantage of also requiring all of JACK clients to run as root. Real-time scheduling is inherently dangerous; a badly or maliciously coded application can hang the system. Worse, running as root gives an intruder too many opportunities to damage or co-opt the entire system by attacking the JACK server or its clients. Systems connected to the Internet would be well-advised to avoid this approach. There are safer ways to gain the needed privileges, the exact method depends on which Operating System you run.

  How do I configure Linux 2.6?

  For Linux 2.6, the Realtime Linux Security Module provides a relatively easy way for non-root users to gain real-time privileges. Some audio-oriented distributions include this module as a separate binary package or with the kernel image. Otherwise, you will need to download the realtime-lsm source and build it yourself.

  This loadable kernel extension selectively grants real-time privileges to user programs. If loaded with modprobe realtime gid=29, it will permit real-time operation for all members of group 29 (the Debian "audio" group). It provides several additional options, described in the user documentation.

  There is an allcaps=1 option, which duplicates the effect of running Linux 2.4 with the capabilities patch. To use that you must compile JACK with --enable-capabilites as you would for the 2.4 kernel. You will need this if you prefer to run jackstart -R rather than jackd -R. If you only use Linux 2.6, you need not bother with it.

  Currently (as of 2.6.7) JACK has a serious problem creating SCHED_FIFO threads for real-time processing. It is unclear whether this is a bug in JACK, in the new Native PThreads Library (NPTL), or in the 2.6 kernel. At the moment no one has a solution, but there is a workaround: define LD_ASSUME_KERNEL=2.4.19 in the environment of the jackd process and of every JACK client. The easiest way to do this is setting it in ~/.profile , or wherever you customarily define global environment variables. Glibc developer Ulrich Drepper explains the operation of LD_ASSUME_KERNEL in more detail.

  How do I configure Linux 2.4?

  The vanilla Linux 2.4 kernel does not adequately support real-time scheduling. For reliable low-latency operation you need the low-latency patches from Andrew Morton. With these patches, 2.4 performs quite well.

  In addition, non-root users need a way to gain real-time scheduling privileges. The preferred solution on 2.4 is using a setuid root application to run the jackd binary as a non-root user, transfering the privileges needed for real-time scheduling. This requires that the kernel allow one process to grant its privileges to another using the CAP_SETPCAP capability. In the givertcap page, Tommi Ilmonen discusses this technique in more depth. Although this capability is built into the kernel, it is disabled by default because of a serious security exposure: if an attacker somehow manages to subvert some system daemon running with root privileges, it can then use CAP_SETPCAP to deny needed privileges to other root processes. Enabling this capability would not be appropriate for an Internet server system, but for an audio workstation the risk is generally acceptable.

  Linux 2.4 kernels require a small kernel patch to enable CAP_SETPCAP. Go to include/linux/capability.h in your kernel sources, and change the line

    #define CAP_INIT_EFF_SET    to_cap_t(~0&~CAP_TO_MASK(CAP_SETPCAP))
  

  to

    #define CAP_INIT_EFF_SET    to_cap_t( ~0 )
  

  and the line

    #define CAP_INIT_INH_SET    to_cap_t(0)
  

  to

    #define CAP_INIT_INH_SET    to_cap_t( ~0 )
  

  Then, recompile and install your 2.4 kernel.

  Once you have a kernel with capabilities enabled, build JACK with the --enable-capabilities option of ./configure. This installs a jackstart binary you can invoke as a normal user to start the jackd server with real-time privileges. The server will also give these privileges to the JACK thread in all its clients.

  To compile jack with capabilities enabled you will need libcap. Most distributions include this package, which is also available in source form. You also need the md5sum program and the openssl libraries to calculate and and verify the integrity of the jackd binary.

  How do I configure Mac OS X?

  On Mac OS X, all users have real-time privileges. No special tuning is required for real-time scheduling. But, OS X lacks POSIX support for locking pages into real memory. JACK will run without locking memory, but users should avoid running too many other applications when performing critical real-time tasks. If there is too much memory contention, the operating system might page out data needed for the time-critical process cycle, causing dropouts.

  Mac OS X users should take a look at Jack Tools, a set of tools for integrating JACK into the Apple CoreAudio environment.

  What about other Operating Systems?

  BSD does not provide any way to grant real-time privileges to non-root users. So, jackd -R only works for the superuser.

  Some older BSD variants lack POSIX support for locking pages into real memory. JACK will run without locking memory, but users should avoid running too many other applications when performing critical real-time tasks. If there is too much memory contention, the operating system might page out data needed for the time-critical process cycle, causing dropouts.

  What other software tuning should I consider?

  ALSA driver settings can affect performance to a large degree. Try adjusting the number of periods (anything other than 2 or 3 will probably not help you with JACK). For some cards, using just --playback or just --capture may help. Avoid using a plug-layer PCM device (like default). See the terse ALSA driver help (jackd -d alsa -h) or the jackd man page for a list of options.

  It has been found that mounting /tmp/jack as tmpfs (in RAM) solves problems that many people have experienced with xruns while using JACK. The solutions below help when your /tmp directory is mounted on a journalled filesystem.

  Just put this in your /etc/fstab

  none /tmp/jack tmpfs defaults 0 0

  There is also a compile option to enable JACK to place its FIFOs on a ram-based filesystem follows:

  ---

  # mkdir /mnt/ramfs

  [edit /etc/fstab and add the following line]

  none /mnt/ramfs tmpfs defaults 0 0

  Then use --with-default-tmpdir=/mnt/ramfs to the JACK configure line when you build it. No clients need to be recompiled.

  ---

JACK, jackd, libjack, jackit, wha?

There is a profusion of names surrounding the JACK project, and hopefully this will help clear things up.

JACK

JACK is the name of the whole system. It may be written as Jack if you prefer. It is an acronym for "Jack Audio Connection Kit". Do you know JACK?

jackd, libjack

As a system, JACK has a number of parts. The server process is called jackd, and the library that applications link to is called libjack. From a theoretical perspective, this distinction is not important, but it is helpful to note the difference when describing JACK internals, due to the fact that these components execute in different processes and address spaces.

jackit, jack-audio-connection-kit

As luck would have it, by the time we got around to registering a sourceforge site for JACK, there was already another program out there by the same name. "jackit" is a play on the original JACK acronym. Not only does that other project have the sourceforge name, it has mandrake and debian packages too, so we needed a new name for releases. At the moment, we are releasing tarballs as jack-audio-connection-kit.