1 <?xml version="1.0"?><!--*-nxml-*-->
2 <!DOCTYPE manpage SYSTEM "xmltoman.dtd">
3 <?xml-stylesheet type="text/xsl" href="xmltoman.xsl" ?>
8 This file is part of PulseAudio.
10 PulseAudio is free software; you can redistribute it and/or modify it
11 under the terms of the GNU Lesser General Public License as
12 published by the Free Software Foundation; either version 2.1 of the
13 License, or (at your option) any later version.
15 PulseAudio is distributed in the hope that it will be useful, but WITHOUT
16 ANY WARRANTY; without even the implied warranty of MERCHANTABILITY
17 or FITNESS FOR A PARTICULAR PURPOSE. See the GNU Lesser General
18 Public License for more details.
20 You should have received a copy of the GNU Lesser General Public
21 License along with PulseAudio; if not, write to the Free Software
22 Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307
26 <manpage name="pulseaudio" section="1" desc="The PulseAudio Sound System">
29 <cmd>pulseaudio [<arg>options</arg>]</cmd>
30 <cmd>pulseaudio <opt>--help</opt></cmd>
31 <cmd>pulseaudio <opt>--dump-conf</opt></cmd>
32 <cmd>pulseaudio <opt>--dump-modules</opt></cmd>
33 <cmd>pulseaudio <opt>--dump-resample-methods</opt></cmd>
34 <cmd>pulseaudio <opt>--cleanup-shm</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-resampe-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>-k | --kill</opt></p>
95 <optdesc><p>Kill an already running PulseAudio daemon of the
96 calling user (Equivalent to sending a SIGTERM).</p></optdesc>
100 <p><opt>--check</opt></p>
102 <optdesc><p>Return 0 as return code when the PulseAudio daemon
103 is already running for the calling user.</p></optdesc>
108 <p><opt>--system</opt><arg>[=BOOL]</arg></p>
110 <optdesc><p>Run as system-wide instance instead of
111 per-user. Please not that this disables certain features of
112 PulseAudio and is generally not recommended unless the system
113 knows no local users (e.g. is a thin client). This feature needs
114 special configuration and a dedicated UNIX user set up. It is
115 highly recommended to combine this with
116 <opt>--disallow-module-loading</opt> (see below).</p></optdesc>
120 <p><opt>-D | --daemon</opt><arg>[=BOOL]</arg></p>
122 <optdesc><p>Daemonize after startup, i.e. detach from the
123 terminal.</p></optdesc>
127 <p><opt>--fail</opt><arg>[=BOOL]</arg></p>
129 <optdesc><p>Fail startup when any of the commands specified in
130 the startup script <file>default.pa</file> (see below)
135 <p><opt>--high-priority</opt><arg>[=BOOL]</arg></p>
137 <optdesc><p>Try to acquire a high Unix nice level. This will
138 only succeed if the calling user has a non-zero RLIMIT_NICE
139 resource limit set (on systems that support this), or we're
140 called SUID root (see below), or we are configure to be run as
141 system daemon (see <arg>--system</arg> above). It is recommended
142 to enable this, since it is only a negligible security risk (see
143 below).</p></optdesc>
147 <p><opt>--realtime</opt><arg>[=BOOL]</arg></p>
149 <optdesc><p>Try to acquire a real-time scheduling for
150 PulseAudio's I/O threads. This will only succeed if the calling
151 user has a non-zero RLIMIT_RTPRIO resource limit set (on systems
152 that support this), or we're called SUID root (see below), or we
153 are configure to be run as system daemon (see
154 <arg>--system</arg> above). It is recommended to enable this
155 only for trusted users, since it is a major security risk (see
156 below).</p></optdesc>
160 <p><opt>--disallow-module-loading</opt><arg>[=BOOL]</arg></p>
162 <optdesc><p>Disallow module loading after startup. This is a
163 security feature since it disallows additional module loading
164 during runtime and on user request. It is highly recommended
165 when <arg>--system</arg> is used (see above). Note however, that
166 this breaks certain features like automatic module loading on hot
172 <p><opt>--exit-idle-time</opt><arg>=SECS</arg></p>
174 <optdesc><p>Terminate the daemon when idle and the specified
175 number of seconds passed.</p></optdesc>
179 <p><opt>--module-idle-time</opt><arg>=SECS</arg></p>
181 <optdesc><p>Unload autoloaded modules when idle and the
182 specified number of seconds passed.</p></optdesc>
186 <p><opt>--scache-idle-time</opt><arg>=SECS</arg></p>
188 <optdesc><p>Unload autoloaded samples from the cache when the
189 haven't been used for the specified number of
190 seconds.</p></optdesc>
194 <p><opt>--log-level</opt><arg>[=LEVEL]</arg></p>
196 <optdesc><p>If an argument is passed, set the log level to the
197 specified value, otherwise increase the configured verbosity
198 level by one. The log levels are numerical from 0 to 4,
199 corresponding to <arg>error</arg>, <arg>warn</arg>,
200 <arg>notice</arg>, <arg>info</arg>, <arg>debug</arg>. Default
201 log level is <arg>notice</arg>, i.e. all log messages with lower
202 log levels are printed: <arg>error</arg>, <arg>warn</arg>,
203 <arg>notice</arg>.</p></optdesc>
209 <optdesc><p>Increase the configured verbosity level by one (see
210 <opt>--log-level</opt> above). Specify multiple times to
211 increase log level multiple times.</p></optdesc>
215 <p><opt>--log-target</opt><arg>={auto,syslog,stderr}</arg></p>
217 <optdesc><p>Specify the log target. If set to <arg>auto</arg>
218 (which is the default), then logging is directed to syslog when
219 <opt>--daemonize</opt> is passed, otherwise to
220 STDERR.</p></optdesc>
224 <p><opt>--p | --dl-search-path</opt><arg>=PATH</arg></p>
226 <optdesc><p>Set the search path for dynamic shared objects
227 (plugins).</p></optdesc>
231 <p><opt>--resample-method</opt><arg>=METHOD</arg></p>
233 <optdesc><p>Use the specified resampler by default (See
234 <opt>--dump-resample-methods</opt> above for possible
235 values).</p></optdesc>
239 <p><opt>--use-pid-file</opt><arg>[=BOOL]</arg></p>
241 <optdesc><p>Create a PID file. If this options is disabled it is possible to run multiple sound servers per user.</p></optdesc>
245 <p><opt>--no-cpu-limit</opt><arg>[=BOOL]</arg></p>
247 <optdesc><p>Do not install CPU load limiter on platforms that
248 support it. By default, PulseAudio will terminate itself when it
249 notices that it takes up too much CPU time. This is useful as a
250 protection against system lockups when real-time scheduling is
251 used (see below). Disabling this meachnism is useful when
252 debugging PulseAudio with tools like <manref name="valgrind"
253 section="1"/> which slow down execution.</p></optdesc>
257 <p><opt>--disable-shm</opt><arg>[=BOOL]</arg></p>
259 <optdesc><p>PulseAudio clients and the server can exchange audio
260 data via POSIX shared memory segments (on systems that support
261 this). If disabled PulseAudio will communicate exclusively over
262 sockets. Please note that data transfer via shared memory
263 segments is always disabled when PulseAudio is running with
264 <opt>--system</opt> enabled (see above).</p></optdesc>
268 <p><opt>-L | --load</opt><arg>="MODULE ARGUMENTS"</arg></p>
270 <optdesc><p>Load the specified plugin module with the specified
271 arguments.</p></optdesc>
275 <p><opt>-F | --file</opt><arg>=FILENAME</arg></p>
277 <optdesc><p>Run the specified script on startup. May be
278 specified multiple times to specify multiple scripts to be run
279 in order. Combine with <opt>-n</opt> to disable loading of the
280 default script <file>default.pa</file> (see below).</p></optdesc>
285 <optdesc><p>Open a command interpreter on STDIN/STDOUT after
286 startup. This may be used to configure PulseAudio dynamically
287 during runtime. Equivalent to
288 <opt>--load</opt><arg>=module-cli</arg>.</p></optdesc>
293 <optdesc><p>Don't load default script file
294 <file>default.pa</file> (see below) on startup. Useful in
295 conjunction with <opt>-C</opt> or
296 <opt>--file</opt>.</p></optdesc>
302 <section name="Files">
304 <p><file>~/.pulse/daemon.conf</file>,
305 <file>@pulseconfdir@/daemon.conf</file>: configuration settings
306 for the PulseAudio daemon. If the version in the user's home
307 directory does not exist the global configuration file is
308 loaded. See <manref name="pulse-daemon.conf" section="5"/> for
309 more information.</p>
311 <p><file>~/.pulse/default.pa</file>,
312 <file>@pulseconfdir@/default.pa</file>: the default configuration
313 script to execute when the PulseAudio daemon is started. If the
314 version in the user's home directory does not exist the global
315 configuration script is loaded. See <manref name="default.pa"
316 section="5"/> for more information.</p>
318 <p><file>~/.pulse/client.conf</file>,
319 <file>@pulseconfdir@/client.conf</file>: configuration settings
320 for PulseAudio client applications. If the version in the user's
321 home directory does not exist the global configuration file is
322 loaded. See <manref name="pulse-client.conf" section="5"/> for
323 more information.</p>
327 <section name="Signals">
329 <p><arg>SIGINT, SIGTERM</arg>: the PulseAudio daemon will shut
330 down (Same as <opt>--kill</opt>).</p>
332 <p><arg>SIGHUP</arg>: dump a long status report to STDOUT or
333 syslog, depending on the configuration.</p>
335 <p><arg>SIGUSR1</arg>: load module-cli, allowing runtime
336 reconfiguration via STDIN/STDOUT.</p>
338 <p><arg>SIGUSR2</arg>: load module-cli-protocol-unix, allowing
339 runtime reconfiguration via a AF_UNIX socket. See <manref
340 name="pacmd" section="1"/> for more information.</p>
344 <section name="UNIX Groups and users">
346 <p>Group <arg>pulse-rt</arg>: if the PulseAudio binary is marked
347 SUID root, then membership of the calling user in this group
348 decides whether real-time and/or high-priority scheduling is
349 enabled. Please note that enabling real-time scheduling is a
350 security risk (see below).</p>
352 <p>Group <arg>pulse-access</arg>: if PulseAudio is running as a system
353 daemon (see <opt>--system</opt> above) access is granted to
354 members of this group when they connect via AF_UNIX sockets. If
355 PulseAudio is running as a user daemon this group has no
358 <p>User <arg>pulse</arg>, group <arg>pulse</arg>: if PulseAudio is running as a system
359 daemon (see <opt>--system</opt> above) and is started as root the
360 daemon will drop priviliges and become a normal user process using
361 this user and group. If PulseAudio is running as a user daemon
362 this user and group has no meaning.</p>
365 <section name="Real-time and high-priority scheduling">
369 <section name="Authors">
370 <p>The PulseAudio Developers <@PACKAGE_BUGREPORT@>; PulseAudio is available from <url href="@PACKAGE_URL@"/></p>
373 <section name="See also">
375 <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"/>