more consistent naming of MIDI ports (vs. audio); drop use of ALSA seq client ID...
[jack.git] / jackd / jackd.1.in
blob857ffa7da6e92b1f7f6d2c14417eb8d333cdcf6a
1 .TH "JACKD" "1" "@VERSION@" "April 2006" ""
2 .SH "NAME"
3 jackd, jackstart \- JACK Audio Connection Kit sound server
4 .SH "SYNOPSYS"
5 \fBjackd\fR [\fIoptions\fR] \fB\-d\fI backend \fR 
6 [\fIbackend\-parameters\fR]
7 .br
8 \fBjackstart\fR [\fIoptions\fR] \fB\-d\fI backend \fR 
9 [\fIbackend\-parameters\fR]
10 .br
11 \fBjackd \-\-help\fR
12 .SH "DESCRIPTION"
13 \fBjackd\fR invokes the JACK audio server daemon.  The \fBjackstart\fR
14 command provides JACK's built\-in support for Linux 2.4.x kernels with
15 the realtime capabilities patch.  Use \fBjackd\fR for Linux 2.6.x and
16 all other systems.  All parameters are the same.
18 JACK is a low\-latency audio server.  Originally written for the
19 GNU/Linux operating system, it also supports Mac OS X and various Unix
20 platforms.  JACK can connect a number of different client applications
21 to an audio device and also to each other.  Most clients are external,
22 running in their own processes as normal applications.  JACK also
23 supports internal clients, which run within the \fBjackd\fR process
24 using a loadable "plugin" interface.
26 JACK differs from other audio servers in being designed from the
27 ground up for professional audio work.  It focuses on two key areas:
28 synchronous execution of all clients, and low latency operation.
30 For the latest JACK information, please consult the web site,
31 <\fBhttp://www.jackaudio.org\fR>.
32 .SH "OPTIONS"
33 .TP
34 \fB\-d, \-\-driver \fIbackend\fR [\fIbackend\-parameters\fR ]
35 .br
36 Select the audio interface backend.  The current list of supported
37 backends is: \fBalsa\fR, \fBcoreaudio\fR, \fBdummy\fR, \fBfreebob\fR,
38 \fBoss\fR \fBsun\fR and \fBportaudio\fR.  They are not all available
39 on all platforms.  All \fIbackend\-parameters\fR are optional.
41 .TP
42 \fB\-h, \-\-help\fR
43 .br
44 Print a brief usage message describing the main \fBjackd\fR options.
45 These do not include \fIbackend\-parameters\fR, which are listed using
46 the \fB\-\-help\fR option for each specific backend.  Examples below
47 show how to list them.
48 .TP
49 \fB\-m, \-\-no\-mlock\fR
50 Do not attempt to lock memory, even if \fB\-\-realtime\fR.
51 .TP
52 \fB\-n, \-\-name\fR \fIserver\-name\fR
53 Name this \fBjackd\fR instance \fIserver\-name\fR.  If unspecified,
54 this name comes from the \fB$JACK_DEFAULT_SERVER\fR environment
55 variable.  It will be "default" if that is not defined.
56 .TP
57 \fB\-p, \-\-port\-max \fI n\fR
58 Set the maximum number of ports the JACK server can manage.  
59 The default value is 256.
60 .TP
61 \fB\-r, \-\-replace-registry\fR 
62 .br
63 Remove the shared memory registry used by all JACK server instances
64 before startup. This should rarely be used, and is intended only
65 for occasions when the structure of this registry changes in ways
66 that are incompatible across JACK versions (which is rare).
67 .TP
68 \fB\-R, \-\-realtime\fR 
69 .br
70 Use realtime scheduling.  This is needed for reliable low\-latency
71 performance.  On most systems, it requires \fBjackd\fR to run with
72 special scheduler and memory allocation privileges, which may be
73 obtained in several ways.  The simplest, and least-secure method is to
74 run \fBjackd\fR with root privileges.  This means that all JACK
75 clients must also run as root.  With a Linux 2.6 kernel, ordinary
76 users can run \fBjackd\fR and its clients using options of the
77 realtime LSM.  Linux 2.4 kernels need "POSIX draft capabilities"
78 enabled (see the \fB<linux/capability.h>\fR include file).  Using that
79 method, ordinary users who invoke the daemon using \fBjackstart\fR,
80 can later launch JACK clients without running them as root.  See
81 .I http://jackit.sourceforge.net/docs/faq.php#a52 
82 for more information.
83 .TP
84 \fB\-P, \-\-realtime\-priority \fIint\fR
85 When running \fB\-\-realtime\fR, set the scheduler priority to
86 \fIint\fR.
87 .TP
88 \fB\-\-silent\fR
89 Silence any output during operation.
90 .TP
91 \fB\-T, \-\-temporary\fR
92 Exit once all clients have closed their connections.
93 .TP
94 \fB\-t, \-\-timeout \fIint\fR
95 .br
96 Set client timeout limit in milliseconds.  The default is 500 msec.
97 In realtime mode the client timeout must be smaller than the watchdog timeout (5000 msec).
98 .TP
99 \fB\-Z, \-\-nozombies\fR
101 Prevent JACK from ever kicking out clients because they were too slow.
102 This cancels the effect any specified timeout value, but JACK and its clients are
103 still subject to the supervision of the watchdog thread or its equivalent.
105 \fB\-u, \-\-unlock\fR
107 Unlock libraries GTK+, QT, FLTK, Wine.
109 \fB\-v, \-\-verbose\fR
110 Give verbose output.
112 \fB\-c, \-\-clocksource\fR (\fI c(ycle)\fR | \fI h(pet) \fR | \fI s(ystem) \fR)
113 Select a specific wall clock (Cycle Counter, HPET timer, System timer).
115 \fB\-V, \-\-version\fR
116 Print the current JACK version number and exit.
117 .SS ALSA BACKEND OPTIONS
119 \fB\-C, \-\-capture\fR [ \fIname\fR ]
120 Provide only capture ports, unless combined with \-D or \-P.  Parameterally set 
121 capture device name.
123 \fB\-d, \-\-device \fIname\fR
125 The ALSA pcm device \fIname\fR to use.  If none is specified, JACK will
126 use "hw:0", the first hardware card defined in \fB/etc/modules.conf\fR.
128 \fB\-z, \-\-dither [rectangular,triangular,shaped,none]
129 Set dithering mode.  If \fBnone\fR or unspecified, dithering is off.
130 Only the first letter of the mode name is required.
132 \fB\-D, \-\-duplex\fR
133 Provide both capture and playback ports.  Defaults to on unless only one 
134 of \-P or \-C is specified.
136 \fB\-h, \-\-help\fR Print a brief usage message describing only the
137 \fBalsa\fR backend parameters.
139 \fB\-M, \-\-hwmeter\fR
141 Enable hardware metering for devices that support it.  Otherwise, use
142 software metering.
144 \fB\-H, \-\-hwmon\fR
146 Enable hardware monitoring of capture ports.  This is a method for
147 obtaining "zero latency" monitoring of audio input.  It requires
148 support in hardware and from the underlying ALSA device driver.
150 When enabled, requests to monitor capture ports will be satisfied by
151 creating a direct signal path between audio interface input and output
152 connectors, with no processing by the host computer at all.  This
153 offers the lowest possible latency for the monitored signal.
155 Presently (March 2003), only the RME Hammerfall series and cards based
156 on the ICE1712 chipset (M\-Audio Delta series, Terratec, and others)
157 support \fB\-\-hwmon\fR.  In the future, some consumer cards may also
158 be supported by modifying their mixer settings.
160 Without \fB\-\-hwmon\fR, port monitoring requires JACK to read audio
161 into system memory, then copy it back out to the hardware again,
162 imposing the basic JACK system latency determined by the
163 \fB\-\-period\fR and \fB\-\-nperiods\fR parameters.
165 \fB\-i, \-\-inchannels \fIint\fR
167 Number of capture channels.  Default is maximum supported by hardware.
169 \fB\-n, \-\-nperiods \fIint\fR
171 Specify the number of periods of playback latency.  In seconds, this
172 corresponds to \fB\-\-nperiods\fR times \fB\-\-period\fR divided by
173 \fB\-\-rate\fR.  The default is 2, the minimum allowable.  For most
174 devices, there is no need for any other value with the
175 \fB\-\-realtime\fR option.  Without realtime privileges or with boards
176 providing unreliable interrupts (like ymfpci), a larger value may
177 yield fewer xruns.  This can also help if the system is not tuned for
178 reliable realtime scheduling.
180 For most ALSA devices, the hardware buffer has exactly
181 \fB\-\-period\fR times \fB\-\-nperiods\fR frames.  Some devices demand
182 a larger buffer.  If so, JACK will use the smallest possible buffer
183 containing at least \fB\-\-nperiods\fR, but the playback latency does
184 not increase.
186 For USB audio devices it is recommended to use \fB\-n 3\fR. Firewire
187 devices supported by FFADO (formerly Freebob) are configured with
188 \fB\-n 3\fR by default.
190 \fB\-o, \-\-outchannels \fIint\fR
192 Number of playback channels.  Default is maximum supported by hardware.
194 \fB\-P, \-\-playback\fR [ \fIname\fR ]
195 Provide only playback ports, unless combined with \-D or \-C.  Optionally set 
196 playback device name.
198 \fB\-p, \-\-period \fIint\fR
200 Specify the number of frames between JACK \fBprocess()\fR calls.  This
201 value must be a power of 2, and the default is 1024.  If you need low 
202 latency, set \fB\-p\fR as low as you can go without seeing xruns.  A larger 
203 period size yields higher latency, but makes xruns less likely.  The JACK 
204 capture latency in seconds is \fB\-\-period\fR divided by \fB\-\-rate\fR.
206 \fB\-r, \-\-rate \fIint\fR
207 Specify the sample rate.  The default is 48000.
209 \fB\-S, \-\-shorts
211 Try to configure card for 16\-bit samples first, only trying 32\-bits if
212 unsuccessful.  Default is to prefer 32\-bit samples.
214 \fB\-s, \-\-softmode\fR 
216 Ignore xruns reported by the ALSA driver.  This makes JACK less likely
217 to disconnect unresponsive ports when running without \fB\-\-realtime\fR.
218 .SS COREAUDIO BACKEND PARAMETERS
220 \fB\-c \-\-channel\fR
221 Maximum number of channels (default: 2)
223 \fB\-i \-\-channelin\fR
224 Maximum number of input channels (default: 2)
226 \fB\-o \-\-channelout\fR
227 Maximum number of output channels (default: 2)
229 \fB\-C \-\-capture\fR
230 Whether or not to capture (default: true)
232 \fB\-P \-\-playback\fR
233 Whether or not to playback (default: true)
235 \fB\-D \-\-duplex\fR
236 Capture and playback (default: true)
238 \fB\-r \-\-rate\fR
239 Sample rate (default: 44100)
241 \fB\-p \-\-period\fR
242 Frames per period (default: 128). Must be a power of 2.
244 \fB\-n \-\-name\fR
245 Driver name (default: none)
247 \fB\-I \-\-id\fR
248 Audio Device ID (default: 0)
249 .SS DUMMY BACKEND PARAMETERS
251 \fB\-C, \-\-capture \fIint\fR
252 Specify number of capture ports. The default value is 2.
254 \fB\-P, \-\-playback \fIint\fR
255 Specify number of playback ports. The default value is 2.
257 \fB\-r, \-\-rate \fIint\fR
258 Specify sample rate. The default value is 48000.
260 \fB\-p, \-\-period \fIint\fR
261 Specify the number of frames between JACK \fBprocess()\fR calls.  This
262 value must be a power of 2, and the default is 1024.  If you need low 
263 latency, set \fB\-p\fR as low as you can go without seeing xruns.  A larger 
264 period size yields higher latency, but makes xruns less likely.  The JACK 
265 capture latency in seconds is \fB\-\-period\fR divided by \fB\-\-rate\fR.
267 \fB\-w, \-\-wait \fIint\fR 
268 Specify number of usecs to wait between engine processes. 
269 The default value is 21333.
270 .SS OSS BACKEND PARAMETERS
272 \fB\-r, \-\-rate \fIint\fR
273 Specify the sample rate.  The default is 48000.
275 \fB\-p, \-\-period \fIint\fR
276 Specify the number of frames between JACK \fBprocess()\fR calls.  This
277 value must be a power of 2, and the default is 1024.  If you need low 
278 latency, set \fB\-p\fR as low as you can go without seeing xruns.  A larger 
279 period size yields higher latency, but makes xruns less likely.  The JACK 
280 capture latency in seconds is \fB\-\-period\fR divided by \fB\-\-rate\fR.
282 \fB\-n, \-\-nperiods \fIint\fR
283 Specify the number of periods in the hardware buffer.  The default is
284 2.  The period size (\fB\-p\fR) times \fB\-\-nperiods\fR times four is
285 the JACK buffer size in bytes.  The JACK output latency in seconds is
286 \fB\-\-nperiods\fR times \fB\-\-period\fR divided by \fB\-\-rate\fR.
288 \fB\-w, \-\-wordlength \fIint\fR
289 Specify the sample size in bits. The default is 16.
291 \fB\-i, \-\-inchannels \fIint\fR
292 Specify how many channels to capture (default: 2)
294 \fB\-o, \-\-outchannels \fIint\fR
295 Specify number of playback channels (default: 2)
297 \fB\-C, \-\-capture \fIdevice_file\fR
298 Specify input device for capture (default: /dev/dsp)
300 \fB\-P, \-\-playback \fIdevice_file\fR
301 Specify output device for playback (default: /dev/dsp)
303 \fB\-b, \-\-ignorehwbuf \fIboolean\fR
304 Specify, whether to ignore hardware period size (default: false)
305 .SS SUN BACKEND PARAMETERS
307 \fB\-r, \-\-rate \fIint\fR
308 Specify the sample rate.  The default is 48000.
310 \fB\-p, \-\-period \fIint\fR
311 Specify the number of frames between JACK \fBprocess()\fR calls.  This
312 value must be a power of 2, and the default is 1024.  If you need low 
313 latency, set \fB\-p\fR as low as you can go without seeing xruns.  A larger 
314 period size yields higher latency, but makes xruns less likely.  The JACK 
315 capture latency in seconds is \fB\-\-period\fR divided by \fB\-\-rate\fR.
317 \fB\-n, \-\-nperiods \fIint\fR
318 Specify the number of periods in the hardware buffer.  The default is
319 2.  The period size (\fB\-p\fR) times \fB\-\-nperiods\fR times four
320 (assuming 2 channels 16-bit samples) is the JACK buffer size in bytes.
321 The JACK output latency in seconds is \fB\-\-nperiods\fR times
322 \fB\-\-period\fR divided by \fB\-\-rate\fR.
324 \fB\-w, \-\-wordlength \fIint\fR
325 Specify the sample size in bits. The default is 16.
327 \fB\-i, \-\-inchannels \fIint\fR
328 Specify how many channels to capture (default: 2)
330 \fB\-o, \-\-outchannels \fIint\fR
331 Specify number of playback channels (default: 2)
333 \fB\-C, \-\-capture \fIdevice_file\fR
334 Specify input device for capture (default: /dev/audio)
336 \fB\-P, \-\-playback \fIdevice_file\fR
337 Specify output device for playback (default: /dev/audio)
339 \fB\-b, \-\-ignorehwbuf \fIboolean\fR
340 Specify, whether to ignore hardware period size (default: false)
341 .SS PORTAUDIO BACKEND PARAMETERS
343 \fB\-c \-\-channel\fR
344 Maximum number of channels (default: all available hardware channels)
346 \fB\-i \-\-channelin\fR
347 Maximum number of input channels (default: all available hardware channels)
349 \fB\-o \-\-channelout\fR
350 Maximum number of output channels (default: all available hardware channels)
352 \fB\-C \-\-capture\fR
353 Whether or not to capture (default: true)
355 \fB\-P \-\-playback\fR
356 Whether or not to playback (default: true)
358 \fB\-D \-\-duplex\fR
359 Capture and playback (default: true)
361 \fB\-r \-\-rate\fR
362 Sample rate (default: 48000)
364 \fB\-p \-\-period\fR
365 Frames per period (default: 1024). Must be a power of 2.
367 \fB\-n \-\-name\fR
368 Driver name (default: none)
370 \fB\-z \-\-dither\fR
371 Dithering mode (default: none)
372 .SH "EXAMPLES"
374 Print usage message for the parameters specific to each backend.
376 \fBjackd \-d alsa \-\-help\fR
378 \fBjackd \-d coreaudio \-\-help\fR
380 \fBjackd \-d dummy \-\-help\fR
382 \fBjackd \-d freebob \-\-help\fR
384 \fBjackd \-d oss \-\-help\fR
386 \fBjackd \-d sun \-\-help\fR
388 \fBjackd \-d portaudio \-\-help\fR
390 Run the JACK daemon with realtime priority using the first ALSA
391 hardware card defined in \fB/etc/modules.conf\fR.
393 \fBjackstart \-\-realtime \-\-driver=alsa\fR
395 Run the JACK daemon with low latency giving verbose output, which can
396 be helpful for trouble\-shooting system latency problems.  A
397 reasonably well\-tuned system with a good sound card and a
398 low\-latency kernel can handle these values reliably.  Some can do
399 better.  If you get xrun messages, try a larger buffer.  Tuning a
400 system for low latency can be challenging.  The JACK FAQ,
401 .I http://jackit.sourceforge.net/docs/faq.php\fR
402 has some useful suggestions.
404 \fBjackstart \-Rv \-d alsa \-p 128 \-n 2 \-r 44100\fR
406 Run \fBjackd\fR with realtime priority using the "sblive" ALSA device
407 defined in ~/.asoundrc.  Apply shaped dithering to playback audio.
409 \fBjackd \-R \-d alsa \-d sblive \-\-dither=shaped\fR
411 Run \fBjackd\fR with no special privileges using the second ALSA
412 hardware card defined in \fB/etc/modules.conf\fR.  Any xruns reported
413 by the ALSA backend will be ignored.  The larger buffer helps reduce
414 data loss.  Rectangular dithering will be used for playback.
416 \fBjackd \-d alsa \-d hw:1 \-p2048 \-n3 \-\-softmode \-zr\fR
418 Run \fBjackd\fR in full\-duplex mode using the ALSA hw:0,0 device for 
419 playback and the hw:0,2 device for capture.
421 \fBjackd \-d alsa \-P hw:0,0 \-C hw:0,2\fR
423 Run \fBjackd\fR in playback\-only mode using the ALSA hw:0,0 device. 
425 \fBjackd \-d alsa \-P hw:0,0\fR
426 .SH "ENVIRONMENT"
428 JACK is evolving a mechanism for automatically starting the server
429 when needed.  Any client started without a running JACK server will
430 attempt to start one itself using the command line found in the first
431 line of \fB$HOME/.jackdrc\fR if it exists, or \fB/etc/jackdrc\fR if it
432 does not.  If neither file exists, a built\-in default command will be
433 used, including the \fB\-T\fR flag, which causes the server to shut
434 down when all clients have exited.
436 As a transition, this only happens when \fB$JACK_START_SERVER\fR is
437 defined in the environment of the calling process.  In the future this
438 will become normal behavior.  In either case, defining
439 \fB$JACK_NO_START_SERVER\fR disables this feature.
441 To change where JACK looks for the backend drivers, set
442 \fB$JACK_DRIVER_DIR\fR.
444 \fB$JACK_DEFAULT_SERVER\fR specifies the default server name.  If not
445 defined, the string "default" is used.  If set in their respective
446 environments, this affects \fBjackd\fR unless its \fB\-\-name\fR
447 parameter is set, and all JACK clients unless they pass an explicit
448 name to \fBjack_client_open()\fR.
450 .SH "SEE ALSO:"
452 .I http://www.jackaudio.org
454 The official JACK website with news, docs and a list of JACK clients.
456 .I http://lists.sourceforge.net/mailman/listinfo/jackit\-devel
458 The JACK developers' mailing list.  Subscribe, to take part in
459 development of JACK or JACK clients.  User questions are also welcome,
460 there is no user-specific mailing list.
462 .I http://www.jackosx.com/
464 Tools specific to the Mac OS X version of JACK.
466 .I http://www.alsa\-project.org
468 The Advanced Linux Sound Architecture.
469 .SH "BUGS"
470 Please report bugs to
472 .I http://jackit.sourceforge.net/mantis/main_page.php
473 .SH "AUTHORS"
474 Architect and original implementor: Paul Davis
476 Original design Group: Paul Davis, David Olofson, Kai Vehmanen, Benno Sennoner,
477 Richard Guenther, and other members of the Linux Audio Developers group.
479 Programming: Paul Davis, Jack O'Quin, Taybin Rutkin, Stephane Letz, Fernando
480 Pablo Lopez-Lezcano, Steve Harris, Jeremy Hall, Andy Wingo, Kai
481 Vehmanen, Melanie Thielker, Jussi Laako, Tilman Linneweh, Johnny Petrantoni.
483 Manpage written by Stefan Schwandter, Jack O'Quin and Alexandre
484 Prokoudine.