PulseAudio/Configuration

From ArchWiki
Jump to: navigation, search

Merge-arrows-2.pngThis article or section is a candidate for merging with PulseAudio.Merge-arrows-2.png

Notes: Most of valuable informations have been merged; when it is done completely, please redirect this page to PulseAudio#Configuration. (Discuss in Talk:PulseAudio/Configuration#)
PulseAudio PulseAudio is a general purpose sound server intended to run as a middleware between your applications and your hardware devices, either using ALSA or OSS. In its default configuration, PulseAudio attemps to make controlling and routing audio streams to the correct place easier with its own graphical configuration tools and deep integration in some desktop environments, like the sound applet in GNOME or plasma-pa in KDE Plasma. It also offers easy network streaming accross local devices using Avahi if enabled. While its main purpose is to ease audio configuration, its modular design allows more advanced users to configure the daemon precisely to best suit their needs.

Installation

PulseAudio only requires the pulseaudio package to run, but you may also want to install various other tools to help you configure it and integrate better with your desktop environment.

PulseAudio packages
Package Usage
pulseaudio (required) The main daemon, commandline tools and libraries.
pulseaudio-alsa Provides an /etc/asound.conf configuration file that sets the ALSA default plugin to pulse, thus redirecting playback and capture to PulseAudio. Highly recommended to avoid conflicts between ALSA applications and PulseAudio if you intend to run PulseAudio all the time and use the default configuration.
paprefs A GUI for general daemon configuration.
pavucontrol An advanced volume control GUI: allows to change the volume of individual streams and configure the ports of all sound cards.
ponymix and pamixer-gitAUR CLI mixers similar to pavucontrol.
PaWebControl A web GUI similar to pavucontrol to remotely control volumes (like from a mobile device).
pasystray-gitAUR A system tray for volume adjustment as well as a few basic operations like switching sinks and sources.
kdemultimedia-kmix KDE's default volume control applet with similar functions to pavucontrol.
kdeplasma-applets-veromixAUR[broken link: archived in aur-mirror] An advanced PulseAudio applet for KDE.

Easy configuration

By default, PulseAudio is configured to automatically detect all sound cards and manage them. It takes control of all detected ALSA devices and redirect all audio streams to itself, making the PulseAudio daemon the central configuration point. The daemon should work mostly out of the box, only requiring a few minor tweaks using the GUI configuration tools. All settings are saved in ~/.config/pulse and automatically restored when the daemon starts. Use the following tools to configure the daemon to your taste:

paprefs

  • Simultaneous output to all sound cards
  • Network device streaming and discovery (requires Avahi daemon to be installed and running): play sound on any computer on your network from any computer.

pavucontrol

  • Per-application volume control
  • Manage input and output devices volumes and outputs
  • Sound card configuration to select input/output ports to use and enable/disable devices
Warning: Do not attempt to change the ALSA configuration files while using the default PulseAudio configuration. The default configuration grabs the hardware devices directly in order to allow all the on-the-fly configurations using the GUIs. Changes to the ALSA configurations will very likely be ignored by PulseAudio and ALSA applications will break randomly while trying to access an ALSA device already used by PulseAudio. If you intend to change the ALSA configurations, also configure PulseAudio manually to output to your own ALSA device and play nice with your configuration.

Advanced configuration

While PulseAudio usually runs fine out of the box and requires only minimal configuration, advanced users can change almost every aspect of the daemon by either altering the default configuration file to disable modules or writing your own from scratch. PulseAudio runs as a server daemon that can run either system-wide or on per-user basis using a client/server architecture. The daemon by itself does nothing without its modules except to provide an API and host dynamically loaded modules. The audio routing and processing tasks are all handled by various modules, including Pulse's native protocol itself (provided by module-native-protocol-unix). Clients reach the server through one of many protocol modules that will accept audio from external sources, route it through PulseAudio and eventually have it go out through a final other module. The output module does not have to be an actual sound output: it can dump the stream into a file, stream it to a broadcasting server such as Icecast, or even just discard it.

Configuration files

PulseAudio can be configured in multiple ways depending on your needs and uses multiple different configuration files. Configuration files are read from ~/.config/pulse/ first, then from /etc/pulse/ for system-wide defaults. People usually change the system-wide version unless they intend to have multiple users with different configurations.

daemon.conf

This is the main configuration file to configure the daemon itself. It defines base settings like the default sample rates used by modules, resampling methods, realtime scheduling and various other settings related to the server process. These can not be changed at runtime without restarting the PulseAudio daemon. Most defaults make sense here and are self-explaining, see the pulse-daemon.conf man page for additional information. Boolean options accepts any of these: true, yes, on and 1 as well as false, no, off and 0.

Notable configuration options
Option Description
system-instance If set to yes, the daemon will run as a system-wide instance. Highly discouraged as it can introduce security issues. Can be used when multiple users will use sound at the same time, either remotely or locally using Xorg multiseat. Defaults to no.
realtime-scheduling If your kernel supports realtime scheduling (for instance, Kernels#-rt or Kernels#-ck), set this to yes to ensure PulseAudio can deliver low-latency glitch-free playback. You can adjust realtime-priority as well to have it use the correct priority, especially when JACK is also running on the system.
exit-idle-time If you want to run PulseAudio only when needed and use ALSA otherwise, you can set a delay in seconds after which the daemon will automatically shutdown after all clients are disconnected. Set it to -1 to disable this feature.
resample-method When PulseAudio needs to pass audio from one module to another using incompatible sample-rate (for example, playback at 96kHz to a card that only supports a maximum of 48kHz), specifies which resampler to use. You can use the command $ pulseaudio --dump-resample-methods to list all available resamplers and choose the best tradeoff between CPU usage and audio quality for your taste.
Tip: One of the major complaint about PulseAudio is its high CPU usage in some use cases. A lot of these cases happens when pulse needs to resample multiple streams (individually). If you intend to mix multiple sample rates often, consider creating an additional sink at the correct sample rate which you can then feed back to your main sink, resampling only once.
enable-remixing When the input and output have a different channel count (for example, outputting a 6 channel movie into a stereo sink), pulse can either remix all the channels (default, yes) or just trivially map the channels by their name (left goes to left, right to right, all others ignored) when no
flat-volumes If yes (default), all input sources have their volume relative to the maximum volume of the entire sound card. This allows each application to individually adjust their volume so for example, raising your VoIP call volume will raise the hardware volume and adjust your music player volume so it stays where it was, avoiding confusion by having to lower manually the music player then raise the global volume.
Warning: Sometimes this can be more confusing than what it solves and some applications unaware of this feature can set their volume at 100% at startup, potentially blowing your speakers or your ears. If unsure, prefer to set this to no so pulse will use the classic ALSA behavior instead.
default-fragments Audio samples are splitted into multiple fragments of default-fragment-size-msec each. The larger the buffer is, the less likely audio will skip when the system is overloaded, but will also increase the overall latency. Increase this value if you have issues.
default-fragment-size-msec The size in milliseconds of each fragment. This is the amount of data that will be processed at once by the daemon. TODO: Verify


default.pa

This file is a startup script and is used to configure modules. It is actually parsed and read after the daemon has finished initializing and additional commands can be sent at runtime using $ pactl or $ pacmd. The startup script can also be provided on the command line by starting PulseAudio in a terminal using $ pulseaudio -nC. This will make the daemon load the CLI module and will accept the configuration directly from the command line, and output resulting information or error messages on the same terminal. This can be useful when debugging the daemon or just to test various modules before setting them permanently on disk. The manual page is quite self explaining, please consult man pulse-cli-syntax for the details of the syntax.

In order to configure the daemon, you will mostly only need the very basic commands:

Basic PA commands
Command Action
load-module module-name option1=value1 option2=value2 Loads a module called module-name with two options called option1 and option2
unload-module 42 or unload-module module-alsa-sink Unloads a module by its index (returned by the load-module command) or all modules by name.
.fail Allows all commands after this statement to fail without interrupting the script and shutting down the daemon. This is useful when you know some commands could fail and would not affect overall operation, like loading modules for removable devices or network devices that can potentially get unreachable.
.nofail Reverse of .fail: failing commands after this statement will interrupt the script and will cause the daemon to return an error.

There are plenty more commands available that are useful at runtime to control the daemon, see the pactl manpage for more details. Everything that an be made in pavucontrol can also be made on the command line, useful for bash scripts.


client.conf

This is the configuration file read by every PulseAudio client applications. It is used to configure runtime options for individual clients. It can be used to set the configure the default sink and source statically as well as allowing (or disallowing) clients to automatically start the server if not currently running.

Useful client.conf options
Option Description
autospawn If enabled, clients will automatically start PulseAudio if it is not already running when a client attempts to connect to it. This can be useful if you do not want PulseAudio to always be running to conserve system resources. Otherwise, you really should have it start with your X11 session.

Connection & authentication

Since PulseAudio runs as a daemon as the current user, clients needs to know where to find the daemon socket to connect to it as well as a shared random cookie file clients use to authenticate with it. By default, clients should be able to locate the daemon without problem using environment variables, X11 root window properties and finally by trying the default location (unix:/run/user/$ID/pulse/native). However, if you have clients that needs to access PulseAudio outside of your X11 session like mpd running as a different user, you will need to tell it how to connect to your PulseAudio instance. See PulseAudio/Examples#TODO[broken link: invalid section] for a complete example. An authentication cookie containing random bytes is enabled by default to ensure audio does not leak from one user to another on a multi-user system. If you already control who can access the server using user/group permissions, you can disable the cookie by passing auth-cookie-enabled=0 to module-native-protocol-unix.

Environment variables

These two variables are the important ones in order for libpulse clients to locate PulseAudio if you moved its socket to somewhere else. See man pulseaudio for more details and other useful environment variables clients will read.

Variable Definition
PULSE_SERVER Defines where the server is. It takes a protocol prefix like unix: or tcp followed by the path or IP of the server. Example: unix:/home/pulse/native-sock.
PULSE_COOKIE Point this to the location of a file that contains the random cookie generated by PulseAudio. This file will be read by clients and its content sent to the server, thus the file has to be readable by all audio clients. It does not need to be the same file, as long as its content matches the one the daemon uses.

X11 properties

PulseAudio also uses window properties on the root window of the X11 server to help find the daemon. Since environment variables cannot be modified after child processes are started , X11 properties are more flexible because they are more easily changed because they are globally shared. As long as applications receive a DISPLAY= environment variable, it can read the most up-to-date values. X11 properties can be queried using xprop -root, or with pax11publish -d to read pulse-specific properties. pax11publish can also be used to update the properties from environment variables (pax11publish -e or remove them entirely . If possible, it is recommended to let PulseAudio do it my itself using the module-x11-publish module or the start-pulseaudio-x11 command. The following table is there only for completeness, you should not ever need to manually set these variables by hand.

Variable Definition
PULSE_SERVER String value (xprop -root -f PULSE_SERVER 8s -set PULSE_SERVER "unix:/tmp/pulse-sock"), works the same as the environment variable of the same name.
PULSE_COOKIE String value that contains the hexadecimal representation of the authentication cookie.


Modules

Protocols

Tango-document-new.pngThis article is a stub.Tango-document-new.png

Notes: Local sound, network sound, file sounds, streaming servers (Discuss in Talk:PulseAudio/Configuration#)

ALSA

Tango-document-new.pngThis article is a stub.Tango-document-new.png

Notes: TODO: Explain both static ALSA configuration and automatic detection. How to use ALSA plugins. Mention that PulseAudio likes real hardware way better than plugins for latency and power-saving controls (Discuss in Talk:PulseAudio/Configuration#)

JACK

Tango-document-new.pngThis article is a stub.Tango-document-new.png

Notes: Jack auto-detection or static Jack client (Discuss in Talk:PulseAudio/Configuration#)

Filters & Routing

Tango-document-new.pngThis article is a stub.Tango-document-new.png

Notes: Collection of useful modules for audio processing (EQ) and routing (combining card, splitting cards, imitating JACK features (Discuss in Talk:PulseAudio/Configuration#)


Further resources

Tango-document-new.pngThis article is a stub.Tango-document-new.png

Notes: Links to useful documentation, official PA wiki, manual pages, etc. (Discuss in Talk:PulseAudio/Configuration#)