Migrating from release 4.3.1 or earlier

This document describes the changes that need to be made to migrate from release 4.3.1 or earlier to release 5.0.0 or later.

Core components renames

The following core components have been renamed:

• /usr/bin/ { bluealsa => bluealsad }
• /usr/bin/ { bluealsa-cli => bluealsactl }
• /usr/share/dbus-1/system.d/ { bluealsa.conf => org.bluealsa.conf }

Depending on the installation method, the configuration files might have been installed in different locations. If bluez-alsa was installed from the source, the best way to perform the migration is to remove the old installation and install the new one from scratch.

cd <path-to-bluez-alsa-build-dir>
# Uninstall the old version
git checkout v4.3.1 # or earlier used version
make && sudo make uninstall
# Install the new version
git checkout master
make && sudo make install

Configuration changes

1. From now on, the bluealsactl (formerly bluealsa-cli) is enabled by default. In order to disable it, one should use the --disable-ctl option during the configuration step.

D-Bus API changes

1. In the entire project, the term "sampling" was replaced with "rate" to be more consistent with the ALSA terminology. This includes the PCM property exposed by via D-Bus API. That means that the BlueALSA system service and D-Bus clients are not compatible across the v4.3.1 and newer versions.

Command line options changes

1. The --a2dp-volume option of BlueALSA system service has been removed. Now, the native A2DP volume is enabled by default. In order to disable it, one can use the bluealsactl tool to enable software volume scaling for desired PCM.

2. The --sampling option of the bluealsactl codec was renamed to --rate.

3. The --mixer-name option of bluealsa-aplay was renamed to --mixer-control.

4. The --profile-a2dp and --profile-sco options of bluealsa-aplay were removed in favor of --profile=TYPE. The behavior of using A2DP profile by default was not changed.

ALSA plugin changes

1. The ALSA plugins now use the logging API provided by alsa-lib. This means that the format of log messages and the default priority threshold has changed. By default only error messages are now output, even when --enable-debug is included in the configure options of the build; whereas previously debug builds of the plugins output debug messages by default. Note that this change applies only to the ALSA plugins, not to bluealsad nor bluealsa-aplay. Consult the bluealsa-plugins(7) manual page for details of the new message format and the method for enabling debug output with debug builds.