pulse-autoconf

Releases

PulseAudio server dynamic configuration daemon

Overview

Pulse-autoconf monitors a running PulseAudio server instance and ensures that a certain configuration is in place.

In particular, it can set up and maintain system-wide echo cancellation that "just works" for e.g. voice chats or video conferencing.
System-wide echo cancellation is great, because you can secretly listen to music while attending a voice or video chat, and nobody will be able to hear your music as PulseAudio filters it from your microphone. Same goes for, let's say, a video game you are playing on the side.

But wait, there's more!
Pulse-autoconf can additionally set up PulseAudio in such a way that you can mix any applications' audio into your microphone, and still play these applications' sounds back to you as well. You can mix music into the voice chat and listen to it, too! Annoying your friends has never been easier. Caution, pulse-autoconf does not protect you from getting kicked off voice chats by pissed-off participants.

All of this is possible with just PulseAudio's built-in capabilities. Among other things, PulseAudio already features decent echo cancellation. It is just somewhat awkward to set up and it does not automatically adapt to devices being added or removed, for example when you plug in or unplug a headset.

Pulse-autoconf handles this for you. For example, it makes sure that echo cancellation is always active between a dynamically determined master source and master sink, and that the virtual echo cancellation devices are set as fallbacks. If sources or sinks are added or removed, the echo cancellation is unloaded and re-applied to now possibly different masters, and affected streams are moved to the new virtual echo cancellation devices.

Features

Built-in presets

Out-of-the-box pulse-autoconf comes with 4 presets that can be applied to the PulseAudio server. Symbology:

(Application), {Audio source}, [Audio sink], {m} = Monitor of audio sink
{}* = Fallback ("default") source
[]* = Fallback ("default") sink

EchoCancellation

This preset determines a master source and master sink, for example a headset's microphone and speakers, and sets up echo cancellation between them:

{Microphone}
    ||
{src_main}* --------------> (Voice chat) -------------> [sink_main]*
                                                            ||
                                                        [Speakers]

EchoCancellationWithSourcesMix

This preset also provides echo cancellation between a master source and sink. In addition to that, it creates a virtual sink for sound effects, "sink_fx".

Any audio that is played into "sink_fx" is relayed to the speakers as well as to another virtual sink "sink_mix", where it is mixed together with the microphone. The monitor of "sink_mix" is provided as virtual source "src_main".
An application that records from "src_main" will receive both the audio from the microphone and the audio that is being played into "sink_fx".

With this, one can play additional audio into e.g. a voice chat or streaming application.

{Microphone}
    ||
{src_ec} -----------------> [sink_mix]{m}=={src_main}* -----> (Voice chat)
              Loopback            ^                                |
                                  | Loopback                       |
                                  |                                v
(Soundboard) ---------> [sink_fx]{m} -----------------------> [sink_main]*
                                             Loopback             ||
                                                              [Speakers]

For more information about this setup see Mixing additional audio into the microphone's audio at the ArchWiki.

EchoCancellationPlacebo

Mimics the behavior and results of EchoCancellation without actually applying echo cancellation, in case no echo cancellation is desired yet the usual main sink and source should remain available for applications.

It determines a master sink and source in the same way as EchoCancellation does, and then just remaps them to "sink_main" and "src_main", respectively.

None

Does nothing, intended to "switch off" pulse-autoconf.

Usage

pulse-autoconf
pulse-autoconf --help
pulse-autoconf --version
pulse-autoconf EditConfig [customEditor] [customEditorArgument]...
pulse-autoconf ListSinksAndSources [showMonitors] [sleepTime]

Pulse-autoconf sources these configuration files, in this order, wildcards expanded alphabetically:

In parallel with pulse-autoconf you typically use the graphical "PulseAudio Volume Control" application (also known as "pavucontrol") to do the fine tuning, such as choosing your desired audio hardware configuration and controlling which application plays to or records from which virtual device.

The user-level configuration files (the last two of the listed paths) are monitored for changes during runtime. If they have changed, pulse-autoconf will unload its current preset, reload its entire configuration, and apply the (now possibly different) preset.

The manual page is not written yet, so to see the available settings for now please have a look at the source code and do a text search for "setDefaultSettings".

Examples

Let's see the two main pulse-autoconf presets in action.

We are using a desktop PC that plays its sound on a 5.0 speaker surround sound system through its analog 3.5 mm (1/8 inch) audio jacks.
Attached to the PC is a USB webcam, whose microphone we wish to use for voice and video chat.

We set this up in the "Configuration" tab of the "PulseAudio Volume Control" application ("pavucontrol"):

PulseAudio Volume Control: Audio hardware configuration

This means that the PC has an output device for the speakers, and an input device for the webcam's microphone.
(In the "Input Devices" view, the selector at the bottom has been set to "All except monitors" to hide monitor devices from view as to make it less confusing.)

PulseAudio Volume Control: No preset, output devices PulseAudio Volume Control: No preset, input devices

In PulseAudio terms, the output device (speakers) is an audio sink, because applications' audio goes in, and the input device (microphone) is an audio source, because audio comes out for applications to tap.

EchoCancellation: "I want to listen to music with nobody on the voice chat knowing"

"EchoCancellation" is pulse-autoconf's default preset, so let's just run pulse-autoconf and see what happens:

[your-user@your-system ~]$ pulse-autoconf
 INFO  This is pulse-autoconf 1.5.1
 INFO  Applying preset "EchoCancellation"
 INFO  Echo cancellation sink master is "alsa_output.pci-0000_0a_00.4.analog-surround-50"
 INFO  Echo cancellation source master is "alsa_input.usb-Microsoft_Microsoft___LifeCam_HD-3000-02.multichannel-input"

Just like that, system-wide echo cancellation has been set up between the speakers and the USB webcam's microphone. Anything that the PC plays to the speakers will be filtered out from what the microphone records.

However, PulseAudio cannot "wave a magic wand" over an audio sink and an audio source and just "make them echo-cancelled". Instead, PulseAudio's echo cancellation module works by creating virtual echo-cancelled "clones" of two "master" devices for which echo cancellation should be set up, and all applications must use these "clones" instead of the actual devices for the echo cancellation to work.

Pulse-autoconf names these virtual "clone" devices "Main sink" and "Main source", respectively, and sets them as the fallback (or "default") devices for all applications to use.

PulseAudio Volume Control: EchoCancellation preset, output devices view PulseAudio Volume Control: EchoCancellation preset, input devices view

We are all set, so let's reap the benefits. We start playing music on the speakers with DeaDBeeF at a pleasant background volume, and then we fire up the Flatpak Discord app and join a voice chat (which shows up as "WEBRTC VoiceEngine").

PulseAudio Volume Control: EchoCancellation preset, playback view PulseAudio Volume Control: EchoCancellation preset, recording view

Let's see what is going on.

This is the echo cancellation at work. Or maybe the microphone is muted or broken? Well, let's check in the "Input Devices" view:

PulseAudio Volume Control: EchoCancellation preset, input devices view, devices active

No, the microphone is indeed working and picking up the racket from the speakers. It is the echo cancellation after all.

As long as DeaDBeeF plays to "Main sink" the other voice chat participants will not be able to hear the music. This works well as long as the music is not overly loud. If you crank it up, the voice chat participants will still not hear it, but they will also not be able to hear you very well when you talk.

EchoCancellationWithSourcesMix: "I want to play music on the voice chat in good quality"

Or, possibly, "I want to play fart noises at the other voice chat participants". Whatever, you do you, not judging.

For this we need to tell pulse-autoconf to use the "EchoCancellationWithSourcesMix" preset, which we do by editing a configuration text file. Launch the "Configure" action to open the file in a text editor:

Pulse-Autoconf Desktop Entry

Alternatively, on the command line, run the "EditConfig" pulse-autoconf action:

[your-user@your-system ~]$ pulse-autoconf EditConfig

A template configuration file will be created if no file exists. Uncomment this line, then save the file:

preset="EchoCancellationWithSourcesMix"

If pulse-autoconf is already running, it will notice this and change the preset on-the-fly. If it is not running yet, let's start it:

[your-user@your-system ~]$ pulse-autoconf
 INFO  Sourcing configuration file "/home/your-user/.config/pulse-autoconf/pulse-autoconf.conf"
 INFO  This is pulse-autoconf 1.5.1
 INFO  Applying preset "EchoCancellationWithSourcesMix"
 INFO  Echo cancellation sink master is "alsa_output.pci-0000_0a_00.4.analog-surround-50"
 INFO  Echo cancellation source master is "alsa_input.usb-Microsoft_Microsoft___LifeCam_HD-3000-02.multichannel-input"

Just like with the "EchoCancellation" preset, we get a "Main sink" and a "Main source". Additionally, we get an "Effects sink".
To cut to the chase: Any audio, for example music, that is played into "Effects sink", is both

PulseAudio Volume Control: EchoCancellationWithSourcesMix preset, playback view

And this is all there is to it. Music feeding from your speakers back into your microphone is of no concern due to the echo cancellation, so nobody will hear the music "twice".
You should keep any continuous audio like music at an acceptable low volume; loud music is prone to interfere with the other participants' microphones. Also, because of said low volume, you might need to disable speech detection in the voice chat application so that it does not mute your music while you are not talking.

To make the "Effects sink" work as advertised pulse-autoconf needs to create some intermediate virtual sinks and sources in the PulseAudio sound server that are not meant to be used by applications. Accordingly, their descriptions contain "(do not use)". Maybe in the future there will be a way to hide them, but until then just do not use them.

Troubleshooting

Some known issues and how to deal with them.

Sample rate drops to 32000 Hz when echo cancellation is active

Workaround: Add "ecParams+=(rate=48000)" to a pulse-autoconf configuration file.
This tells the echo cancellation module to use a sample rate of 48000 Hz.

Background: Contrary to the PulseAudio module documentation, in some constellations setting the echo cancellation parameter "use_master_format=1" is insufficient for making WebRTC echo cancellation use the physical device's sample rate.

It might be that WebRTC echo cancellation supports sample rates of 32000 Hz and 48000 Hz, but not 44100 Hz, and if your physical device uses/prefers 44100 Hz then PulseAudio compromises to 32000 Hz, which is an audible difference to the worse.

License

GNU General Public License version 3

Packages

Browseable sources

These source files of the latest tag can be viewed in the browser:

Releases

pulse-autoconf-1.5.1

03 May 2021 (2021-05-03 22:00:22 UTC)

pulse-autoconf-1.5.1.tar.gz SHA256 checksum SHA384 checksum PGP signature

pulse-autoconf-1.5.0

17 April 2021 (2021-04-17 23:23:31 UTC)

pulse-autoconf-1.5.0.tar.gz SHA256 checksum SHA384 checksum PGP signature

pulse-autoconf-1.4.2

16 April 2021 (2021-04-16 18:11:50 UTC)

pulse-autoconf-1.4.2.tar.gz SHA256 checksum SHA384 checksum PGP signature

pulse-autoconf-1.4.1

12 April 2021 (2021-04-12 23:46:47 UTC)

pulse-autoconf-1.4.1.tar.gz SHA256 checksum SHA384 checksum PGP signature

pulse-autoconf-1.4.0

11 April 2021 (2021-04-11 20:47:03 UTC)

pulse-autoconf-1.4.0.tar.gz SHA256 checksum SHA384 checksum PGP signature

pulse-autoconf-1.3.1

08 March 2021 (2021-03-08 17:46:12 UTC)

pulse-autoconf-1.3.1.tar.gz SHA256 checksum SHA384 checksum PGP signature

pulse-autoconf-1.3.0

10 February 2021 (2021-02-10 18:14:31 UTC)

pulse-autoconf-1.3.0.tar.gz SHA256 checksum SHA384 checksum PGP signature

pulse-autoconf-1.2.1

08 February 2021 (2021-02-08 13:28:42 UTC)

pulse-autoconf-1.2.1.tar.gz SHA256 checksum SHA384 checksum PGP signature

pulse-autoconf-1.2.0

07 February 2021 (2021-02-07 00:22:40 UTC)

pulse-autoconf-1.2.0.tar.gz SHA256 checksum SHA384 checksum PGP signature

pulse-autoconf-1.1.0

03 February 2021 (2021-02-03 19:25:43 UTC)

pulse-autoconf-1.1.0.tar.gz SHA256 checksum SHA384 checksum PGP signature

pulse-autoconf-1.0.0

01 February 2021 (2021-02-01 19:36:03 UTC)

pulse-autoconf-1.0.0.tar.gz SHA256 checksum SHA384 checksum PGP signature

pulse-autoconf-0.0.9

01 February 2021 (2021-02-01 15:49:58 UTC)

pulse-autoconf-0.0.9.tar.gz SHA256 checksum SHA384 checksum PGP signature

pulse-autoconf-0.0.8

31 January 2021 (2021-01-31 15:35:53 UTC)

pulse-autoconf-0.0.8.tar.gz SHA256 checksum SHA384 checksum PGP signature

pulse-autoconf-0.0.7

30 January 2021 (2021-01-30 00:18:32 UTC)

pulse-autoconf-0.0.7.tar.gz SHA256 checksum SHA384 checksum PGP signature

pulse-autoconf-0.0.6

26 January 2021 (2021-01-26 14:30:03 UTC)

pulse-autoconf-0.0.6.tar.gz SHA256 checksum SHA384 checksum PGP signature

pulse-autoconf-0.0.5

21 January 2021 (2021-01-21 12:45:20 UTC)

pulse-autoconf-0.0.5.tar.gz SHA256 checksum SHA384 checksum PGP signature

pulse-autoconf-0.0.4

31 August 2020 (2020-08-31 17:31:51 UTC)

pulse-autoconf-0.0.4.tar.gz SHA256 checksum SHA384 checksum PGP signature

pulse-autoconf-0.0.3

10 August 2020 (2020-08-10 22:01:24 UTC)

pulse-autoconf-0.0.3.tar.gz SHA256 checksum SHA384 checksum PGP signature

pulse-autoconf-0.0.2

06 August 2020 (2020-08-06 21:54:12 UTC)

pulse-autoconf-0.0.2.tar.gz SHA256 checksum SHA384 checksum PGP signature