Move JackGnuPlotMonitor's implementation to JackTools.h
[jack2.git] / man / jackd.0
blobf04ecbcc99cb3e13732448d07081e8edb6d1b835
1 .TH "JACKD" "1" "!VERSION!" "!DATE!" ""
2 .SH "NAME"
3 jackd \- JACK Audio Connection Kit sound server
4 .SH "SYNOPSIS"
5 \fBjackd\fR [\fIoptions\fR] \fB\-d\fI backend \fR 
6 [\fIbackend\-parameters\fR]
7 .br
8 \fBjackd \-\-help\fR
9 .SH "DESCRIPTION"
10 \fBjackd\fR is the JACK audio server daemon, a low\-latency audio
11 server.  Originally written for the
12 GNU/Linux operating system, it also supports Mac OS X and various Unix
13 platforms.  JACK can connect a number of different client applications
14 to an audio device and also to each other.  Most clients are external,
15 running in their own processes as normal applications.  JACK also
16 supports internal clients, which run within the \fBjackd\fR process
17 using a loadable "plugin" interface.
19 JACK differs from other audio servers in being designed from the
20 ground up for professional audio work.  It focuses on two key areas:
21 synchronous execution of all clients, and low latency operation.
23 For the latest JACK information, please consult the web site,
24 <\fBhttp://www.jackaudio.org\fR>.
25 .SH "OPTIONS"
26 .TP
27 \fB\-d, \-\-driver \fIbackend\fR [\fIbackend\-parameters\fR ]
28 .br
29 Select the audio interface backend.  The current list of supported
30 backends is: \fBalsa\fR, \fBcoreaudio\fR, \fBdummy\fR, \fBfreebob\fR,
31 \fBoss\fR \fBsun\fR and \fBportaudio\fR.  They are not all available
32 on all platforms.  All \fIbackend\-parameters\fR are optional.
34 .TP
35 \fB\-h, \-\-help\fR
36 .br
37 Print a brief usage message describing the main \fBjackd\fR options.
38 These do not include \fIbackend\-parameters\fR, which are listed using
39 the \fB\-\-help\fR option for each specific backend.  Examples below
40 show how to list them.
41 .TP
42 \fB\-m, \-\-no\-mlock\fR
43 Do not attempt to lock memory, even if \fB\-\-realtime\fR.
44 .TP
45 \fB\-n, \-\-name\fR \fIserver\-name\fR
46 Name this \fBjackd\fR instance \fIserver\-name\fR.  If unspecified,
47 this name comes from the \fB$JACK_DEFAULT_SERVER\fR environment
48 variable.  It will be "default" if that is not defined.
49 .TP
50 \fB\-p, \-\-port\-max \fI n\fR
51 Set the maximum number of ports the JACK server can manage.  
52 The default value is 256.
53 .TP
54 \fB\-\-replace-registry\fR 
55 .br
56 Remove the shared memory registry used by all JACK server instances
57 before startup. This should rarely be used, and is intended only
58 for occasions when the structure of this registry changes in ways
59 that are incompatible across JACK versions (which is rare).
60 .TP
61 \fB\-R, \-\-realtime\fR 
62 .br
63 Use realtime scheduling (default = true). This is needed for reliable low\-latency
64 performance.  On many systems, it requires \fBjackd\fR to run with
65 special scheduler and memory allocation privileges, which may be
66 obtained in several ways. 
67 .TP
68 \fB\-r, \-\-no-realtime\fR
69 .br
70 Do not use realtime scheduling. 
71 .TP
72 \fB\-P, \-\-realtime\-priority \fIint\fR
73 When running \fB\-\-realtime\fR, set the scheduler priority to
74 \fIint\fR.
75 .TP
76 \fB\-\-silent\fR
77 Silence any output during operation.
78 .TP
79 \fB\-T, \-\-temporary\fR
80 Exit once all clients have closed their connections.
81 .TP
82 \fB\-t, \-\-timeout \fIint\fR
83 .br
84 Set client timeout limit in milliseconds.  The default is 500 msec.
85 In realtime mode the client timeout must be smaller than the watchdog timeout (5000 msec).
86 .TP
87 \fB\-Z, \-\-nozombies\fR
88 .br
89 Prevent JACK from ever kicking out clients because they were too slow.
90 This cancels the effect any specified timeout value, but JACK and its clients are
91 still subject to the supervision of the watchdog thread or its equivalent.
92 .TP
93 \fB\-u, \-\-unlock\fR
94 .br
95 Unlock libraries GTK+, QT, FLTK, Wine.
96 .TP
97 \fB\-v, \-\-verbose\fR
98 Give verbose output.
99 .TP
100 \fB\-c, \-\-clocksource\fR (\fI c(ycle)\fR | \fI h(pet) \fR | \fI s(ystem) \fR)
101 Select a specific wall clock (Cycle Counter, HPET timer, System timer).
103 \fB\-V, \-\-version\fR
104 Print the current JACK version number and exit.
105 .SS ALSA BACKEND OPTIONS
107 \fB\-C, \-\-capture\fR [ \fIname\fR ]
108 Provide only capture ports, unless combined with \-D or \-P.  Parameterally set 
109 capture device name.
111 \fB\-d, \-\-device \fIname\fR
113 The ALSA pcm device \fIname\fR to use.  If none is specified, JACK will
114 use "hw:0", the first hardware card defined in \fB/etc/modules.conf\fR.
116 \fB\-z, \-\-dither [rectangular,triangular,shaped,none]
117 Set dithering mode.  If \fBnone\fR or unspecified, dithering is off.
118 Only the first letter of the mode name is required.
120 \fB\-D, \-\-duplex\fR
121 Provide both capture and playback ports.  Defaults to on unless only one 
122 of \-P or \-C is specified.
124 \fB\-h, \-\-help\fR Print a brief usage message describing only the
125 \fBalsa\fR backend parameters.
127 \fB\-M, \-\-hwmeter\fR
129 Enable hardware metering for devices that support it.  Otherwise, use
130 software metering.
132 \fB\-H, \-\-hwmon\fR
134 Enable hardware monitoring of capture ports.  This is a method for
135 obtaining "zero latency" monitoring of audio input.  It requires
136 support in hardware and from the underlying ALSA device driver.
138 When enabled, requests to monitor capture ports will be satisfied by
139 creating a direct signal path between audio interface input and output
140 connectors, with no processing by the host computer at all.  This
141 offers the lowest possible latency for the monitored signal.
143 Presently (March 2003), only the RME Hammerfall series and cards based
144 on the ICE1712 chipset (M\-Audio Delta series, Terratec, and others)
145 support \fB\-\-hwmon\fR.  In the future, some consumer cards may also
146 be supported by modifying their mixer settings.
148 Without \fB\-\-hwmon\fR, port monitoring requires JACK to read audio
149 into system memory, then copy it back out to the hardware again,
150 imposing the basic JACK system latency determined by the
151 \fB\-\-period\fR and \fB\-\-nperiods\fR parameters.
153 \fB\-i, \-\-inchannels \fIint\fR
155 Number of capture channels.  Default is maximum supported by hardware.
157 \fB\-n, \-\-nperiods \fIint\fR
159 Specify the number of periods of playback latency.  In seconds, this
160 corresponds to \fB\-\-nperiods\fR times \fB\-\-period\fR divided by
161 \fB\-\-rate\fR.  The default is 2, the minimum allowable.  For most
162 devices, there is no need for any other value with the
163 \fB\-\-realtime\fR option.  Without realtime privileges or with boards
164 providing unreliable interrupts (like ymfpci), a larger value may
165 yield fewer xruns.  This can also help if the system is not tuned for
166 reliable realtime scheduling.
168 For most ALSA devices, the hardware buffer has exactly
169 \fB\-\-period\fR times \fB\-\-nperiods\fR frames.  Some devices demand
170 a larger buffer.  If so, JACK will use the smallest possible buffer
171 containing at least \fB\-\-nperiods\fR, but the playback latency does
172 not increase.
174 For USB audio devices it is recommended to use \fB\-n 3\fR. Firewire
175 devices supported by FFADO (formerly Freebob) are configured with
176 \fB\-n 3\fR by default.
178 \fB\-o, \-\-outchannels \fIint\fR
180 Number of playback channels.  Default is maximum supported by hardware.
182 \fB\-P, \-\-playback\fR [ \fIname\fR ]
183 Provide only playback ports, unless combined with \-D or \-C.  Optionally set 
184 playback device name.
186 \fB\-p, \-\-period \fIint\fR
188 Specify the number of frames between JACK \fBprocess()\fR calls.  This
189 value must be a power of 2, and the default is 1024.  If you need low 
190 latency, set \fB\-p\fR as low as you can go without seeing xruns.  A larger 
191 period size yields higher latency, but makes xruns less likely.  The JACK 
192 capture latency in seconds is \fB\-\-period\fR divided by \fB\-\-rate\fR.
194 \fB\-r, \-\-rate \fIint\fR
195 Specify the sample rate.  The default is 48000.
197 \fB\-S, \-\-shorts
199 Try to configure card for 16\-bit samples first, only trying 32\-bits if
200 unsuccessful.  Default is to prefer 32\-bit samples.
202 \fB\-s, \-\-softmode\fR 
204 Ignore xruns reported by the ALSA driver.  This makes JACK less likely
205 to disconnect unresponsive ports when running without \fB\-\-realtime\fR.
207 \fB\-X, \-\-midi \fR[\fIseq\fR|\fIraw\fR]
209 Specify which ALSA MIDI system to provide access to. Using \fBraw\fR
210 will provide a set of JACK MIDI ports that correspond to each raw ALSA
211 device on the machine. Using \fBseq\fR will provide a set of JACK MIDI
212 ports that correspond to each ALSA "sequencer" client (which includes
213 each hardware MIDI port on the machine). \fBraw\fR provides slightly
214 better performance but does not permit JACK MIDI communication with
215 software written to use the ALSA "sequencer" API.
216 .SS COREAUDIO BACKEND PARAMETERS
218 \fB\-c \-\-channels\fR
219 Maximum number of channels (default: 2)
221 \fB\-i \-\-inchannels\fR
222 Maximum number of input channels (default: 2)
224 \fB\-o \-\-outchannels\fR
225 Maximum number of output channels (default: 2)
227 \fB\-C \-\-capture\fR
228 Whether or not to capture (default: true)
230 \fB\-P \-\-playback\fR
231 Whether or not to playback (default: true)
233 \fB\-D \-\-monitor\fR
234 Provide monitor ports for the output (default: false)
236 \fB\-D \-\-duplex\fR
237 Capture and playback (default: true)
239 \fB\-r \-\-rate\fR
240 Sample rate (default: 44100)
242 \fB\-p \-\-period\fR
243 Frames per period (default: 128). Must be a power of 2.
245 \fB\-d \-\-device\fR
246 CoreAudio device name (default: none)
248 \fB\-I \-\-input\-latency\fR
249 Extra input latency (frames) (default: 0)
251 \fB\-O \-\-output\-latency\fR
252 Extra output latency (frames) (default: 0)
254 \fB\-l \-\-list\-devices \fR
255 Display available CoreAudio devices (default: false)
257 \fB\-H \-\-hog \fR
258 Take exclusive access of the audio device (default: false)
260 \fB\-L \-\-async\-latency  \fR
261 Extra output latency in asynchronous mode (percent) (default: 100)
263 \fB\-G \-\-grain  \fR
264 Computation grain in RT thread (percent) (default: 100)
266 \fB\-s \-\-clock\-drift  \fR
267 Whether to compensate clock drift in dynamically created aggregate device (default: false)
268 .SS DUMMY BACKEND PARAMETERS
270 \fB\-C, \-\-capture \fIint\fR
271 Specify number of capture ports. The default value is 2.
273 \fB\-P, \-\-playback \fIint\fR
274 Specify number of playback ports. The default value is 2.
276 \fB\-r, \-\-rate \fIint\fR
277 Specify sample rate. The default value is 48000.
279 \fB\-p, \-\-period \fIint\fR
280 Specify the number of frames between JACK \fBprocess()\fR calls.  This
281 value must be a power of 2, and the default is 1024.  If you need low 
282 latency, set \fB\-p\fR as low as you can go without seeing xruns.  A larger 
283 period size yields higher latency, but makes xruns less likely.  The JACK 
284 capture latency in seconds is \fB\-\-period\fR divided by \fB\-\-rate\fR.
286 \fB\-w, \-\-wait \fIint\fR 
287 Specify number of usecs to wait between engine processes. 
288 The default value is 21333.
291 .SS NETONE BACKEND PARAMETERS
294  \fB\-i, \-\-audio\-ins \fIint\fR
295 Number of capture channels (default: 2)
297  \fB\-o, \-\-audio\-outs \fIint\fR
298 Number of playback channels (default: 2)
300  \fB\-I, \-\-midi\-ins \fIint\fR
301 Number of midi capture channels (default: 1)
302 .TP 
303 \fB\-O, \-\-midi\-outs \fIint\fR
304 Number of midi playback channels (default: 1)
306  \fB\-r, \-\-rate \fIint\fR
307 Sample rate (default: 48000)
308 .TP 
309 \fB\-p, \-\-period \fIint\fR
310 Frames per period (default: 1024)
311 .TP 
312 \fB\-n, \-\-num\-periods \fIint\fR
313 Network latency setting in no. of periods (default: 5)
314 .TP 
315 \fB\-l, \-\-listen\-port \fIint\fR
316 The socket port we are listening on for sync packets (default: 3000)
317 .TP 
318 \fB\-f, \-\-factor \fIint\fR
319 Factor for sample rate reduction (default: 1)
320 .TP 
321 \fB\-u, \-\-upstream\-factor \fIint\fR
322 Factor for sample rate reduction on the upstream (default: 0)
323 .TP 
324 \fB\-c, \-\-celt \fIint\fR
325 sets celt encoding and number of kbits per channel (default: 0)
326 .TP 
327 \fB\-b, \-\-bit\-depth \fIint\fR
328 Sample bit\-depth (0 for float, 8 for 8bit and 16 for 16bit) (default: 0)
329 .TP 
330 \fB\-t, \-\-transport\-sync \fIint\fR
331 Whether to slave the transport to the master transport (default: true)
332 .TP 
333 \fB\-a, \-\-autoconf \fIint\fR
334 Whether to use Autoconfig, or just start. (default: true)
335 .TP 
336 \fB\-R, \-\-redundancy \fIint\fR
337 Send packets N times (default: 1)
338 .TP 
339 \fB\-e, \-\-native\-endian \fIint\fR
340 Dont convert samples to network byte order. (default: false)
341 .TP 
342 \fB\-J, \-\-jitterval \fIint\fR
343 attempted jitterbuffer microseconds on master (default: 0)
344 .TP 
345 \fB\-D, \-\-always\-deadline \fIint\fR
346 always use deadline (default: false)
349 .SS OSS BACKEND PARAMETERS
351 \fB\-r, \-\-rate \fIint\fR
352 Specify the sample rate.  The default is 48000.
354 \fB\-p, \-\-period \fIint\fR
355 Specify the number of frames between JACK \fBprocess()\fR calls.  This
356 value must be a power of 2, and the default is 1024.  If you need low 
357 latency, set \fB\-p\fR as low as you can go without seeing xruns.  A larger 
358 period size yields higher latency, but makes xruns less likely.  The JACK 
359 capture latency in seconds is \fB\-\-period\fR divided by \fB\-\-rate\fR.
361 \fB\-n, \-\-nperiods \fIint\fR
362 Specify the number of periods in the hardware buffer.  The default is
363 2.  The period size (\fB\-p\fR) times \fB\-\-nperiods\fR times four is
364 the JACK buffer size in bytes.  The JACK output latency in seconds is
365 \fB\-\-nperiods\fR times \fB\-\-period\fR divided by \fB\-\-rate\fR.
367 \fB\-w, \-\-wordlength \fIint\fR
368 Specify the sample size in bits. The default is 16.
370 \fB\-i, \-\-inchannels \fIint\fR
371 Specify how many channels to capture (default: 2)
373 \fB\-o, \-\-outchannels \fIint\fR
374 Specify number of playback channels (default: 2)
376 \fB\-C, \-\-capture \fIdevice_file\fR
377 Specify input device for capture (default: /dev/dsp)
379 \fB\-P, \-\-playback \fIdevice_file\fR
380 Specify output device for playback (default: /dev/dsp)
382 \fB\-b, \-\-ignorehwbuf \fIboolean\fR
383 Specify, whether to ignore hardware period size (default: false)
384 .SS SUN BACKEND PARAMETERS
386 \fB\-r, \-\-rate \fIint\fR
387 Specify the sample rate.  The default is 48000.
389 \fB\-p, \-\-period \fIint\fR
390 Specify the number of frames between JACK \fBprocess()\fR calls.  This
391 value must be a power of 2, and the default is 1024.  If you need low 
392 latency, set \fB\-p\fR as low as you can go without seeing xruns.  A larger 
393 period size yields higher latency, but makes xruns less likely.  The JACK 
394 capture latency in seconds is \fB\-\-period\fR divided by \fB\-\-rate\fR.
396 \fB\-n, \-\-nperiods \fIint\fR
397 Specify the number of periods in the hardware buffer.  The default is
398 2.  The period size (\fB\-p\fR) times \fB\-\-nperiods\fR times four
399 (assuming 2 channels 16-bit samples) is the JACK buffer size in bytes.
400 The JACK output latency in seconds is \fB\-\-nperiods\fR times
401 \fB\-\-period\fR divided by \fB\-\-rate\fR.
403 \fB\-w, \-\-wordlength \fIint\fR
404 Specify the sample size in bits. The default is 16.
406 \fB\-i, \-\-inchannels \fIint\fR
407 Specify how many channels to capture (default: 2)
409 \fB\-o, \-\-outchannels \fIint\fR
410 Specify number of playback channels (default: 2)
412 \fB\-C, \-\-capture \fIdevice_file\fR
413 Specify input device for capture (default: /dev/audio)
415 \fB\-P, \-\-playback \fIdevice_file\fR
416 Specify output device for playback (default: /dev/audio)
418 \fB\-b, \-\-ignorehwbuf \fIboolean\fR
419 Specify, whether to ignore hardware period size (default: false)
420 .SS PORTAUDIO BACKEND PARAMETERS
422 \fB\-c \-\-channel\fR
423 Maximum number of channels (default: all available hardware channels)
425 \fB\-i \-\-channelin\fR
426 Maximum number of input channels (default: all available hardware channels)
428 \fB\-o \-\-channelout\fR
429 Maximum number of output channels (default: all available hardware channels)
431 \fB\-C \-\-capture\fR
432 Whether or not to capture (default: true)
434 \fB\-P \-\-playback\fR
435 Whether or not to playback (default: true)
437 \fB\-D \-\-duplex\fR
438 Capture and playback (default: true)
440 \fB\-r \-\-rate\fR
441 Sample rate (default: 48000)
443 \fB\-p \-\-period\fR
444 Frames per period (default: 1024). Must be a power of 2.
446 \fB\-n \-\-name\fR
447 Driver name (default: none)
449 \fB\-z \-\-dither\fR
450 Dithering mode (default: none)
451 .SH "EXAMPLES"
453 Print usage message for the parameters specific to each backend.
455 \fBjackd \-d alsa \-\-help\fR
457 \fBjackd \-d coreaudio \-\-help\fR
459 \fBjackd \-d net \-\-help\fR
461 \fBjackd \-d dummy \-\-help\fR
463 \fBjackd \-d firewire \-\-help\fR
465 \fBjackd \-d freebob \-\-help\fR
467 \fBjackd \-d oss \-\-help\fR
469 \fBjackd \-d sun \-\-help\fR
471 \fBjackd \-d portaudio \-\-help\fR
473 Run the JACK daemon with realtime priority using the first ALSA
474 hardware card defined in \fB/etc/modules.conf\fR.
476 \fBjackstart \-\-realtime \-\-driver=alsa\fR
478 Run the JACK daemon with low latency giving verbose output, which can
479 be helpful for trouble\-shooting system latency problems.  A
480 reasonably well\-tuned system with a good sound card and a
481 low\-latency kernel can handle these values reliably.  Some can do
482 better.  If you get xrun messages, try a larger buffer.  Tuning a
483 system for low latency can be challenging.  The JACK FAQ,
484 .I http://jackit.sourceforge.net/docs/faq.php\fR
485 has some useful suggestions.
487 \fBjackstart \-Rv \-d alsa \-p 128 \-n 2 \-r 44100\fR
489 Run \fBjackd\fR with realtime priority using the "sblive" ALSA device
490 defined in ~/.asoundrc.  Apply shaped dithering to playback audio.
492 \fBjackd \-R \-d alsa \-d sblive \-\-dither=shaped\fR
494 Run \fBjackd\fR with no special privileges using the second ALSA
495 hardware card defined in \fB/etc/modules.conf\fR.  Any xruns reported
496 by the ALSA backend will be ignored.  The larger buffer helps reduce
497 data loss.  Rectangular dithering will be used for playback.
499 \fBjackd \-d alsa \-d hw:1 \-p2048 \-n3 \-\-softmode \-zr\fR
501 Run \fBjackd\fR in full\-duplex mode using the ALSA hw:0,0 device for 
502 playback and the hw:0,2 device for capture.
504 \fBjackd \-d alsa \-P hw:0,0 \-C hw:0,2\fR
506 Run \fBjackd\fR in playback\-only mode using the ALSA hw:0,0 device. 
508 \fBjackd \-d alsa \-P hw:0,0\fR
509 .SH "ENVIRONMENT"
511 JACK is evolving a mechanism for automatically starting the server
512 when needed.  Any client started without a running JACK server will
513 attempt to start one itself using the command line found in the first
514 line of \fB$HOME/.jackdrc\fR if it exists, or \fB/etc/jackdrc\fR if it
515 does not.  If neither file exists, a built\-in default command will be
516 used, including the \fB\-T\fR flag, which causes the server to shut
517 down when all clients have exited.
519 As a transition, this only happens when \fB$JACK_START_SERVER\fR is
520 defined in the environment of the calling process.  In the future this
521 will become normal behavior.  In either case, defining
522 \fB$JACK_NO_START_SERVER\fR disables this feature.
524 To change where JACK looks for the backend drivers, set
525 \fB$JACK_DRIVER_DIR\fR.
527 \fB$JACK_DEFAULT_SERVER\fR specifies the default server name.  If not
528 defined, the string "default" is used.  If set in their respective
529 environments, this affects \fBjackd\fR unless its \fB\-\-name\fR
530 parameter is set, and all JACK clients unless they pass an explicit
531 name to \fBjack_client_open()\fR.
533 .SH "SEE ALSO:"
535 .I http://www.jackaudio.org
537 The official JACK website with news, docs and a list of JACK clients.
539 .I http://jackaudio.org/email
541 The JACK developers' mailing list.  Subscribe, to take part in
542 development of JACK or JACK clients.  User questions are also welcome,
543 there is no user-specific mailing list.
545 .I http://www.jackosx.com/
547 Tools specific to the Mac OS X version of JACK.
549 .I http://www.alsa\-project.org
551 The Advanced Linux Sound Architecture.
552 .SH "BUGS"
553 Please report bugs to
555 .I http://trac.jackaudio.org/
556 .SH "AUTHORS"
557 Architect and original implementor: Paul Davis
559 Original design Group: Paul Davis, David Olofson, Kai Vehmanen, Benno Sennoner,
560 Richard Guenther, and other members of the Linux Audio Developers group.
562 Programming: Paul Davis, Jack O'Quin, Taybin Rutkin, Stephane Letz, Fernando
563 Pablo Lopez-Lezcano, Steve Harris, Jeremy Hall, Andy Wingo, Kai
564 Vehmanen, Melanie Thielker, Jussi Laako, Tilman Linneweh, Johnny
565 Petrantoni, Torben Hohn.
567 Manpage written by Stefan Schwandter, Jack O'Quin and Alexandre
568 Prokoudine.