Translation(s): none


Buetooth Audio

The instructions on this page should should apply to devices for streaming of high-quality audio or for voice communication implemented by the following Bluetooth profiles:

Basic Audio Profile (BAP)
Bluetooth 5.2 LE, LC3 and LC3Plus codecs, a successor of A2DP, supports duplex audio transmission.
Advanced Audio Distribution Profile (A2DP)

A standard for how Bluetooth devices that can stream high-quality audio to remote devices. This is most commonly used for linking wireless headphones and speakers to your PC. Some devices support duplex A2DP codecs (AptX LL, FastStream) suitable for headsets providing high enough quality of the main audio stream

Headset Profile (HSP) and Hands-Free Profile (HSP)
provide speech-grade quality of bidirectional audio due to low sampling frequency.

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). Alternatively Bluetooth ALSA available since Debian 12 bookworm allows to avoid running of a high-level sound server.

#PipeWire supports more audio codecs, however prior to to Debian 12 bookworm, #PulseAudio is the default audio server and you may face issues with PipeWire in earlier Debian releases.

If you are using the GNOME desktop then you can not choose audio server implementation. In Debian 12 bookworm the gnome-core package has a hard dependency on pipewire-audio while in Debian 11 bullseye the same package depends on pulseaudio and pulseaudio-module-bluetooth. An attempt to install the alternative audio server will result in a prompt to remove desktop environment packages.

If your Bluetooth adapter is not recognized then follow generic BluetoothUser#Firmware instructions to install extra packages.

PulseAudio

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. Note that simply having the pipewire package installed does not mean this section is relevant to you, as it needs to have also been specially configured to replace PulseAudio.

In Debian, PipeWire supports more modern codecs than PulseAudio without the need to install any external modules. In particular, PipeWire 0.3.65 (bookworm) supports mSBC, SBC, SBC-XQ, FastStream, LC3, LDAC, AptX, AptX-HD, and AptX LL. 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


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 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.

In addition, you need the following settings in /etc/pulse/default.pa or /etc/pulse/default.pa.d/bluez5.pa:

load-module module-bluez5-device
load-module module-bluez5-discover

Then restart pulseaudio.

SBC codec

The SBC codec mandatory for A2DP is often described as having poor quality. Actually it allows wide range of parameters* and with recommended High Quality settings (e.g. Joint Stereo with 48 kHz sampling rate and 51 bitpool value has 345 kb/s bit rate) should not be significantly worse than other codecs. Some devices have significantly lower limit for bitbool value that causes degraded quality. In the case of unreliable connection (weak signal, interference with other Bluetooth, WiFi, and USB devices) communicating devices may negotiate to to lower bitpool value. Another reason for perceptible difference with other codecs might be different equalizer presets.

Unfortunately PipeWire and PulseAudio do not expose supported and actually used codec settings. There are no diagnostic tools that may query a device. The only way is to capture Bluetooth traffic and to find packets with codec settings. Either hcidump or wireshark/tshark (dumpcap -i bluetooth0) may be used. An example of hcidump capture:

< ACL data: handle 256 flags 0x00 dlen 20
    L2CAP(d): cid 0x0043 len 16 [psm 25]
      AVDTP(p): Set config cmd: transaction 8 nsp 0x00
        ACP SEID 1 - INT SEID 9
        Media Transport
        Media Codec - SBC
          48kHz 
          JointStereo 
          16 Blocks
          8 Subbands
          Loudness 
          Bitpool Range 2-52
        Delay Reporting

Maximum bitbool value allows SBC HQ settings.

SBC-XQ* is a kind of trick to overcome maximum bitbool limit imposed by devices. It uses Dual Channel instead of Joint Stereo mode, so bitpool value should be doubled. An example of packet decoded by tshark (wrapped):

165   5.296488 localhost () → <Vendor_aa:bb:cc> (<HeadPhones Model>) AVDTP 25 Sent Command - SetConfiguration
 - ACP SEID [1 - Audio Sink] - INT SEID [11 - unknown unknown]
 - Audio SBC (48000 | DualChannel | block: 16 | subbands: 8 | allocation: Loudness
   | bitpool: 2..39)

On the other hand mSBC is a speech-grade codec with 16 kHz sampling rate used by Head Set and Hands Free Profiles (HSP and HSF). Ensure that namely A2DP profile is used when you do not need microphone.

FastStream is a duplex variant of the SBS codec that allows to enable microphone without significant degradation of headphones audio quality. It is supported by PipeWire in Debian 12 bookworm. Likely its support will be a part of PulseAudio-17 release.

AptX and LDAC codecs

Both PipeWire and PulseAudio supports the AptX and LDAC codecs in Debian 12 bookworm. In the case of PulseAudio install gstreamer1.0-plugins-bad. In Debian 11 bullseye these codecs are available for PipeWire, but not for PulseAudio.

The AptX LL variant is supported only by PipeWire since Debia 12 bookworm.

A third-party project adds support for these additional codecs as well. 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.

AAC codec

The AAC codec is unavailable in Debian 12 bookworm.

In the case of PipeWire its support (see the 1021370 request) requires libfdk-aac2, however a decision has not made if this package may be moved from the non-free to the main section (see 981285). The only workaround is to build the AAC Bluetooth plugin from sources.

PulseAudio-16 (Debian 12 bookworm) does not support AAC. Despite necessary patches from the gstreamer merge request !1172 are applied to gstreamer1.0-fdkaac, there are pending changes in the PulseAudio Bluetooth plugin, see the upstream merge request !473.

LC3 codec

A Bluetooth 5.2 LE codec supported by PipeWire since Debian 12 bookworm. It is a part of the Basic Audio Profile (BAP), so it requires enabling of experimental features in bluetoothd (see BluetoothUser#Experimental_Features). Otherwise you will get the following messages in journalctl output

bluetoothd[7679]: profiles/audio/bap.c:bap_init() D-Bus experimental not enabled
bluetoothd[7679]: src/plugin.c:plugin_init() Failed to init bap plugin


See also


CategorySound CategoryWireless