diff --git a/jackd/jackd.1.in b/jackd/jackd.1.in index b1bcb5f..bbe64ad 100644 --- 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\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\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 -, later adapted by Jack O'Quin -. +Manpage written by Stefan Schwandter, Jack O'Quin and Alexandre +Prokoudine.