Differences between revisions 27 and 28
Revision 27 as of 2020-09-26 06:45:41
Size: 6532
Editor: JohnLines
Comment:
Revision 28 as of 2021-05-12 07:17:45
Size: 8565
Comment: Major overhaul. Notable changes include PipeWire being documented (article is server-neutral now), the deprecation of pulseaudio-modules-bt, removing a product recommendation, and broad modernization.
Deletions are marked like this. Additions are marked like this.
Line 1: Line 1:
A2DP is the "Advanced Audio Distribution Profile" which describes how Bluetooth devices can stream stereo-quality audio to remote devices. It enables connecting high quality audio bluetooth devices, such as headphones and speakers, to your system. #language en
~-[[DebianWiki/EditorGuide#translation|Translation(s)]]: none-~
----
A2DP is the "Advanced Audio Distribution Profile", a standard for how Bluetooth devices can stream high-quality audio to remote devices. This is most commonly used for linking wireless headphones and speakers to your PC. The instructions in this page should apply to any A2DP-compatible device.
Line 5: Line 8:
== Requirements == == Pre-configuration ==
Line 7: Line 10:
To connect to a given device you need working bluetooth on your machine and the following packages, one of which is non-free software which will require you to enable the non-free repository in your [[SourcesList|apt sources]]. In short: To connect to a given device, you need Bluetooth hardware on your PC (either built-in, or in the form of a USB dongle), the Bluez daemon, and a compatible audio server (either PulseAudio or PipeWire).

=== Firmware ===
If your hardware supports Bluetooth but Debian is unable to find any Bluetooth devices, you may have a dongle based on a Broadcom BCM203x chipset, requiring extra firmware to be installed.

Add a non-free component to your [[SourcesList|apt sources]] and install the DebianPkg:bluez-firmware package.

=== PulseAudio ===
PulseAudio is the default audio server in Debian. Unless you know what you're doing, you probably want to follow these instructions.

Install the DebianPkg:pulseaudio-module-bluetooth package if it's not already installed. You probably also want DebianPkg:pavucontrol (or DebianPkg:pavucontrol-qt on LXQt or Plasma desktops) to configure your device after connecting it.

Once you have installed the Bluetooth module, it may be necessary to restart the bluetooth and pulseaudio services:
Line 10: Line 25:
apt install pulseaudio pulseaudio-module-bluetooth pavucontrol bluez-firmware # service bluetooth restart
$ killall pulseaudio
Line 13: Line 29:
Once you have installed these packages, it may be necessary to restart the bluetooth and pulseaudio services: After connecting your device (see the "Pairing" section), your device will appear in Pavucontrol, where you can set it as your default audio output device, change individual applications to output using it, configure its profile, etc.
Line 15: Line 31:
{{{
service bluetooth restart
}}}
=== PipeWire ===
These instructions are mutually exclusive to the !PulseAudio section, for users that are using the newer PipeWire audio server instead. This is also documented on the !PipeWire wiki page in brief.
Line 19: Line 34:
{{{
killall pulseaudio
}}}
In Debian, !PipeWire supports more modern codecs than !PulseAudio without the need to install any external modules. In particular, !PipeWire 0.3.26 supports mSBC, SBC, SBC-XQ, AAC, LDAC, AptX, and AptX-HD. It also supports the HSP_HS, HSP_AG, HFP_HF, and HFP_AG headset roles. Support for more codecs is in-progress.

At minimum, you will need to install the [[DebianPkg:libspa-0.2-bluetooth]] package, remove the DebianPkg:pulseaudio-module-bluetooth package (if previously installed), and then either reboot your computer or restart the !PipeWire services, otherwise device connections will fail with "Protocol not available".

!PipeWire will attempt to choose the best possible codec by default. You can override this, and tweak many other related settings, in the {{{/etc/pipewire/media-session.d/bluez-monitor.conf}}} file. You can edit this directly, or store local per-user changes by copying the file to {{{~/.config/pipewire/media-session.d/bluez-monitor.conf}}} and editing that instead. You can check the currently-used codec with {{{pactl list sinks}}}

Additionally, since the release of !PipeWire 0.3.19, there have been numerous Bluetooth-related feature additions and bug fixes. Experienced Bullseye/Testing users may consider upgrading to the newer version of !PipeWire that's in DebianExperimental to resolve these.

----
Line 25: Line 46:
It is also highly recommended to install a graphical pairing tool. If you are using GNOME as your desktop environment, '''bluetooth-applet''' should already be installed from the [[DebianPkg:gnome-bluetooth|gnome-bluetooth]] package. It is also highly recommended to install a graphical pairing tool. GNOME relies on DebianPkg:gnome-bluetooth, after which you can find a "Bluetooth" section of your settings. KDE Plasma relies on DebianPkg:bluedevil, which is a module for your system settings, a system tray applet, and a wizard for connecting to your devices. Other desktops can use the agnostic DebianPkg:blueman tool.
Line 27: Line 48:
If you are using an alternative desktop environment that does not already include graphical bluetooth tools, you can use the '''blueman-applet''' from the [[DebianPkg:blueman|blueman]] package: More information, and instructions on using the CLI {{{bluetoothctl}}} tool, can be found on the main BluetoothUser page.
Line 29: Line 50:
{{{
apt install blueman
}}}

Both of these applets will appear in the notification area of your desktop environment and will provide options for pairing and connecting to your speakers or headphones.

Pair your device as usual and give it the "trust" attribute. The "trust" attribute allows the device to automatically establish a connection to your machine when turned on and in range.

== Configuring ==

Using '''pavucontrol''' from the [[DebianPkg:pavucontrol|pavucontrol]] package, it is really easy to setup A2DP for your device, and map connections to it. Your paired headphones should appear as an option to output audio.

Don't forget to put it in high quality mode (A2DP) in the configuration tab. This is necessary for some devices that have mixed mode.

== Compatible devices ==

Any A2DP device should work out of the box.

If you still didn't bought one, the Creative WP-300 works very well and has a very very nice sound.
----
Line 53: Line 56:
Bluetooth headset is connected, but ALSA/PulseAudio fails to pick up the connected device or there's no device to pick. This happens because GDM captures A2DP sink on session start, as GDM needs pulseaudio in the gdm session for accessibility. For example, the screen
reader requires it. See [[DebianBug:805414]] for some discussion.
Your Bluetooth headset is connected, but PulseAudio fails to pick up the connected device, or there's no device to pick. This happens because GDM captures A2DP sink on session start, as GDM needs !PulseAudio in the GDM session for accessibility. For example, the screen reader requires it. See [[DebianBug:805414]] for some discussion.
Line 56: Line 58:
==== Workaround 1: disable pulseaudio in gdm ==== ==== Workaround 1: Disable PulseAudio in GDM ====
Line 71: Line 73:
You may also need to disable pulseaudio startup (however in Buster onwards this has already been removed in the gdm3 postinst): You may also need to disable !PulseAudio startup (however in Debian 10/Buster and newer, this has already been removed in the gdm3 postinst):
Line 77: Line 79:
In order to auto-connect a2dp for some devices, add this to '''/etc/pulse/default.pa''': In order to auto-connect A2DP for some devices, add this to '''/etc/pulse/default.pa''':
Line 85: Line 87:
Now the sound device (bluetooth headset) should be accessible through '''pavucontrol''' and standard audio device manager. Now your audio device should be accessible through '''pavucontrol''' and your desktop's standard audio settings.
Line 87: Line 89:
==== Workaround 2: disable pulseaudio's bluetooth in gdm ==== ==== Workaround 2: Disable PulseAudio's Bluetooth in GDM ====
Line 89: Line 91:
The actual solution package maintainers are looking into next is to simply disable the bluetooth sink in the gdm pulseaudio daemon so that it doesn't take over the device. Add this to `/var/lib/gdm3/.config/pulse/default.pa`: The actual solution package maintainers are looking into next is to simply disable the Bluetooth sink in the GDM !PulseAudio daemon so that it doesn't take over the device. Add this to `/var/lib/gdm3/.config/pulse/default.pa`:
Line 113: Line 115:
The actual solution is for pulseaudio to release the Bluetooth device when it is not in use. This is discussed in the Pulseaudio DebianBug:845938 which has a few upstream bugs pending as well that are related. The actual solution is for !PulseAudio to release the Bluetooth device when it is not in use. This is discussed in the !PulseAudio DebianBug:845938 which has a few upstream bugs pending as well that are related.
Line 117: Line 119:
The volumeicon tray icon may not automatically recognize a bluetooth a2dp device when a connection is established. See [[https://github.com/Maato/volumeicon/issues/73|Volumeicon does not work to adjust bluetooth volume]] for discussion and possible workarounds / fix.

==== Workaround 1: restart volumeicon ====

==== Workaround 2: adjust pulseaudio configuration to switch on connect ====
[[https://github.com/Maato/volumeicon/issues/49|Change of the default device not automatically detected]]
The volumeicon tray icon may not automatically recognize a Bluetooth A2DP device when a connection is established. See [[https://github.com/Maato/volumeicon/issues/73|issue #73, "volumeicon does not work to adjust bluetooth volume"]] and [[https://github.com/Maato/volumeicon/issues/49|issue #49, "change of the default device not automatically detected"]] for discussion and possible workarounds / fix. You might also try simply restarting Volumeicon, or adjusting your !PulseAudio configuration to switch on connect.
Line 126: Line 123:
I have had problems connecting with a bluetooth speaker once, with this error in the logs: This error can appear when using !PipeWire as your audio server and attempting to pair a device via Bluetooth, without first uninstalling the DebianPkg:DebianPkg:pulseaudio-module-bluetooth package.
Line 128: Line 125:
{{{
oct 04 18:46:19 angela bluetoothd[8025]: a2dp-sink profile connect failed for XX:XX:XX:XX:XX: Protocol not available
}}}
If you're using !PulseAudio, !PulseAudio may not be properly connecting to the device. It might be because it was already playing. Stopping anything playing on !PulseAudio, restarting !PulseAudio, and reconnecting to the device may fix the problem.
Line 132: Line 127:
I am not sure exactly what the problem is, but it seems like Pulseaudio wasn't properly connecting to the device. It might be because it was already playing. Stopping anything playing on pulseaudio, restarting pulseaudio and reconnecting to the device fixed the problem. === AptX, LDAC, and AAC codecs are not available with PulseAudio ===
Line 134: Line 129:
=== aptX (HD) and LDAC codecs are not available to be used with my device === While newer audio codecs such as AptX, LDAC, and AAC are available in PipeWire, they're still unavailable for !PulseAudio users in Debian. !PulseAudio has recently gained support for these codecs via GStreamer. Unfortunately, GStreamer is only supporting these codecs from v1.20 onwards. This means that support for modern codecs with !PulseAudio is not available in Debian 10 or Debian 11. It is expected to land in Debian 12.
Line 136: Line 131:
The licenses of these codecs may not comply to the Debian rules of free software, but there is a project making these codecs available. A third-party project adds support for these additional codecs. It is deprecated and the creator recommends users either avoid it entirely, or switch to !PipeWire. Nonetheless, it's still a fully functional option in Debian 10: https://github.com/EHfive/pulseaudio-modules-bt
Line 138: Line 133:
[[https://github.com/EHfive/pulseaudio-modules-bt|https://github.com/EHfive/pulseaudio-modules-bt]] Additionally, a third-party script for Debian 10 is available which will automatically configure and install the additional codecs via the deprecated pulseaudio-modules-bt project: https://github.com/lagerimsi-ds/debian-buster_bluetooth_aptX-LDAC
Line 140: Line 135:
Also a Bash script is available and tested on '''Debian Buster''', that fits to a normal Debian install. It installes every prequesites needed on Debian to compile and use the codecs with pulseaudio.

[[https://github.com/lagerimsi-ds/debian-buster_bluetooth_aptX-LDAC/|https://github.com/lagerimsi-ds/debian-buster_bluetooth_aptX-LDAC/]]

If the pulseaudio sink adjusts automatically to SBC-sink (not A2DP-sink with aptX or LDAC), just reconnect your device.
If the !PulseAudio sink adjusts automatically to SBC-sink (not A2DP-sink with aptX or LDAC), just reconnect your device.

Translation(s): none


A2DP is the "Advanced Audio Distribution Profile", a standard for how Bluetooth devices can stream high-quality audio to remote devices. This is most commonly used for linking wireless headphones and speakers to your PC. The instructions in this page should apply to any A2DP-compatible device.

Pre-configuration

In short: To connect to a given device, you need Bluetooth hardware on your PC (either built-in, or in the form of a USB dongle), the Bluez daemon, and a compatible audio server (either PulseAudio or PipeWire).

Firmware

If your hardware supports Bluetooth but Debian is unable to find any Bluetooth devices, you may have a dongle based on a Broadcom BCM203x chipset, requiring extra firmware to be installed.

Add a non-free component to your apt sources and install the bluez-firmware package.

PulseAudio

PulseAudio is the default audio server in Debian. Unless you know what you're doing, you probably want to follow these instructions.

Install the pulseaudio-module-bluetooth package if it's not already installed. You probably also want pavucontrol (or pavucontrol-qt on LXQt or Plasma desktops) to configure your device after connecting it.

Once you have installed the Bluetooth module, it may be necessary to restart the bluetooth and pulseaudio services:

# service bluetooth restart
$ killall pulseaudio

After connecting your device (see the "Pairing" section), your device will appear in Pavucontrol, where you can set it as your default audio output device, change individual applications to output using it, configure its profile, etc.

PipeWire

These instructions are mutually exclusive to the PulseAudio section, for users that are using the newer PipeWire audio server instead. This is also documented on the PipeWire wiki page in brief.

In Debian, PipeWire supports more modern codecs than PulseAudio without the need to install any external modules. In particular, PipeWire 0.3.26 supports mSBC, SBC, SBC-XQ, AAC, LDAC, AptX, and AptX-HD. It also supports the HSP_HS, HSP_AG, HFP_HF, and HFP_AG headset roles. Support for more codecs is in-progress.

At minimum, you will need to install the libspa-0.2-bluetooth package, remove the pulseaudio-module-bluetooth package (if previously installed), and then either reboot your computer or restart the PipeWire services, otherwise device connections will fail with "Protocol not available".

PipeWire will attempt to choose the best possible codec by default. You can override this, and tweak many other related settings, in the /etc/pipewire/media-session.d/bluez-monitor.conf file. You can edit this directly, or store local per-user changes by copying the file to ~/.config/pipewire/media-session.d/bluez-monitor.conf and editing that instead. You can check the currently-used codec with pactl list sinks

Additionally, since the release of PipeWire 0.3.19, there have been numerous Bluetooth-related feature additions and bug fixes. Experienced Bullseye/Testing users may consider upgrading to the newer version of PipeWire that's in DebianExperimental to resolve these.


Pairing

It is also highly recommended to install a graphical pairing tool. GNOME relies on gnome-bluetooth, after which you can find a "Bluetooth" section of your settings. KDE Plasma relies on bluedevil, which is a module for your system settings, a system tray applet, and a wizard for connecting to your devices. Other desktops can use the agnostic blueman tool.

More information, and instructions on using the CLI bluetoothctl tool, can be found on the main BluetoothUser page.


Troubleshooting

Refused to switch profile to a2dp_sink: Not connected

Your Bluetooth headset is connected, but PulseAudio fails to pick up the connected device, or there's no device to pick. This happens because GDM captures A2DP sink on session start, as GDM needs PulseAudio in the GDM session for accessibility. For example, the screen reader requires it. See 805414 for some discussion.

Workaround 1: Disable PulseAudio in GDM

In order to prevent GDM from capturing the A2DP sink on session start, edit /var/lib/gdm3/.config/pulse/client.conf (or create it, if it doesn't exist):

autospawn = no
daemon-binary = /bin/true

After that you have to grant access to this file to Debian-gdm user:

chown Debian-gdm:Debian-gdm /var/lib/gdm3/.config/pulse/client.conf

You may also need to disable PulseAudio startup (however in Debian 10/Buster and newer, this has already been removed in the gdm3 postinst):

rm /var/lib/gdm3/.config/systemd/user/sockets.target.wants/pulseaudio.socket

In order to auto-connect A2DP for some devices, add this to /etc/pulse/default.pa:

load-module module-switch-on-connect

Reboot.

Now your audio device should be accessible through pavucontrol and your desktop's standard audio settings.

Workaround 2: Disable PulseAudio's Bluetooth in GDM

The actual solution package maintainers are looking into next is to simply disable the Bluetooth sink in the GDM PulseAudio daemon so that it doesn't take over the device. Add this to /var/lib/gdm3/.config/pulse/default.pa:

#!/usr/bin/pulseaudio -nF
#

# load system wide configuration
.include /etc/pulse/default.pa

### unload driver modules for Bluetooth hardware
.ifexists module-bluetooth-policy.so
  unload-module module-bluetooth-policy
.endif

.ifexists module-bluetooth-discover.so
  unload-module module-bluetooth-discover
.endif

This was first discovered in the Arch wiki.

Solution

The actual solution is for PulseAudio to release the Bluetooth device when it is not in use. This is discussed in the PulseAudio 845938 which has a few upstream bugs pending as well that are related.

Unable to control volume with volumeicon-alsa

The volumeicon tray icon may not automatically recognize a Bluetooth A2DP device when a connection is established. See issue #73, "volumeicon does not work to adjust bluetooth volume" and issue #49, "change of the default device not automatically detected" for discussion and possible workarounds / fix. You might also try simply restarting Volumeicon, or adjusting your PulseAudio configuration to switch on connect.

a2dp-sink profile connect failed [...]: Protocol not available

This error can appear when using PipeWire as your audio server and attempting to pair a device via Bluetooth, without first uninstalling the DebianPkg:pulseaudio-module-bluetooth package.

If you're using PulseAudio, PulseAudio may not be properly connecting to the device. It might be because it was already playing. Stopping anything playing on PulseAudio, restarting PulseAudio, and reconnecting to the device may fix the problem.

AptX, LDAC, and AAC codecs are not available with PulseAudio

While newer audio codecs such as AptX, LDAC, and AAC are available in PipeWire, they're still unavailable for PulseAudio users in Debian. PulseAudio has recently gained support for these codecs via GStreamer. Unfortunately, GStreamer is only supporting these codecs from v1.20 onwards. This means that support for modern codecs with PulseAudio is not available in Debian 10 or Debian 11. It is expected to land in Debian 12.

A third-party project adds support for these additional codecs. It is deprecated and the creator recommends users either avoid it entirely, or switch to PipeWire. Nonetheless, it's still a fully functional option in Debian 10: https://github.com/EHfive/pulseaudio-modules-bt

Additionally, a third-party script for Debian 10 is available which will automatically configure and install the additional codecs via the deprecated pulseaudio-modules-bt project: https://github.com/lagerimsi-ds/debian-buster_bluetooth_aptX-LDAC

If the PulseAudio sink adjusts automatically to SBC-sink (not A2DP-sink with aptX or LDAC), just reconnect your device.