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 .TP
 219 \fB\-X, \-\-midi \fR[\fIseq\fR|\fIraw\fR]
 220 .br
 221 Specify which ALSA MIDI system to provide access to. Using \fBraw\fR
 222 will provide a set of JACK MIDI ports that correspond to each raw ALSA
 223 device on the machine. Using \fBseq\fR will provide a set of JACK MIDI
 224 ports that correspond to each ALSA "sequencer" client (which includes
 225 each hardware MIDI port on the machine). \fBraw\fR provides slightly
 226 better performance but does not permit JACK MIDI communication with
 227 software written to use the ALSA "sequencer" API.
 228 .SS COREAUDIO BACKEND PARAMETERS
 229 .TP
 230 \fB\-c \-\-channel\fR
 231 Maximum number of channels (default: 2)
 232 .TP
 233 \fB\-i \-\-channelin\fR
 234 Maximum number of input channels (default: 2)
 235 .TP
 236 \fB\-o \-\-channelout\fR
 237 Maximum number of output channels (default: 2)
 238 .TP
 239 \fB\-C \-\-capture\fR
 240 Whether or not to capture (default: true)
 241 .TP
 242 \fB\-P \-\-playback\fR
 243 Whether or not to playback (default: true)
 244 .TP
 245 \fB\-D \-\-duplex\fR
 246 Capture and playback (default: true)
 247 .TP
 248 \fB\-r \-\-rate\fR
 249 Sample rate (default: 44100)
 250 .TP
 251 \fB\-p \-\-period\fR
 252 Frames per period (default: 128). Must be a power of 2.
 253 .TP
 254 \fB\-n \-\-name\fR
 255 Driver name (default: none)
 256 .TP
 257 \fB\-I \-\-id\fR
 258 Audio Device ID (default: 0)
 259 .SS DUMMY BACKEND PARAMETERS
 260 .TP
 261 \fB\-C, \-\-capture \fIint\fR
 262 Specify number of capture ports. The default value is 2.
 263 .TP
 264 \fB\-P, \-\-playback \fIint\fR
 265 Specify number of playback ports. The default value is 2.
 266 .TP
 267 \fB\-r, \-\-rate \fIint\fR
 268 Specify sample rate. The default value is 48000.
 269 .TP
 270 \fB\-p, \-\-period \fIint\fR
 271 Specify the number of frames between JACK \fBprocess()\fR calls.  This
 272 value must be a power of 2, and the default is 1024.  If you need low
 273 latency, set \fB\-p\fR as low as you can go without seeing xruns.  A larger
 274 period size yields higher latency, but makes xruns less likely.  The JACK
 275 capture latency in seconds is \fB\-\-period\fR divided by \fB\-\-rate\fR.
 276 .TP
 277 \fB\-w, \-\-wait \fIint\fR
 278 Specify number of usecs to wait between engine processes.
 279 The default value is 21333.
 280 .SS OSS BACKEND PARAMETERS
 281 .TP
 282 \fB\-r, \-\-rate \fIint\fR
 283 Specify the sample rate.  The default is 48000.
 284 .TP
 285 \fB\-p, \-\-period \fIint\fR
 286 Specify the number of frames between JACK \fBprocess()\fR calls.  This
 287 value must be a power of 2, and the default is 1024.  If you need low
 288 latency, set \fB\-p\fR as low as you can go without seeing xruns.  A larger
 289 period size yields higher latency, but makes xruns less likely.  The JACK
 290 capture latency in seconds is \fB\-\-period\fR divided by \fB\-\-rate\fR.
 291 .TP
 292 \fB\-n, \-\-nperiods \fIint\fR
 293 Specify the number of periods in the hardware buffer.  The default is
 294 2.  The period size (\fB\-p\fR) times \fB\-\-nperiods\fR times four is
 295 the JACK buffer size in bytes.  The JACK output latency in seconds is
 296 \fB\-\-nperiods\fR times \fB\-\-period\fR divided by \fB\-\-rate\fR.
 297 .TP
 298 \fB\-w, \-\-wordlength \fIint\fR
 299 Specify the sample size in bits. The default is 16.
 300 .TP
 301 \fB\-i, \-\-inchannels \fIint\fR
 302 Specify how many channels to capture (default: 2)
 303 .TP
 304 \fB\-o, \-\-outchannels \fIint\fR
 305 Specify number of playback channels (default: 2)
 306 .TP
 307 \fB\-C, \-\-capture \fIdevice_file\fR
 308 Specify input device for capture (default: /dev/dsp)
 309 .TP
 310 \fB\-P, \-\-playback \fIdevice_file\fR
 311 Specify output device for playback (default: /dev/dsp)
 312 .TP
 313 \fB\-b, \-\-ignorehwbuf \fIboolean\fR
 314 Specify, whether to ignore hardware period size (default: false)
 315 .SS SUN BACKEND PARAMETERS
 316 .TP
 317 \fB\-r, \-\-rate \fIint\fR
 318 Specify the sample rate.  The default is 48000.
 319 .TP
 320 \fB\-p, \-\-period \fIint\fR
 321 Specify the number of frames between JACK \fBprocess()\fR calls.  This
 322 value must be a power of 2, and the default is 1024.  If you need low
 323 latency, set \fB\-p\fR as low as you can go without seeing xruns.  A larger
 324 period size yields higher latency, but makes xruns less likely.  The JACK
 325 capture latency in seconds is \fB\-\-period\fR divided by \fB\-\-rate\fR.
 326 .TP
 327 \fB\-n, \-\-nperiods \fIint\fR
 328 Specify the number of periods in the hardware buffer.  The default is
 329 2.  The period size (\fB\-p\fR) times \fB\-\-nperiods\fR times four
 330 (assuming 2 channels 16-bit samples) is the JACK buffer size in bytes.
 331 The JACK output latency in seconds is \fB\-\-nperiods\fR times
 332 \fB\-\-period\fR divided by \fB\-\-rate\fR.
 333 .TP
 334 \fB\-w, \-\-wordlength \fIint\fR
 335 Specify the sample size in bits. The default is 16.
 336 .TP
 337 \fB\-i, \-\-inchannels \fIint\fR
 338 Specify how many channels to capture (default: 2)
 339 .TP
 340 \fB\-o, \-\-outchannels \fIint\fR
 341 Specify number of playback channels (default: 2)
 342 .TP
 343 \fB\-C, \-\-capture \fIdevice_file\fR
 344 Specify input device for capture (default: /dev/audio)
 345 .TP
 346 \fB\-P, \-\-playback \fIdevice_file\fR
 347 Specify output device for playback (default: /dev/audio)
 348 .TP
 349 \fB\-b, \-\-ignorehwbuf \fIboolean\fR
 350 Specify, whether to ignore hardware period size (default: false)
 351 .SS PORTAUDIO BACKEND PARAMETERS
 352 .TP
 353 \fB\-c \-\-channel\fR
 354 Maximum number of channels (default: all available hardware channels)
 355 .TP
 356 \fB\-i \-\-channelin\fR
 357 Maximum number of input channels (default: all available hardware channels)
 358 .TP
 359 \fB\-o \-\-channelout\fR
 360 Maximum number of output channels (default: all available hardware channels)
 361 .TP
 362 \fB\-C \-\-capture\fR
 363 Whether or not to capture (default: true)
 364 .TP
 365 \fB\-P \-\-playback\fR
 366 Whether or not to playback (default: true)
 367 .TP
 368 \fB\-D \-\-duplex\fR
 369 Capture and playback (default: true)
 370 .TP
 371 \fB\-r \-\-rate\fR
 372 Sample rate (default: 48000)
 373 .TP
 374 \fB\-p \-\-period\fR
 375 Frames per period (default: 1024). Must be a power of 2.
 376 .TP
 377 \fB\-n \-\-name\fR
 378 Driver name (default: none)
 379 .TP
 380 \fB\-z \-\-dither\fR
 381 Dithering mode (default: none)
 382 .SH "EXAMPLES"
 383 .PP
 384 Print usage message for the parameters specific to each backend.
 385 .IP
 386 \fBjackd \-d alsa \-\-help\fR
 387 .br
 388 \fBjackd \-d coreaudio \-\-help\fR
 389 .br
 390 \fBjackd \-d dummy \-\-help\fR
 391 .br
 392 \fBjackd \-d freebob \-\-help\fR
 393 .br
 394 \fBjackd \-d oss \-\-help\fR
 395 .br
 396 \fBjackd \-d sun \-\-help\fR
 397 .br
 398 \fBjackd \-d portaudio \-\-help\fR
 399 .PP
 400 Run the JACK daemon with realtime priority using the first ALSA
 401 hardware card defined in \fB/etc/modules.conf\fR.
 402 .IP
 403 \fBjackstart \-\-realtime \-\-driver=alsa\fR
 404 .PP
 405 Run the JACK daemon with low latency giving verbose output, which can
 406 be helpful for trouble\-shooting system latency problems.  A
 407 reasonably well\-tuned system with a good sound card and a
 408 low\-latency kernel can handle these values reliably.  Some can do
 409 better.  If you get xrun messages, try a larger buffer.  Tuning a
 410 system for low latency can be challenging.  The JACK FAQ,
 411 .I http://jackit.sourceforge.net/docs/faq.php\fR
 412 has some useful suggestions.
 413 .IP
 414 \fBjackstart \-Rv \-d alsa \-p 128 \-n 2 \-r 44100\fR
 415 .PP
 416 Run \fBjackd\fR with realtime priority using the "sblive" ALSA device
 417 defined in ~/.asoundrc.  Apply shaped dithering to playback audio.
 418 .IP
 419 \fBjackd \-R \-d alsa \-d sblive \-\-dither=shaped\fR
 420 .PP
 421 Run \fBjackd\fR with no special privileges using the second ALSA
 422 hardware card defined in \fB/etc/modules.conf\fR.  Any xruns reported
 423 by the ALSA backend will be ignored.  The larger buffer helps reduce
 424 data loss.  Rectangular dithering will be used for playback.
 425 .IP
 426 \fBjackd \-d alsa \-d hw:1 \-p2048 \-n3 \-\-softmode \-zr\fR
 427 .PP
 428 Run \fBjackd\fR in full\-duplex mode using the ALSA hw:0,0 device for
 429 playback and the hw:0,2 device for capture.
 430 .IP
 431 \fBjackd \-d alsa \-P hw:0,0 \-C hw:0,2\fR
 432 .PP
 433 Run \fBjackd\fR in playback\-only mode using the ALSA hw:0,0 device.
 434 .IP
 435 \fBjackd \-d alsa \-P hw:0,0\fR
 436 .SH "ENVIRONMENT"
 437 .br
 438 JACK is evolving a mechanism for automatically starting the server
 439 when needed.  Any client started without a running JACK server will
 440 attempt to start one itself using the command line found in the first
 441 line of \fB$HOME/.jackdrc\fR if it exists, or \fB/etc/jackdrc\fR if it
 442 does not.  If neither file exists, a built\-in default command will be
 443 used, including the \fB\-T\fR flag, which causes the server to shut
 444 down when all clients have exited.
 445
 446 As a transition, this only happens when \fB$JACK_START_SERVER\fR is
 447 defined in the environment of the calling process.  In the future this
 448 will become normal behavior.  In either case, defining
 449 \fB$JACK_NO_START_SERVER\fR disables this feature.
 450
 451 To change where JACK looks for the backend drivers, set
 452 \fB$JACK_DRIVER_DIR\fR.
 453
 454 \fB$JACK_DEFAULT_SERVER\fR specifies the default server name.  If not
 455 defined, the string "default" is used.  If set in their respective
 456 environments, this affects \fBjackd\fR unless its \fB\-\-name\fR
 457 parameter is set, and all JACK clients unless they pass an explicit
 458 name to \fBjack_client_open()\fR.
 459
 460 .SH "SEE ALSO:"
 461 .PP
 462 .I http://www.jackaudio.org
 463 .br
 464 The official JACK website with news, docs and a list of JACK clients.
 465 .PP
 466 .I http://lists.sourceforge.net/mailman/listinfo/jackit\-devel
 467 .br
 468 The JACK developers' mailing list.  Subscribe, to take part in
 469 development of JACK or JACK clients.  User questions are also welcome,
 470 there is no user-specific mailing list.
 471 .PP
 472 .I http://www.jackosx.com/
 473 .br
 474 Tools specific to the Mac OS X version of JACK.
 475 .PP
 476 .I http://www.alsa\-project.org
 477 .br
 478 The Advanced Linux Sound Architecture.
 479 .SH "BUGS"
 480 Please report bugs to
 481 .br
 482 .I http://jackit.sourceforge.net/mantis/main_page.php
 483 .SH "AUTHORS"
 484 Architect and original implementor: Paul Davis
 485 .PP
 486 Original design Group: Paul Davis, David Olofson, Kai Vehmanen, Benno Sennoner,
 487 Richard Guenther, and other members of the Linux Audio Developers group.
 488 .PP
 489 Programming: Paul Davis, Jack O'Quin, Taybin Rutkin, Stephane Letz, Fernando
 490 Pablo Lopez-Lezcano, Steve Harris, Jeremy Hall, Andy Wingo, Kai
 491 Vehmanen, Melanie Thielker, Jussi Laako, Tilman Linneweh, Johnny Petrantoni.
 492 .PP
 493 Manpage written by Stefan Schwandter, Jack O'Quin and Alexandre
 494 Prokoudine.