149 lines
6.3 KiB
Plaintext
149 lines
6.3 KiB
Plaintext
/*
|
|
* This is the main page of the JACK reference manual, built using
|
|
* doxygen.
|
|
*/
|
|
|
|
/**
|
|
@mainpage (LADI) JACK Audio Connection Kit API Reference
|
|
|
|
@section intro Introduction
|
|
|
|
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.
|
|
|
|
JACK is a low-latency audio server, written for any operating system
|
|
that is reasonably POSIX compliant. 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 [jackdbus.ladish.org](http://jackdbus.ladish.org)
|
|
@see [Upstream jackaudio.org site - jackaudio.org](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 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 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)
|
|
|
|
|
|
@section license License
|
|
|
|
Copyright (C) 2001-2023 by Paul Davis, Stephane Letz, Jack O'Quinn, Torben Hohn, Nedko Arnaidov, Filipe Coelho 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 the GNU General Public License
|
|
along with this program. If not, see <https://www.gnu.org/licenses/>.
|
|
|
|
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.
|
|
|
|
*/
|