Installation from source - arkq/bluez-alsa GitHub Wiki

This page shows step by step the installation process of BlueALSA from the source code for various Linux distributions.

BlueALSA uses the GNU autoconf/automake build system. Given BlueALSA's aim of small size and minimum redundancy, it makes many of its features optional and only includes them if explicitly requested when configuring the build. This guide lists all the available options and gives details of any extra dependencies introduced by each option.

For general help with using autoconf, see the GNU autoconf manual Running configure scripts. There are also many tutorials on the web, just search for gnu autotools tutorial. However, this guide aims to provide sufficient instructions so no prior special knowledge of GNU automake or autoconf is required to complete the task of BlueALSA build and installation.

This installation guide does not cover bluealsad daemon automatic startup; for systemd integration please look at the systemd wiki page.

Firstly make sure that all essential build tools are installed. These are:
git, autotools, libtool, pkg-config, gcc, binutils, and the standard unix shell utilities.

Also required are the third-party libraries on which BlueALSA depends. The essential ones required by the BlueALSA core functions are:
libasound (1.0.27 or later), libbluetooth (5.51 or later), libglib2.0 (2.58.2 or later), libsbc (1.5 or later)

If building bluealsa-aplay (which is enabled by default) or bluealsactl then there is an additional dependency on:
libdbus (1.6 or later)

If building the optional man pages, there is an additional tool required, rst2man which is part of the python docutils project.

Here are some example install instructions for a few linux distributions; in each the first line installs the tools and the second installs the libraries:

sudo apt-get install git automake build-essential libtool pkg-config python3-docutils
sudo apt-get install libasound2-dev libbluetooth-dev libdbus-1-dev libglib2.0-dev libsbc-dev

sudo dnf install git automake libtool pkgconfig gcc python3-docutils
sudo dnf install alsa-lib-devel bluez-libs-devel dbus-glib-devel sbc-devel

sudo pacman -S git base-devel python-docutils
sudo pacman -S alsa-lib bluez-libs dbus glib2 sbc

Clone the BlueALSA source code from Github into your workarea:

git clone https://github.com/arkq/bluez-alsa.git
cd bluez-alsa

Prepare the auto configuration tools to use your development environment. It is very important to do this step after the essential requirements installation of step 1 above. In the bluez-alsa directory run the automatic reconfiguration as follows:

autoreconf --install --force

The --force option is necessary to ensure that the correct version identifier is compiled into the built executables. Re-run this command whenever the source code is updated, for example after using git pull.

Create a new directory in which to perform the build. This will keep the build products separate from the source code and make it easier to restart afresh if you need to change the configuration. We will call this directory "build", but you can use any unique name. If you are cross-compiling you may wish to create separate build directories, one for each host platform. You may also wish to have separate build directories for a debug build and a release build.

mkdir build
cd build

At this stage you need to decide which optional features you wish to include (if any). In order to compile additional codecs and utilities you must install additional dependencies. For more information on obtaining each individual dependency, see the section Additional Dependencies below. (Note that some codecs require a license, especially for commercial use).

The BlueALSA configure script offers all the standard autoconf options, and in addition the following specific options are available.

• --enable-debug  [since v1.0.0]
  enable debugging support (a lot of debug text will be written to the stderr of both the daemon and the alsa client).

• --enable-debug-time  [since v1.2.0]
  enable debug timing support

• --with-libunwind  [since v3.0.0]
  use libunwind for call-stack unwinding - requires libunwind 1.1 or later.

By default, the BlueALSA configure script builds only the mandated SBC codec support for the A2DP profile. To add support for other A2DP codecs, each must be explicitly enabled on the configure command line. The codecs that can be enabled are:

• --enable-aac  [since v1.2.0]
  enable AAC support - requires fdk-aac 0.1.1 or later development headers and libraries

• --enable-aptx  [since v1.3.0]
  enable aptX support - BlueALSA supports three alternative aptX libraries: openaptx by @arkq, libopenaptx by @pali, or libfreeaptx (which is a fork of libopenaptx and is used by PipeWire). Requires development headers and libraries from one of those three alternatives. By default this option selects openaptx (2.0.0 or later) by @arkq unless --with-libopenaptx or --with-libfreeaptx is used. Adding either --with-libopenaptx or --with-libfreeaptx option is recommended if one wants to use aptX codecs, as they have better decoder support.

• --enable-aptx-hd  [since v2.0.0]
  enable aptX HD support - requires openaptx development headers and libraries (unless --with-libopenaptx or --with-libfreeaptx is used; it is recommended to use one of those options for aptx HD).

• --with-libopenaptx  [since v3.1.0]
  use libopenaptx for aptX and aptX HD - requires libopenaptx 0.2.0 or later development headers and libraries.

• --with-libfreeaptx  [since v4.2.0]
  use libfreeaptx for aptX and aptX HD - requires libfreeaptx 0.1.1 or later development headers and libraries.

• --enable-faststream  [since v4.0.0]
  enable FastStream support - no additional libraries required

• --enable-lc3plus  [since v4.0.0]
  enable LC3plus support - requires LC3plus development headers and libraries

• --enable-ldac  [since v2.0.0]
  enable LDAC support - requires ldacBT development headers and libraries (ldacBT-abr 1.0.0 or later, ldacBT-dec and ldacBT-enc 2.0.0 or later.

• --enable-mp3lame  [since v2.0.0]
  enable MP3 support - requires mp3lame development headers and libraries

• --enable-mpg123  [since v2.0.0]
  enable MPG123 decoding support - requires mpg123 1.0.0 or later development headers and libraries

• --enable-opus  [since v4.3.0]
  enable Opus support - requires opus development headers and libraries

By default, the BlueALSA configure script builds only the mandated CVSD codec for the HSP and HFP profiles. It is possible to also add support for the mSBC and LC3-SWB codecs for HFP by explicitly enabling them on the configure command line:

• --enable-lc3-swb  [since v4.2.0]
  enable LC3-SWB support - requires liblc3 1.0.0 or later development headers and libraries

• --enable-msbc  [since v2.0.0]
  enable mSBC support - requires spandsp 0.0.6 or later development headers and libraries

• --enable-midi  [since v4.2.0]
  enable Bluetooth LE MIDI support - requires no extra libraries at build time. See wiki page Using BlueALSA as BLE MIDI server for more details of BLE midi support.

BlueALSA can be built with additional features to improve compatibility with some other applications by enabling some or all of these features on the configure command line:

• --enable-ofono  [since v1.4.0]
  enable HFP over oFono - requires no extra libraries at build time. Including this option will enable BlueALSA's support for ofono. In this case BlueALSA will defer all telephone integration to oFono if an ofono service is discovered at run-time. If no ofono service is available then BlueALSA will fall back on its own internal HFP implementation.

• --enable-upower  [since v2.1.0]
  enable UPower integration - requires no extra libraries at build time. When built with this option, BlueALSA will advertise support for a battery level indicator to Bluetooth devices.

• --disable-payloadcheck  [since v1.3.0]
  disable RTP payload type check (workaround for a bug in PulseAudio versions before 13.0, and some Android versions) Earlier releases of PulseAudio, and also Android, set a non-compliant value in the payload type field of RTP packets, meaning that Bluetooth standard compliant devices and applications (such as BlueALSA) would reject those packets. This option disables that check in BlueALSA, permitting a computer running PulseAudio to use another computer running BlueALSA as an audio sink. This bug in PulseAudio was fixed in release 13.0; not sure which Android versions are affected.

A number of utility applications are included in the BlueALSA sources. These options determine whether they are built or not. See the linked manual page for more information about each utility.

• --disable-aplay  [since v1.2.0]
  disable building of the bluealsa-aplay tool. See manual page.
  bluealsa-aplay is built by default - this option removes it from the build.
  bluealsa-aplay requires libdbus 1.6 or later development headers and libraries.

• --with-libsamplerate  [not yet released]
  include libsamplerate adaptive resampling support when building bluealsa-aplay.
  Requires libsamplerate 0.2.0 or later development headers and libraries.

• --disable-ctl  [not yet released]
  disable building of the bluealsactl tool. See manual page.
  bluealsactl is built by default - this option removes it from the build.
  bluealsactl requires libdbus (dbus-1 1.6 or later) development headers and libraries.

• --enable-a2dpconf  [since v3.0.0]
  enable building of the a2dpconf tool. See manual page.

• --enable-rfcomm   [since v1.3.0]
  enable building of the bluealsa-rfcomm tool. See manual page.
  Requires readline development headers and libraries.

• --enable-hcitop  [since v1.3.0]
  enable building of hcitop tool. See manual page.
  Requires libbsd 0.8 or later and ncurses development headers and libraries.

• --enable-cli  [from v3.1.0 up to v4.3.1]
  enable building of the bluealsa-cli tool. See manual page.
  Release v4.3.1 was the last release to include bluealsa-cli. After that release it was renamed to bluealsactl and included in the bulld by default. See option --disable-ctl above.
  Requires libdbus (dbus-1 1.6 or later) development headers and libraries.

• --enable-manpages  [since v3.0.0]
  build and install manual pages for the bluealsad daemon, the BlueALSA ALSA plugins, and the enabled utilities. Requires the utility rst2man from the docutils project.

• --enable-test  [since v1.4.0]
  build the unit test programs - requires check 0.9.10 or later testing framework. Some of the tests also require sndfile 1.0 or later; those tests will be omitted if sndfile is not available.

• --with-coverage  [since v3.0.0]
  use lcov for test coverage reporting - requires lcov 1.14 or later.

By default, BlueALSA will use the install prefix /usr. This is unusual for autoconf projects, which usually default to /usr/local. This choice was made because the alsa plugin modules must be installed in the same prefix as libasound, and most Linux distributions will have installed the alsa components in /usr.

From alsa release 1.1.7 or later, the main alsa runtime configuration file contains a hard-coded path to local configuration files: /etc/alsa/conf.d So, unless your distribution has patched that file, it is necessary to place the BlueALSA local config file (20-bluealsa.conf) in that directory. The BlueALSA installer will by default do so. This can be overriden either with the standard option: --sysconfdir=DIR (to place the file in DIR/alsa/conf.d) or with the BlueALSA specific option: --with-alsaconfdir=DIR (to place the file in DIR)

For alsa release 1.1.6 and earlier, the BlueALSA configure script will place the alsa configuration file in the default /usr/share/alsa/alsa.conf.d. This can be overridden with either the standard option --datadir=DIR (for DIR/alsa/alsa.conf.d) or with the BlueALSA specific option: --with-alsaconfdir=DIR (to place the file in DIR).

From release 4.1.0 BlueALSA includes persistent storage for device volume settings. By default, configure will set the directory used for this storage to be /var/lib/bluealsa. However, if the --prefix=PREFIX option is given, then this default will be changed to PREFIX/var/lib/bluealsa. To select some other directory, use the --localstatedir=DIR standard option; in this case the BlueALSA storage directory will be DIR/lib/bluealsa. Note that when using systemd, the bluealsad executable will use the directory given by the systemd StateDirectory= directive relative to systemd's preset path for state files, resulting in /var/lib/bluealsa, overriding the compiled-in value set here by configure.

• --with-dbusconfdir=dir  [since v2.0.0]
  path to D-Bus system bus configuration files. By default, configure will use pkg-config to find the D-Bus configuration root on the build system, then append /dbus-1/system.d and install the D-Bus config file there (ignoring any --prefix setting). Starting with BlueALSA release 4.2.0 configure uses pkg-config --variable=datadir dbus-1 (as now recommended by the D-Bus project), which typically evaluates to /usr/share/ giving a default path of /usr/share/dbus-1/system.d. BlueALSA releases 4.1.1 and earlier used pkg-config --variable=sysconfdir dbus-1 giving a typical default path of /etc/dbus-1/systemd.

If you are installing into a sysroot that is not the build system root, then you can use this option to override that default.

• --with-alsaplugindir=dir  [since v1.0.0]
  path where ALSA plugin files are stored. By default, configure will use pkg-config --variable=libdir alsa to find the ALSA library install root on the build system, then append /alsa-lib and install the ALSA plugin library files there (ignoring any --prefix setting). If you are installing into a sysroot that is not the build system root, then you can use this option to override that default.

• --with-alsaconfdir=dir  [since v1.4.0]
  path to ALSA add-on configuration files. By default configure will use the ALSA default location (relative to any --prefix= setting) for the build system. If you are installing into a sysroot that is not the build system root, then you can use this option to override that default.

• --with-bash-completion[=DIR]  [since v3.1.0]
  install a bash completion script in DIR (or in the bash completions default directory if DIR is not specified). This script requires the bash-completion 2.0 or later package to be installed on the runtime host.

• --enable-systemd  [since v4.0.0]
  install default systemd service unit files for bluealsad and bluealsa-aplay. Requires systemd version 200 or later.

• --with-systemdsystemunitdir=DIR  [since v4.0.0]
  directory in which to install systemd unit files. By default, configure will use pkg-config --variable=systemdsystemunitdir systemd to find the correct path. If you are installing into a sysroot that is not the build system root, then you can use this option to override that default.

• --with-systemdbluealsadargs=ARGS  [since v4.0.0]
  bluealsad arguments to be used in the installed bluealsa.service file. ARGS must be a valid list of bluealsad command-line options; see the bluealsad manual page for details. If this option is not given then the default used is -S -p a2dp-source -p a2dp-sink --all-codecs.

• --with-systemdbluealsaaplayargs=ARGS  [since v4.0.0]
  bluealsa-aplay arguments to be used in the installed bluealsa-aplay.service file. ARGS must be a valid list of bluealsa-aplay command-line options; see the bluealsa-aplay manual page for details. If this option is not given then the default used is -S.

• --with-bluealsaduser=USER  [since v4.1.0]
  set up the installation to run bluealsad as user USER, defaults to root if this option is not given. When used with bluez <= 5.50, USER must be a member of the "bluetooth" group. This option configures the bluealsa.service file and also configures D-Bus to permit USER to own the service name org.bluealsa. See D-Bus Policy for more information on the BlueALSA D-Bus policy file.

• --with-bluealsaaplayuser=USER  [since v4.1.0]
  configure the systemd bluealsa-aplay.service unit file to run bluealsa-aplay as user USER, defaults to root if this option is not given. USER must be a member of the "audio" group.

If necessary, it is possible to set various environment variables to alter choices made by the configure script - particularly fine-tuning the search paths for various components. To see a list of the variables that can be used, and a complete list of all command line options, in the build directory type:

../configure --help

In order to compile additional codecs and utilities, one must install additional dependencies as noted against the options above. These must be installed before running the configure script. Example package names for some distributions:

(*) - RaspberryPiOS repository does not have any built packages for fdk-aac so this must be built from source for this platform. Upstream sources are maintained on GitHub at https://github.com/mstorsjo/fdk-aac

(**) - ldacBT in distributions' repositories does not provide decoding support.

(***) - Some distributions' repositories include both libopenaptx and libfreeaptx, some have only one of them, some have neither. You should seek advice from your distribution for which to choose. If your distribution does not include either library, you can obtain the original sources from: pali/libopenaptx or libfreeptx.

(****) - Since debian trixie, ubuntu 24.10 and Fedora 41 the development package is necessary so that the systemd pkg-config support is available to the bluez-alsa configure script. Earlier releases of those distributions had the systemd pkg-config support installed by default.

Some dependencies are not available in the distributions' repositories, and must be built from source. See the respective project repository for instructions:

• openaptx
• ldacBT
• LC3plus - the lc3plus source code can be built as a shared library from @arkq's mirror of LC3plus. Build either the fixed point or floating point source code with

make libLC3plus.so

in the appropriate sub-directory of src. The makefile does not include an install target, so you must copy the library file and header file to appropriate locations manually. For example:

sudo cp libLC3plus.so /usr/local/lib
sudo cp lc3plus.h /usr/local/include

For bluez-alsa release 4.1.0 or earlier, please see https://github.com/arkq/bluez-alsa/issues/479#issuecomment-1618857445 for more information.

Once the required configuration options have been chosen, and the build dependencies installed, the build area can be configured. From within the build directory, type:

../configure --option1 --option2 ...

Some examples:

• To generate a simple debug build, with no additional options:

  ../configure --enable-debug

• To generate a debug build with support for AAC and compatible with older PulseAudio releases:

  ../configure --enable-debug --enable-aac --disable-payloadcheck

• To generate a release build with support for AAC, aptX, oFono and mSBC:

  ../configure --enable-aac --enable-aptx --with-libopenaptx --enable-ofono --enable-msbc

• To generate a release build with support for LDAC encoding and decoding (assuming that the full version of Sony libldac library was installed in the /opt/libldac directory):

  export LDAC_ABR_CFLAGS="-I/opt/libldac/include" LDAC_ABR_LIBS="-L/opt/libldac/lib -lldacBT_abr"
  export LDAC_DEC_CFLAGS="-I/opt/libldac/include" LDAC_DEC_LIBS="-L/opt/libldac/lib -lldacBT_dec"
  export LDAC_ENC_CFLAGS="-I/opt/libldac/include" LDAC_ENC_LIBS="-L/opt/libldac/lib -lldacBT_enc"
  ../configure --enable-ldac

It is possible to select additional options passed to the compiler or linker by setting some environment variables used by make or by setting some variables understood by make on the command line. This is most often done to set diagnostic, optimization or debug options. Options for the compiler can be set using the variable CFLAGS. In most cases this is not necessary and to compile BlueALSA it is sufficient to run, in the build directory:

make

In general BlueALSA works well, even on low powered single-board devices. If your runtime host is very limited in available storage or memory space, or has very limited CPU power, then some optimization by the compiler may be beneficial.

For gcc and clang the relevant options for optimization are (taken from the output of gcc --help=optimizers):

  -O<number> Set optimization level to <number>.
  -Ofast     Optimize for speed disregarding exact standards compliance.
  -Og        Optimize for debugging experience rather than speed or size.
  -Os        Optimize for space rather than speed.
  -Oz        Optimize for space aggressively rather than speed.

It is possible to further reduce the size of the binary files by adding the flag -s which strips out some information used only by the linker and debuggers.

As a general guide

• to optimize for minimum size use make CFLAGS="-Os -s"
• to optimize for maximum speed use make CFLAGS="-Ofast -s"
• to optimize for best compromize between speed and size use make CFLAGS="-O2 -s"
• to optimize for best debugging ability use make CFLAGS="-Og -g"

For more specific guidance consult the documentation for your compiler or seek help from your distribution.

It is important to note that most of the processor usage of bluealsad is actually the encoding and decoding of the Bluetooth codecs, which is done by the third-party codec libraries. It is therefore more important to use optimized builds of those libraries than to optimize BlueALSA itself.

Before BlueALSA can be used its components must be installed into the correct locations so that ALSA, D-Bus, and other system services can find them.

To install the built BlueALSA on the build machine, use:

sudo make install

To install into a directory tree that can be zipped and transferred to another machine, use:

make DESTDIR=$(pwd)/BLUEALSA install

substitute any name you prefer for the directory in place of "BLUEALSA".

To create packages suitable for installation by your distribution package manager, seek advice from your distribution.

It is also necessary to install the runtime dependencies for all the libraries included in the build. For some distributions (such as Arch) both development and runtime components are included in a single package. For others (such as Debian and Fedora) separate packages must be installed. The following table gives the relevant package names for some distributions.

Debian based distributions require a particular version of runtime a library package to be specified. The best choice (and available choices) depends on the OS release in use. The table gives alternative packages for recent releases, however it may not always be kept up-to-date with the latest release.

(*) Not available in RaspberryPiOS repositories.

The alsa project team changed the default directory structure for config files with release 1.1.7. In order to ease the transition when upgrading to this release, some distributions (e.g. Debian buster) support both structures by placing config files in the old structure, and creating symlinks to the files from the new structure (or vice-versa). The BlueALSA make install does not create these sym links. Therefore, to make sure that all applications obtain the correct alsa configuration, it may be advisable to manually create the symlink for the BlueALSA config (20-bluealsa.conf) on such distributions.

The "old" directory for alsa config files before 1.1.7 was:

/usr/share/alsa/alsa.conf.d/

and the "new" directory in alsa 1.1.7 and later is:

/etc/alsa/conf.d/