doc/mainpage.dox

   1 /*
   2  * This is the main page of the JACK reference manual, built using
   3  * doxygen.
   4  */
   5
   6 /**
   7 @mainpage JACK Audio Connection Kit
   8
   9 @section intro Introduction
  10
  11 JACK is a low-latency audio server, written for any operating system
  12 that is reasonably POSIX compliant. It currently exists for Linux, OS
  13 X, Solaris, FreeBSD and Windows. It can connect several client
  14 applications to an audio device, and allow them to share audio with
  15 each other.  Clients can run as separate processes like normal
  16 applications, or within the JACK server as "plugins".
  17
  18 JACK was designed from the ground up for professional audio work, and
  19 its design focuses on two key areas: synchronous execution of all
  20 clients, and low latency operation.
  21
  22 @see <http://jackaudio.org>
  23
  24 @section jack_overview JACK Overview
  25
  26 Traditionally it has been hard if not impossible to write audio
  27 applications that can share data with each other. In addition,
  28 configuring and managing audio interface hardware has often been one
  29 of the most complex aspect of writing audio software.
  30
  31 JACK changes all this by providing an API that does several things:
  32
  33     1. provides a high level abstraction for programmers that
  34        removes the audio interface hardware from the picture and
  35        allows them to concentrate on the core functionality of
  36        their software.
  37
  38     2. allows applications to send and receive audio data to/from
  39        each other as well as the audio interface. There is
  40        difference in how an application sends or receives
  41        data regardless of whether it comes from another application
  42        or an audio interface.
  43
  44 For programmers with experience of several other audio APIs such as
  45 PortAudio, Apple's CoreAudio, Steinberg's VST and ASIO as well as many
  46 others, JACK presents a familiar model: your program provides a
  47 "callback" function that will be executed at the right time. Your
  48 callback can send and receive data as well as do other signal
  49 processing tasks. You are not responsible for managing audio
  50 interfaces or threading, and there is no "format negotiation": all
  51 audio data within JACK is represented as 32 bit floating point values.
  52
  53 For those with experiences rooted in the Unix world, JACK presents a
  54 somewhat unfamiliar API. Most Unix APIs are based on the read/write
  55 model spawned by the "everything is a file" abstraction that Unix is
  56 rightly famous for. The problem with this design is that it fails to
  57 take the realtime nature of audio interfaces into account, or more
  58 precisely, it fails to force application developers to pay sufficient
  59 attention to this aspect of their task. In addition, it becomes rather
  60 difficult to facilitate inter-application audio routing when different
  61 programs are not all running synchronously.
  62
  63 Using JACK within your program is very simple, and typically consists
  64 of just:
  65
  66    - calling @ref jack_client_open() to connect to the JACK server.
  67    - registering "ports" to enable data to be moved to and from
  68        your application.
  69    - registering a "process callback" which will be called at the
  70        right time by the JACK server.
  71    - telling JACK that your application is ready to start processing
  72        data.
  73
  74 There is a lot more that you can do with JACK's interfaces, but for
  75 many applications, this is all that is needed.  The @ref
  76 simple_client.c example demonstrates a complete (simple!) JACK
  77 application that just copies the signal arriving at its input port to
  78 its output port.  Similarly, @ref inprocess.c shows how to write an
  79 internal client "plugin" that runs within the JACK server process.
  80
  81 @section reference Reference
  82
  83 The JACK programming interfaces are described in several header files.
  84 We present them here broken into useful categories to make the API a
  85 little clearer:
  86
  87     - @ref ClientFunctions
  88     - @ref ClientCallbacks
  89     - @ref ClientThreads
  90     - @ref ServerControl
  91     - @ref PortFunctions
  92     - @ref PortSearching
  93     - @ref TimeFunctions
  94     - @ref TransportControl
  95     - @ref ErrorOutput
  96     - @ref NonCallbackAPI
  97     - @ref MIDIAPI
  98
  99 The full API is described in:
 100
 101   - @ref jack.h "<jack/jack.h>" is the main JACK interface.
 102   - @ref statistics.h "<jack/statistics.h>" provides interfaces for
 103   monitoring the performance of a running JACK server.
 104   - @ref intclient.h "<jack/intclient.h>" allows loading and unloading
 105   JACK internal clients.
 106   - @ref ringbuffer.h "<jack/ringbuffer.h>" defines a simple API for
 107   using lock-free ringbuffers.  These are a good way to pass data
 108   between threads, when streaming realtime data to slower media, like
 109   audio file playback or recording.
 110   - @ref transport.h "<jack/transport.h>" defines a simple transport
 111   control mechanism for starting, stopping and repositioning clients.
 112   This is described in the @ref transport-design document.
 113   - @ref types.h "<jack/types.h>" defines the main JACK data types.
 114   - @ref thread.h "<jack/thread.h>" functions standardize thread
 115   creation for JACK and its clients.
 116   - @ref midiport.h "<jack/midiport.h>" functions to handle reading
 117   and writing of MIDI data to a port
 118
 119 In addition, the tools directory provides numerous examples
 120 of simple JACK clients that nevertheless use the API to do something
 121 useful.  It includes
 122
 123   - a metronome.
 124   - a recording client that can capture any number of channels
 125       from any JACK sources and store them as an audio file.
 126   - command line clients to control the transport mechanism,
 127        change the buffer size and more.
 128   - commands to load and unload JACK internal clients.
 129   - tools for checking the status of a running JACK system.
 130
 131 and many more.
 132
 133 @section porting Porting
 134
 135 JACK is designed to be portable to any system supporting the relevant
 136 POSIX and ANSI C standards.  It currently runs under GNU/Linux, Mac OS
 137 X and Berkeley Unix on several different processor architectures.  If
 138 you want to port JACK to another platform, please read the @ref
 139 porting-guide document.
 140
 141 @section license License
 142
 143 Copyright (C) 2001-2003 by Paul Davis and others.
 144
 145 JACK is free software; you can redistribute it and/or modify it under
 146 the terms of the GNU GPL and LGPL licenses as published by the Free
 147 Software Foundation, <http://www.gnu.org>.  The JACK server uses the
 148 GPL, as noted in the source file headers.  However, the JACK library
 149 is licensed under the LGPL, allowing proprietary programs to link with
 150 it and use JACK services.  You should have received a copy of these
 151 Licenses along with the program; if not, write to the Free Software
 152 Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307,
 153 USA.
 154
 155 This program is distributed in the hope that it will be useful, but
 156 WITHOUT ANY WARRANTY; without even the implied warranty of
 157 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
 158 General Public License for more details.
 159
 160 */