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 POSIX conformant
12 operating systems such as GNU/Linux and Apple's OS X. It can connect
13 several client applications to an audio device, and allow them to
14 share audio with each other. Clients can run as separate processes
15 like normal applications, or within the JACK server as "plugins".
16
17 JACK was designed from the ground up for professional audio work, and
18 its design focuses on two key areas: synchronous execution of all
19 clients, and low latency operation.
20
21 @see <http://jackit.sourceforge.net>
22
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_new 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. This <simple_client.c>
76 demonstrates a complete (simple!) JACK application that just copies
77 the signal arriving at its input port to its output port.
78
79 @section reference Reference
80
81 The JACK programming interfaces are described in several header files:
82
83 - <jack/jack.h> defines most of the interfaces used by JACK clients.
84 - <jack/transport.h> provides a simple transport control mechanism
85 for starting, stopping and repositioning clients. This is described
86 in the @ref transport-design document.
87 - <jack/types.h> defines most of the data types for JACK.
88 - <jack/ringbuffer.h> defines a simple API for using lock-free
89 ringbuffers, a very valuable and common data structure in real
90 time streaming media software. It is critical for use in
91 applications that do disk I/O such as audio file players and
92 recording software.
93
94 In addition, the example_clients directory provides numerous examples
95 of simple JACK clients that nevertheless use the API to do something
96 useful. It includes
97
98 - a metronome.
99 - a recording client that can capture any number of channels
100 from any JACK sources and store them as an audio file.
101 - command line clients to control the transport mechanism,
102 change the buffer size and more.
103 - simple examples of wrapping a GUI around a JACK application.
104 - tools for checking the status of a running JACK system.
105
106 @section license License
107
108 Copyright (C) 2001-2003 by Paul Davis and others.
109
110 JACK is free software; you can redistribute it and/or modify it under
111 the terms of the GNU GPL and LGPL licenses as published by the Free
112 Software Foundation, <http://www.gnu.org>. The JACK server uses the
113 GPL, as noted in the source file headers. However, the JACK library
114 is licensed under the LGPL, allowing proprietary programs to link with
115 it and use JACK services. You should have received a copy of these
116 Licenses along with the program; if not, write to the Free Software
117 Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307,
118 USA.
119
120 This program is distributed in the hope that it will be useful, but
121 WITHOUT ANY WARRANTY; without even the implied warranty of
122 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
123 General Public License for more details.
124
125 */
This page was automatically generated by the
LXR engine.
Visit the LXR main site for more
information.