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="pulse-daemon.conf" section="5" desc="PulseAudio daemon configuration file">
27 <p><file>~/.pulse/daemon.conf</file></p>
29 <p><file>@pulseconfdir@/daemon.conf</file></p>
33 <p>The PulseAudio sound server reads configuration directives from
34 a file <file>~/.pulse/daemon.conf</file> on startup and when that
35 file doesn't exist from
36 <file>@pulseconfdir@/daemon.conf</file>. Please note that the
37 server also reads a configuration script on startup
38 <file>default.pa</file> which also contains runtime configuration
41 <p>The configuration file is a simple collection of variable
42 declarations. If the configuration file parser encounters either ;
43 or # it ignores the rest of the line until its end.</p>
45 <p>For the settings that take a boolean argument the values
46 <opt>true</opt>, <opt>yes</opt>, <opt>on</opt> and <opt>1</opt>
47 are equivalent, resp. <opt>false</opt>, <opt>no</opt>,
48 <opt>off</opt>, <opt>0</opt>.</p>
52 <section name="General Directives">
55 <p><opt>daemonize= </opt> Daemonize after startup. Takes a
56 boolean value, defaults to <opt>no</opt>. The <opt>--daemonize</opt>
57 command line option takes precedence.</p>
61 <p><opt>fail=</opt> Fail to start up if any of the directives
62 in the configuration script <file>default.pa</file>
63 fail. Takes a boolean argument, defaults to <opt>yes</opt>. The <opt>--fail</opt> command line
64 option takes precedence.</p>
68 <p><opt>allow-module-loading=</opt> Allow/disallow module
69 loading after startup. This is a security feature that if
70 dsabled makes sure that no further modules may be loaded into
71 the PulseAudio server after startup completed. It is recommended
72 to disable this when <opt>system-instance</opt> is
73 enabled. Please note that certain features like automatic
74 hot-plug support will not work if this option is enabled. Takes
75 a boolean argument, defaults to <opt>yes</opt>. The
76 <opt>--disallow-module-loading</opt> command line option takes
81 <p><opt>allow-exit=</opt> Allow/disallow exit on user
82 request. Defaults to <opt>yes</opt>.</p>
86 <p><opt>resample-method=</opt> The resampling algorithm to
87 use. Use one of <opt>src-sinc-best-quality</opt>,
88 <opt>src-sinc-medium-quality</opt>, <opt>src-sinc-fastest</opt>,
89 <opt>src-zero-order-hold</opt>, <opt>src-linear</opt>,
90 <opt>trivial</opt>, <opt>speex-float-N</opt>,
91 <opt>speex-fixed-N</opt>, <opt>ffmpeg</opt>. See the
92 documentation of libsamplerate for an explanation for the
93 different src- methods. The method <opt>trivial</opt> is the most basic
94 algorithm implemented. If you're tight on CPU consider using
95 this. On the other hand it has the worst quality of them
96 all. The Speex resamplers take an integer quality setting in the
97 range 0..9 (bad...good). They exist in two flavours: <opt>fixed</opt> and
98 <opt>float</opt>. The former uses fixed point numbers, the latter relies on
99 floating point numbers. On most desktop CPUs the float point
100 resmampler is a lot faster, and it also offers slightly better
101 quality. See the output of <opt>dump-resample-methods</opt> for
102 a complete list of all available resamplers. Defaults to
103 <opt>speex-float-3</opt>. The <opt>--resample-method</opt>
104 command line option takes precedence. Note that some modules
105 overwrite or allow overwriting of the resampler to use.</p>
109 <p><opt>enable-remixing=</opt> If disabled never upmix or
110 downmix channels to different channel maps. Instead, do a simple
111 name-based matching only. Defaults to <opt>yes.</opt></p>
115 <p><opt>enable-lfe-remixing=</opt> if disabeld when upmixing or
116 downmixing ignore LFE channels. When this option is dsabled the
117 output LFE channel will only get a signal when an input LFE
118 channel is available as well. If no input LFE channel is
119 available the output LFE channel will always be 0. If no output
120 LFE channel is available the signal on the input LFE channel
121 will be ignored. Defaults to <opt>no</opt>.</p>
125 <p><opt>use-pid-file=</opt> Create a PID file in
126 <file>/tmp/pulse-$USER/pid</file>. Of this is enabled you may
127 use commands like <opt>--kill</opt> or <opt>--check</opt>. If
128 you are planning to start more than one PulseAudio process per
129 user, you better disable this option since it effectively
130 disables multiple instances. Takes a boolean argument, defaults
131 to <opt>yes</opt>. The <opt>--no-cpu-limit</opt> command line
132 option takes precedence.</p>
136 <p><opt>cpu-limit=</opt> If disabled do not install the CPU load
137 limiter, even on platforms where it is supported. This option is
138 useful when debugging/profiling PulseAudio to disable disturbing
139 SIGXCPU signals. Takes a boolean argument, defaults to
140 <opt>no</opt>. The <opt>--no-cpu-limit</opt> command line
141 argument takes precedence.</p>
145 <p><opt>system-instance=</opt> Run the daemon as system-wide
146 instance, requires root priviliges. Takes a boolean argument,
147 defaults to <opt>no</opt>. The <opt>--system</opt> command line
148 argument takes precedence.</p>
152 <p><opt>enable-shm=</opt> Enable data transfer via POSIX
153 shared memory. Takes a boolean argument, defaults to
154 <opt>yes</opt>. The <opt>--disable-shm</opt> command line
155 argument takes precedence.</p>
159 <p><opt>shm-size-bytes=</opt> Sets the shared memory segment
160 size for the daemon, in bytes. If left unspecified or is set to 0
161 it will default to some system-specific default, usually 64
162 MiB. Please note that usually there is no need to change this
163 value, unless you are running an OS kernel that does not do
164 memory overcommit.</p>
168 <p><opt>lock-memory=</opt> Locks the entire PulseAudio process
169 into memory. While this might increase drop-out safety when used
170 in conjunction with real-time scheduling this takes away a lot
171 of memory from other processes and might hence considerably slow
172 down your system. Defaults to <opt>no</opt>.</p>
176 <p><opt>flat-volumes=</opt> Enable 'flat' volumes, i.e. where
177 possible let the sink volume equal the maximum of the volumes of
178 the inputs connected to it. Takes a boolean argument, defaults
179 to <opt>yes</opt>.</p>
184 <section name="Scheduling">
187 <p><opt>high-priority=</opt> Renice the daemon after startup to
188 become a high-priority process. This a good idea if you
189 experience drop-outs during playback. However, this is a certain
190 security issue, since it works when called SUID root only, or
191 RLIMIT_NICE is used. root is dropped immediately after gaining
192 the nice level on startup, thus it is presumably safe. See
193 <manref section="1" name="pulseaudio"/> for more
194 information. Takes a boolean argument, defaults to <opt>yes</opt>. The <opt>--high-priority</opt>
195 command line option takes precedence.</p>
199 <p><opt>realtime-scheduling=</opt> Try to acquire SCHED_FIFO
200 scheduling for the IO threads. The same security concerns as
201 mentioned above apply. However, if PA enters an endless loop,
202 realtime scheduling causes a system lockup. Thus, realtime
203 scheduling should only be enabled on trusted machines for
204 now. Please not that only the IO threads of PulseAudio are made
205 real-time. The controlling thread is left a normally scheduled
206 thread. Thus enabling the high-priority option is orthogonal.
207 See <manref section="1" name="pulseaudio"/> for more
208 information. Takes a boolean argument, defaults to <opt>yes</opt>. The
209 <opt>--realtime</opt> command line option takes precedence.</p>
213 <p><opt>realtime-priority=</opt> The realtime priority to
214 acquire, if <opt>realtime-scheduling</opt> is enabled. Note: JACK uses 10
215 by default, 9 for clients. Thus it is recommended to choose the
216 PulseAudio real-time priorities lower. Some PulseAudio threads
217 might choose a priority a little lower or higher than the
218 specified value. Defaults to <opt>5</opt>.</p>
222 <p><opt>nice-level=</opt> The nice level to acquire for the
223 daemon, if <opt>high-priority</opt> is enabled. Note: on some
224 distributions X11 uses -10 by default. Defaults to -11.</p>
229 <section name="Idle Times">
232 <p><opt>exit-idle-time=</opt> Terminate the daemon after the
233 last client quit and this time in seconds passed. Use a negative value to
234 disable this feature. Defaults to 20. The
235 <opt>--exit-idle-time</opt> command line option takes
240 <p><opt>scache-idle-time=</opt> Unload autoloaded sample cache
241 entries after being idle for this time in seconds. Defaults to
242 20. The <opt>--scache-idle-time</opt> command line option takes
248 <section name="Paths">
251 <p><opt>dl-search-path=</opt> The path were to look for dynamic
252 shared objects (DSOs/plugins). You may specify more than one
253 path seperated by colons. The default path depends on compile
254 time settings. The <opt>--dl-search-path</opt> command line
255 option takes precedence. </p>
259 <p><opt>default-script-file=</opt> The default configuration
260 script file to load. Specify an empty string for not loading a
261 default script file. The default behaviour is to load
262 <file>~/.pulse/default.pa</file>, and if that file does not
263 exist fall back to the system wide installed version
264 <file>@pulseconfdir@/default.pa</file>. If run in system-wide
265 mode the file <file>@pulseconfdir@/system.pa</file> is used
266 instead. If <opt>-n</opt> is passed on the command line
267 or <opt>default-script-file=</opt> is disabled the default
268 configuration script is ignored.</p>
272 <p><opt>load-default-script-file=</opt> Load the default
273 configuration script file as specified
274 in <opt>default-script-file=</opt>. Defaults to <opt>yes</opt>.</p>
279 <section name="Logging">
282 <p><opt>log-target=</opt> The default log target. Use either
283 <opt>stderr</opt>, <opt>syslog</opt> or <opt>auto</opt>. The
284 latter is equivalent to <opt>sylog</opt> in case
285 <opt>daemonize</opt> is enabled, otherwise to
286 <opt>stderr</opt>. Defaults to <opt>auto</opt>. The
287 <opt>--log-target</opt> command line option takes
292 <p><opt>log-level=</opt> Log level, one of <opt>debug</opt>,
293 <opt>info</opt>, <opt>notice</opt>, <opt>warning</opt>,
294 <opt>error</opt>. Log messages with a lower log level than
295 specified here are not logged. Defaults to
296 <opt>notice</opt>. The <opt>--log-level</opt> command line
297 option takes precedence. The <opt>-v</opt> command line option
298 might alter this setting.</p>
302 <p><opt>log-meta=</opt> With each logged message log the code
303 location the message was generated from. Defaults to
308 <p><opt>log-time=</opt> With each logged messages log the
309 relative time since startup. Defaults to <opt>no</opt>.</p>
313 <p><opt>log-backtrace=</opt> When greater than 0, with each
314 logged message log a code stack trace up the the specified
315 number of stack frames. Defaults to <opt>0</opt>.</p>
320 <section name="Resource Limits">
322 <p>See <manref name="getrlimit" section="2"/> for
323 more information. Set to -1 if PulseAudio shall not touch the resource
324 limit. Not all resource limits are available on all operating
328 <p><opt>rlimit-as</opt> Defaults to -1.</p>
331 <p><opt>rlimit-rss</opt> Defaults to -1.</p>
334 <p><opt>rlimit-core</opt> Defaults to -1.</p>
337 <p><opt>rlimit-data</opt> Defaults to -1.</p>
340 <p><opt>rlimit-fsize</opt> Defaults to -1.</p>
343 <p><opt>rlimit-nofile</opt> Defaults to 256.</p>
346 <p><opt>rlimit-stack</opt> Defaults to -1.</p>
349 <p><opt>rlimit-nproc</opt> Defaults to -1.</p>
352 <p><opt>rlimit-locks</opt> Defaults to -1.</p>
355 <p><opt>rlimit-sigpending</opt> Defaults to -1.</p>
358 <p><opt>rlimit-msgqueue</opt> Defaults to -1.</p>
361 <p><opt>rlimit-memlock</opt> Defaults to 16 KiB. Please note
362 that the JACK client libraries may require more locked
366 <p><opt>rlimit-nice</opt> Defaults to 31. Please make sure that
367 the default nice level as configured with <opt>nice-level</opt>
368 fits in this resource limit, if <opt>high-priority</opt> is
372 <p><opt>rlimit-rtprio</opt> Defaults to 9. Please make sure that
373 the default real-time priority level as configured with
374 <opt>realtime-priority=</opt> fits in this resource limit, if
375 <opt>realtime-scheduling</opt> is enabled. The JACK client
376 libraries require a real-time prority of 9 by default. </p>
379 <p><opt>rlimit-rttime</opt> Defaults to 1000000.</p>
384 <section name="Default Device Settings">
386 <p>Most drivers try to open the audio device with these settings
387 and then fall back to lower settings. The default settings are CD
388 quality: 16bit native endian, 2 channels, 44100 Hz sampling.</p>
391 <p><opt>default-sample-format=</opt> The default sampling
392 format. Specify one of <opt>u8</opt>, <opt>s16le</opt>,
393 <opt>s16be</opt>, <opt>s24le</opt>, <opt>s24be</opt>,
394 <opt>s24-32le</opt>, <opt>s24-32be</opt>, <opt>s32le</opt>,
395 <opt>s32be</opt> <opt>float32le</opt>, <opt>float32be</opt>,
396 <opt>ulaw</opt>, <opt>alaw</opt>. Depending on the endianess of
397 the CPU the formats <opt>s16ne</opt>, <opt>s16re</opt>,
398 <opt>s24ne</opt>, <opt>s24re</opt>, <opt>s24-32ne</opt>,
399 <opt>s24-32re</opt>, <opt>s32ne</opt>, <opt>s32re</opt>,
400 <opt>float32ne</opt>, <opt>float32re</opt> (for native,
401 resp. reverse endian) are available as aliases.</p>
405 <p><opt>default-sample-rate=</opt> The default sample frequency.</p>
409 <p><opt>default-sample-channels</opt> The default number of channels.</p>
413 <p><opt>default-channel-map</opt> The default channel map.</p>
418 <section name="Default Fragment Settings">
420 <p>Some hardware drivers require the hardware playback buffer to
421 be subdivided into several fragments. It is possible to change
422 these buffer metrics for machines with high scheduling
423 latencies. Not all possible values that may be configured here are
424 available in all hardware. The driver will to find the nearest
425 setting supported. Modern drivers that support timer-based
426 scheduling ignore these options.</p>
429 <p><opt>default-fragments=</opt> The default number of
430 fragments. Defaults to 4.</p>
433 <p><opt>default-fragment-size-msec=</opt>The duration of a
434 single fragment. Defaults to 25ms (i.e. the total buffer is thus
440 <section name="Authors">
441 <p>The PulseAudio Developers <@PACKAGE_BUGREPORT@>; PulseAudio is available from <url href="@PACKAGE_URL@"/></p>
444 <section name="See also">
446 <manref name="pulse-client.conf" section="5"/>, <manref name="default.pa" section="5"/>, <manref name="pulseaudio" section="1"/>, <manref name="pacmd" section="1"/>