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 "no". 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 "yes". The <opt>--fail</opt> command line
64 option takes precedence.</p>
68 <p><opt>disallow-module-loading=</opt> Disallow module loading
69 after startup. This is a security feature that makes sure that
70 no further modules may be loaded into the PulseAudio server
71 after startup completed. It is recommended to enable this when
72 <opt>system-instance</opt> is enabled. Please note that certain
73 features like automatic hot-plug support will not work if this
74 option is enabled. Takes a boolean argument, defaults to
75 <opt>no</opt>. The <opt>--disallow-module-loading</opt> command line
76 option takes precedence.</p>
80 <p><opt>disallow-exit=</opt> Disallow exit on user
81 request. Defaults to <opt>no</opt>.</p>
85 <p><opt>resample-method=</opt> The resampling algorithm to
86 use. Use one of <opt>src-sinc-best-quality</opt>,
87 <opt>src-sinc-medium-quality</opt>, <opt>src-sinc-fastest</opt>,
88 <opt>src-zero-order-hold</opt>, <opt>src-linear</opt>,
89 <opt>trivial</opt>, <opt>speex-float-N</opt>,
90 <opt>speex-fixed-N</opt>, <opt>ffmpeg</opt>. See the
91 documentation of libsamplerate for an explanation for the
92 different src- methods. The method <opt>trivial</opt> is the most basic
93 algorithm implemented. If you're tight on CPU consider using
94 this. On the other hand it has the worst quality of them
95 all. The Speex resamplers take an integer quality setting in the
96 range 0..9 (bad...good). They exist in two flavours: <opt>fixed</opt> and
97 <opt>float</opt>. The former uses fixed point numbers, the latter relies on
98 floating point numbers. On most desktop CPUs the float point
99 resmampler is a lot faster, and it also offers slightly better
100 quality. See the output of <opt>dump-resample-methods</opt> for
101 a complete list of all available resamplers. Defaults to
102 <opt>speex-float-3</opt>. The <opt>--resample-method</opt>
103 command line option takes precedence. Note that some modules
104 overwrite or allow overwriting of the resampler to use.</p>
108 <p><opt>disable-remixing=</opt> Never upmix or downmix channels
109 to different channel maps. Instead, do a simple name-based
114 <p><opt>disable-lfe-remixing=</opt> When upmixing or downmixing
115 ignore LFE channels. When this option is on the output LFE
116 channel will only get a signal when an input LFE channel is
117 available as well. If no input LFE channel is available the
118 output LFE channel will always be 0. If no output LFE channel is
119 available the signal on the input LFE channel will be
120 ignored. Defaults to "on".</p>
124 <p><opt>use-pid-file=</opt> Create a PID file in
125 <file>/tmp/pulse-$USER/pid</file>. Of this is enabled you may
126 use commands like <opt>--kill</opt> or <opt>--check</opt>. If
127 you are planning to start more than one PulseAudio process per
128 user, you better disable this option since it effectively
129 disables multiple instances. Takes a boolean argument, defaults
130 to <opt>yes</opt>. The <opt>--no-cpu-limit</opt> command line
131 option takes precedence.</p>
135 <p><opt>no-cpu-limit=</opt> Do not install the CPU load limiter,
136 even on platforms where it is supported. This option is useful
137 when debugging/profiling PulseAudio to disable disturbing
138 SIGXCPU signals. Takes a boolean argument, defaults to <opt>no</opt>. The
139 <opt>--no-cpu-limit</opt> command line argument takes
144 <p><opt>system-instance=</opt> Run the daemon as system-wide
145 instance, requires root priviliges. Takes a boolean argument,
146 defaults to <opt>no</opt>. The <opt>--system</opt> command line
147 argument takes precedence.</p>
151 <p><opt>disable-shm=</opt> Disable data transfer via POSIX
152 shared memory. Takes a boolean argument, defaults to
153 <opt>no</opt>. The <opt>--disable-shm</opt> command line
154 argument takes precedence.</p>
158 <p><opt>shm-size-bytes=</opt> Sets the shared memory segment
159 size for the daemon, in bytes. If left unspecified or is set to 0
160 it will default to some system-specific default, usually 64
161 MiB. Please note that usually there is no need to change this
162 value, unless you are running an OS kernel that does not do
163 memory overcommit.</p>
167 <p><opt>flat-volumes=</opt> Enable 'flat' volumes, i.e. where
168 possible let the sink volume equal the maximum of the volumes of
169 the inputs connected to it. Takes a boolean argument, defaults
170 to <opt>yes</opt>.</p>
175 <section name="Scheduling">
178 <p><opt>high-priority=</opt> Renice the daemon after startup to
179 become a high-priority process. This a good idea if you
180 experience drop-outs during playback. However, this is a certain
181 security issue, since it works when called SUID root only, or
182 RLIMIT_NICE is used. root is dropped immediately after gaining
183 the nice level on startup, thus it is presumably safe. See
184 <manref section="1" name="pulseaudio"/> for more
185 information. Takes a boolean argument, defaults to "yes". The <opt>--high-priority</opt>
186 command line option takes precedence.</p>
190 <p><opt>realtime-scheduling=</opt> Try to acquire SCHED_FIFO
191 scheduling for the IO threads. The same security concerns as
192 mentioned above apply. However, if PA enters an endless loop,
193 realtime scheduling causes a system lockup. Thus, realtime
194 scheduling should only be enabled on trusted machines for
195 now. Please not that only the IO threads of PulseAudio are made
196 real-time. The controlling thread is left a normally scheduled
197 thread. Thus enabling the high-priority option is orthogonal.
198 See <manref section="1" name="pulseaudio"/> for more
199 information. Takes a boolean argument, defaults to "no". The
200 <opt>--realtime</opt> command line option takes precedence.</p>
204 <p><opt>realtime-priority=</opt> The realtime priority to
205 acquire, if <opt>realtime-scheduling</opt> is enabled. Note: JACK uses 10
206 by default, 9 for clients. Thus it is recommended to choose the
207 PulseAudio real-time priorities lower. Some PulseAudio threads
208 might choose a priority a little lower or higher than the
209 specified value. Defaults to "5".</p>
213 <p><opt>nice-level=</opt> The nice level to acquire for the
214 daemon, if <opt>high-priority</opt> is enabled. Note: on some
215 distributions X11 uses -10 by default. Defaults to -11.</p>
220 <section name="Idle Times">
223 <p><opt>exit-idle-time=</opt> Terminate the daemon after the
224 last client quit and this time in seconds passed. Use a negative value to
225 disable this feature. Defaults to -1. The
226 <opt>--exit-idle-time</opt> command line option takes
231 <p><opt>module-idle-time=</opt> Unload autoloaded modules after
232 being idle for this time in seconds. Defaults to 20. The
233 <opt>--module-idle-time</opt> command line option takes
238 <p><opt>scache-idle-time=</opt> Unload autoloaded sample cache
239 entries after being idle for this time in seconds. Defaults to
240 20. The <opt>--scache-idle-time</opt> command line option takes
246 <section name="Paths">
249 <p><opt>dl-search-path=</opt> The path were to look for dynamic
250 shared objects (DSOs/plugins). You may specify more than one
251 path seperated by colons. The default path depends on compile
252 time settings. The <opt>--dl-search-path</opt> command line
253 option takes precedence. </p>
257 <p><opt>default-script-file=</opt> The default configuration
258 script file to load. Specify an empty string for not loading a
259 default script file. The default behaviour is to load
260 <file>~/.pulse/default.pa</file>, and if that file does not
261 exist fall back to the system wide installed version
262 <file>@pulseconfdir@/default.pa</file>. If run in system-wide
263 mode the file <file>@pulseconfdir@/system.pa</file> is used
264 instead. If <opt>-n</opt> is passed on the command line
265 or <opt>default-script-file=</opt> is disabled the default
266 configuration script is ignored.</p>
270 <p><opt>default-script-file=</opt> Load the default
271 configuration script file as specified
272 in <opt>default-script-file=</opt>. Defaults to "yes".</p>
277 <section name="Logging">
280 <p><opt>log-target=</opt> The default log target. Use either
281 <opt>stderr</opt>, <opt>syslog</opt> or <opt>auto</opt>. The
282 latter is equivalent to <opt>sylog</opt> in case
283 <opt>daemonize</opt> is enabled, otherwise to
284 <opt>stderr</opt>. Defaults to <opt>auto</opt>. The
285 <opt>--log-target</opt> command line option takes
290 <p><opt>log-level=</opt> Log level, one of <opt>debug</opt>,
291 <opt>info</opt>, <opt>notice</opt>, <opt>warning</opt>,
292 <opt>error</opt>. Log messages with a lower log level than
293 specified here are not logged. Defaults to
294 <opt>notice</opt>. The <opt>--log-level</opt> command line
295 option takes precedence. The <opt>-v</opt> command line option
296 might alter this setting.</p>
301 <section name="Resource Limits">
303 <p>See <manref name="getrlimit" section="2"/> for
304 more information. Set to -1 if PulseAudio shall not touch the resource
305 limit. Not all resource limits are available on all operating
309 <p><opt>rlimit-as</opt> Defaults to -1.</p>
312 <p><opt>rlimit-rss</opt> Defaults to -1.</p>
315 <p><opt>rlimit-core</opt> Defaults to -1.</p>
318 <p><opt>rlimit-data</opt> Defaults to -1.</p>
321 <p><opt>rlimit-fsize</opt> Defaults to -1.</p>
324 <p><opt>rlimit-nofile</opt> Defaults to 256.</p>
327 <p><opt>rlimit-stack</opt> Defaults to -1.</p>
330 <p><opt>rlimit-nproc</opt> Defaults to -1.</p>
333 <p><opt>rlimit-locks</opt> Defaults to -1.</p>
336 <p><opt>rlimit-sigpending</opt> Defaults to -1.</p>
339 <p><opt>rlimit-msgqueue</opt> Defaults to -1.</p>
342 <p><opt>rlimit-memlock</opt> Defaults to 16 KiB. Please note
343 that the JACK client libraries may require more locked
347 <p><opt>rlimit-nice</opt> Defaults to 31. Please make sure that
348 the default nice level as configured with <opt>nice-level</opt>
349 fits in this resource limit, if <opt>high-priority</opt> is
353 <p><opt>rlimit-rtprio</opt> Defaults to 9. Please make sure that
354 the default real-time priority level as configured with
355 <opt>realtime-priority=</opt> fits in this resource limit, if
356 <opt>realtime-scheduling</opt> is enabled. The JACK client
357 libraries require a real-time prority of 9 by default. </p>
360 <p><opt>rlimit-rttime</opt> Defaults to 1000000.</p>
365 <section name="Default Device Settings">
367 <p>Most drivers try to open the audio device with these settings
368 and then fall back to lower settings. The default settings are CD
369 quality: 16bit native endian, 2 channels, 44100 Hz sampling.</p>
372 <p><opt>default-sample-format=</opt> The default sampling
373 format. Specify one of <opt>u8</opt>, <opt>s16le</opt>,
374 <opt>s16be</opt>, <opt>s32le</opt>,
375 <opt>s32be</opt>, <opt>float32le</opt>, <opt>float32be</opt>,
376 <opt>ulaw</opt>, <opt>alaw</opt>. Depending on the endianess of
378 formats <opt>s16ne</opt>, <opt>s16re</opt>, <opt>s32ne</opt>, <opt>s32re</opt>,
379 <opt>float32ne</opt>, <opt>float32re</opt> (for native,
380 resp. reverse endian) are available as aliases.</p>
384 <p><opt>default-sample-rate=</opt> The default sample frequency.</p>
388 <p><opt>default-sample-channels</opt> The default number of channels.</p>
392 <p><opt>default-channel-map</opt> The default channel map.</p>
397 <section name="Default Fragment Settings">
399 <p>Some hardware drivers require the hardware playback buffer to
400 be subdivided into several fragments. It is possible to change
401 these buffer metrics for machines with high scheduling
402 latencies. Not all possible values that may be configured here are
403 available in all hardware. The driver will to find the nearest
404 setting supported.</p>
407 <p><opt>default-fragments=</opt> The default number of
408 fragments. Defaults to 4.</p>
411 <p><opt>default-fragment-size-msec=</opt>The duration of a
412 single fragment. Defaults to 25ms (i.e. the total buffer is thus
418 <section name="Authors">
419 <p>The PulseAudio Developers <@PACKAGE_BUGREPORT@>; PulseAudio is available from <url href="@PACKAGE_URL@"/></p>
422 <section name="See also">
424 <manref name="pulse-client.conf" section="5"/>, <manref name="default.pa" section="5"/>, <manref name="pulseaudio" section="1"/>, <manref name="pacmd" section="1"/>