PulseAudio integration

Using BlueALSA Together with Pipewire or PulseAudio

Pipewire (https://pipewire.org) is now the most commonly used audio server on modern Linux desktops, and is also very widely used in server installations too. PulseAudio (https://www.freedesktop.org/wiki/Software/PulseAudio/) was the de-facto Linux standard audio server, particularly for desktop installations, before Pipewire was adopted, and is still used by many distributions. Many linux distributions' desktops require either Pipewire or PulseAudio in order to provide full functionality.

Both Pipewire and PulseAudio have their own Bluetooth audio implementation which is sufficient in many common usage scenarios. If you need to use Pipewire or PulseAudio for any reason then it is recommended to at least try its internal Bluetooth audio implementation before attempting this integration. Conversely, if you do not need a general purpose audio server, then it is recommended to use BlueALSA for Bluetooth audio and not to run Pipewire or PulseAudio at all.

Of course, there may be rare occasions when you find it necessary to run BlueALSA in combination with Pipewire or PulseAudio. This wiki article describes one method of achieving this in an integrated way.

Preparing Pipewire or PulseAudio for use with BlueALSA

Bluez allows only one service to register as provider of a Bluetooth profile, so it is necessary to disable the Pipewire or PulseAudio Bluetooth modules in order to use BlueALSA.

Disable Pipewire Bluetooth Support

If using Pipewire, the Pipewire Bluetooth SPA module can be disabled using Wireplumber. Wireplumber changed its configuration file format and syntax in release 0.5.0; so this method depends on the Wireplumber version in use.

Wireplumber release 0.5.0 and later:

Override the default configuration by creating the file

/etc/wireplumber/wireplumber.conf.d/disable-bluetooth.conf

with the following contents:
```
wireplumber.profiles = {
    main = {
        hardware.bluetooth = disabled
        monitor.bluez = disabled
        monitor.bluez.seat-monitoring = disabled
    }
}
```
Wireplumber release 0.4.17 and earlier:

For these releases it is sufficient to override the single lua file which by default enables Bluetooth support. So we only need to create an empty file:

/etc/wireplumber/bluetooth.lua.d/90-enable-all.lua

With both methods it is necessary to re-start the wireplumber service to apply the configuration change.

systemctl --user restart wireplumber

To restore Bluetooth support in Pipewire, simply delete the file created above, then restart Wireplumber.

Disable PulseAudio Bluetooth modules

If using PulseAudio, there are three ways to disable the PulseAudio Bluetooth modules.

Uninstall the module packages

Many distributions deliver the PulseAudio Bluetooth modules as separate packages, and so for these the simplest solution is to uninstall those packages. For example, on Ubuntu
```
sudo apt remove pulseaudio-module-bluetooth
```
Remove the modules from the PulseAudio configuration

If the modules cannot be uninstalled, then they can still be disabled in the PulseAudio configuration. This is achieved by editing the file

/etc/pulse/default.pa

to comment out the Bluetooth module entries as shown here:
```
### Automatically load driver modules for Bluetooth hardware
#.ifexists module-bluetooth-policy.so
#load-module module-bluetooth-policy
#.endif

#.ifexists module-bluetooth-discover.so
#load-module module-bluetooth-discover
#.endif
```
Restart the PulseAudio service to read the new configuration. On most desktop systems this service is configured to automatically restart, so it is sufficient to type:
```
pulseaudio --kill
```
Unload the PulseAudio Bluetooth modules at runtime

It is possible to temporarily remove the modules at runtime with the commands:
```
pactl unload-module module-bluetooth-policy
pactl unload-module module-bluetooth-discover
```
Note that these commands will have to be re-run each time PulseAudio is restarted.

Remove PulseAudio ALSA default configuration

This step applies only to PulseAudio; the Pipewire ALSA configuration does not interfere with ALSA applications. PulseAudio installs itself as the default ALSA PCM device. To achieve this it uses a "hook" function that can interfere with the user's own PCM definitions. As many BlueALSA configurations depend on specific entries in the ALSA configuration it is recommended to remove the "hook" function. This can be done by deleting the symbolic link:

/etc/alsa/conf.d/99-pulse.conf

If you wish to continue using PulseAudio as the default ALSA PCM device you can do so by adding this line to your ~/.asoundrc file:

pcm.!default pulse

Adding BlueALSA Devices as Pipewire or PulseAudio Sinks / Sources

With the above changes, it is possible to run the BlueALSA service at the same time as Pipewire or PulseAudio. Applications will have to connect to ALSA directly using the ALSA API to use Bluetooth devices; neither Pipewire nor PulseAudio will see them. So applications that are configured to use the Pipewire or PulseAudio APIs (including most desktop volume control panels) will be unable to use Bluetooth audio. That may be good enough for many systems, so this section is optional and only relevant if you need to use BlueALSA devices via the Pipewire or PulseAudio API.

Important

This approach should be considered as "experimental" and as such suffers many compromises and limitations. It is not suitable for production systems.

In particular, both Pipewire and PulseAudio rely on an accurate timer on the associated sound card to achieve stream synchronization, for example with a video stream or for loopback to another audio device. A BlueALSA PCM has no associated sound card, and the ALSA external IO plugin API does not support period time-stamping, so that stream synchronization is not possible when using BlueALSA with PulseAudio and difficult with Pipewire. This issue can also cause regular "glitches" in the audio stream if Pipewire or PulseAdio is trying to synchronise the stream.

The Pipewire native API permits the creation of ALSA PCM nodes only from ALSA sound cards; it cannot be used to create PCM nodes that are based on the ALSA ioplug API (such as BlueALSA). However, from release 0.3.79, Pipewire's pulseaudio emulation API does support loading of such ALSA devices, so we can use PulseAudio tools with Pipewire to achieve our desired result. For that reason, the remainder of this article discusses only the PulseAudio API, but the principles and examples apply equally to Pipewire so long as its pulseaudio emulation is enabled.

To present BlueALSA PCMs via the PulseAudio API it is necessary to do a little more preparation of the configuration, and then to load the relevant modules into PulseAudio manually. The following 3 steps describe this procedure.

1. Define ALSA PCM for BlueALSA with no conversions

It is recommended to allow Pipewire or PulseAudio to perform any necessary audio format conversions internally, and not to use the alsa-lib "plug" or other ALSA plugins. This is especially important if you have libasound version 1.1.2 or 1.1.3 which will otherwise cause the PulseAudio daemon to deadlock. A simple way to achieve this is to create a file 21-bluealsa-raw.conf in the appropriate ALSA configuration directory

/usr/share/alsa/alsa.conf.d/21-bluealsa-raw.conf ( alsa-lib version <= 1.1.6 )
/etc/alsa/conf.d/21-bluealsa-raw.conf ( alsa-lib version >= 1.1.7 )

Put the following into that file:

pcm.bluealsa_raw {
	@args [ DEV PROFILE CODEC VOL SOFTVOL DELAY SRV ]
	@args.DEV {
		type string
		default {
			@func refer
			name defaults.bluealsa.device
		}
	}
	@args.PROFILE {
		type string
		default {
			@func refer
			name defaults.bluealsa.profile
		}
	}
	@args.CODEC {
		type string
		default {
			@func refer
			name defaults.bluealsa.codec
		}
	}
	@args.VOL {
		type string
		default {
			@func refer
			name defaults.bluealsa.volume
		}
	}
	@args.SOFTVOL {
		type string
		default {
			@func refer
			name defaults.bluealsa.softvol
		}
	}
	@args.DELAY {
		type integer
		default {
			@func refer
			name defaults.bluealsa.delay
		}
	}
	@args.SRV {
		type string
		default {
			@func refer
			name defaults.bluealsa.service
		}
	}
	type bluealsa
	device $DEV
	profile $PROFILE
	codec $CODEC
	volume $VOL
	softvol $SOFTVOL
	delay $DELAY
	service $SRV
}

2. Configure PulseAudio to suspend on idle

Unless configured otherwise, PulseAudio may immediately open and hold each BlueALSA PCM device that is loaded. This wastes Bluetooth bandwidth and remote device battery charge, and can cause problems for devices that support both A2DP and SCO PCMs. The only way to keep a PCM loaded but not open is to "suspend" it.

Pipewire appears to suspend a BlueALSA device immediately that its stream stops, so there is no extra configuration required; but for PulseAudio it is necessary to explicitly suspend the device. Most PulseAudio GUI tools (including pavucontrol) do not allow the user to manually suspend and unsuspend sinks and sources. The workaround for this is to enable the "suspend-on-idle" feature, with a sufficiently low timeout. Some linux distributions enable this feature, others do not. To check if your PulseAudio instance has this module loaded, type:

pactl list modules

and look for the module-suspend-on-idle entry:

Module #20
	Name: module-suspend-on-idle
	Argument: timeout=5
	Usage counter: n/a
	Properties:
		module.author = "Lennart Poettering"
		module.description = "When a sink/source is idle for too long, suspend it"
		module.version = "11.1"

The Module number, and other parameter values, may differ.

If the module is loaded, check the "Argument:" parameter. We need a low timeout value because there will be silence of that amount of time when switching from A2DP to SCO. If the Argument is blank, the default timeout is 5 seconds.

If the module is not loaded or the timeout needs to be changed, we must edit the file /etc/pulse/default.pa. Add an entry (or edit an existing entry) as:

### Automatically suspend sinks/sources that become idle for too long
load-module module-suspend-on-idle timeout=2

Important

pavucontrol by default shows volume meters for each device, and these prevent the devices from being suspended while pavucontrol is running. To disable the volume meters, and thus enable the auto suspend feature when pavucontrol is running, go to the pavucontrol Configuration tab and uncheck the "Show volume meters" checkbox in the bottom left-hand corner.

3. Create sink and / or source objects

Each Bluetooth device that you wish to use with Pipewire or PulseAudio needs to be added individually as a sink, source, or both as appropriate. If you wish to use both A2DP and SCO profiles for a single device, then they too will need to be added individually.

The way to add a device is to load the module-alsa-sink or module-alsa-source modules with appropriate parameters. In order to later remove a device, it is helpful to make a note of the module index allocated to it. The utility pactl returns that index on successful completion. The complete list of parameters for these modules can be seen here: https://www.freedesktop.org/wiki/Software/PulseAudio/Documentation/User/Modules/

Always give the device a unique internal name, so that we can use it to identify the correct node whwn using PulseAudio or Pipewire command line tools such as pactl, pacmd or pw-cli. We recommend a name starting with "bluealsa" and including the device address and profile to make it easily identifiable. For example bluealsa.sink.XX_XX_XX_XX_XX_XX.a2dp.

It is helpful to also give the device a user-friendly description for use in the description displayed in graphical tools such as pavucontrol or other desktop sound control applications/widgets, by using the sink_properties or source_properties parameter as appropriate.

It is also possible to set the display icon in the source_properties parameter - it will default to "audio-card" but you may prefer to use "audio-speakers-bluetooth", "audio-headphones-bluetooth", "audio-headset-bluetooth", "phone-bluetooth", or maybe just "bluetooth". The icons actually available will depend on your desktop distribution.

The device must first be connected before adding to PulseAudio.

For example, to load a playback (sink) device, set its internal name (used by command line tools such as pactl and pacmd), set its user-friendly description and icon, and record its allocated module index, type:

MODULE=$(pactl load-module module-alsa-sink device='bluealsa_raw:DEV=XX:XX:XX:XX:XX:XX,PROFILE=a2dp' sink_name=UniqueInternalName sink_properties="device.description='My\ Friendly\ Description'device.icon_name=bluetooth")

(Note the use of "bluealsa_raw" as defined above in the device field, and the need to escape space characters with a backslash in the description field. Do not leave any space between property settings)

To remove the device from PulseAudio, type

pactl unload-module $MODULE

The procedure for a capture (source) device is the same, except to use 'source' in place of 'sink' in the commands:

MODULE=$(pactl load-module module-alsa-source device='bluealsa_raw:DEV=XX:XX:XX:XX:XX:XX,PROFILE=a2dp' source_name=MyFriendlyName source_properties="device.description='My\ Friendly\ Description'device.icon_name=bluetooth")

Special notes for BlueALSA Capture (Pipewire/PulseAudio source) devices

A common use-case with PulseAudio is to use sinks to play audio from applications to speakers, but to use sources only to route incoming audio from a device (e.g. a mobile phone) directly to the speakers using PulseAudio's internal "module_loopback" module. However, this module needs to be able to synchronise the Bluetooth stream with the output device, and as noted above this does not work with BlueALSA PCMs. So for this specific case with BlueALSA, the best results are usually obtained by using bluealsa-play and not to load the BlueALSA PCM using module-alsa-source. Run bluealsa-aplay as:

bluealsa-aplay --pcm=pipewire

or on a pulseaudio installation:

bluealsa-aplay --pcm=pulse

so that the sound is played through Pipewire (or PulseAudio) and can be controlled using Pipewire or PulseAudio clients. (Note that both Pipewire and PulseAudio are normally run in the user's session, so bluealsa-aplay must also be run under the user's account to have permission to connect to the audio service).

If it is required to direct the audio to recording applications, then it is necessary to use module-alsa-source. In this case, bluealsa-aplay cannot be used so module-loopback is probably the best available alternative. Results can sometimes be improved by explicitly setting the buffer parameters for both the source module and the loopback module. For example, load the source module with additional parameters:

pactl load-module module-alsa-source fragments=2 fragment_size=9600 ...

The other parameters are as given above.

Load the loopback module after the source module, giving its source as the name used by the BlueALSA module parameter source_name, and set the latency_msec parameter. Try a latency of around 150 msec, and then perhaps experiment with different values to see if the resulting stream is improved. Use the source_dont_move parameter to ensure that the loopback does not automatically switch to the local microphone when the Bluetooth device stops sending audio. For example:

pactl load-module module-loopback source_dont_move=true source='MyFriendlyName' latency_msec=150

Delay / Latency reporting

Neither Pipewire nor PulseAudio use the PCM delay property of an ALSA PCM.

For PulseAudio there is no alternative method informing an application of the delay, so video synchronization is impossible.

When using Pipewire, there is a node parameter called "ProcessLatency", which works much the same way as the BlueALSA "DelayAdjustment" property, and we can use "ProcessLatency" to "fix" the delay reported to the application. For example, if bluealsa-cli info reports Delay: 286.0 ms, then (assuming we set the sink_name to bluealsa.sink.XX_XX_XX_XX_XX_XX.a2dp) we can do:

pw-cli set-param 'bluealsa.sink.XX_XX_XX_XX_XX_XX.a2dp' ProcessLatency '{ ns = 286000000 }'

Automating The Addition Of BlueALSA Devices to Pipewire or PulseAudio

It is possible to automate the above procedure by running a service that listens for D-Bus ObjectManager events from org.bluealsa and invokes the above pactl commands in response to the addition and removal of BlueALSA PCMs.

This example uses the program bluealsa-agent from the bluealsa-autoconfig project to deal with the BlueALSA D-Bus interface. Install the following script as a bluealsa-agent command (for example called "pipewire"), and run the bluealsa-agent service with the command line option --status=Running,Delay.

On Bluetooth source nodes (a2dp-source, hfp-ag, hsp-ag) the PulseAudio sinks and sources are created as soon as the device connects; on target nodes (a2dp-sink, hfp-hf, hsp-hs) the sinks and sources are created only when the audio stream is started by the remote device.

#!/bin/bash

# Some variables which can be used to customise this script.

# Select which device types to exclude from loading into pipewire/pulseaudio.
# A space separated list of types, where valid types are:
#    a2dp_source a2dp_sink sco_source sco_sink
# outputs (speakers, headphones) are "sinks",
# inputs (microphones) are "sources".
# By default no devices are excluded
# For example, to exclude all sources (recommended when using with
# bluealsa-aplay):
#   EXCLUDE="a2dp_source sco_source"
EXCLUDE=

# Change this if you wish to use a different icon for clients such as
# pavucontrol.
ICON_NAME="bluetooth"

# For BlueALSA playback devices only, set this to "yes" to use the most recently
# connected BlueALSA PCM as the Pipewire or Pulseaudio default device.
SET_DEFAULT_SINK=

# For BlueALSA capture devices only, setting this to "yes" will enable the
# Pipewire/PulseAudio loopback module to feed the Bluetooth stream to a local
# speaker.
# Note that this rarely works well and is not recommended.
ENABLE_LOOPBACK=

# Pipewire node name or PulseAudio sink name to use for loopback output.
# Leave blank to select the default sink. Must be a valid pipewire node name or
# pulseaudio sink name, for example "alsa_output.pci-0000_00_1b.0.analog-stereo"
LOOPBACK_DEVICE_NAME=

# Directory in which to store state information for each connected device
DATADIR="/tmp/bluealsa-agent/$(basename $0)"

# Do not change anything below this line.

pwcli=$(type -p pw-cli) && "$pwcli" ls Core &>/dev/null || pwcli=

state_file="${2:1}"
state_file="${DATADIR}/${state_file//\//_}"

declare -A pa_format=(
	[U8]=u8
	[S16_LE]=s16le
	[S24_LE]=s24le
	[S32_LE]=s32le
)

declare -A sample_size=(
	[u8]=1
	[s16le]=2
	[s24le]=3
	[s32le]=4
)

set_latency() {
	[[ "$pwcli" ]] || return
	local name="$1"
	if [[ -z "$name" ]] ; then
		local addr="$BLUEALSA_PCM_PROPERTY_ADDRESS"
		local type="$BLUEALSA_PCM_PROPERTY_TRANSPORT_TYPE"
		local mode="$BLUEALSA_PCM_PROPERTY_MODE"
		name="bluealsa.${mode}.${addr//:/_}.$type"
	fi
	local latency=$(( BLUEALSA_PCM_PROPERTY_DELAY * 100000))
	(( latency > 0 )) || return
	"$pwcli" set-param "$name" ProcessLatency "{ ns = $latency }" &>/dev/null
}


load_module() {
	[[ "$EXCLUDE" =~ "${BLUEALSA_PCM_PROPERTY_TRANSPORT_TYPE}_${BLUEALSA_PCM_PROPERTY_MODE}" ]] && return

	[[ -d "$DATADIR" ]] || mkdir -p "$DATADIR" || {
		echo "Cannot create state directory [$DATADIR]" >&2
		return 1
	}

	local addr="$BLUEALSA_PCM_PROPERTY_ADDRESS"
	local type="$BLUEALSA_PCM_PROPERTY_TRANSPORT_TYPE"
	local profile="$BLUEALSA_PCM_PROPERTY_PROFILE"
	local device="bluealsa_raw:DEV=$addr,PROFILE=$type"
	local mode="$BLUEALSA_PCM_PROPERTY_MODE"
	local alias="$BLUEALSA_PCM_PROPERTY_NAME"
	local name="bluealsa.${mode}.${addr//:/_}.$type"
	local description="Bluetooth:\ ${alias// /\\ }\ ($profile)"
	local format="${pa_format[$BLUEALSA_PCM_PROPERTY_FORMAT]}"
	[[ -n "$format" ]] || return
	local channels="$BLUEALSA_PCM_PROPERTY_CHANNELS"
	local rate="$BLUEALSA_PCM_PROPERTY_SAMPLING"

	local module_id=$(pactl load-module "module-alsa-$mode" "format='$format'" "rate='$rate'" "channels='$channels'" "device='$device'" "${mode}_name='$name'" "${mode}_properties=device.description='$description'device.icon_name='$ICON_NAME'")
	[[ "$module_id" ]] || return

	set_latency "$name"
	default_id=
	if [[ "$SET_DEFAULT_SINK" == yes && "$mode" == "sink" ]] ; then
		default_id="$(pactl get-default-sink)"
		pactl set-default-sink "$name"
	fi

	echo "$module_id $default_id" >"$state_file"

	if [[ "$ENABLE_LOOPBACK" == yes && "$mode" == "source" ]] ; then
		local sink=
		[[ "$LOOPBACK_DEVICE_NAME" ]] && sink="sink='$LOOPBACK_DEVICE_NAME'"
		pactl load-module module-loopback "source_dont_move='true'" "source='$name'" "$sink" "format='$format'" "rate='$rate'" "channels='$channels'"
	fi
}

unload_module() {
	read module_id default_id <"$state_file"
	if [[ "$module_id" ]] ; then
		pactl unload-module "$module_id" 2>/dev/null
		rm "$state_file"
		if [[ "$default_id" ]] ; then
			pactl set-default-sink "$default_id"
		fi
	fi
}

case "$BLUEALSA_PCM_PROPERTY_TRANSPORT" in
	*-source|*-AG)
		case "$1" in
			"add") load_module ;;
			"remove") unload_module ;;
			"update") set_latency ;;
		esac
		;;
	*)
		case "$1" in
			"update")
				[[ "$BLUEALSA_PCM_PROPERTY_CHANGES" == *RUNNING* ]] || exit
				if [[ "$BLUEALSA_PCM_PROPERTY_RUNNING" == "true" ]] ; then
					load_module
				else
					unload_module
				fi
				;;
			"remove")
				unload_module
				;;
		esac
		;;
esac

See the comments near the top of the script for more information on customising various aspects of the script.

Note

When switching a stream from an A2DP sink to a SCO sink on the same device, there may be several seconds of silence before the stream resumes, because with some Bluetooth devices SCO playback will only commence when the A2DP device is suspended by PulseAudio or vice-versa.

Provide feedback

Saved searches

Use saved searches to filter your results more quickly