man/pulse-daemon.conf.5.xml.in

   1 <?xml version="1.0"?><!--*-nxml-*-->
   2 <!DOCTYPE manpage SYSTEM "xmltoman.dtd">
   3 <?xml-stylesheet type="text/xsl" href="xmltoman.xsl" ?>
   4
   5 <!--
   6 This file is part of PulseAudio.
   7
   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.
  12
  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.
  17
  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
  21 USA.
  22 -->
  23
  24 <manpage name="pulse-daemon.conf" section="5" desc="PulseAudio daemon configuration file">
  25
  26   <synopsis>
  27     <p><file>~/.pulse/daemon.conf</file></p>
  28
  29     <p><file>@pulseconfdir@/daemon.conf</file></p>
  30   </synopsis>
  31
  32   <description>
  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
  39     directives.</p>
  40
  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>
  44
  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>
  49
  50   </description>
  51
  52   <section name="General Directives">
  53
  54     <option>
  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>
  58     </option>
  59
  60     <option>
  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>
  65     </option>
  66
  67     <option>
  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
  77       precedence.</p>
  78     </option>
  79
  80     <option>
  81       <p><opt>allow-exit=</opt> Allow/disallow exit on user
  82       request. Defaults to <opt>yes</opt>.</p>
  83     </option>
  84
  85     <option>
  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>
 106     </option>
 107
 108     <option>
 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>
 112     </option>
 113
 114     <option>
 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>
 122     </option>
 123
 124     <option>
 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>
 133     </option>
 134
 135     <option>
 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>
 142     </option>
 143
 144     <option>
 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>
 149     </option>
 150
 151     <option>
 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>
 156     </option>
 157
 158     <option>
 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>
 165     </option>
 166
 167     <option>
 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>
 173     </option>
 174
 175     <option>
 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>
 180     </option>
 181
 182   </section>
 183
 184   <section name="Scheduling">
 185
 186     <option>
 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>
 196     </option>
 197
 198     <option>
 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>
 210     </option>
 211
 212     <option>
 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>
 219     </option>
 220
 221     <option>
 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>
 225     </option>
 226
 227   </section>
 228
 229   <section name="Idle Times">
 230
 231     <option>
 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
 236       precedence.</p>
 237     </option>
 238
 239     <option>
 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
 243       precedence.</p>
 244     </option>
 245
 246   </section>
 247
 248   <section name="Paths">
 249
 250     <option>
 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>
 256     </option>
 257
 258     <option>
 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>
 269     </option>
 270
 271     <option>
 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>
 275     </option>
 276
 277   </section>
 278
 279   <section name="Logging">
 280
 281     <option>
 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
 288       precedence.</p>
 289     </option>
 290
 291     <option>
 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>
 299     </option>
 300
 301     <option>
 302       <p><opt>log-meta=</opt> With each logged message log the code
 303       location the message was generated from. Defaults to
 304       <opt>no</opt>.</p>
 305     </option>
 306
 307     <option>
 308       <p><opt>log-time=</opt> With each logged messages log the
 309       relative time since startup. Defaults to <opt>no</opt>.</p>
 310     </option>
 311
 312     <option>
 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>
 316     </option>
 317
 318   </section>
 319
 320   <section name="Resource Limits">
 321
 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
 325     systems.</p>
 326
 327     <option>
 328       <p><opt>rlimit-as</opt> Defaults to -1.</p>
 329     </option>
 330     <option>
 331       <p><opt>rlimit-rss</opt> Defaults to -1.</p>
 332     </option>
 333     <option>
 334       <p><opt>rlimit-core</opt> Defaults to -1.</p>
 335     </option>
 336     <option>
 337       <p><opt>rlimit-data</opt> Defaults to -1.</p>
 338     </option>
 339     <option>
 340       <p><opt>rlimit-fsize</opt> Defaults to -1.</p>
 341     </option>
 342     <option>
 343       <p><opt>rlimit-nofile</opt> Defaults to 256.</p>
 344     </option>
 345     <option>
 346       <p><opt>rlimit-stack</opt> Defaults to -1.</p>
 347     </option>
 348     <option>
 349       <p><opt>rlimit-nproc</opt> Defaults to -1.</p>
 350     </option>
 351     <option>
 352       <p><opt>rlimit-locks</opt> Defaults to -1.</p>
 353     </option>
 354     <option>
 355       <p><opt>rlimit-sigpending</opt> Defaults to -1.</p>
 356     </option>
 357     <option>
 358       <p><opt>rlimit-msgqueue</opt> Defaults to -1.</p>
 359     </option>
 360     <option>
 361       <p><opt>rlimit-memlock</opt> Defaults to 16 KiB. Please note
 362       that the JACK client libraries may require more locked
 363       memory.</p>
 364     </option>
 365     <option>
 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
 369       enabled.</p>
 370     </option>
 371     <option>
 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>
 377     </option>
 378     <option>
 379       <p><opt>rlimit-rttime</opt> Defaults to 1000000.</p>
 380     </option>
 381
 382   </section>
 383
 384   <section name="Default Device Settings">
 385
 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>
 389
 390     <option>
 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>
 402     </option>
 403
 404     <option>
 405       <p><opt>default-sample-rate=</opt> The default sample frequency.</p>
 406     </option>
 407
 408     <option>
 409       <p><opt>default-sample-channels</opt> The default number of channels.</p>
 410     </option>
 411
 412     <option>
 413       <p><opt>default-channel-map</opt> The default channel map.</p>
 414     </option>
 415
 416   </section>
 417
 418   <section name="Default Fragment Settings">
 419
 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>
 427
 428     <option>
 429       <p><opt>default-fragments=</opt> The default number of
 430       fragments. Defaults to 4.</p>
 431     </option>
 432     <option>
 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
 435       100ms long).</p>
 436     </option>
 437
 438   </section>
 439
 440   <section name="Authors">
 441     <p>The PulseAudio Developers &lt;@PACKAGE_BUGREPORT@&gt;; PulseAudio is available from <url href="@PACKAGE_URL@"/></p>
 442   </section>
 443
 444   <section name="See also">
 445     <p>
 446       <manref name="pulse-client.conf" section="5"/>, <manref name="default.pa" section="5"/>, <manref name="pulseaudio" section="1"/>, <manref name="pacmd" section="1"/>
 447     </p>
 448   </section>
 449
 450 </manpage>