1<?xml version="1.0"?><!--*-nxml-*--> 2<!DOCTYPE manpage SYSTEM "xmltoman.dtd"> 3<?xml-stylesheet type="text/xsl" href="xmltoman.xsl" ?> 4 5<!-- 6This file is part of PulseAudio. 7 8PulseAudio is free software; you can redistribute it and/or modify it 9under the terms of the GNU Lesser General Public License as 10published by the Free Software Foundation; either version 2.1 of the 11License, or (at your option) any later version. 12 13PulseAudio is distributed in the hope that it will be useful, but WITHOUT 14ANY WARRANTY; without even the implied warranty of MERCHANTABILITY 15or FITNESS FOR A PARTICULAR PURPOSE. See the GNU Lesser General 16Public License for more details. 17 18You should have received a copy of the GNU Lesser General Public 19License along with PulseAudio; if not, see <http://www.gnu.org/licenses/>. 20--> 21 22<manpage name="pulseaudio" section="1" desc="The PulseAudio Sound System"> 23 24 <synopsis> 25 <cmd>pulseaudio [<arg>options</arg>]</cmd> 26 <cmd>pulseaudio <opt>--help</opt></cmd> 27 <cmd>pulseaudio <opt>--version</opt></cmd> 28 <cmd>pulseaudio <opt>--dump-conf</opt></cmd> 29 <cmd>pulseaudio <opt>--dump-modules</opt></cmd> 30 <cmd>pulseaudio <opt>--dump-resample-methods</opt></cmd> 31 <cmd>pulseaudio <opt>--cleanup-shm</opt></cmd> 32 <cmd>pulseaudio <opt>--start</opt></cmd> 33 <cmd>pulseaudio <opt>--kill</opt></cmd> 34 <cmd>pulseaudio <opt>--check</opt></cmd> 35 </synopsis> 36 37 <description> 38 <p>PulseAudio is a networked low-latency sound server for Linux, POSIX and Windows systems.</p> 39 </description> 40 41 <options> 42 43 <option> 44 <p><opt>-h | --help</opt></p> 45 46 <optdesc><p>Show help.</p></optdesc> 47 </option> 48 49 <option> 50 <p><opt>--version</opt></p> 51 52 <optdesc><p>Show version information.</p></optdesc> 53 </option> 54 55 <option> 56 <p><opt>--dump-conf</opt></p> 57 58 <optdesc><p>Load the daemon configuration file 59 <file>daemon.conf</file> (see below), parse remaining 60 configuration options on the command line and dump the resulting 61 daemon configuration, in a format that is compatible with 62 <file>daemon.conf</file>.</p></optdesc> 63 </option> 64 65 <option> 66 <p><opt>--dump-modules</opt></p> 67 68 <optdesc><p>List available loadable modules. Combine with 69 <opt>-v</opt> for a more elaborate listing.</p></optdesc> 70 </option> 71 72 <option> 73 <p><opt>--dump-resample-methods</opt></p> 74 <optdesc><p>List available audio resamplers.</p></optdesc> 75 </option> 76 77 <option> 78 <p><opt>--cleanup-shm</opt></p> 79 80 <optdesc><p>Identify stale PulseAudio POSIX shared memory 81 segments in <file>/dev/shm</file> and remove them if 82 possible. This is done implicitly whenever a new daemon starts 83 up or a client tries to connect to a daemon. It should normally 84 not be necessary to issue this command by hand. Only available 85 on systems with POSIX shared memory segments implemented via a 86 virtual file system mounted to <file>/dev/shm</file> 87 (e.g. Linux).</p></optdesc> 88 </option> 89 90 <option> 91 <p><opt>--start</opt></p> 92 93 <optdesc><p>Start PulseAudio if it is not running yet. This is 94 different from starting PulseAudio without <opt>--start</opt> 95 which would fail if PA is already running. PulseAudio is 96 guaranteed to be fully initialized when this call 97 returns. Implies <opt>--daemonize</opt>.</p></optdesc> 98 </option> 99 100 <option> 101 <p><opt>-k | --kill</opt></p> 102 103 <optdesc><p>Kill an already running PulseAudio daemon of the 104 calling user (Equivalent to sending a SIGTERM).</p></optdesc> 105 </option> 106 107 <option> 108 <p><opt>--check</opt></p> 109 110 <optdesc><p>Return 0 as return code when the PulseAudio daemon 111 is already running for the calling user, or non-zero 112 otherwise. Produces no output on the console except for errors 113 to stderr.</p> 114 115 <p>Note that a non-zero return value doesn't necessarily mean that 116 PulseAudio is not usable. Even if the server is not running, it 117 may get automatically started via PulseAudio's autospawning 118 mechanism or systemd's socket activation, or the environment might 119 be such that checking for processes doesn't work (for example, the 120 running server might not show up in a container, even if the 121 server is accessible via a socket). Also disabling PID files with 122 <opt>--use-pid-file=no</opt> prevents <opt>--check</opt> from 123 detecting running servers.</p> 124 125 <p>A more robust check in most situations would be to try 126 establishing a client connection to the server. Unfortunately 127 there's currently no <opt>--check-connection</opt> option to 128 replace <opt>--check</opt>, but running "pactl info" could be a 129 pretty good substitute.</p></optdesc> 130 </option> 131 132 133 <option> 134 <p><opt>--system</opt><arg>[=BOOL]</arg></p> 135 136 <optdesc><p>Run as system-wide instance instead of 137 per-user. Please note that this disables certain features of 138 PulseAudio and is generally not recommended unless the system 139 knows no local users (e.g. is a thin client). This feature needs 140 special configuration and a dedicated UNIX user set up. It is 141 highly recommended to combine this with 142 <opt>--disallow-module-loading</opt> (see below).</p></optdesc> 143 </option> 144 145 <option> 146 <p><opt>-D | --daemonize</opt><arg>[=BOOL]</arg></p> 147 148 <optdesc><p>Daemonize after startup, i.e. detach from the 149 terminal. Note that when running as a systemd service you should 150 use <opt>--daemonize=no</opt> for systemd notification to work. 151 </p></optdesc> 152 </option> 153 154 <option> 155 <p><opt>--fail</opt><arg>[=BOOL]</arg></p> 156 157 <optdesc><p>Fail startup when any of the commands specified in 158 the startup script <file>default.pa</file> (see below) 159 fails.</p></optdesc> 160 </option> 161 162 <option> 163 <p><opt>--high-priority</opt><arg>[=BOOL]</arg></p> 164 165 <optdesc><p>Try to acquire a high Unix nice level. This will 166 only succeed if the calling user has a non-zero RLIMIT_NICE 167 resource limit set (on systems that support this), or we're 168 configured to be run as 169 system daemon (see <arg>--system</arg> above). It is recommended 170 to enable this, since it is only a negligible security risk (see 171 below).</p></optdesc> 172 </option> 173 174 <option> 175 <p><opt>--realtime</opt><arg>[=BOOL]</arg></p> 176 177 <optdesc><p>Try to acquire a real-time scheduling for 178 PulseAudio's I/O threads. This will only succeed if the calling 179 user has a non-zero RLIMIT_RTPRIO resource limit set (on systems 180 that support this), or rtkit is available and allows PulseAudio 181 to enable real-time scheduling, or we are configured to be run as 182 system daemon (see <arg>--system</arg> above).</p></optdesc> 183 </option> 184 185 <option> 186 <p><opt>--disallow-module-loading</opt><arg>[=BOOL]</arg></p> 187 188 <optdesc><p>Disallow module loading after startup. This is a 189 security feature since it disallows additional module loading 190 during runtime and on user request. It is highly recommended 191 when <arg>--system</arg> is used (see above). Note however, that 192 this breaks certain features like automatic module loading on hot 193 plug.</p></optdesc> 194 195 </option> 196 197 <option> 198 <p><opt>--disallow-exit</opt><arg>[=BOOL]</arg></p> 199 200 <optdesc><p>Disallow user requested exit</p></optdesc> 201 </option> 202 203 <option> 204 <p><opt>--exit-idle-time</opt><arg>=SECS</arg></p> 205 206 <optdesc> 207 <p>Terminate the daemon after the last client quit and this time in 208 seconds passed. Use a negative value to disable this feature. Defaults 209 to 20.</p> 210 211 <p>When PulseAudio runs in the per-user mode and detects a login 212 session, then any positive value will be reset to 0 so that PulseAudio 213 will terminate immediately on logout. A positive value therefore has 214 effect only in environments where there's no support for login session 215 tracking (or if the user is logged in without a session spawned, 216 a.k.a. lingering). A negative value can still be used to disable any 217 automatic exit.</p> 218 219 <p>When PulseAudio runs in the system mode, automatic exit is always 220 disabled, so this option does nothing.</p> 221 </optdesc> 222 </option> 223 224 <option> 225 <p><opt>--scache-idle-time</opt><arg>=SECS</arg></p> 226 227 <optdesc><p>Unload autoloaded samples from the cache when they 228 haven't been used for the specified number of 229 seconds.</p></optdesc> 230 </option> 231 232 <option> 233 <p><opt>--log-level</opt><arg>[=LEVEL]</arg></p> 234 235 <optdesc><p>If an argument is passed, set the log level to the 236 specified value, otherwise increase the configured verbosity 237 level by one. The log levels are numerical from 0 to 4, 238 corresponding to <arg>error</arg>, <arg>warn</arg>, 239 <arg>notice</arg>, <arg>info</arg>, <arg>debug</arg>. Default 240 log level is <arg>notice</arg>, i.e. all log messages with lower 241 log levels are printed: <arg>error</arg>, <arg>warn</arg>, 242 <arg>notice</arg>.</p></optdesc> 243 </option> 244 245 <option> 246 <p><opt>-v | --verbose</opt></p> 247 248 <optdesc><p>Increase the configured verbosity level by one (see 249 <opt>--log-level</opt> above). Specify multiple times to 250 increase log level multiple times.</p></optdesc> 251 </option> 252 253 <option> 254 <p><opt>--log-target</opt><arg>={auto,syslog,journal,stderr,file:PATH,newfile:PATH}</arg></p> 255 256 <optdesc><p>Specify the log target. If set to <arg>auto</arg> 257 (which is the default), then logging is directed to syslog when 258 <opt>--daemonize</opt> is passed, otherwise to 259 STDERR. If set to <arg>journal</arg> logging is directed to the systemd 260 journal. If set to <arg>file:PATH</arg>, logging is directed to 261 the file indicated by PATH. <arg>newfile:PATH</arg> is otherwise 262 the same as file:PATH, but existing files are never overwritten. 263 If the specified file already exists, a suffix is added to the 264 file name to avoid overwriting.</p></optdesc> 265 </option> 266 267 <option> 268 <p><opt>--log-meta</opt><arg>[=BOOL]</arg></p> 269 270 <optdesc><p>Show source code location in log messages.</p></optdesc> 271 </option> 272 273 <option> 274 <p><opt>--log-time</opt><arg>[=BOOL]</arg></p> 275 276 <optdesc><p>Show timestamps in log messages.</p></optdesc> 277 </option> 278 279 <option> 280 <p><opt>--log-backtrace</opt><arg>=FRAMES</arg></p> 281 282 <optdesc><p>When FRAMES is greater than 0, log for each message a 283 stack trace up to the number of specified stack frames.</p></optdesc> 284 </option> 285 286 <option> 287 <p><opt>-p | --dl-search-path</opt><arg>=PATH</arg></p> 288 289 <optdesc><p>Set the search path for dynamic shared objects 290 (plugins).</p></optdesc> 291 </option> 292 293 <option> 294 <p><opt>--resample-method</opt><arg>=METHOD</arg></p> 295 296 <optdesc><p>Use the specified resampler by default (See 297 <opt>--dump-resample-methods</opt> above for possible 298 values).</p></optdesc> 299 </option> 300 301 <option> 302 <p><opt>--use-pid-file</opt><arg>[=BOOL]</arg></p> 303 304 <optdesc><p>Create a PID file. If this options is disabled it is possible to run multiple sound servers per user.</p></optdesc> 305 </option> 306 307 <option> 308 <p><opt>--no-cpu-limit</opt><arg>[=BOOL]</arg></p> 309 310 <optdesc><p>Do not install CPU load limiter on platforms that 311 support it. By default, PulseAudio will terminate itself when it 312 notices that it takes up too much CPU time. This is useful as a 313 protection against system lockups when real-time scheduling is 314 used (see below). Disabling this mechanism is useful when 315 debugging PulseAudio with tools like <manref name="valgrind" 316 section="1"/> which slow down execution.</p></optdesc> 317 </option> 318 319 <option> 320 <p><opt>--disable-shm</opt><arg>[=BOOL]</arg></p> 321 322 <optdesc><p>PulseAudio clients and the server can exchange audio 323 data via POSIX or memfd shared memory segments (on systems that 324 support this). If disabled PulseAudio will communicate exclusively 325 over sockets. Please note that data transfer via shared memory 326 segments is always disabled when PulseAudio is running with 327 <opt>--system</opt> enabled (see above).</p></optdesc> 328 </option> 329 330 <option> 331 <p><opt>--enable-memfd</opt><arg>[=BOOL]</arg></p> 332 333 <optdesc><p>PulseAudio clients and the server can exchange audio 334 data via memfds - the anonymous Linux Kernel shared memory mechanism 335 (on kernels that support this). If disabled PulseAudio will 336 communicate via POSIX shared memory.</p></optdesc> 337 </option> 338 339 <option> 340 <p><opt>-L | --load</opt><arg>="MODULE ARGUMENTS"</arg></p> 341 342 <optdesc><p>Load the specified plugin module with the specified 343 arguments.</p></optdesc> 344 </option> 345 346 <option> 347 <p><opt>-F | --file</opt><arg>=FILENAME</arg></p> 348 349 <optdesc><p>Run the specified script on startup. May be 350 specified multiple times to specify multiple scripts to be run 351 in order. Combine with <opt>-n</opt> to disable loading of the 352 default script <file>default.pa</file> (see below).</p></optdesc> 353 </option> 354 <option> 355 <p><opt>-C</opt></p> 356 357 <optdesc><p>Open a command interpreter on STDIN/STDOUT after 358 startup. This may be used to configure PulseAudio dynamically 359 during runtime. Equivalent to 360 <opt>--load</opt><arg>=module-cli</arg>.</p></optdesc> 361 </option> 362 <option> 363 <p><opt>-n</opt></p> 364 365 <optdesc><p>Don't load default script file 366 <file>default.pa</file> (see below) on startup. Useful in 367 conjunction with <opt>-C</opt> or 368 <opt>--file</opt>.</p></optdesc> 369 </option> 370 371 372 </options> 373 374 <section name="Files"> 375 376 <p><file>~/.config/pulse/daemon.conf</file>, 377 <file>@PA_DEFAULT_CONFIG_DIR@/daemon.conf</file>: configuration settings 378 for the PulseAudio daemon. If the version in the user's home 379 directory does not exist the global configuration file is 380 loaded. See <manref name="pulse-daemon.conf" section="5"/> for 381 more information.</p> 382 383 <p><file>~/.config/pulse/default.pa</file>, 384 <file>@PA_DEFAULT_CONFIG_DIR@/default.pa</file>: the default configuration 385 script to execute when the PulseAudio daemon is started. If the 386 version in the user's home directory does not exist the global 387 configuration script is loaded. See <manref name="default.pa" 388 section="5"/> for more information.</p> 389 390 <p><file>~/.config/pulse/client.conf</file>, 391 <file>@PA_DEFAULT_CONFIG_DIR@/client.conf</file>: configuration settings 392 for PulseAudio client applications. If the version in the user's 393 home directory does not exist the global configuration file is 394 loaded. See <manref name="pulse-client.conf" section="5"/> for 395 more information.</p> 396 397 </section> 398 399 <section name="Signals"> 400 401 <p><arg>SIGINT, SIGTERM</arg>: the PulseAudio daemon will shut 402 down (Same as <opt>--kill</opt>).</p> 403 404 <p><arg>SIGHUP</arg>: dump a long status report to STDOUT or 405 syslog, depending on the configuration.</p> 406 407 <p><arg>SIGUSR1</arg>: load module-cli, allowing runtime 408 reconfiguration via STDIN/STDOUT.</p> 409 410 <p><arg>SIGUSR2</arg>: load module-cli-protocol-unix, allowing 411 runtime reconfiguration via a AF_UNIX socket. See <manref 412 name="pacmd" section="1"/> for more information.</p> 413 414 </section> 415 416 <section name="UNIX Groups and users"> 417 418 <p>Group <arg>pulse-access</arg>: if PulseAudio is running as a system 419 daemon (see <opt>--system</opt> above) access is granted to 420 members of this group when they connect via AF_UNIX sockets. If 421 PulseAudio is running as a user daemon this group has no 422 meaning.</p> 423 424 <p>User <arg>pulse</arg>, group <arg>pulse</arg>: if PulseAudio is running as a system 425 daemon (see <opt>--system</opt> above) and is started as root the 426 daemon will drop privileges and become a normal user process using 427 this user and group. If PulseAudio is running as a user daemon 428 this user and group has no meaning.</p> 429 </section> 430 431 <section name="Real-time and high-priority scheduling"> 432 <p>To minimize the risk of drop-outs during playback it is 433 recommended to run PulseAudio with real-time scheduling if the 434 underlying platform supports it. This decouples the scheduling 435 latency of the PulseAudio daemon from the system load and is thus 436 the best way to make sure that PulseAudio always gets CPU time 437 when it needs it to refill the hardware playback 438 buffers. Unfortunately this can be a security risk on some systems, 439 since PulseAudio runs as user process, and giving realtime 440 scheduling privileges to a user always comes with the risk 441 that the user misuses it to lock up the system -- which is 442 possible since making a process real-time effectively disables 443 preemption. To solve this problem, PulseAudio uses rtkit to safely 444 acquire real-time scheduling when available.</p> 445 446 <p>If the risk of locking up the machine is 447 considered too big to enable real-time scheduling, high-priority 448 scheduling can be enabled instead (i.e. negative nice level). This 449 can be enabled by passing <opt>--high-priority</opt> (see above) 450 when starting PulseAudio and may also be enabled with the 451 appropriate option in <file>daemon.conf</file>. Negative nice 452 levels can only be enabled when the appropriate resource limit 453 RLIMIT_NICE is set (see <manref name="setrlimit" section="2"/> for 454 more information), possibly configured in 455 <file>/etc/security/limits.conf</file>. A resource limit of 31 456 (corresponding with nice level -11) is recommended.</p> 457 </section> 458 459 <section name="Environment variables"> 460 461 <p>The PulseAudio client libraries check for the existence of the 462 following environment variables and change their local configuration accordingly:</p> 463 464 <p><arg>$PULSE_SERVER</arg>: the server string specifying the server 465 to connect to when a client asks for a sound server connection and doesn't 466 explicitly ask for a specific server. The server string is a list of 467 server addresses separated by whitespace which are tried in turn. A server 468 address consists of an optional address type specifier (unix:, tcp:, tcp4:, 469 tcp6:), followed by a path or host address. A host address may include an 470 optional port number. A server address may be prefixed by a string enclosed 471 in {}. In this case the following server address is ignored unless the prefix 472 string equals the local hostname or the machine id (/etc/machine-id).</p> 473 474 <p><arg>$PULSE_SINK</arg>: the symbolic name of the sink to connect to when a client creates a playback stream and doesn't explicitly ask for a specific sink.</p> 475 476 <p><arg>$PULSE_SOURCE</arg>: the symbolic name of the source to connect to when a client creates a record stream and doesn't explicitly ask for a specific source.</p> 477 478 <p><arg>$PULSE_BINARY</arg>: path of PulseAudio executable to run when server auto-spawning is used.</p> 479 480 <p><arg>$PULSE_CLIENTCONFIG</arg>: path of file that shall be read instead of <file>client.conf</file> (see above) for client configuration.</p> 481 482 <p><arg>$PULSE_COOKIE</arg>: path of file that contains the PulseAudio 483 authentication cookie. Defaults to <file>~/.config/pulse/cookie</file>.</p> 484 485 <p>These environment settings take precedence -- if set -- over the configuration settings from <file>client.conf</file> (see above).</p> 486 487 </section> 488 489 <section name="Authors"> 490 <p>The PulseAudio Developers <@PACKAGE_BUGREPORT@>; PulseAudio is available from <url href="@PACKAGE_URL@"/></p> 491 </section> 492 493 <section name="See also"> 494 <p> 495 <manref name="pulse-daemon.conf" section="5"/>, <manref name="default.pa" section="5"/>, <manref name="pulse-client.conf" section="5"/>, <manref name="pacmd" section="1"/> 496 </p> 497 </section> 498 499</manpage> 500