 jack   faq    download     documentation    developers     applications    lists        
       
       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.

SourceForge.net Project Page
Document History
