BPI-CM9-Linux/aml-comp/vendor/amlogic/bluez-alsa/TROUBLESHOOTING.md

<!--
SPDX-FileCopyrightText: 2016-2025 BlueALSA developers
SPDX-License-Identifier: MIT
-->

# Troubleshooting BlueALSA

This document presents solutions to some of the most commonly encountered
errors when using BlueALSA.

## 1. Couldn't acquire D-Bus name: org.bluealsa

The BlueALSA server registers a unique "well-known service name" with D-Bus,
which is used by client applications to identify the correct service instance.
By default it uses the name "org.bluealsa". There are three reasons why
starting the service may fail with the
`"Couldn't acquire D-Bus name: org.bluealsa"` error message:

- The BlueALSA D-Bus policy file is not installed, or is in the wrong
location.\
In a default install, the file should be
`/usr/share/dbus-1/system.d/org.bluealsa.conf`; but if BlueALSA was installed
from a distribution package then the distribution may have moved it to
`/etc/dbus-1/system.d/org.bluealsa.conf`. Check with your distribution
documentation in case D-Bus uses a different location on your system. Older
versions of BlueALSA used `/etc/dbus-1/system.d/org.bluealsa.conf`, so you may
find you have versions of the file in both locations. In that case D-Bus will
attempt to apply the policy from both files, with the `/etc` file taking
precedence in case of conflict.
Re-install BlueALSA if the file is missing.

- The user account that the BlueALSA service is started under is not
permitted to do so by the D-Bus policy.\
The BlueALSA D-Bus policy file must contain a rule that permits the BlueALSA
service account to register names with the prefix `org.bluealsa`. The default
BlueALSA D-Bus policy file permits only `root` to register the prefix
`org.bluealsa`. To permit some other user account the D-Bus policy must be
updated. For example to permit the BlueALSA service to run under the account
name `bluealsa` in addition to being able to run as `root`:

   ```xml
   <busconfig>

     <policy user="bluealsa">
       <allow own_prefix="org.bluealsa"/>
       <allow send_destination="org.bluealsa"/>
     </policy>

     <policy user="root">
       <allow own_prefix="org.bluealsa"/>
       <allow send_destination="org.bluealsa"/>
     </policy>

     <policy group="audio">
       <allow send_destination="org.bluealsa"/>
     </policy>

   </busconfig>
   ```

- Another instance of the BlueALSA service is already running.\
To run a second instance of the BlueALSA service, it must use a different
well-known service name. This will also require updating the BlueALSA D-Bus
policy file. See the manual page [bluealsad(8)][] for more information and an
example of running multiple `bluealsad` instances.

If the D-Bus policy file is edited, then it is necessary to refresh the D-Bus
service for the change to take effect. On most systems this can be achieved
with (as `root`) :

```sh
systemctl reload dbus.service
```

[bluealsad(8)]: doc/bluealsad.8.rst

## 2. Couldn't get BlueALSA PCM: PCM not found

In contrast to standard ALSA sound cards, BlueALSA does not expose all PCMs
right away. In the first place it is required to connect remote Bluetooth
device with desired Bluetooth profile - run `bluealsad --help` for the list
of available profiles. For querying currently connected audio profiles (and
connected devices), run `bluealsa-aplay --list-devices`. The common
misconception is an attempt to use A2DP playback device as a capture one in
case where A2DP is not listed in the "List of CAPTURE Bluetooth Devices"
section.

Additionally, the cause of the "PCM not found" error might be an incorrect
ALSA PCM name. Run `bluealsa-aplay --list-pcms` for the list of currently
available ALSA PCM names - it might give you a hint what is wrong with your
`.asoundrc` entry. Also, take a look at the [bluealsa-plugins manual
page](doc/bluealsa-plugins.7.rst).

## 3. Couldn't get BlueALSA PCM: Rejected send message

This error message indicates that the user does not have permission to use
the BlueALSA service. BlueALSA client applications require permission from
D-Bus to communicate with the BlueALSA service. This permission is granted
by a D-Bus policy configuration file. A default BlueALSA installation will
grant permission only to members of the `audio` group and `root` (this is in
line with normal practice on ALSA systems whereby membership of the `audio`
group is required to use sound card devices).

There are several reasons why this permission is not granted:

- The D-Bus service has not been refreshed after installing BlueALSA.\
Try `sudo systemctl reload dbus.service`. If that does not work, try
rebooting.

- The user is not a member of the `audio` group.

- The user session was created before the user was added to the `audio`
 group.\
Log out, then log in again.

- The BlueALSA D-Bus policy file is not installed, or is in the wrong
location.\
In a default install, the file should be
`/usr/share/dbus-1/system.d/org.bluealsa.conf`. Check with your distribution
documentation in case D-Bus uses a different location on your system.
Re-install BlueALSA if the file is missing.

## 4. Couldn't open PCM: Device or resource busy

BlueALSA supports only one client connection to each PCM. This error occurs
when an application tries to set the hardware parameters for a PCM that is
already in use. Note that `bluealsa-aplay` opens each PCM (of the appropriate
profile) as soon as it connects, and therefore attempting to use an application
such as `arecord` to capture from BlueALSA while `bluealsa-aplay` is running
will result in this error.

## 5. Using BlueALSA alongside PulseAudio or PipeWire

It is not advisable to run BlueALSA if either PulseAudio or PipeWire are also
running with their own Bluetooth modules enabled. If one would like to have a
deterministic setup, it is first necessary to disable Bluetooth in those
applications.

On startup, the BlueALSA service will issue warnings if some other application
has already registered the Bluetooth Audio profiles:

```text
bluealsad: W: UUID already registered in BlueZ [hci0]: 0000110a-0000-1000-8000-00805f9b34fb
bluealsad: W: UUID already registered in BlueZ [hci0]: 0000110b-0000-1000-8000-00805f9b34fb
bluealsad: W: UUID already registered in BlueZ: 0000111f-0000-1000-8000-00805f9b34fb
```

However, as it is normal practice to start BlueALSA at boot and to start
PulseAudio only when the user logs in, these warnings may not appear in the
logs.

In the unlikely event that one should need to run BlueALSA at the same time as
PipeWire or PulseAudio, there are some hints on how to disable the PipeWire and
PulseAudio Bluetooth modules in the wiki: [PipeWire or PulseAudio integration][]

[PipeWire or PulseAudio integration]: https://github.com/arkq/bluez-alsa/wiki/PulseAudio-integration

## 6. ALSA thread-safe API (alsa-lib >= 1.1.2, <= 1.1.3)

ALSA library versions 1.1.2 and 1.1.3 had a bug in their thread-safe API
functions. This bug does not affect hardware audio devices, but it affects
many software plug-ins. Random deadlocks are inevitable. The best advice is
to use a more recent alsa-lib release, or if that is not possible then
disable the thread locking code via an environment variable, as follows:

```shell
export LIBASOUND_THREAD_SAFE=0
```