jack1/jackd/jackd.1.in

.TH JACKD "1" @VERSION@ "Sept. 2003"
.SH NAME
jackd, jackstart \- JACK Audio Connection Kit sound server
.SH SYNOPSYS
\fBjackd\fR [ \fI options \fR ] \fB \-d \fI driver \fR 
[\fI driver options \fR ]
.br
\fBjackstart\fR [ \fI options \fR ] \fB \-d \fI driver \fR 
[\fI driver options \fR ]
.br
\fBjackd \-\-help\fR
.SH DESCRIPTION
\fBjackd\fR invokes the JACK audio server daemon.  When using JACK's
built-in support for realtime capabilities, use the \fBjackstart\fR
command, instead.  All options are the same.

JACK is a low-latency audio server, originally written for the
GNU/Linux operating system.  It can connect a number of different JACK
client applications to an audio device, and also to each other.  Most
clients are external, running in their own processes as normal
applications.  JACK also supports internal clients, which run within
the \fBjackd\fR process using a loadable "plugin" interface.

JACK differs from other audio servers in being designed from the
ground up for professional audio work.  It focuses on two key areas:
synchronous execution of all clients, and low latency operation.

For the latest JACK information, please consult the web site,
<\fBhttp://jackit.sourceforge.net\fR>.
.SH OPTIONS
.TP
\fB\-h, \-\-help\fR
.br
Print a brief usage message describing the main \fBjackd\fR options.
These do not include driver options, which are obtained using the
\fB\-\-help\fR option for that specific driver, instead.
.TP
\fB\-a, \-\-asio\fR
.br
Force absolute realtime behaviour on the system.  Rather than allowing
clients to take a time determined by the kernel, they are determined
to have timed out on receipt of the next interrupt from the audio
interface.  This only makes sense when used with an ASIO-style
configuration where there are 2 periods per buffer (see
\fB\-\-nperiods\fR).  It is safe to omit this parameter, if you don't
need to enforce strict realtime limits.  It can be useful for testing
the realtime behavior of a new JACK clients.
.TP
\fB\-t, \-\-timeout \fIint\fR
.br
Set client timeout limit in microseconds.  The default is 500 msec
when not in realtime mode (see: \-R).
.TP
\fB\-R, \-\-realtime\fR 
.br
Use realtime scheduling.  This is needed for reliable low-latency
performance.  It requires \fBjackd\fR to run with special scheduler
and memory allocation privileges, which may be obtained in two ways.
The first method is to run \fBjackd\fR with root privileges, which
means that all JACK clients must also run as root.  The second method
requires a kernel with "POSIX draft capabilities" enabled (see the
\fB<linux/capability.h>\fR include file).  Then, an ordinary user can
invoke the daemon using \fBjackstart\fR, and later launch JACK clients
without running as root.
.TP
\fB\-P, \-\-realtime\-priority \fIint\fR
When running \fB\-\-realtime\fR, set the scheduler priority to
\fIint\fR.
.TP
\fB\-D, \-\-tmpdir \fIdirectory\fR
Set the \fIdirectory\fR to use for temporary files.
.TP
\fB\-v, \-\-verbose\fR
Give verbose output.
.TP
\fB\-V, \-\-version\fR
Print the current JACK version number and exit.
.TP
\fB\-d, \-\-driver \fI driver \fR [ \fI driver-options \fR ] 
.br
Select the output driver.  The only \fIdriver\fR currently documented
is \fBalsa\fR (see below).
.SS ALSA DRIVER OPTIONS
.TP
\fB\-h, \-\-help\fR Print a brief usage message describing only the
\fBalsa\fR driver options.
.TP
\fB\-d, \-\-device \fIname\fR
.br
The ALSA pcm device \fIname\fR to use ("default" if none specified).
.TP
\fB\-r, \-\-rate \fIint\fR
Specify the sample rate.  The default is 48000.
.TP
\fB\-p, \-\-period \fIint\fR
.br
Specify the number of frames between JACK \fBprocess()\fR calls.  The
default is 1024.  If you need low latency, set \fB\-p\fR as low as you
can go without seeing xruns.  A larger period size yields higher
latency, but makes xruns less likely.  The JACK input latency in
seconds is \fB\-\-period\fR divided by \fB\-\-rate\fR.
.TP
\fB\-n, \-\-nperiods \fIint\fR
.br
Specify the number of periods in the hardware buffer.  The default is
2.  The period size (\fB\-p\fR) times \fB\-\-nperiods\fR times four is
the JACK buffer size in bytes.  The JACK output latency in seconds is
\fB\-\-nperiods\fR times \fB\-\-period\fR divided by \fB\-\-rate\fR.
.TP
\fB\-D, \-\-duplex\fR
Provide both capture and playback ports (the default).
.TP
\fB\-C, \-\-capture\fR
Provide only capture ports.
.TP
\fB\-P, \-\-playback\fR
Provide only playback ports.
.TP
\fB\-H, \-\-hwmon\fR
.br
Enable hardware monitoring of capture ports.  This is a method for
obtaining "zero latency" monitoring of audio input.  It requires
support in hardware and from the underlying ALSA device driver.

When enabled, requests to monitor capture ports will be satisfied by
creating a direct signal path between audio interface input and output
connectors, with no processing by the host computer at all.  This
offers the lowest possible latency for the monitored signal.

Presently (March 2003), only the RME Hammerfall series and cards based
on the ICE1712 chipset (M-Audio Delta series, Terratec, and others)
support \fB\-\-hwmon\fR.  In the future, some consumer cards may also
be supported by modifying their mixer settings.

Without \fB\-\-hwmon\fR, port monitoring requires JACK to read audio
into system memory, then copy it back out to the hardware again,
imposing the basic JACK system latency determined by the
\fB\-\-period\fR and \fB\-\-nperiods\fR options.
.TP
\fB\-M, \-\-hwmeter\fR
.br
Enable hardware metering for devices that support it.  Otherwise, use
software metering.
.TP
\fB\-s, \-\-softmode\fR 
.br
Ignore xruns reported by the ALSA driver.  This makes JACK less likely
to disconnect unresponsive ports when running without
\fB\-\-realtime\fR.
.TP
\fB\-z, --dither [rectangular,triangular,shaped,none]
Set dithering mode.  If \fBnone\fR or unspecified, dithering is off.
Only the first letter of the mode name is required.
.SH EXAMPLES
.PP
Print usage message for options specific to the \fBalsa\fR driver.
.IP
\fBjackd \-d alsa \-\-help\fR
.PP
Run the JACK daemon with realtime priority using the first ALSA
hardware card defined in \fB/etc/modules.conf\fR.  This must be run on
a kernel with capabilities enabled.
.IP 
\fBjackstart \-\-realtime \-\-driver=alsa \-\-device=hw:0\fR
.PP
Run the JACK daemon with low latency.  A reasonably well-tuned
current-generation system with a decent sound card and a low-latency
kernel with capabilities enabled can handle these values reliably.
Some can do better.  If you get xrun messages, try a larger buffer.
Tuning a system for low latency is challenging.  The JACK FAQ,
<\fBhttp://jackit.sourceforge.net/docs/faq.php\fR> has some useful
suggestions.
.IP 
\fBjackstart \-R \-d alsa \-d hw:0 \-p 128 \-n 3 \-r 44100\fR
.PP
Run \fBjackd\fR with realtime priority using the "sblive" ALSA device
defined in ~/.asoundrc.  Apply shaped dithering to playback audio.
This must be run as root.
.IP 
\fBjackd \-R \-d alsa \-d sblive \-\-dither=shaped\fR
.PP
Run \fBjackd\fR with no special privileges using the "sblive" ALSA
device defined in ~/.asoundrc.  Any xruns reported by the ALSA driver
will be ignored.  The larger buffer helps reduce data loss.
Rectangular dithering will be used for playback.
.IP 
\fBjackd \-d alsa \-d sblive \-p1024 \-n3 \-\-softmode \-zr\fR
.SH SEE ALSO:
.BR <\fBhttp://www.alsa-project.org\fR>
.SH BUGS
Please send bug reports to <\fBjackit-devel@lists.sourceforge.net\fR>.
.SH AUTHORS
Paul Davis and others.
.PP
Manpage originally written by Stefan Schwandter
<e9925373@student.tuwien.ac.at> and later adapted by Jack O'Quin
<joq@joq.us>.