Bluetooth headset

Related articles

• Bluetooth

Currently, Arch Linux supports the A2DP profile (Audio Sink) for remote audio playback with the default installation.

Headset via Pipewire

PipeWire acts as a drop-in replacement for PulseAudio and offers an easy way to set up Bluetooth headsets. It includes out-of-the-box support for A2DP sink profiles using SBC/SBC-XQ, AptX, LDAC or AAC codecs, and HFP/HSP.

Install pipewire-pulse (which replaces pulseaudio and pulseaudio-bluetooth).

The daemon will be started automatically as a user service. Use pavucontrol or your desktop environment's settings for configuration. For more information, see PipeWire#Bluetooth devices.

Battery level reporting

To get the current battery level of your headset reported to upower, the bluetoothd daemon must be started with experimental features.

This can be done by creating a replacement unit file for bluetooth.service and appending -E to the ExecStart line. Restart the service afterwards.

Alternatively, a drop-in file for bluetooth.service can be created, with the following contents:

/etc/systemd/system/bluetooth.service.d/override.conf

[Service]
ExecStart=
ExecStart=/usr/lib/bluetooth/bluetoothd --experimental

Restart the service afterwards.

Headset via Bluez5/PulseAudio

Install the pulseaudio-alsa, pulseaudio-bluetooth and bluez-utils packages, the last of which provides the bluetoothctl utility.

Note: Before continuing, ensure that the bluetooth device is not blocked by rfkill.

Configuration via CLI

Start bluetooth.service.

Now we can use the bluetoothctl command line utility to pair and connect. For troubleshooting and more detailed explanations of bluetoothctl see the Bluetooth article. Run

$ bluetoothctl

to be greeted by its internal command prompt. Then enter:

[bluetooth]# power on
[bluetooth]# agent on
[bluetooth]# default-agent
[bluetooth]# scan on

Now make sure that your headset is in pairing mode. It should be discovered shortly. For example,

[NEW] Device 00:1D:43:6D:03:26 Lasmex LBT10

shows a device that calls itself "Lasmex LBT10" and has MAC address "00:1D:43:6D:03:26". We will now use that MAC address to initiate the pairing:

[bluetooth]# pair 00:1D:43:6D:03:26

After pairing, you also need to explicitly connect the device (if this does not work, try the trust command below before attempting to connect):

[bluetooth]# connect 00:1D:43:6D:03:26

If you are getting a connection error org.bluez.Error.Failed retry by killing existing PulseAudio daemon first:

$ pulseaudio -k
[bluetooth]# connect 00:1D:43:6D:03:26

Finally, if you want to automatically connect to this device in the future:

[bluetooth]# trust 00:1D:43:6D:03:26

If everything works correctly, you now have a separate output device in PulseAudio.

Note: The device may be off by default. Select its audio profile (OFF, A2DP, HFP) in the "Configuration" tab of pavucontrol.

You can now redirect any audio through that device using the "Playback" and "Recording" tabs of pavucontrol.

You can now disable scanning again and exit the program:

[bluetooth]# scan off
[bluetooth]# exit

Setting up auto connection

To make your headset auto connect you need to enable PulseAudio's switch-on-connect module. Do this by adding the following lines to /etc/pulse/default.pa:

/etc/pulse/default.pa

### Automatically switch to newly-connected devices
load-module module-switch-on-connect

Note:

• Make sure that your bluetooth audio device is trusted, otherwise repeated pairing will fail. See Bluetooth#Pairing for details.
• By default, your Bluetooth adapter will not power on after boot. See Bluetooth#Auto power-on after boot/resume for details.

Media controls

To use the media controls they may be forwarded to MPRIS, where they can be picked up by media players that support MPRIS for external control. See MPRIS#Bluetooth for details.

Configuration via GNOME Bluetooth

Note: The A2DP profile will not activate using this method with pulseaudio 9/10 due to an ongoing bug, leading to possible low quality mono sound. See #A2DP not working with PulseAudio for a possible solution.

You can use GNOME Bluetooth graphical front-end to easily configure your bluetooth headset.

First, you need to be sure that bluetooth.service systemd unit is running.

Open GNOME Bluetooth and activate the bluetooth. After scanning for devices, you can connect to your headset selecting it on the device list. You can directly access to sound configuration panel from the device menu. On the sound panel, a new sink should appear when your device is connected.

LDAC/aptX

LDAC/aptX codec support can be enabled by installing pulseaudio-modules-bt^AUR and libldac, and restarting PulseAudio. See its project page for configuration tips. You can verify the codec you are using for connection as follows:

$ pactl list | grep a2dp_codec

Troubleshooting

Note: Many users report frustration with getting A2DP/Bluetooth Headsets to work. see #Switch between HSP/HFP and A2DP setting for additional information.

Bad sound / Static noise / "Muddy" sound

If you experience bad sound quality with your headset, it could in all likelihood be because your headset is not set to the correct profile. See #Switch between HSP/HFP and A2DP setting to solve the problem.

Selected audio profile, but headset inactive and audio cannot be redirected

Deceptively, this menu is available before the device has been connected; annoyingly it will have no effect. The menu seems to be created as soon as the receiver recognizes the device.

Make sure to run bluetoothctl as root and connect the device manually. There may be configuration options to remove the need to do this each time, but neither pairing nor trusting induce automatic connecting for me.

Pairing fails with AuthenticationFailed

If pairing fails, you can try enabling or disabling SSPMode with:

# btmgmt ssp off

or

# btmgmt ssp on

You may need to turn off BlueTooth while you run this command.

Pairing works, but connecting does not

You might see the following error in bluetoothctl:

[bluetooth]# connect 00:1D:43:6D:03:26
Attempting to connect to 00:1D:43:6D:03:26
Failed to connect: org.bluez.Error.Failed

To further investigate, check the unit status of bluetooth.service or have a look at the log as follows:

# journalctl -n 20

You might see a message like this:

bluetoothd[5556]: a2dp-sink profile connect failed for 00:1D:43:6D:03:26: Protocol not available

This may be due to the pulseaudio-bluetooth package not being installed (or pulseaudio-modules-bt-git^AUR needing a clean reinstall). Install it if it missing, then restart pulseaudio.

It can also be due to permission, especially if starting pulseaudio as root allows you to connect. Add your user to the lp group, then restart pulseaudio. See /etc/dbus-1/system.d/bluetooth.conf for reference.

If the issue is not due to the missing package, the problem in this case is that PulseAudio is not catching up. A common solution to this problem is to restart PulseAudio. Note that it is perfectly fine to run bluetoothctl as root while PulseAudio runs as user. After restarting PulseAudio, retry to connect. It is not necessary to repeat the pairing.

If restarting PulseAudio does not work, you need to load module-bluetooth-discover.

# pactl load-module module-bluetooth-discover

The same load-module command can be added to /etc/pulse/default.pa.

If that still does not work, or you are using PulseAudio's system-wide mode, also load the following PulseAudio modules (again these can be loaded via your default.pa or system.pa):

module-bluetooth-policy
module-bluez5-device
module-bluez5-discover

It is also possible there are no write permissions for the owner of /var/lib/bluetooth/. If this is the case, you may get the device to work by removing and re-pairing it, but the issue will return after rebooting. Restoring write permissions fixes this issue:

# chmod -R u+w /var/lib/bluetooth

Connecting works, but there are sound glitches all the time

This is very likely to occur when the Bluetooth and the WiFi share the same chip as they share the same physical antenna and possibly band range (2.4GHz). Although this works seamlessly on Windows, this is not the case on Linux.

A possible solution is to move your WiFi network to 5GHz so that there will be no interference. If your card/router does not support this, you can upgrade your WiFi drivers/firmware. This approach works on Realtek 8723BE and latest rtl drivers for this chip from AUR.

If nothing of the previous is possible, a less effective mitigation is to tweak the fragment size and the latency on PulseAudio output port, trying to compensate interference. Reasonable values must be chosen, because these settings can make the audio out of sync (e.g. when playing videos). To change the latency of the bluetooth headset's port (e.g. to 125000 microseconds in the following example):

$ pactl set-port-latency-offset <bluez_card> headset-output 125000

where the identifier of the card can be found with

$ pacmd list-sinks | egrep -o 'bluez_card[^>]*'

The fragment size can be set in the config file /etc/pulse/daemon.conf and takes effect after a restart of PulseAudio (for more details please see PulseAudio/Troubleshooting#Setting the default fragment number and buffer size in PulseAudio).

Perhaps it will help to add options ath9k btcoex_enable=1 to the /etc/modprobe.d/ath9k.conf (with the appropriate bluetooth adapter):

/etc/modprobe.d/ath9k.conf

# possibly fix for sound glitches
options ath9k btcoex_enable=1

Then restart.

Connecting works, but I cannot play sound

Make sure that you see the following messages in your system log:

bluetoothd[5556]: Endpoint registered: sender=:1.83 path=/MediaEndpoint/A2DPSource
bluetoothd[5556]: Endpoint registered: sender=:1.83 path=/MediaEndpoint/A2DPSink

If you see a message similar to this, you can go on and investigate your PulseAudio configuration. Otherwise, go back and ensure the connection is successful.

When using GDM, another instance of PulseAudio is started, which "captures" your bluetooth device connection. This can be prevented by masking the pulseaudio socket for the GDM user by doing the following:

# mkdir -p  /var/lib/gdm/.config/systemd/user
# ln -s /dev/null  /var/lib/gdm/.config/systemd/user/pulseaudio.socket

On next reboot the second instance of PulseAudio will not be started.

It may happen that bluez wrongly considers an headset as not a2dp capable. In this case, search the index of the bluetooth device with

$ pacmd ls

Among the output there should be a section related to the bluetooth headset, containing something similar to

$ pacmd ls

index: 2
        name: <bluez_card.XX_XX_XX_XX_XX_XX>
        driver: <module-bluez5-device.c>
        owner module: 27
        properties:
                device.description = "SONY MDR-100ABN"
                device.string = "XX:XX:XX:XX:XX:XX"
                device.api = "bluez"
                device.class = "sound"
                ...

To manually set the profile, run

$ pacmd set-card-profile 2 a2dp_sink

where 2 is the index of the device retrieved through pacmd ls.

Connecting works, sound plays fine until headphones become idle, then stutters

If the headphones play sound correctly until they become idle and then stutter on resume (e.g. because the sound is paused, or because no sound is played for a while), try disabling PulseAudio's automatic sink/source suspension on idle.

Some user reports huge delays or even no sound when the Bluetooth connection does not send any data. This is due to the module-suspend-on-idle module, which automatically suspends sinks/sources on idle. As this can cause problems with headset, the responsible module can be deactivated.

To disable loading of the module-suspend-on-idle module, comment out the following line in the configuration file in use (~/.config/pulse/default.pa or /etc/pulse/default.pa):

~/.config/pulse/default.pa

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

Finally restart PulseAudio to apply the changes.

UUIDs has unsupported type

During pairing you might see this output in bluetoothctl:

[CHG] Device 00:1D:43:6D:03:26 UUIDs has unsupported type

This message is a very common one and can be ignored.

PC shows device as paired, but is not recognized by device

This might be due to the device not supporting bluetooth LE for pairing.

Try setting ControllerMode = bredr in /etc/bluetooth/main.conf. See [2].

Device connects, then disconnects after a few moments

If you see messages like the following in the journal, and your device fails to connect or disconnects shortly after connecting:

bluetoothd: Unable to get connect data for Headset Voice gateway: getpeername: Transport endpoint is not connected (107)
bluetoothd: connect error: Connection refused (111)

This may be because you have already paired the device with another operating system using the same bluetooth adapter (e.g., dual-booting). Some devices cannot handle multiple pairings associated with the same MAC address (i.e., bluetooth adapter). You can fix this by re-pairing the device. Start by removing the device:

$ bluetoothctl
[bluetooth]# devices
Device XX:XX:XX:XX:XX:XX My Device
[bluetooth]# remove XX:XX:XX:XX:XX:XX

Then restart bluetooth.service, turn on your bluetooth adapter, make your device discoverable, re-scan for devices, and re-pair your device. Depending on your bluetooth manager, you may need to perform a full reboot in order to re-discover the device.

Apple AirPods have low volume

Create a drop-in file for bluetooth.service with the following contents:

/etc/systemd/system/bluetooth.service.d/noplugin-avrc.conf

[Service]
ExecStart=
ExecStart=/usr/lib/bluetooth/bluetoothd --noplugin=avrcp

Then, restart bluetooth.service, reload its configuration, and reconnect your headset.

Additionally, for AirPods Pro, disable the spatial audio and enable Mono in the settings of your iPhone.

This can also solve issues with some devices that are unable to be controlled through AVRCP.

Apple AirPods Pro working with PulseAudio as A2DP Sink but not with HSP/HFP

If you find that AirPods Pro are working with PulseAudio, but are incapable of using the HSP/HFP configurations (in pavucontrol's Configurations tab, usually listed as unavailable), try switching to pipewire-pulse.

Note that switching to pipewire-pulse (and restarting your computer or the appropriate user-level systemd services) should enable HSP/HFP, but may also disable A2DP. (When selecting A2DP Sink in the Configurations tab, the option is instantly deselected and becomes Off.) If you encounter this issue, try removing/renaming the /var/lib/bluetooth folder like so:

# mv /var/lib/bluetooth /var/lib/bluetooth.bak

Re-pair your AirPods Pro (and other devices) afterwards. This should make all configurations (HSP/HFP and A2DP) available again and easily accessible from pavucontrol and pacmd.

HSP problem: the bluetooth sink and source are created, but no audio is being transmitted

You may be missing firmware or the SCO (audio protocol of HSP and HFP) routing might be wrong. See [3] - the firmware for BCM20702 can be installed via bcm20702a1-firmware^AUR or bcm20702b0-firmware^AUR.

Error: Failed to start discovery org.bluez.Error.InProgress

If your headset is discovered, but fails to connect with the error "Failed to start discovery org.bluez.Error.InProgress", install bluez-hciconfig^AUR and run

$ hciconfig hciX up
$ hciconfig hciX reset

where X is the identifier of your computer's bluetooth device (typically 0).

You should then be able to connect following the steps in #Configuration via CLI.

Switch between HSP/HFP and A2DP setting

This can easily be achieved by the following command where the card_number can be obtained by running pacmd list-cards.

$ pacmd set-card-profile card_number a2dp_sink

For enabling automatic profile switching from A2DP to HSP when a recording stream appears without any role set, you can append auto_switch=2 to load-module module-bluetooth-policy in /etc/pulse/default.pa.

For more information about PulseAudio profiles, see PulseAudio Documentation.

A2DP not working with PulseAudio

Socket interface problem

If PulseAudio fails when changing the profile to A2DP with bluez 4.1+ and PulseAudio 3.0+, you can try disabling the Socket interface from /etc/bluetooth/main.conf by removing the line Enable=Socket and adding line Disable=Socket.

A2DP sink profile is unavailable

When the A2DP sink profile is unavailable it will not be possible to switch to the A2DP sink (output) with a PulseAudio front-end and the A2DP sink will not even be listed. This can be confirmed with pactl.

$ pactl list | grep -C2 A2DP
     Profiles:
             headset_head_unit: Headset Head Unit (HSP/HFP) (sinks: 1, sources: 1, priority: 30, available: yes)
             a2dp_sink: High Fidelity Playback (A2DP Sink) (sinks: 1, sources: 0, priority: 40, available: no)
             off: Off (sinks: 0, sources: 0, priority: 0, available: yes)
        Active Profile: headset_head_unit

Trying to manually set the card profile with pacmd will fail.

$ pacmd set-card-profile bluez_card.C4_45_67_09_12_00 a2dp_sink
Failed to set card profile to 'a2dp_sink'.

This is known to happen from version 10.0 of Pulseaudio when connecting to Bluetooth headphones via Bluedevil or another BlueZ front-end. See related bug report.

This issue also appears after initial pairing of Headphones with some Bluetooth controllers (e.g. 0a12:0001, Cambridge Silicon Radio) which might default to the Handsfree or Headset - HS service and will not allow switching to the A2DP PulseAudio sink that requires the AudioSink service.

Possible solutions:

• For some headsets, using the headset's volume or play/pause controls while connected can trigger the A2DP profile to become available.
• It is possible that connecting to a headset via bluetoothctl from bluez-utils will make the A2DP sink profile available. There is an automation for this every time a bluetooth device is connected: fix-bt-a2dp^AUR (detailed usage)

[bluetooth]# connect headset_MAC_address

• Manually switching to Bluetooth's AudioSink service which would make the A2DP profile and its A2DP PulseAudio sink available. This can be done with blueman-manager which included in blueman or by registering the UUID of the AudioSink service with bluetoothctl.

$ bluetoothctl
[bluetooth]# menu gatt
[bluetooth]# register-service 0000110b-0000-1000-8000-00805f9b34fb
[bluetooth]# quit

• Disable the headset profile

/etc/bluetooth/main.conf

[General]
Disable=Headset

• Enable MultiProfile support. This may help with headsets that support A2DP as well as Headset audio.

/etc/bluetooth/main.conf

[General]
MultiProfile=multiple

• Sometimes, none of the steps above will work. You may have tried rebooting and powering bluetooth off and on to no avail. In this case, try restarting the bluetooth.service.
• Alternatively, replacing pulseaudio-bluetooth with pulseaudio-modules-bt^AUR or pulseaudio-modules-bt-git^AUR, which provides additional Bluetooth codecs, may resolve the issue.
• For some headphone models with audio control panel, the A2DP profile must be enabled by pressing the Play/Pause button on the panel.

Gnome with GDM

The instructions below were tested on Gnome 3.24.2 and PulseAudio 10.0 however they may still be applicable and useful for other versions.

If PulseAudio fails when changing the profile to A2DP while using GNOME with GDM, you need to prevent GDM from starting its own instance of PulseAudio:

• Prevent Pulseaudio clients from automatically starting a server if one is not running by adding the following:

/var/lib/gdm/.config/pulse/client.conf

autospawn = no
daemon-binary = /bin/true

• Prevent systemd from starting Pulseaudio anyway with socket activation:

$ sudo -ugdm mkdir -p /var/lib/gdm/.config/systemd/user
$ sudo -ugdm ln -s /dev/null /var/lib/gdm/.config/systemd/user/pulseaudio.socket

• Restart, and check that there is no PulseAudio process for the gdm user using:

$ pgrep -u gdm pulseaudio

Further discussion about this problem and alternative fixes can be found at [4] and [5]. Alternatively, one may try and install fix-bt-a2dp^AUR.

HFP not working with PulseAudio

HFP-only bluetooth headsets may not be usable in the standard configuration of PulseAudio. The respective profiles occur, but they are not available:

• bluetoothctl info output shows:

UUID: Audio Sink                (0000110b-0000-1000-8000-00805f9b34fb)
UUID: A/V Remote Control Target (0000110c-0000-1000-8000-00805f9b34fb)
UUID: A/V Remote Control        (0000110e-0000-1000-8000-00805f9b34fb)
UUID: Handsfree                 (0000111e-0000-1000-8000-00805f9b34fb)

• pactl list of respective device shows:

...
Profiles:
      ...
      headset_head_unit: Headset Head Unit (HSP/HFP) (sinks: 1, sources: 1, priority: 30, available: no)

To solve the respective issue, update to pulseaudio (>=13) and potentially pulseaudio-modules-bt-git^AUR and bluez (>=5.5) to latest versions. Then install ofono^AUR (start and enable using systemctl) and phonesim^AUR and create / activate a fake modem as described here [6]:

Note: The steps following the creation of phonesim.conf should be done every time you want to connect the headset.

• Create /etc/ofono/phonesim.conf with:

[phonesim]
Address=127.0.0.1
Driver=phonesim
Port=12345

• Start as user:

$ phonesim -p 12345 /usr/share/phonesim/default.xml &

• Enable and start ofono service.
• Power modem:

$ dbus-send --print-reply --system --dest=org.ofono /phonesim org.ofono.Modem.SetProperty string:"Powered" variant:boolean:true

• Activate modem:

$ dbus-send --print-reply --system --dest=org.ofono /phonesim org.ofono.Modem.SetProperty string:"Online" variant:boolean:true

• To check the results, use the test commands from ofono^AUR installed in /usr/lib/ofono/test/. To power, activate, and test the modem you can use:

$ /usr/lib/ofono/test/enable-modem /phonesim
$ /usr/lib/ofono/test/online-modem /phonesim
$ /usr/lib/ofono/test/list-modems

The output of the respective modem section should read like this:

...
[ /phonesim ]
  Online = 1
  Powered = 1
  Lockdown = 0
  Emergency = 0
  Manufacturer = MeeGo
  ...

• Finally, restart pulseaudio and reconnect headset. Now, HFP should be available:

headset_head_unit: Headset Head Unit (HSP/HFP) (sinks: 1, sources: 1, priority: 30, available: yes)

Note: HFP support is not stable and may cause glitches with switching to A2DP; try reconnecting, if the needed mode is not available.

Disable auto switching headset to HSP/HFP

When using a bluetooth headset that supports multiple profiles, some applications switch to HSP/HFP profile automatically. If this behaviour is undesired you can disable this by appending the auto_switch=false parameter to the bluetooth-policy module:

/etc/pulse/default.pa

load-module module-bluetooth-policy auto_switch=false