KDE PulseAudio Integration

This document describes how the PulseAudio integration in KDE works and some thoughts for the future.

I'll describe things first at a high level (i.e. what you should expect to see) and then go on to describe how things work in the lower levels for those that are interested in such things!

Firstly there are two primary areas of KDE in which PulseAudio support is needed: Phonon (the media playback system used by most KDE applications) and KMix (the mixer application used to control device volumes). Colin Guthrie has contributed code to integrate PulseAudio into both these components.

Phonon

With regards to a properly integrated Phonon, you can verify that your build supports PulseAudio by going to "System Settings" → "Multimedia" (on some distros the "Multimedia" tab is labelled as "Audio and Video Settings"). If all is well, you should see a screen similar to the following:

NB, the "Speaker Setup" tab in the above screen shot will be/is part of KDE 4.6: See Speak(er Setup) now, or Forever hold your Peace.

The devices shown will obviously be different on your system, however 99% of systems will have an "Internal Audio Analog Stereo" listing (or an "Internal Audio Digital Stereo" entry). To cross reference, the command pactl list sinks | grep device.description should list the same device names as the active (i.e. non-greyed out) outputs.

If you do not see this full list, you may see simply a single PulseAudio entry like this:

This generally implies that Phonon has been compiled correctly with PulseAudio support but that the KDE-specific support module for PulseAudio has not been loaded. This module (called module-device-manager) can be started manually by running the script "start-pulseaudio-kde" which should be shipped with PulseAudio since 0.9.21. This file is launched on startup via an XDG compliant .desktop file (/etc/xdg/autostart/pulseaudio-kde.desktop).

Finally you may see a list that looks more like this:

This indicates that PulseAudio support is NOT enabled in your Phonon build, or that PulseAudio itself is not running when the config dialog was launched. On most systems where PulseAudio is deployed, it is configured to auto-spawn, so this is an unlikely scenario in which to find yourself.

If you find yourself in the last state, you should contact your distro (i.e. via their bug reporting tool) and request that they include PulseAudio support in their Phonon package and refer them to the Phonon Build Instructions.

KMix

KMix provides a general purpose mixer to adjust device volumes under KDE. With properly integrated PulseAudio support, it is also possible to control individual application volumes too as well as move specific applications to different devices (although using the Category-based device preferences in Phonon configuration above is generally preferred).

If you KMix installation is properly compiled with PA support (full support is included in KDE 4.5 and patches against 4.4 can be found via Colin Guthrie's GIT repository - simply clone the repo and run git diff master..pulse to get a patch that should apply to your KDE Multimedia 4.4 source), you should see the following UI:

The primary UI will always consist of four fixed tabs - in contrast to the traditional KMix which shows one tab per device. The tabs should be self explanatory, but the first tab will automatically show any new devices when they become available. If you wish to control individual channels, simply right click on the slider and choose the "Split Channels" option.

If you see a more traditional KMix interface like this:

Then chances are that if you see this interface, your KDE Multimedia package was not compiled with support for PulseAudio (as above, PA is generally configured to auto-spawn when needed, so it should be running when KMix starts). If this is the case, you should again contact your distro and ask them to integrate support.

Potential Problems

One thing that can happen is that some other process "hogs" the audio device during PulseAudio startup. When this happens PA is unable to use the device until it is restarted. If PA is unable to open your hardware, you will automatically be given a "Dummy Output". As the name suggests, anything that is "Played" via this device is inaudible). This "Dummy Output" should be easily visible in both KMix and Phonon. If this happens, then you can debug which process is hogging the hardware via the command: sudo lsof /dev/snd/* /dev/dsp* (Note that apps which have the /dev/snd/control* devices open are unlikely to interfere).

If you need to restart PulseAudio, generally a reboot is simplest. Alternatively, issue the commands: pulseaudio -k; start-pulseaudio-x11; start-pulseaudio-kde. The first command will kill the running daemon, then the second two start PulseAudio and load some additional modules that are normally loaded as part of your typical login procedure. Please note that some applications may require to be restarted after restarting PulseAudio.

Reporting Bugs

When reporting bugs either to your distro (preferred), KDE or directly here to the PulseAudio project, you should include at least the following information in your bug report:

The output of pactl list (preferably grabbed when a stream is playing - even if you cannot hear anything).
The output of amixer -c0 (where 0 is the card number, if you have multiple cards, please include the output for all cards).
The output of sudo lsof /dev/snd/* /dev/dsp* (sudo just runs this command as root, you are welcome to use a different mechanism to issue the command as root if you prefer)
The output of getfacl /dev/snd/* In order to obtain a debug log from PulseAudio itself there are two ways:
1. Rerun pulseaudio via the console and copy/paste the output
2. Turn up the debug level in /etc/pulse/daemon.conf (log-level = debug) and copy/paste from syslog (grep pulseaudio /var/log/message). The first option is generally more useful for hardcore debuggers but it does sometimes come with problems - namely the fact that PulseAudio will autospawn itself when needed in it's default setup which can make running it manually a bit tricky!. Normally you would do something like: pulseaudio -k; pulseaudio -vvvvv. This kills the currently running process of PA and then immediately starts a new one, but turns up verbosity and stays in the foreground. If you get an error message that mentions "E: main.c: pa_pid_file_create() failed." then chances are, PA automatically respawned between the two commands. Typically running the command a few times will allow the timing to work, but sometimes it can take a while and method 2 becomes more practical. You can also disable autospawning via /etc/pulse/client.conf but this can cause some anomalies during startup (e.g. KMix not detecting PA support and loading in ALSA mode etc.), so isn't recommended unless you do a lot of debug work and know these issues. If you do use method 1, then you should run the scripts start-pulseaudio-x11 and start-pulseaudio-kde in a separate terminal once PA has started up. These are normally run for you automatically at login, so you're just repeating those steps.

For the second option, PA will need to be restarted for the changes in daemon.conf to take effect. A reboot is simplest, but running pulseaudio -k; start-pulseaudio-x11; start-pulseaudio-kde should also suffice. You can then grab the data from your syslog (as root) via grep pulseaudio /var/log/messages. Please try not to include unnecessary information and try and isolate the particular run that causes problems when including the debug log in bug reports. If you can, it would be great to annotate the log at particular points where some anomaly occurs.

Distro Support

The following Distributions are known to provide fully integrated support:

Mandriva: 2010.0 onwards
Fedora: 13 onwards

Phonon Build Instructions

Building Phonon is non-trivial due to the fact that there are actually two competing versions: one shipped with Qt itself and one maintained by KDE developers which is hosted on Gitorious The latter version is needed for full PulseAudio support. Currently version 4.4.1 + two additional patches is recommended. Version 4.4.2 will be released shortly.

In order to have full support, it is generally recommended that you build Qt with Phonon support, but simply do not package/distribute the libraries and headers for phonon, then build a separate package from the Gitorious version to provide the actual libraries and headers. This is how it is done on Mandriva and it seems to work very well.

Qt 4.7 should support building Phonon externally to deal more elegantly with this general problem.

More Details

Colin Guthrie outlined the work he did with the Phonon Support in a rather detailed post. It is not necessarily for the feint hearted, and not targeted at general user consumption!