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>@PA_DEFAULT_CONFIG_DIR@/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>@PA_DEFAULT_CONFIG_DIR@/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 and speex for explanations of the
  93       different src- and speex- methods, respectively. The method
  94       <opt>trivial</opt> is the most basic algorithm implemented. If
  95       you're tight on CPU consider using this. On the other hand it has
  96       the worst quality of them all. The Speex resamplers take an
  97       integer quality setting in the range 0..10 (bad...good). They
  98       exist in two flavours: <opt>fixed</opt> and <opt>float</opt>. The former uses fixed point
  99       numbers, the latter relies on floating point numbers. On most
 100       desktop CPUs the float point resampler is a lot faster, and it
 101       also offers slightly better quality. See the output of
 102       <opt>dump-resample-methods</opt> for a complete list of all
 103       available resamplers. Defaults to <opt>speex-float-3</opt>. The
 104       <opt>--resample-method</opt> command line option takes precedence.
 105       Note that some modules overwrite or allow overwriting of the
 106       resampler to use.</p>
 107     </option>
 108
 109     <option>
 110       <p><opt>enable-remixing=</opt> If disabled never upmix or
 111       downmix channels to different channel maps. Instead, do a simple
 112       name-based matching only. Defaults to <opt>yes.</opt></p>
 113     </option>
 114
 115     <option>
 116       <p><opt>enable-lfe-remixing=</opt> if disabeld when upmixing or
 117       downmixing ignore LFE channels. When this option is dsabled the
 118       output LFE channel will only get a signal when an input LFE
 119       channel is available as well. If no input LFE channel is
 120       available the output LFE channel will always be 0. If no output
 121       LFE channel is available the signal on the input LFE channel
 122       will be ignored. Defaults to <opt>no</opt>.</p>
 123     </option>
 124
 125     <option>
 126       <p><opt>use-pid-file=</opt> Create a PID file in the runtime directory
 127       (<file>$HOME/.pulse/*-runtime/pid</file>). If this is enabled you may
 128       use commands like <opt>--kill</opt> or <opt>--check</opt>. If
 129       you are planning to start more than one PulseAudio process per
 130       user, you better disable this option since it effectively
 131       disables multiple instances. Takes a boolean argument, defaults
 132       to <opt>yes</opt>. The <opt>--use-pid-file</opt> command line
 133       option takes precedence.</p>
 134     </option>
 135
 136     <option>
 137       <p><opt>cpu-limit=</opt> If disabled do not install the CPU load
 138       limiter, even on platforms where it is supported. This option is
 139       useful when debugging/profiling PulseAudio to disable disturbing
 140       SIGXCPU signals. Takes a boolean argument, defaults to
 141       <opt>no</opt>. The <opt>--no-cpu-limit</opt> command line
 142       argument takes precedence.</p>
 143     </option>
 144
 145     <option>
 146       <p><opt>system-instance=</opt> Run the daemon as system-wide
 147       instance, requires root priviliges. Takes a boolean argument,
 148       defaults to <opt>no</opt>. The <opt>--system</opt> command line
 149       argument takes precedence.</p>
 150     </option>
 151
 152     <option>
 153       <p><opt>enable-shm=</opt> Enable data transfer via POSIX
 154       shared memory. Takes a boolean argument, defaults to
 155       <opt>yes</opt>. The <opt>--disable-shm</opt> command line
 156       argument takes precedence.</p>
 157     </option>
 158
 159     <option>
 160       <p><opt>shm-size-bytes=</opt> Sets the shared memory segment
 161       size for the daemon, in bytes. If left unspecified or is set to 0
 162       it will default to some system-specific default, usually 64
 163       MiB. Please note that usually there is no need to change this
 164       value, unless you are running an OS kernel that does not do
 165       memory overcommit.</p>
 166     </option>
 167
 168     <option>
 169       <p><opt>lock-memory=</opt> Locks the entire PulseAudio process
 170       into memory. While this might increase drop-out safety when used
 171       in conjunction with real-time scheduling this takes away a lot
 172       of memory from other processes and might hence considerably slow
 173       down your system. Defaults to <opt>no</opt>.</p>
 174     </option>
 175
 176     <option>
 177       <p><opt>flat-volumes=</opt> Enable 'flat' volumes, i.e. where
 178       possible let the sink volume equal the maximum of the volumes of
 179       the inputs connected to it. Takes a boolean argument, defaults
 180       to <opt>yes</opt>.</p>
 181     </option>
 182
 183   </section>
 184
 185   <section name="Scheduling">
 186
 187     <option>
 188       <p><opt>high-priority=</opt> Renice the daemon after startup to
 189       become a high-priority process. This a good idea if you
 190       experience drop-outs during playback. However, this is a certain
 191       security issue, since it works when called SUID root only, or
 192       RLIMIT_NICE is used. root is dropped immediately after gaining
 193       the nice level on startup, thus it is presumably safe. See
 194       <manref section="1" name="pulseaudio"/> for more
 195       information. Takes a boolean argument, defaults to <opt>yes</opt>. The <opt>--high-priority</opt>
 196       command line option takes precedence.</p>
 197     </option>
 198
 199     <option>
 200       <p><opt>realtime-scheduling=</opt> Try to acquire SCHED_FIFO
 201       scheduling for the IO threads. The same security concerns as
 202       mentioned above apply. However, if PA enters an endless loop,
 203       realtime scheduling causes a system lockup. Thus, realtime
 204       scheduling should only be enabled on trusted machines for
 205       now. Please not that only the IO threads of PulseAudio are made
 206       real-time. The controlling thread is left a normally scheduled
 207       thread. Thus enabling the high-priority option is orthogonal.
 208       See <manref section="1" name="pulseaudio"/> for more
 209       information. Takes a boolean argument, defaults to <opt>yes</opt>. The
 210       <opt>--realtime</opt> command line option takes precedence.</p>
 211     </option>
 212
 213     <option>
 214       <p><opt>realtime-priority=</opt> The realtime priority to
 215       acquire, if <opt>realtime-scheduling</opt> is enabled. Note: JACK uses 10
 216       by default, 9 for clients. Thus it is recommended to choose the
 217       PulseAudio real-time priorities lower. Some PulseAudio threads
 218       might choose a priority a little lower or higher than the
 219       specified value. Defaults to <opt>5</opt>.</p>
 220     </option>
 221
 222     <option>
 223       <p><opt>nice-level=</opt> The nice level to acquire for the
 224       daemon, if <opt>high-priority</opt> is enabled. Note: on some
 225       distributions X11 uses -10 by default. Defaults to -11.</p>
 226     </option>
 227
 228   </section>
 229
 230   <section name="Idle Times">
 231
 232     <option>
 233       <p><opt>exit-idle-time=</opt> Terminate the daemon after the
 234       last client quit and this time in seconds passed. Use a negative value to
 235       disable this feature. Defaults to 20. The
 236       <opt>--exit-idle-time</opt> command line option takes
 237       precedence.</p>
 238     </option>
 239
 240     <option>
 241       <p><opt>scache-idle-time=</opt> Unload autoloaded sample cache
 242       entries after being idle for this time in seconds. Defaults to
 243       20. The <opt>--scache-idle-time</opt> command line option takes
 244       precedence.</p>
 245     </option>
 246
 247   </section>
 248
 249   <section name="Paths">
 250
 251     <option>
 252       <p><opt>dl-search-path=</opt> The path were to look for dynamic
 253       shared objects (DSOs/plugins). You may specify more than one
 254       path seperated by colons. The default path depends on compile
 255       time settings. The <opt>--dl-search-path</opt> command line
 256       option takes precedence. </p>
 257     </option>
 258
 259     <option>
 260       <p><opt>default-script-file=</opt> The default configuration
 261       script file to load. Specify an empty string for not loading a
 262       default script file. The default behaviour is to load
 263       <file>~/.pulse/default.pa</file>, and if that file does not
 264       exist fall back to the system wide installed version
 265       <file>@PA_DEFAULT_CONFIG_DIR@/default.pa</file>. If run in system-wide
 266       mode the file <file>@PA_DEFAULT_CONFIG_DIR@/system.pa</file> is used
 267       instead. If <opt>-n</opt> is passed on the command line
 268       or <opt>default-script-file=</opt> is disabled the default
 269       configuration script is ignored.</p>
 270     </option>
 271
 272     <option>
 273       <p><opt>load-default-script-file=</opt> Load the default
 274       configuration script file as specified
 275       in <opt>default-script-file=</opt>. Defaults to <opt>yes</opt>.</p>
 276     </option>
 277
 278   </section>
 279
 280   <section name="Logging">
 281
 282     <option>
 283       <p><opt>log-target=</opt> The default log target. Use either
 284       <opt>stderr</opt>, <opt>syslog</opt> or <opt>auto</opt>. The
 285       latter is equivalent to <opt>sylog</opt> in case
 286       <opt>daemonize</opt> is enabled, otherwise to
 287       <opt>stderr</opt>. Defaults to <opt>auto</opt>. The
 288       <opt>--log-target</opt> command line option takes
 289       precedence.</p>
 290     </option>
 291
 292     <option>
 293       <p><opt>log-level=</opt> Log level, one of <opt>debug</opt>,
 294       <opt>info</opt>, <opt>notice</opt>, <opt>warning</opt>,
 295       <opt>error</opt>. Log messages with a lower log level than
 296       specified here are not logged. Defaults to
 297       <opt>notice</opt>. The <opt>--log-level</opt> command line
 298       option takes precedence. The <opt>-v</opt> command line option
 299       might alter this setting.</p>
 300     </option>
 301
 302     <option>
 303       <p><opt>log-meta=</opt> With each logged message log the code
 304       location the message was generated from. Defaults to
 305       <opt>no</opt>.</p>
 306     </option>
 307
 308     <option>
 309       <p><opt>log-time=</opt> With each logged messages log the
 310       relative time since startup. Defaults to <opt>no</opt>.</p>
 311     </option>
 312
 313     <option>
 314       <p><opt>log-backtrace=</opt> When greater than 0, with each
 315       logged message log a code stack trace up the the specified
 316       number of stack frames. Defaults to <opt>0</opt>.</p>
 317     </option>
 318
 319   </section>
 320
 321   <section name="Resource Limits">
 322
 323     <p>See <manref name="getrlimit" section="2"/> for
 324     more information. Set to -1 if PulseAudio shall not touch the resource
 325     limit. Not all resource limits are available on all operating
 326     systems.</p>
 327
 328     <option>
 329       <p><opt>rlimit-as</opt> Defaults to -1.</p>
 330     </option>
 331     <option>
 332       <p><opt>rlimit-rss</opt> Defaults to -1.</p>
 333     </option>
 334     <option>
 335       <p><opt>rlimit-core</opt> Defaults to -1.</p>
 336     </option>
 337     <option>
 338       <p><opt>rlimit-data</opt> Defaults to -1.</p>
 339     </option>
 340     <option>
 341       <p><opt>rlimit-fsize</opt> Defaults to -1.</p>
 342     </option>
 343     <option>
 344       <p><opt>rlimit-nofile</opt> Defaults to 256.</p>
 345     </option>
 346     <option>
 347       <p><opt>rlimit-stack</opt> Defaults to -1.</p>
 348     </option>
 349     <option>
 350       <p><opt>rlimit-nproc</opt> Defaults to -1.</p>
 351     </option>
 352     <option>
 353       <p><opt>rlimit-locks</opt> Defaults to -1.</p>
 354     </option>
 355     <option>
 356       <p><opt>rlimit-sigpending</opt> Defaults to -1.</p>
 357     </option>
 358     <option>
 359       <p><opt>rlimit-msgqueue</opt> Defaults to -1.</p>
 360     </option>
 361     <option>
 362       <p><opt>rlimit-memlock</opt> Defaults to 16 KiB. Please note
 363       that the JACK client libraries may require more locked
 364       memory.</p>
 365     </option>
 366     <option>
 367       <p><opt>rlimit-nice</opt> Defaults to 31. Please make sure that
 368       the default nice level as configured with <opt>nice-level</opt>
 369       fits in this resource limit, if <opt>high-priority</opt> is
 370       enabled.</p>
 371     </option>
 372     <option>
 373       <p><opt>rlimit-rtprio</opt> Defaults to 9. Please make sure that
 374       the default real-time priority level as configured with
 375       <opt>realtime-priority=</opt> fits in this resource limit, if
 376       <opt>realtime-scheduling</opt> is enabled. The JACK client
 377       libraries require a real-time prority of 9 by default. </p>
 378     </option>
 379     <option>
 380       <p><opt>rlimit-rttime</opt> Defaults to 1000000.</p>
 381     </option>
 382
 383   </section>
 384
 385   <section name="Default Device Settings">
 386
 387     <p>Most drivers try to open the audio device with these settings
 388     and then fall back to lower settings. The default settings are CD
 389     quality: 16bit native endian, 2 channels, 44100 Hz sampling.</p>
 390
 391     <option>
 392       <p><opt>default-sample-format=</opt> The default sampling
 393       format. Specify one of <opt>u8</opt>, <opt>s16le</opt>,
 394       <opt>s16be</opt>, <opt>s24le</opt>, <opt>s24be</opt>,
 395       <opt>s24-32le</opt>, <opt>s24-32be</opt>, <opt>s32le</opt>,
 396       <opt>s32be</opt> <opt>float32le</opt>, <opt>float32be</opt>,
 397       <opt>ulaw</opt>, <opt>alaw</opt>. Depending on the endianess of
 398       the CPU the formats <opt>s16ne</opt>, <opt>s16re</opt>,
 399       <opt>s24ne</opt>, <opt>s24re</opt>, <opt>s24-32ne</opt>,
 400       <opt>s24-32re</opt>, <opt>s32ne</opt>, <opt>s32re</opt>,
 401       <opt>float32ne</opt>, <opt>float32re</opt> (for native,
 402       resp. reverse endian) are available as aliases.</p>
 403     </option>
 404
 405     <option>
 406       <p><opt>default-sample-rate=</opt> The default sample frequency.</p>
 407     </option>
 408
 409     <option>
 410       <p><opt>default-sample-channels</opt> The default number of channels.</p>
 411     </option>
 412
 413     <option>
 414       <p><opt>default-channel-map</opt> The default channel map.</p>
 415     </option>
 416
 417   </section>
 418
 419   <section name="Default Fragment Settings">
 420
 421     <p>Some hardware drivers require the hardware playback buffer to
 422     be subdivided into several fragments. It is possible to change
 423     these buffer metrics for machines with high scheduling
 424     latencies. Not all possible values that may be configured here are
 425     available in all hardware. The driver will to find the nearest
 426     setting supported. Modern drivers that support timer-based
 427     scheduling ignore these options.</p>
 428
 429     <option>
 430       <p><opt>default-fragments=</opt> The default number of
 431       fragments. Defaults to 4.</p>
 432     </option>
 433     <option>
 434       <p><opt>default-fragment-size-msec=</opt>The duration of a
 435       single fragment. Defaults to 25ms (i.e. the total buffer is thus
 436       100ms long).</p>
 437     </option>
 438
 439   </section>
 440
 441   <section name="Default Sync Volume Settings">
 442
 443     <p>With the flat volume feature enabled, the sink HW volume is set
 444     to the same level as the highest volume input stream. Any other streams
 445     (with lower volumes) have the appropriate adjustment applied in SW to
 446     bring them to the correct overall level. Sadly hadware mixer changes
 447     cannot be timed accurately and thus this change of volumes can somtimes
 448     cause the resulting output sound to be momentarily too loud or too soft.
 449     So to ensure SW and HW volumes are applied concurrently without any
 450     glitches, their application needs to be synchronized. The sink
 451     implementation needs to support synchronized volumes. The following
 452     parameters can be used to refine the process.</p>
 453
 454     <option>
 455       <p><opt>enable-sync-volume=</opt> Enable sync volume for the sinks that
 456       support it. This feature is enabled by default.</p>
 457     </option>
 458     <option>
 459       <p><opt>sync-volume-safety-margin-usec=</opt> The amount of time (in
 460       usec) by which the HW volume increases are delayed and HW volume
 461       decreases are advanced. Defaults to 8000 usec.</p>
 462     </option>
 463     <option>
 464       <p><opt>sync-volume-extra-delay-usec=</opt> The amount of time (in usec)
 465       by which HW volume changes are delayed. Negative values are also allowed.
 466       Defaults to 0.</p>
 467     </option>
 468
 469   </section>
 470
 471   <section name="Authors">
 472     <p>The PulseAudio Developers &lt;@PACKAGE_BUGREPORT@&gt;; PulseAudio is available from <url href="@PACKAGE_URL@"/></p>
 473   </section>
 474
 475   <section name="See also">
 476     <p>
 477       <manref name="pulse-client.conf" section="5"/>, <manref name="default.pa" section="5"/>, <manref name="pulseaudio" section="1"/>, <manref name="pacmd" section="1"/>
 478     </p>
 479   </section>
 480
 481 </manpage>