jackd/jackd.1.in

   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.
  17
  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.
  25
  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.
  29
  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.
  40
  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
 100 .br
 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.
 104 .TP
 105 \fB\-u, \-\-unlock\fR
 106 .br
 107 Unlock libraries GTK+, QT, FLTK, Wine.
 108 .TP
 109 \fB\-v, \-\-verbose\fR
 110 Give verbose output.
 111 .TP
 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).
 114 .TP
 115 \fB\-V, \-\-version\fR
 116 Print the current JACK version number and exit.
 117 .SS ALSA BACKEND OPTIONS
 118 .TP
 119 \fB\-C, \-\-capture\fR [ \fIname\fR ]
 120 Provide only capture ports, unless combined with \-D or \-P.  Parameterally set
 121 capture device name.
 122 .TP
 123 \fB\-d, \-\-device \fIname\fR
 124 .br
 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.
 127 .TP
 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.
 131 .TP
 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.
 135 .TP
 136 \fB\-h, \-\-help\fR Print a brief usage message describing only the
 137 \fBalsa\fR backend parameters.
 138 .TP
 139 \fB\-M, \-\-hwmeter\fR
 140 .br
 141 Enable hardware metering for devices that support it.  Otherwise, use
 142 software metering.
 143 .TP
 144 \fB\-H, \-\-hwmon\fR
 145 .br
 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.
 149
 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.
 154
 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.
 159
 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.
 164 .TP
 165 \fB\-i, \-\-inchannels \fIint\fR
 166 .br
 167 Number of capture channels.  Default is maximum supported by hardware.
 168 .TP
 169 \fB\-n, \-\-nperiods \fIint\fR
 170 .br
 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.
 179
 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.
 185
 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.
 189 .TP
 190 \fB\-o, \-\-outchannels \fIint\fR
 191 .br
 192 Number of playback channels.  Default is maximum supported by hardware.
 193 .TP
 194 \fB\-P, \-\-playback\fR [ \fIname\fR ]
 195 Provide only playback ports, unless combined with \-D or \-C.  Optionally set
 196 playback device name.
 197 .TP
 198 \fB\-p, \-\-period \fIint\fR
 199 .br
 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.
 205 .TP
 206 \fB\-r, \-\-rate \fIint\fR
 207 Specify the sample rate.  The default is 48000.
 208 .TP
 209 \fB\-S, \-\-shorts
 210 .br
 211 Try to configure card for 16\-bit samples first, only trying 32\-bits if
 212 unsuccessful.  Default is to prefer 32\-bit samples.
 213 .TP
 214 \fB\-s, \-\-softmode\fR
 215 .br
 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
 219 .TP
 220 \fB\-c \-\-channel\fR
 221 Maximum number of channels (default: 2)
 222 .TP
 223 \fB\-i \-\-channelin\fR
 224 Maximum number of input channels (default: 2)
 225 .TP
 226 \fB\-o \-\-channelout\fR
 227 Maximum number of output channels (default: 2)
 228 .TP
 229 \fB\-C \-\-capture\fR
 230 Whether or not to capture (default: true)
 231 .TP
 232 \fB\-P \-\-playback\fR
 233 Whether or not to playback (default: true)
 234 .TP
 235 \fB\-D \-\-duplex\fR
 236 Capture and playback (default: true)
 237 .TP
 238 \fB\-r \-\-rate\fR
 239 Sample rate (default: 44100)
 240 .TP
 241 \fB\-p \-\-period\fR
 242 Frames per period (default: 128). Must be a power of 2.
 243 .TP
 244 \fB\-n \-\-name\fR
 245 Driver name (default: none)
 246 .TP
 247 \fB\-I \-\-id\fR
 248 Audio Device ID (default: 0)
 249 .SS DUMMY BACKEND PARAMETERS
 250 .TP
 251 \fB\-C, \-\-capture \fIint\fR
 252 Specify number of capture ports. The default value is 2.
 253 .TP
 254 \fB\-P, \-\-playback \fIint\fR
 255 Specify number of playback ports. The default value is 2.
 256 .TP
 257 \fB\-r, \-\-rate \fIint\fR
 258 Specify sample rate. The default value is 48000.
 259 .TP
 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.
 266 .TP
 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
 271 .TP
 272 \fB\-r, \-\-rate \fIint\fR
 273 Specify the sample rate.  The default is 48000.
 274 .TP
 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.
 281 .TP
 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.
 287 .TP
 288 \fB\-w, \-\-wordlength \fIint\fR
 289 Specify the sample size in bits. The default is 16.
 290 .TP
 291 \fB\-i, \-\-inchannels \fIint\fR
 292 Specify how many channels to capture (default: 2)
 293 .TP
 294 \fB\-o, \-\-outchannels \fIint\fR
 295 Specify number of playback channels (default: 2)
 296 .TP
 297 \fB\-C, \-\-capture \fIdevice_file\fR
 298 Specify input device for capture (default: /dev/dsp)
 299 .TP
 300 \fB\-P, \-\-playback \fIdevice_file\fR
 301 Specify output device for playback (default: /dev/dsp)
 302 .TP
 303 \fB\-b, \-\-ignorehwbuf \fIboolean\fR
 304 Specify, whether to ignore hardware period size (default: false)
 305 .SS SUN BACKEND PARAMETERS
 306 .TP
 307 \fB\-r, \-\-rate \fIint\fR
 308 Specify the sample rate.  The default is 48000.
 309 .TP
 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.
 316 .TP
 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.
 323 .TP
 324 \fB\-w, \-\-wordlength \fIint\fR
 325 Specify the sample size in bits. The default is 16.
 326 .TP
 327 \fB\-i, \-\-inchannels \fIint\fR
 328 Specify how many channels to capture (default: 2)
 329 .TP
 330 \fB\-o, \-\-outchannels \fIint\fR
 331 Specify number of playback channels (default: 2)
 332 .TP
 333 \fB\-C, \-\-capture \fIdevice_file\fR
 334 Specify input device for capture (default: /dev/audio)
 335 .TP
 336 \fB\-P, \-\-playback \fIdevice_file\fR
 337 Specify output device for playback (default: /dev/audio)
 338 .TP
 339 \fB\-b, \-\-ignorehwbuf \fIboolean\fR
 340 Specify, whether to ignore hardware period size (default: false)
 341 .SS PORTAUDIO BACKEND PARAMETERS
 342 .TP
 343 \fB\-c \-\-channel\fR
 344 Maximum number of channels (default: all available hardware channels)
 345 .TP
 346 \fB\-i \-\-channelin\fR
 347 Maximum number of input channels (default: all available hardware channels)
 348 .TP
 349 \fB\-o \-\-channelout\fR
 350 Maximum number of output channels (default: all available hardware channels)
 351 .TP
 352 \fB\-C \-\-capture\fR
 353 Whether or not to capture (default: true)
 354 .TP
 355 \fB\-P \-\-playback\fR
 356 Whether or not to playback (default: true)
 357 .TP
 358 \fB\-D \-\-duplex\fR
 359 Capture and playback (default: true)
 360 .TP
 361 \fB\-r \-\-rate\fR
 362 Sample rate (default: 48000)
 363 .TP
 364 \fB\-p \-\-period\fR
 365 Frames per period (default: 1024). Must be a power of 2.
 366 .TP
 367 \fB\-n \-\-name\fR
 368 Driver name (default: none)
 369 .TP
 370 \fB\-z \-\-dither\fR
 371 Dithering mode (default: none)
 372 .SH "EXAMPLES"
 373 .PP
 374 Print usage message for the parameters specific to each backend.
 375 .IP
 376 \fBjackd \-d alsa \-\-help\fR
 377 .br
 378 \fBjackd \-d coreaudio \-\-help\fR
 379 .br
 380 \fBjackd \-d dummy \-\-help\fR
 381 .br
 382 \fBjackd \-d freebob \-\-help\fR
 383 .br
 384 \fBjackd \-d oss \-\-help\fR
 385 .br
 386 \fBjackd \-d sun \-\-help\fR
 387 .br
 388 \fBjackd \-d portaudio \-\-help\fR
 389 .PP
 390 Run the JACK daemon with realtime priority using the first ALSA
 391 hardware card defined in \fB/etc/modules.conf\fR.
 392 .IP
 393 \fBjackstart \-\-realtime \-\-driver=alsa\fR
 394 .PP
 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.
 403 .IP
 404 \fBjackstart \-Rv \-d alsa \-p 128 \-n 2 \-r 44100\fR
 405 .PP
 406 Run \fBjackd\fR with realtime priority using the "sblive" ALSA device
 407 defined in ~/.asoundrc.  Apply shaped dithering to playback audio.
 408 .IP
 409 \fBjackd \-R \-d alsa \-d sblive \-\-dither=shaped\fR
 410 .PP
 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.
 415 .IP
 416 \fBjackd \-d alsa \-d hw:1 \-p2048 \-n3 \-\-softmode \-zr\fR
 417 .PP
 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.
 420 .IP
 421 \fBjackd \-d alsa \-P hw:0,0 \-C hw:0,2\fR
 422 .PP
 423 Run \fBjackd\fR in playback\-only mode using the ALSA hw:0,0 device.
 424 .IP
 425 \fBjackd \-d alsa \-P hw:0,0\fR
 426 .SH "ENVIRONMENT"
 427 .br
 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.
 435
 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.
 440
 441 To change where JACK looks for the backend drivers, set
 442 \fB$JACK_DRIVER_DIR\fR.
 443
 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.
 449
 450 .SH "SEE ALSO:"
 451 .PP
 452 .I http://www.jackaudio.org
 453 .br
 454 The official JACK website with news, docs and a list of JACK clients.
 455 .PP
 456 .I http://lists.sourceforge.net/mailman/listinfo/jackit\-devel
 457 .br
 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.
 461 .PP
 462 .I http://www.jackosx.com/
 463 .br
 464 Tools specific to the Mac OS X version of JACK.
 465 .PP
 466 .I http://www.alsa\-project.org
 467 .br
 468 The Advanced Linux Sound Architecture.
 469 .SH "BUGS"
 470 Please report bugs to
 471 .br
 472 .I http://jackit.sourceforge.net/mantis/main_page.php
 473 .SH "AUTHORS"
 474 Architect and original implementor: Paul Davis
 475 .PP
 476 Original design Group: Paul Davis, David Olofson, Kai Vehmanen, Benno Sennoner,
 477 Richard Guenther, and other members of the Linux Audio Developers group.
 478 .PP
 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.
 482 .PP
 483 Manpage written by Stefan Schwandter, Jack O'Quin and Alexandre
 484 Prokoudine.