Skip to content

Installation from source

Jump to bottom Edit New page
Arkadiusz Bokowy edited this page Nov 11, 2024 · 67 revisions

Important

This document refers to BlueALSA components by the names used in the latest sources. For release v4.3.1 or earlier please note that:

  • The bluealsad daemon was called bluealsa
  • The bluealsactl utility was called bluealsa-cli

Note

This revision contains package information obtained by browsing the repositories of various Linux distributions. Not all the dependencies listed have been tested for correctness or completeness. It would be most helpful if readers of this page could try out the build on their own preferred distribution and correct any errors or omissions here as appropriate.

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.

1. Install Required Tools and Essential Development Libraries

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:

Debian/Raspberry Pi OS/Ubuntu

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

Fedora

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

Arch

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

2. Obtain The Latest Source Code and Prepare For Build

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

3. Configure The Build Directory

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.

Debugging options

  • --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.

A2DP options

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 (1.2.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

HSP/HFP options

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

MIDI options

  • --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.

Compatibility options

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.

Utility options

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.

  • --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.

Documentation options

  • --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.

Testing options

  • --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.

Installation options

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, defaults to '-S -p a2dp-source -p a2dp-sink' if not specified

  • --with-systemdbluealsaaplayargs=ARGS  [since v4.0.0]
    bluealsa-aplay arguments to be used in the installed bluealsa-aplay.service file, defaults to empty if not specified.

  • --with-bluealsaduser=USER  [since v4.1.0]
    set up the installation to run bluealsad as user USER, defaults to root if not specified. 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 not specified. USER must be a member of the "audio" group.

Environment Settings

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

Additional Dependencies

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:

Dependency Debian / Raspberry Pi OS / Ubuntu Fedora Arch
check check check check
fdk-aac libfdk-aac-dev (*) fdk-aac-free-devel libfdk-aac
lcov lcov lcov lcov
ldacBT (**) libldacbt-enc-dev
libldacbt-abr-dev		 libldac-devel libldac
libbsd libbsd-dev libbsd-devel libbsd
libfreeaptx (***) libfreeaptx-dev libfreeaptx-devel libfreeaptx
liblc3 liblc3-dev liblc3-devel liblc3
libopenaptx (***) libopenaptx-dev [No Fedora package] libopenaptx
libunwind libunwind-dev libunwind-devel libunwind
mpg123 libmpg123-dev mpg123-devel mpg123
mp3lame libmp3lame-dev lame-devel lame
ncurses libncurses-dev ncurses-devel ncurses
opus libopus-dev opus-dev opus
readline libreadline-dev readline-devel readline
rst2man python3-docutils python3-docutils python-docutils
spandsp libspandsp-dev spandsp-devel spandsp

(*) - 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.

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

Running configure

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

4. Finally, Compile and Install:

In the build directory:

make
sudo make install

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.

Dependency Debian / Raspberry Pi OS / Ubuntu Fedora
bash-completion bash-completion bash-completion
dbus dbus dbus-glib
fdk-aac libfdk-aac1 (*)
libfdk-aac2 (*)		 fdk-aac-free
libasound libasound2 alsa-lib
libbluetooth libbluetooth3 bluez-libs
libbsd libbsd0 libbsd
libfreeaptx libfreeaptx0 libfreeaptx
libglib2.0 libglib2.0-0 dbus-glib
liblc3 liblc3-0 liblc3
libopenaptx libopenaptx0 [No Fedora package]
libsbc libsbc1 sbc
libunwind libunwind8 libunwind
mpg123 libmpg123-0 mpg123
mp3lame libmp3lame0 lame
ncurses libncurses5
libncurses6		 ncurses
opus libopus0 opus
readline libreadline7
libreadline8		 readline
spandsp libspandsp2 spandsp

(*) 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/

Add a custom footer
Add a custom sidebar
Clone this wiki locally