1 <?xml version=
"1.0"?><!--*-nxml-*-->
2 <!DOCTYPE manpage SYSTEM
"xmltoman.dtd">
3 <?xml-stylesheet type=
"text/xsl" href=
"xmltoman.xsl" ?>
6 This file is part of PulseAudio.
8 PulseAudio is free software; you can redistribute it and/or modify it
9 under the terms of the GNU Lesser General Public License as
10 published by the Free Software Foundation; either version 2.1 of the
11 License, or (at your option) any later version.
13 PulseAudio is distributed in the hope that it will be useful, but WITHOUT
14 ANY WARRANTY; without even the implied warranty of MERCHANTABILITY
15 or FITNESS FOR A PARTICULAR PURPOSE. See the GNU Lesser General
16 Public License for more details.
18 You should have received a copy of the GNU Lesser General Public
19 License along with PulseAudio; if not, write to the Free Software
20 Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307
24 <manpage name=
"pulseaudio" section=
"1" desc=
"The PulseAudio Sound System">
27 <cmd>pulseaudio [
<arg>options
</arg>]
</cmd>
28 <cmd>pulseaudio
<opt>--help
</opt></cmd>
29 <cmd>pulseaudio
<opt>--version
</opt></cmd>
30 <cmd>pulseaudio
<opt>--dump-conf
</opt></cmd>
31 <cmd>pulseaudio
<opt>--dump-modules
</opt></cmd>
32 <cmd>pulseaudio
<opt>--dump-resample-methods
</opt></cmd>
33 <cmd>pulseaudio
<opt>--cleanup-shm
</opt></cmd>
34 <cmd>pulseaudio
<opt>--start
</opt></cmd>
35 <cmd>pulseaudio
<opt>--kill
</opt></cmd>
36 <cmd>pulseaudio
<opt>--check
</opt></cmd>
40 <p>PulseAudio is a networked low-latency sound server for Linux, POSIX and Windows systems.
</p>
46 <p><opt>-h | --help
</opt></p>
48 <optdesc><p>Show help.
</p></optdesc>
52 <p><opt>--version
</opt></p>
54 <optdesc><p>Show version information.
</p></optdesc>
58 <p><opt>--dump-conf
</opt></p>
60 <optdesc><p>Load the daemon configuration file
61 <file>daemon.conf
</file> (see below), parse remaining
62 configuration options on the command line and dump the resulting
63 daemon configuration, in a format that is compatible with
64 <file>daemon.conf
</file>.
</p></optdesc>
68 <p><opt>--dump-modules
</opt></p>
70 <optdesc><p>List available loadable modules. Combine with
71 <opt>-v
</opt> for a more elaborate listing.
</p></optdesc>
75 <p><opt>--dump-resample-methods
</opt></p>
76 <optdesc><p>List available audio resamplers.
</p></optdesc>
80 <p><opt>--cleanup-shm
</opt></p>
82 <optdesc><p>Identify stale PulseAudio POSIX shared memory
83 segments in
<file>/dev/shm
</file> and remove them if
84 possible. This is done implicitly whenever a new daemon starts
85 up or a client tries to connect to a daemon. It should normally
86 not be necessary to issue this command by hand. Only available
87 on systems with POSIX shared memory segments implemented via a
88 virtual file system mounted to
<file>/dev/shm
</file>
89 (e.g. Linux).
</p></optdesc>
93 <p><opt>--start
</opt></p>
95 <optdesc><p>Start PulseAudio if it is not running yet. This is
96 different from starting PulseAudio without
<opt>--start
</opt>
97 which would fail if PA is already running. PulseAudio is
98 guaranteed to be fully initialized when this call
99 returns. Implies
<opt>--daemon
</opt>.
</p></optdesc>
103 <p><opt>-k | --kill
</opt></p>
105 <optdesc><p>Kill an already running PulseAudio daemon of the
106 calling user (Equivalent to sending a SIGTERM).
</p></optdesc>
110 <p><opt>--check
</opt></p>
112 <optdesc><p>Return
0 as return code when the PulseAudio daemon
113 is already running for the calling user, or non-zero
114 otherwise. Produces no output on the console except for errors
115 to stderr.
</p></optdesc>
120 <p><opt>--system
</opt><arg>[=BOOL]
</arg></p>
122 <optdesc><p>Run as system-wide instance instead of
123 per-user. Please note that this disables certain features of
124 PulseAudio and is generally not recommended unless the system
125 knows no local users (e.g. is a thin client). This feature needs
126 special configuration and a dedicated UNIX user set up. It is
127 highly recommended to combine this with
128 <opt>--disallow-module-loading
</opt> (see below).
</p></optdesc>
132 <p><opt>-D | --daemonize
</opt><arg>[=BOOL]
</arg></p>
134 <optdesc><p>Daemonize after startup, i.e. detach from the
135 terminal.
</p></optdesc>
139 <p><opt>--fail
</opt><arg>[=BOOL]
</arg></p>
141 <optdesc><p>Fail startup when any of the commands specified in
142 the startup script
<file>default.pa
</file> (see below)
147 <p><opt>--high-priority
</opt><arg>[=BOOL]
</arg></p>
149 <optdesc><p>Try to acquire a high Unix nice level. This will
150 only succeed if the calling user has a non-zero RLIMIT_NICE
151 resource limit set (on systems that support this), or we're
152 called SUID root (see below), or we are configure to be run as
153 system daemon (see
<arg>--system
</arg> above). It is recommended
154 to enable this, since it is only a negligible security risk (see
155 below).
</p></optdesc>
159 <p><opt>--realtime
</opt><arg>[=BOOL]
</arg></p>
161 <optdesc><p>Try to acquire a real-time scheduling for
162 PulseAudio's I/O threads. This will only succeed if the calling
163 user has a non-zero RLIMIT_RTPRIO resource limit set (on systems
164 that support this), or we're called SUID root (see below), or we
165 are configure to be run as system daemon (see
166 <arg>--system
</arg> above). It is recommended to enable this
167 only for trusted users, since it is a major security risk (see
168 below).
</p></optdesc>
172 <p><opt>--disallow-module-loading
</opt><arg>[=BOOL]
</arg></p>
174 <optdesc><p>Disallow module loading after startup. This is a
175 security feature since it disallows additional module loading
176 during runtime and on user request. It is highly recommended
177 when
<arg>--system
</arg> is used (see above). Note however, that
178 this breaks certain features like automatic module loading on hot
184 <p><opt>--exit-idle-time
</opt><arg>=SECS
</arg></p>
186 <optdesc><p>Terminate the daemon when idle and the specified
187 number of seconds passed.
</p></optdesc>
191 <p><opt>--scache-idle-time
</opt><arg>=SECS
</arg></p>
193 <optdesc><p>Unload autoloaded samples from the cache when the
194 haven't been used for the specified number of
195 seconds.
</p></optdesc>
199 <p><opt>--log-level
</opt><arg>[=LEVEL]
</arg></p>
201 <optdesc><p>If an argument is passed, set the log level to the
202 specified value, otherwise increase the configured verbosity
203 level by one. The log levels are numerical from
0 to
4,
204 corresponding to
<arg>error
</arg>,
<arg>warn
</arg>,
205 <arg>notice
</arg>,
<arg>info
</arg>,
<arg>debug
</arg>. Default
206 log level is
<arg>notice
</arg>, i.e. all log messages with lower
207 log levels are printed:
<arg>error
</arg>,
<arg>warn
</arg>,
208 <arg>notice
</arg>.
</p></optdesc>
214 <optdesc><p>Increase the configured verbosity level by one (see
215 <opt>--log-level
</opt> above). Specify multiple times to
216 increase log level multiple times.
</p></optdesc>
220 <p><opt>--log-target
</opt><arg>={auto,syslog,journal,stderr,file:PATH,newfile:PATH}
</arg></p>
222 <optdesc><p>Specify the log target. If set to
<arg>auto
</arg>
223 (which is the default), then logging is directed to syslog when
224 <opt>--daemonize
</opt> is passed, otherwise to
225 STDERR. If set to
<arg>journal
</arg> logging is directed to the systemd
226 journal. If set to
<arg>file:PATH
</arg>, logging is directed to
227 the file indicated by PATH.
<arg>newfile:PATH
</arg> is otherwise
228 the same as file:PATH, but existing files are never overwritten.
229 If the specified file already exists, a suffix is added to the
230 file name to avoid overwriting.
</p></optdesc>
234 <p><opt>--log-meta
</opt><arg>[=BOOL]
</arg></p>
236 <optdesc><p>Show source code location in log messages.
</p></optdesc>
240 <p><opt>--log-time
</opt><arg>[=BOOL]
</arg></p>
242 <optdesc><p>Show timestamps in log messages.
</p></optdesc>
246 <p><opt>--log-backtrace
</opt><arg>=FRAMES
</arg></p>
248 <optdesc><p>When FRAMES is greater than
0, log for each message a
249 stack trace up to the number of specified stack frames.
</p></optdesc>
253 <p><opt>--p | --dl-search-path
</opt><arg>=PATH
</arg></p>
255 <optdesc><p>Set the search path for dynamic shared objects
256 (plugins).
</p></optdesc>
260 <p><opt>--resample-method
</opt><arg>=METHOD
</arg></p>
262 <optdesc><p>Use the specified resampler by default (See
263 <opt>--dump-resample-methods
</opt> above for possible
264 values).
</p></optdesc>
268 <p><opt>--use-pid-file
</opt><arg>[=BOOL]
</arg></p>
270 <optdesc><p>Create a PID file. If this options is disabled it is possible to run multiple sound servers per user.
</p></optdesc>
274 <p><opt>--no-cpu-limit
</opt><arg>[=BOOL]
</arg></p>
276 <optdesc><p>Do not install CPU load limiter on platforms that
277 support it. By default, PulseAudio will terminate itself when it
278 notices that it takes up too much CPU time. This is useful as a
279 protection against system lockups when real-time scheduling is
280 used (see below). Disabling this mechanism is useful when
281 debugging PulseAudio with tools like
<manref name=
"valgrind"
282 section=
"1"/> which slow down execution.
</p></optdesc>
286 <p><opt>--disable-shm
</opt><arg>[=BOOL]
</arg></p>
288 <optdesc><p>PulseAudio clients and the server can exchange audio
289 data via POSIX shared memory segments (on systems that support
290 this). If disabled PulseAudio will communicate exclusively over
291 sockets. Please note that data transfer via shared memory
292 segments is always disabled when PulseAudio is running with
293 <opt>--system
</opt> enabled (see above).
</p></optdesc>
297 <p><opt>-L | --load
</opt><arg>=
"MODULE ARGUMENTS"</arg></p>
299 <optdesc><p>Load the specified plugin module with the specified
300 arguments.
</p></optdesc>
304 <p><opt>-F | --file
</opt><arg>=FILENAME
</arg></p>
306 <optdesc><p>Run the specified script on startup. May be
307 specified multiple times to specify multiple scripts to be run
308 in order. Combine with
<opt>-n
</opt> to disable loading of the
309 default script
<file>default.pa
</file> (see below).
</p></optdesc>
314 <optdesc><p>Open a command interpreter on STDIN/STDOUT after
315 startup. This may be used to configure PulseAudio dynamically
316 during runtime. Equivalent to
317 <opt>--load
</opt><arg>=module-cli
</arg>.
</p></optdesc>
322 <optdesc><p>Don't load default script file
323 <file>default.pa
</file> (see below) on startup. Useful in
324 conjunction with
<opt>-C
</opt> or
325 <opt>--file
</opt>.
</p></optdesc>
331 <section name=
"Files">
333 <p><file>~/.config/pulse/daemon.conf
</file>,
334 <file>@PA_DEFAULT_CONFIG_DIR@/daemon.conf
</file>: configuration settings
335 for the PulseAudio daemon. If the version in the user's home
336 directory does not exist the global configuration file is
337 loaded. See
<manref name=
"pulse-daemon.conf" section=
"5"/> for
338 more information.
</p>
340 <p><file>~/.config/pulse/default.pa
</file>,
341 <file>@PA_DEFAULT_CONFIG_DIR@/default.pa
</file>: the default configuration
342 script to execute when the PulseAudio daemon is started. If the
343 version in the user's home directory does not exist the global
344 configuration script is loaded. See
<manref name=
"default.pa"
345 section=
"5"/> for more information.
</p>
347 <p><file>~/.config/pulse/client.conf
</file>,
348 <file>@PA_DEFAULT_CONFIG_DIR@/client.conf
</file>: configuration settings
349 for PulseAudio client applications. If the version in the user's
350 home directory does not exist the global configuration file is
351 loaded. See
<manref name=
"pulse-client.conf" section=
"5"/> for
352 more information.
</p>
356 <section name=
"Signals">
358 <p><arg>SIGINT, SIGTERM
</arg>: the PulseAudio daemon will shut
359 down (Same as
<opt>--kill
</opt>).
</p>
361 <p><arg>SIGHUP
</arg>: dump a long status report to STDOUT or
362 syslog, depending on the configuration.
</p>
364 <p><arg>SIGUSR1
</arg>: load module-cli, allowing runtime
365 reconfiguration via STDIN/STDOUT.
</p>
367 <p><arg>SIGUSR2
</arg>: load module-cli-protocol-unix, allowing
368 runtime reconfiguration via a AF_UNIX socket. See
<manref
369 name=
"pacmd" section=
"1"/> for more information.
</p>
373 <section name=
"UNIX Groups and users">
375 <p>Group
<arg>pulse-rt
</arg>: if the PulseAudio binary is marked
376 SUID root, then membership of the calling user in this group
377 decides whether real-time and/or high-priority scheduling is
378 enabled. Please note that enabling real-time scheduling is a
379 security risk (see below).
</p>
381 <p>Group
<arg>pulse-access
</arg>: if PulseAudio is running as a system
382 daemon (see
<opt>--system
</opt> above) access is granted to
383 members of this group when they connect via AF_UNIX sockets. If
384 PulseAudio is running as a user daemon this group has no
387 <p>User
<arg>pulse
</arg>, group
<arg>pulse
</arg>: if PulseAudio is running as a system
388 daemon (see
<opt>--system
</opt> above) and is started as root the
389 daemon will drop privileges and become a normal user process using
390 this user and group. If PulseAudio is running as a user daemon
391 this user and group has no meaning.
</p>
394 <section name=
"Real-time and high-priority scheduling">
395 <p>To minimize the risk of drop-outs during playback it is
396 recommended to run PulseAudio with real-time scheduling if the
397 underlying platform supports it. This decouples the scheduling
398 latency of the PulseAudio daemon from the system load and is thus
399 the best way to make sure that PulseAudio always gets CPU time
400 when it needs it to refill the hardware playback
401 buffers. Unfortunately this is a security risk on most systems,
402 since PulseAudio runs as user process, and giving realtime
403 scheduling privileges to a user process always comes with the risk
404 that the user misuses it to lock up the system -- which is
405 possible since making a process real-time effectively disables
408 <p>To minimize the risk PulseAudio by default does not enable
409 real-time scheduling. It is however recommended to enable it
410 on trusted systems. To do that start PulseAudio with
411 <opt>--realtime
</opt> (see above) or enabled the appropriate option in
412 <file>daemon.conf
</file>. Since acquiring realtime scheduling is a
413 privileged operation on most systems, some special changes to the
414 system configuration need to be made to allow them to the calling
415 user. Two options are available:
</p>
417 <p>On newer Linux systems the system resource limit RLIMIT_RTPRIO
418 (see
<manref name=
"setrlimit" section=
"2"/> for more information)
419 can be used to allow specific users to acquire real-time
420 scheduling. This can be configured in
421 <file>/etc/security/limits.conf
</file>, a resource limit of
9 is recommended.
</p>
423 <p>Alternatively, the SUID root bit can be set for the PulseAudio
424 binary. Then, the daemon will drop root privileges immediately on
425 startup, however retain the CAP_NICE capability (on systems that
426 support it), but only if the calling user is a member of the
427 <arg>pulse-rt
</arg> group (see above). For all other users all
428 capabilities are dropped immediately. The advantage of this
429 solution is that the real-time privileges are only granted to the
430 PulseAudio daemon -- not to all the user's processes.
</p>
432 <p>Alternatively, if the risk of locking up the machine is
433 considered too big to enable real-time scheduling, high-priority
434 scheduling can be enabled instead (i.e. negative nice level). This
435 can be enabled by passing
<opt>--high-priority
</opt> (see above)
436 when starting PulseAudio and may also be enabled with the
437 appropriate option in
<file>daemon.conf
</file>. Negative nice
438 levels can only be enabled when the appropriate resource limit
439 RLIMIT_NICE is set (see
<manref name=
"setrlimit" section=
"2"/> for
440 more information), possibly configured in
441 <file>/etc/security/limits.conf
</file>. A resource limit of
31
442 (corresponding with nice level -
11) is recommended.
</p>
445 <section name=
"Environment variables">
447 <p>The PulseAudio client libraries check for the existence of the
448 following environment variables and change their local configuration accordingly:
</p>
450 <p><arg>$PULSE_SERVER
</arg>: the server string specifying the server
451 to connect to when a client asks for a sound server connection and doesn't
452 explicitly ask for a specific server. The server string is a list of
453 server addresses separated by whitespace which are tried in turn. A server
454 address consists of an optional address type specifier (unix:, tcp:, tcp4:,
455 tcp6:), followed by a path or host address. A host address may include an
456 optional port number.
</p>
458 <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>
460 <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>
462 <p><arg>$PULSE_BINARY
</arg>: path of PulseAudio executable to run when server auto-spawning is used.
</p>
464 <p><arg>$PULSE_CLIENTCONFIG
</arg>: path of file that shall be read instead of
<file>client.conf
</file> (see above) for client configuration.
</p>
466 <p><arg>$PULSE_COOKIE
</arg>: path of file that contains the PulseAudio
467 authentication cookie. Defaults to
<file>~/.config/pulse/cookie
</file>.
</p>
469 <p>These environment settings take precedence -- if set -- over the configuration settings from
<file>client.conf
</file> (see above).
</p>
473 <section name=
"Authors">
474 <p>The PulseAudio Developers
<@PACKAGE_BUGREPORT@
>; PulseAudio is available from
<url href=
"@PACKAGE_URL@"/></p>
477 <section name=
"See also">
479 <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"/>