code.delx.au - pulseaudio/blob - 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>~/.config/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>~/.config/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       disabled 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-1</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 disabled when upmixing or
 117       downmixing ignore LFE channels. When this option is disabled 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>$XDG_RUNTIMEDIR/pulse/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 privileges. 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>local-server-type=</opt> Please don't use this option if
 154       you don't have to! This option is currently only useful when you
 155       want D-Bus clients to use a remote server. This option may be
 156       removed in future versions. If you only want to run PulseAudio
 157       in the system mode, use the <opt>system-instance</opt> option.
 158       This option takes one of <opt>user</opt>, <opt>system</opt> or
 159       <opt>none</opt> as the argument. This is essentially a duplicate
 160       for the <opt>system-instance</opt> option. The difference is the
 161       <opt>none</opt> option, which is useful when you want to use a
 162       remote server with D-Bus clients. If both this and
 163       <opt>system-instance</opt> are defined, this option takes
 164       precedence. Defaults to whatever the <opt>system-instance</opt>
 165       is set.</p>
 166     </option>
 167
 168     <option>
 169       <p><opt>enable-shm=</opt> Enable data transfer via POSIX
 170       shared memory. Takes a boolean argument, defaults to
 171       <opt>yes</opt>. The <opt>--disable-shm</opt> command line
 172       argument takes precedence.</p>
 173     </option>
 174
 175     <option>
 176       <p><opt>shm-size-bytes=</opt> Sets the shared memory segment
 177       size for the daemon, in bytes. If left unspecified or is set to 0
 178       it will default to some system-specific default, usually 64
 179       MiB. Please note that usually there is no need to change this
 180       value, unless you are running an OS kernel that does not do
 181       memory overcommit.</p>
 182     </option>
 183
 184     <option>
 185       <p><opt>lock-memory=</opt> Locks the entire PulseAudio process
 186       into memory. While this might increase drop-out safety when used
 187       in conjunction with real-time scheduling this takes away a lot
 188       of memory from other processes and might hence considerably slow
 189       down your system. Defaults to <opt>no</opt>.</p>
 190     </option>
 191
 192     <option>
 193       <p><opt>flat-volumes=</opt> Enable 'flat' volumes, i.e. where
 194       possible let the sink volume equal the maximum of the volumes of
 195       the inputs connected to it. Takes a boolean argument, defaults
 196       to <opt>yes</opt>.</p>
 197     </option>
 198
 199   </section>
 200
 201   <section name="Scheduling">
 202
 203     <option>
 204       <p><opt>high-priority=</opt> Renice the daemon after startup to
 205       become a high-priority process. This a good idea if you
 206       experience drop-outs during playback. However, this is a certain
 207       security issue, since it works when called SUID root only, or
 208       RLIMIT_NICE is used. root is dropped immediately after gaining
 209       the nice level on startup, thus it is presumably safe. See
 210       <manref section="1" name="pulseaudio"/> for more
 211       information. Takes a boolean argument, defaults to <opt>yes</opt>. The <opt>--high-priority</opt>
 212       command line option takes precedence.</p>
 213     </option>
 214
 215     <option>
 216       <p><opt>realtime-scheduling=</opt> Try to acquire SCHED_FIFO
 217       scheduling for the IO threads. The same security concerns as
 218       mentioned above apply. However, if PA enters an endless loop,
 219       realtime scheduling causes a system lockup. Thus, realtime
 220       scheduling should only be enabled on trusted machines for
 221       now. Please not that only the IO threads of PulseAudio are made
 222       real-time. The controlling thread is left a normally scheduled
 223       thread. Thus enabling the high-priority option is orthogonal.
 224       See <manref section="1" name="pulseaudio"/> for more
 225       information. Takes a boolean argument, defaults to <opt>yes</opt>. The
 226       <opt>--realtime</opt> command line option takes precedence.</p>
 227     </option>
 228
 229     <option>
 230       <p><opt>realtime-priority=</opt> The realtime priority to
 231       acquire, if <opt>realtime-scheduling</opt> is enabled. Note: JACK uses 10
 232       by default, 9 for clients. Thus it is recommended to choose the
 233       PulseAudio real-time priorities lower. Some PulseAudio threads
 234       might choose a priority a little lower or higher than the
 235       specified value. Defaults to <opt>5</opt>.</p>
 236     </option>
 237
 238     <option>
 239       <p><opt>nice-level=</opt> The nice level to acquire for the
 240       daemon, if <opt>high-priority</opt> is enabled. Note: on some
 241       distributions X11 uses -10 by default. Defaults to -11.</p>
 242     </option>
 243
 244   </section>
 245
 246   <section name="Idle Times">
 247
 248     <option>
 249       <p><opt>exit-idle-time=</opt> Terminate the daemon after the
 250       last client quit and this time in seconds passed. Use a negative value to
 251       disable this feature. Defaults to 20. The
 252       <opt>--exit-idle-time</opt> command line option takes
 253       precedence.</p>
 254     </option>
 255
 256     <option>
 257       <p><opt>scache-idle-time=</opt> Unload autoloaded sample cache
 258       entries after being idle for this time in seconds. Defaults to
 259       20. The <opt>--scache-idle-time</opt> command line option takes
 260       precedence.</p>
 261     </option>
 262
 263   </section>
 264
 265   <section name="Paths">
 266
 267     <option>
 268       <p><opt>dl-search-path=</opt> The path where to look for dynamic
 269       shared objects (DSOs/plugins). You may specify more than one
 270       path separated by colons. The default path depends on compile
 271       time settings. The <opt>--dl-search-path</opt> command line
 272       option takes precedence. </p>
 273     </option>
 274
 275     <option>
 276       <p><opt>default-script-file=</opt> The default configuration
 277       script file to load. Specify an empty string for not loading a
 278       default script file. The default behaviour is to load
 279       <file>~/.config/pulse/default.pa</file>, and if that file does not
 280       exist fall back to the system wide installed version
 281       <file>@PA_DEFAULT_CONFIG_DIR@/default.pa</file>. If run in system-wide
 282       mode the file <file>@PA_DEFAULT_CONFIG_DIR@/system.pa</file> is used
 283       instead. If <opt>-n</opt> is passed on the command line
 284       or <opt>default-script-file=</opt> is disabled the default
 285       configuration script is ignored.</p>
 286     </option>
 287
 288     <option>
 289       <p><opt>load-default-script-file=</opt> Load the default
 290       configuration script file as specified
 291       in <opt>default-script-file=</opt>. Defaults to <opt>yes</opt>.</p>
 292     </option>
 293
 294   </section>
 295
 296   <section name="Logging">
 297
 298     <option>
 299       <p><opt>log-target=</opt> The default log target. Use either
 300       <opt>stderr</opt>, <opt>syslog</opt>, <opt>journal</opt> (optional),
 301       <opt>auto</opt>, <opt>file:PATH</opt> or <opt>newfile:PATH</opt>. On traditional
 302       systems <opt>auto</opt> is equivalent to <opt>syslog</opt>. On systemd-enabled
 303       systems, auto is equivalent to <opt>journal</opt>, in case <opt>daemonize</opt>
 304       is enabled, and to <opt>stderr</opt> otherwise. If set to <opt>file:PATH</opt>,
 305       logging is directed to the file indicated by PATH. <opt>newfile:PATH</opt> is
 306       otherwise the same as <opt>file:PATH</opt>, but existing files are never
 307       overwritten. If the specified file already exists, a suffix is added to
 308       the file name to avoid overwriting. Defaults to <opt>auto</opt>. The
 309       <opt>--log-target</opt> command line option takes precedence.</p>
 310     </option>
 311
 312     <option>
 313       <p><opt>log-level=</opt> Log level, one of <opt>debug</opt>,
 314       <opt>info</opt>, <opt>notice</opt>, <opt>warning</opt>,
 315       <opt>error</opt>. Log messages with a lower log level than
 316       specified here are not logged. Defaults to
 317       <opt>notice</opt>. The <opt>--log-level</opt> command line
 318       option takes precedence. The <opt>-v</opt> command line option
 319       might alter this setting.</p>
 320     </option>
 321
 322     <option>
 323       <p><opt>log-meta=</opt> With each logged message log the code
 324       location the message was generated from. Defaults to
 325       <opt>no</opt>.</p>
 326     </option>
 327
 328     <option>
 329       <p><opt>log-time=</opt> With each logged message log the
 330       relative time since startup. Defaults to <opt>no</opt>.</p>
 331     </option>
 332
 333     <option>
 334       <p><opt>log-backtrace=</opt> When greater than 0, with each
 335       logged message log a code stack trace up the specified
 336       number of stack frames. Defaults to <opt>0</opt>.</p>
 337     </option>
 338
 339   </section>
 340
 341   <section name="Resource Limits">
 342
 343     <p>See <manref name="getrlimit" section="2"/> for
 344     more information. Set to -1 if PulseAudio shall not touch the resource
 345     limit. Not all resource limits are available on all operating
 346     systems.</p>
 347
 348     <option>
 349       <p><opt>rlimit-as</opt> Defaults to -1.</p>
 350     </option>
 351     <option>
 352       <p><opt>rlimit-rss</opt> Defaults to -1.</p>
 353     </option>
 354     <option>
 355       <p><opt>rlimit-core</opt> Defaults to -1.</p>
 356     </option>
 357     <option>
 358       <p><opt>rlimit-data</opt> Defaults to -1.</p>
 359     </option>
 360     <option>
 361       <p><opt>rlimit-fsize</opt> Defaults to -1.</p>
 362     </option>
 363     <option>
 364       <p><opt>rlimit-nofile</opt> Defaults to 256.</p>
 365     </option>
 366     <option>
 367       <p><opt>rlimit-stack</opt> Defaults to -1.</p>
 368     </option>
 369     <option>
 370       <p><opt>rlimit-nproc</opt> Defaults to -1.</p>
 371     </option>
 372     <option>
 373       <p><opt>rlimit-locks</opt> Defaults to -1.</p>
 374     </option>
 375     <option>
 376       <p><opt>rlimit-sigpending</opt> Defaults to -1.</p>
 377     </option>
 378     <option>
 379       <p><opt>rlimit-msgqueue</opt> Defaults to -1.</p>
 380     </option>
 381     <option>
 382       <p><opt>rlimit-memlock</opt> Defaults to 16 KiB. Please note
 383       that the JACK client libraries may require more locked
 384       memory.</p>
 385     </option>
 386     <option>
 387       <p><opt>rlimit-nice</opt> Defaults to 31. Please make sure that
 388       the default nice level as configured with <opt>nice-level</opt>
 389       fits in this resource limit, if <opt>high-priority</opt> is
 390       enabled.</p>
 391     </option>
 392     <option>
 393       <p><opt>rlimit-rtprio</opt> Defaults to 9. Please make sure that
 394       the default real-time priority level as configured with
 395       <opt>realtime-priority=</opt> fits in this resource limit, if
 396       <opt>realtime-scheduling</opt> is enabled. The JACK client
 397       libraries require a real-time priority of 9 by default.</p>
 398     </option>
 399     <option>
 400       <p><opt>rlimit-rttime</opt> Defaults to 1000000.</p>
 401     </option>
 402
 403   </section>
 404
 405   <section name="Default Device Settings">
 406
 407     <p>Most drivers try to open the audio device with these settings
 408     and then fall back to lower settings. The default settings are CD
 409     quality: 16bit native endian, 2 channels, 44100 Hz sampling.</p>
 410
 411     <option>
 412       <p><opt>default-sample-format=</opt> The default sampling
 413       format. Specify one of <opt>u8</opt>, <opt>s16le</opt>,
 414       <opt>s16be</opt>, <opt>s24le</opt>, <opt>s24be</opt>,
 415       <opt>s24-32le</opt>, <opt>s24-32be</opt>, <opt>s32le</opt>,
 416       <opt>s32be</opt> <opt>float32le</opt>, <opt>float32be</opt>,
 417       <opt>ulaw</opt>, <opt>alaw</opt>. Depending on the endianness of
 418       the CPU the formats <opt>s16ne</opt>, <opt>s16re</opt>,
 419       <opt>s24ne</opt>, <opt>s24re</opt>, <opt>s24-32ne</opt>,
 420       <opt>s24-32re</opt>, <opt>s32ne</opt>, <opt>s32re</opt>,
 421       <opt>float32ne</opt>, <opt>float32re</opt> (for native,
 422       resp. reverse endian) are available as aliases.</p>
 423     </option>
 424
 425     <option>
 426       <p><opt>default-sample-rate=</opt> The default sample frequency.</p>
 427     </option>
 428
 429     <option>
 430       <p><opt>default-sample-channels</opt> The default number of channels.</p>
 431     </option>
 432
 433     <option>
 434       <p><opt>default-channel-map</opt> The default channel map.</p>
 435     </option>
 436
 437     <option>
 438       <p><opt>alternate-sample-rate</opt> The alternate sample
 439       frequency. Sinks and sources will use either the
 440       default-sample-rate value or this alternate value, typically 44.1
 441       or 48kHz. Switching between default and alternate values is
 442       enabled only when the sinks/sources are suspended. This option
 443       is ignored in passthrough mode where the stream rate will be used.
 444       If set to the same value as the default sample rate, this feature is
 445       disabled.</p>
 446     </option>
 447
 448   </section>
 449
 450   <section name="Default Fragment Settings">
 451
 452     <p>Some hardware drivers require the hardware playback buffer to
 453     be subdivided into several fragments. It is possible to change
 454     these buffer metrics for machines with high scheduling
 455     latencies. Not all possible values that may be configured here are
 456     available in all hardware. The driver will find the nearest
 457     setting supported. Modern drivers that support timer-based
 458     scheduling ignore these options.</p>
 459
 460     <option>
 461       <p><opt>default-fragments=</opt> The default number of
 462       fragments. Defaults to 4.</p>
 463     </option>
 464     <option>
 465       <p><opt>default-fragment-size-msec=</opt>The duration of a
 466       single fragment. Defaults to 25ms (i.e. the total buffer is thus
 467       100ms long).</p>
 468     </option>
 469
 470   </section>
 471
 472   <section name="Default Deferred Volume Settings">
 473
 474     <p>With the flat volume feature enabled, the sink HW volume is set
 475     to the same level as the highest volume input stream. Any other streams
 476     (with lower volumes) have the appropriate adjustment applied in SW to
 477     bring them to the correct overall level. Sadly hardware mixer changes
 478     cannot be timed accurately and thus this change of volumes can sometimes
 479     cause the resulting output sound to be momentarily too loud or too soft.
 480     So to ensure SW and HW volumes are applied concurrently without any
 481     glitches, their application needs to be synchronized. The sink
 482     implementation needs to support deferred volumes. The following
 483     parameters can be used to refine the process.</p>
 484
 485     <option>
 486       <p><opt>enable-deferred-volume=</opt> Enable deferred volume for the sinks that
 487       support it. This feature is enabled by default.</p>
 488     </option>
 489     <option>
 490       <p><opt>deferred-volume-safety-margin-usec=</opt> The amount of time (in
 491       usec) by which the HW volume increases are delayed and HW volume
 492       decreases are advanced. Defaults to 8000 usec.</p>
 493     </option>
 494     <option>
 495       <p><opt>deferred-volume-extra-delay-usec=</opt> The amount of time (in usec)
 496       by which HW volume changes are delayed. Negative values are also allowed.
 497       Defaults to 0.</p>
 498     </option>
 499
 500   </section>
 501
 502   <section name="Authors">
 503     <p>The PulseAudio Developers &lt;@PACKAGE_BUGREPORT@&gt;; PulseAudio is available from <url href="@PACKAGE_URL@"/></p>
 504   </section>
 505
 506   <section name="See also">
 507     <p>
 508       <manref name="pulse-client.conf" section="5"/>, <manref name="default.pa" section="5"/>, <manref name="pulseaudio" section="1"/>, <manref name="pacmd" section="1"/>
 509     </p>
 510   </section>
 511
 512 </manpage>