jackd man page revisions

git-svn-id: svn+ssh://jackaudio.org/trunk/jack@793 0c269be4-1314-0410-8aa9-9f06e86f4224
21 years ago · 3f6ee6bd5c
--- a/jackd/jackd.1.in
+++ b/jackd/jackd.1.in
@@ -1,25 +1,26 @@
 .TH JACKD "1" @VERSION@ "September 2004"
 .SH NAME
 .TH "JACKD" "1" "@VERSION@" "November 2004" ""
 .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 ]
 .SH "SYNOPSYS"
 \fBjackd\fR [\fIoptions\fR] \fB\-d\fI backend \fR 
 [\fIbackend\-parameters\fR]
 .br
 \fBjackstart\fR [ \fI options \fR ] \fB \-d \fI driver \fR 
 [\fI driver options \fR ]
 \fBjackstart\fR [\fIoptions\fR] \fB\-d\fI backend \fR 
 [\fIbackend\-parameters\fR]
 .br
 \fBjackd \-\-help\fR
 .SH DESCRIPTION
 .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.
 built\-in support for realtime capabilities, use the \fBjackstart\fR
 command, instead.  All parameters 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 is a low\-latency audio server.  Originally written for the
 GNU/Linux operating system, it also supports Mac OS X and various Unix
 platforms.  JACK can connect a number of different 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:
@@ -27,20 +28,21 @@ 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
 .SH "OPTIONS"
 .TP
 \fB\-d, \-\-driver \fI driver \fR [ \fI driver-options \fR ] 
 \fB\-d, \-\-driver \fIbackend\fR [\fIbackend\-parameters\fR ]
 .br
 Select the output driver.  The only \fIdriver\fR currently documented
 here is \fBalsa\fR (see below).  There are additional drivers named
 \fBcoreaudio\fR, \fBdummy\fR, \fBoss\fR and \fBportaudio\fR.  Examples
 below show how to list their parameters.
 Select the audio interface backend.  The current list of supported
 backends is: \fBalsa\fR, \fBcoreaudio\fR, \fBdummy\fR, \fBoss\fR and
 \fBportaudio\fR.  They are not all available on all platforms.  All
 \fIbackend\-parameters\fR are optional.
 .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.
 These do not include \fIbackend\-parameters\fR, which are listed using
 the \fB\-\-help\fR option for each specific backend.  Examples below
 show how to list them.
 .TP
 \fB\-m, \-\-no\-mlock\fR
 Do not attempt to lock memory, even if \fB\-\-realtime\fR.
@@ -51,15 +53,19 @@ The default value is 128.
 .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.
 Use realtime scheduling.  This is needed for reliable low\-latency
 performance.  On most systems, it requires \fBjackd\fR to run with
 special scheduler and memory allocation privileges, which may be
 obtained in several ways.  The simplest, and least-secure method is to
 run \fBjackd\fR with root privileges.  This means that all JACK
 clients must also run as root.  With a Linux 2.6 kernel, ordinary
 users can run \fBjackd\fR and its clients using options of the
 realtime LSM.  Linux 2.4 kernels need "POSIX draft capabilities"
 enabled (see the \fB<linux/capability.h>\fR include file).  Using that
 method, ordinary users who invoke the daemon using \fBjackstart\fR,
 can later launch JACK clients without running them as root.  See
 .I http://jackit.sourceforge.net/docs/faq.php#a52 
 for more information.
 .TP
 \fB\-P, \-\-realtime\-priority \fIint\fR
 When running \fB\-\-realtime\fR, set the scheduler priority to
@@ -85,10 +91,10 @@ Give verbose output.
 .TP
 \fB\-V, \-\-version\fR
 Print the current JACK version number and exit.
 .SS ALSA DRIVER OPTIONS
 .SS ALSA BACKEND OPTIONS
 .TP
 \fB\-C, \-\-capture\fR [ \fIname\fR ]
 Provide only capture ports, unless combined with \-D or \-P.  Optionally set 
 Provide only capture ports, unless combined with \-D or \-P.  Parameterally set 
 capture device name.
 .TP
 \fB\-d, \-\-device \fIname\fR
@@ -96,7 +102,7 @@ capture device name.
 The ALSA pcm device \fIname\fR to use.  If none is specified, JACK will
 use "hw:0", the first hardware card defined in \fB/etc/modules.conf\fR.
 .TP
 \fB\-z, --dither [rectangular,triangular,shaped,none]
 \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.
 .TP
@@ -105,7 +111,7 @@ Provide both capture and playback ports.  Defaults to on unless only one
 of \-P or \-C is specified.
 .TP
 \fB\-h, \-\-help\fR Print a brief usage message describing only the
 \fBalsa\fR driver options.
 \fBalsa\fR backend parameters.
 .TP
 \fB\-M, \-\-hwmeter\fR
 .br
@@ -124,14 +130,14 @@ 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)
 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.
 \fB\-\-period\fR and \fB\-\-nperiods\fR parameters.
 .TP
 \fB\-i, \-\-inchannels \fIint\fR
 .br
@@ -165,17 +171,134 @@ Specify the sample rate.  The default is 48000.
 .TP
 \fB\-S, \-\-shorts
 .br
 Try to configure card for 16-bit samples first, only trying 32-bits if
 unsuccessful.  Default is to prefer 32-bit samples.
 Try to configure card for 16\-bit samples first, only trying 32\-bits if
 unsuccessful.  Default is to prefer 32\-bit samples.
 .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.
 .SH EXAMPLES
 to disconnect unresponsive ports when running without \fB\-\-realtime\fR.
 .SS COREAUDIO BACKEND PARAMETERS
 .TP
 \fB\-c \-\-channel\fR
 Maximum number of channels (default: 2)
 .TP
 \fB\-i \-\-channelin\fR
 Maximum number of input channels (default: 2)
 .TP
 \fB\-o \-\-channelout\fR
 Maximum number of output channels (default: 2)
 .TP
 \fB\-C \-\-capture\fR
 Whether or not to capture (default: true)
 .TP
 \fB\-P \-\-playback\fR
 Whether or not to playback (default: true)
 .TP
 \fB\-D \-\-duplex\fR
 Capture and playback (default: true)
 .TP
 \fB\-r \-\-rate\fR
 Sample rate (default: 44100)
 .TP
 \fB\-p \-\-period\fR
 Frames per period (default: 128)
 .TP
 \fB\-n \-\-name\fR
 Driver name (default: none)
 .TP
 \fB\-I \-\-id\fR
 Audio Device ID (default: 0)
 .SS DUMMY BACKEND PARAMETERS
 .TP
 \fB\-C, \-\-capture \fIint\fR
 Specify number of capture ports. The default value is 2.
 .TP
 \fB\-P, \-\-playback \fIint\fR
 Specify number of playback ports. The default value is 2.
 .TP
 \fB\-r, \-\-rate \fIint\fR
 Specify sample rate. The default value is 48000.
 .TP
 \fB\-p, \-\-period \fIint\fR
 Specify number of frames per period. THe default value 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\-w, \-\-wait \fIint\fR 
 Specify number of usecs to wait between engine processes. 
 The default value is 21333.
 .SS OSS BACKEND PARAMETERS
 .TP
 \fB\-r, \-\-rate \fIint\fR
 Specify the sample rate.  The default is 48000.
 .TP
 \fB\-p, \-\-period \fIint\fR
 Specify 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
 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\-w, \-\-wordlength \fIint\fR
 Specify the sample size in bits. The default is 16.
 .TP
 \fB\-i, \-\-inchannels \fIint\fR
 Specify how many channels to capture (default: 2)
 .TP
 \fB\-o, \-\-outchannels \fIint\fR
 Specify number of playback channels (default: 2)
 .TP
 \fB\-C, \-\-capture \fIdevice_file\fR
 Specify input device for capture (default: /dev/dsp)
 .TP
 \fB\-P, \-\-playback \fIdevice_file\fR
 Specify output device for playback (default: /dev/dsp)
 .TP
 \fB\-b, \-\-ignorehwbuf \fIboolean\fR
 Specify, whether to ignore hardware period size (default: false)
 .SS PORTAUDIO BACKEND PARAMETERS
 .TP
 \fB\-c \-\-channel\fR
 Maximum number of channels (default: all available hardware channels)
 .TP
 \fB\-i \-\-channelin\fR
 Maximum number of input channels (default: all available hardware channels)
 .TP
 \fB\-o \-\-channelout\fR
 Maximum number of output channels (default: all available hardware channels)
 .TP
 \fB\-C \-\-capture\fR
 Whether or not to capture (default: true)
 .TP
 \fB\-P \-\-playback\fR
 Whether or not to playback (default: true)
 .TP
 \fB\-D \-\-duplex\fR
 Capture and playback (default: true)
 .TP
 \fB\-r \-\-rate\fR
 Sample rate (default: 48000)
 .TP
 \fB\-p \-\-period\fR
 Frames per period (default: 1024)
 .TP
 \fB\-n \-\-name\fR
 Driver name (default: none)
 .TP
 \fB\-z \-\-dither\fR
 Dithering mode (default: none)
 .SH "EXAMPLES"
 .PP
 Print usage message for options specific to each driver.
 Print usage message for the parameters specific to each backend.
 .IP
 \fBjackd \-d alsa \-\-help\fR
 .br
@@ -188,51 +311,49 @@ Print usage message for options specific to each driver.
 \fBjackd \-d portaudio \-\-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 
 hardware card defined in \fB/etc/modules.conf\fR.
 .IP
 \fBjackstart \-\-realtime \-\-driver=alsa\fR
 .PP
 Run the JACK daemon with low latency giving verbose output, which can
 be helpful for trouble-shooting system latency problems.  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 
 be helpful for trouble\-shooting system latency problems.  A
 reasonably well\-tuned system with a good sound card and a
 low\-latency kernel can handle these values reliably.  Some can do
 better.  If you get xrun messages, try a larger buffer.  Tuning a
 system for low latency can be challenging.  The JACK FAQ,
 .I http://jackit.sourceforge.net/docs/faq.php\fR
 has some useful suggestions.
 .IP
 \fBjackstart \-Rv \-d alsa \-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 
 .IP
 \fBjackd \-R \-d alsa \-d sblive \-\-dither=shaped\fR
 .PP
 Run \fBjackd\fR with no special privileges using the second ALSA
 hardware card defined in \fB/etc/modules.conf\fR.  Any xruns reported
 by the ALSA driver will be ignored.  The larger buffer helps reduce
 by the ALSA backend will be ignored.  The larger buffer helps reduce
 data loss.  Rectangular dithering will be used for playback.
 .IP 
 .IP
 \fBjackd \-d alsa \-d hw:1 \-p2048 \-n3 \-\-softmode \-zr\fR
 .PP
 Run \fBjackd\fR in full-duplex mode using the ALSA hw:0,0 device for 
 Run \fBjackd\fR in full\-duplex mode using the ALSA hw:0,0 device for 
 playback and the hw:0,2 device for capture.
 .IP 
 .IP
 \fBjackd \-d alsa \-P hw:0,0 \-C hw:0,2\fR
 .PP
 Run \fBjackd\fR in playback-only mode using the ALSA hw:0,0 device. 
 .IP 
 Run \fBjackd\fR in playback\-only mode using the ALSA hw:0,0 device. 
 .IP
 \fBjackd \-d alsa \-P hw:0,0\fR
 .SH ENVIRONMENT
 .SH "ENVIRONMENT"
 .br
 JACK is evolving a mechanism for automatically starting the server
 when needed.  Any client started without a running JACK server will
 attempt to start one itself using the command line found in the first
 line of \fB$HOME/.jackdrc\fR if it exists, or \fB/etc/jackdrc\fR if it
 does not.  If neither file exists, a built-in default command will be
 used, including the \fB-T\fR flag, which causes the server to shut
 does not.  If neither file exists, a built\-in default command will be
 used, including the \fB\-T\fR flag, which causes the server to shut
 down when all clients have exited.

 As a transition, this only happens when \fB$JACK_START_SERVER\fR is
@@ -241,18 +362,31 @@ will become normal behavior.  In either case, defining
 \fB$JACK_NO_START_SERVER\fR disables this feature.

 To change where JACK looks for the backend drivers, set \fB$JACK_DRIVER_DIR\fR.
 .SH SEE ALSO:
 .SH "SEE ALSO:"
 .PP
 .I http://jackit.sourceforge.net
 .br
 The official JACK website with news, docs and a list of JACK clients.
 .PP
 .I http://lists.sourceforge.net/mailman/listinfo/jackit\-devel
 .br
 The JACK developers' mailing list.  Subscribe, to take part in
 development of JACK or JACK clients.  User questions are also welcome,
 there is currently no user-specific mailing list.
 .PP
 .I http://www.jackosx.com/
 .br
 Tools specific to the Mac OS X version of JACK.
 .PP
 .I http://www.alsa\-project.org
 .br
 <\fBjackit-devel@lists.sourceforge.net\fR>
 .br 
 <\fBhttp://www.alsa-project.org\fR>
 .SH BUGS
 The Advanced Linux Sound Architecture.
 .SH "BUGS"
 Please report bugs to
 .br
 <\fBhttp://jackit.sourceforge.net/mantis/main_page.php\fR>
 .SH AUTHORS
 .I http://jackit.sourceforge.net/mantis/main_page.php
 .SH "AUTHORS"
 Paul Davis and others.
 .PP
 Manpage originally written by Stefan Schwandter
 <e9925373@student.tuwien.ac.at>, later adapted by Jack O'Quin
 <joq@joq.us>.
 Manpage written by Stefan Schwandter, Jack O'Quin and Alexandre
 Prokoudine.