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