Skip to content

Using Dynamic ALSA Configuration for BlueALSA PCMs

Jump to bottom
borine edited this page Oct 4, 2021 · 3 revisions

This is draft documentation for an experimental feature currently under development in a fork of bluez-alsa here: https://github.com/borine/bluez-alsa/tree/dynamic

Dynamic BlueALSA PCM ALSA Configuration

BlueALSA can optionally add connected devices to the list of ALSA devices generated by the ALSA namehints API without any need to write ALSA configuration file entries. In this way aplay -L and other applications will show connected BlueALSA PCMs. For example:

$ aplay -L
bluealsa:DEV=XX:XX:XX:XX:XX:XX,PROFILE=sco,SRV=org.bluealsa
    Jabra MOVE v2.3.0 HFP (CVSD)
    Bluetooth Audio Output
bluealsa:DEV=XX:XX:XX:XX:XX:XX,PROFILE=a2dp,SRV=org.bluealsa
    Jabra MOVE v2.3.0 A2DP (aptX)
    Bluetooth Audio Output

See Using the BlueALSA ALSA PCM Plugin for more information on ALSA namehints.

This feature is disabled by default. To enable it add an extra BlueALSA global configuration file to your ALSA configuration. This is achieved by setting the environment variable ALSA_CONFIG_PATH as follows:

ALSA_CONFIG_PATH=/usr/share/alsa/alsa.conf:/usr/share/bluealsa/alsa-dynamic.conf

On systemd systems the simplest way to achieve that is to create a file ~/.config/environment.d/alsa.conf containing that definition.

The PCM description format can be modified by setting the default description in your ~/.asoundrc with:

defaults.bluealsa.description "Description Text"

The description text can contain substitutions that will be expanded for each PCM. The available substitutions are:

 	%a	bluetooth address in format "XX:XX:XX:XX:XX:XX"
 	%c	codec
 	%n	device name (alias)
 	%p	profile
 	%s	stream direction ("Input" | "Output")
 	%%	literal '%'

The text can also contain a single newline which applications such as aplay will use to break the displayed description over two lines. Some other applications, particularly GUI applications, do not always render the newline very well.

The default description definition is:

defaults.bluealsa.description "%n %p (%c)
Bluetooth Audio %s"

Note the newline in this default.

Unfortunately, the majority of existing applications assume that the PCM list is static and only read it once on start-up. Some (e.g. kodi) assume that PCMs are all from soundcards and so refresh the list only in response to a udev event when a card, e.g. USB soundcard, is plugged/unplugged.

Clone this wiki locally