doc/mainpage.dox

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