BlueALSA: Bluetooth audio without a sound server

The gap BlueZ 5 left behind

This project is a rebirth of a direct integration between BlueZ and ALSA, and the reason it exists is a specific change in BlueZ.

Since BlueZ 5, the built-in integration has been removed in favour of third party audio applications. From that point on, BlueZ acts as a middleware between an audio application, which implements the Bluetooth audio profile, and a Bluetooth audio device.

That left a practical gap. To stream audio to or from a Bluetooth device, you have to install a general purpose audio server such as PipeWire or PulseAudio, or use BlueZ version 4, which is deprecated and unmaintained.

BlueALSA's answer is to provide the same Bluetooth audio profile support as PulseAudio, but with fewer dependencies and at a lower level in the software stack. It registers all the classic Bluetooth audio profiles in BlueZ, and also the BLE-MIDI profile, though the other BLE audio profiles are not supported yet. In theory every Bluetooth device with classic audio capabilities can be connected.

So this is not a general purpose audio server that happens to know about Bluetooth. It is a narrow component that does one thing, which is what makes the dependency argument work.

The design target is a device with one application at a time

The README is unusually specific about what BlueALSA is for, and the constraint it states is what shapes every design decision in the project.

BlueALSA is designed specifically for use on small, low-powered, dedicated audio or audio and visual systems where the high-level audio management features of PulseAudio or PipeWire are not required. The target system must be able to function correctly with all its audio applications interfacing directly with ALSA, with only one application at a time using each Bluetooth audio stream.

In such systems BlueALSA adds Bluetooth audio support to the existing ALSA sound card support. The README then draws the line explicitly: the applications are constrained by the capabilities of the ALSA API, and the higher-level audio processing features of audio servers such as PulseAudio and PipeWire are not available.

That sentence is the honest summary of the trade. You give up the mixing, the per-application routing and the network streaming that a sound server provides, and you get a Bluetooth headset that behaves like a sound card. On a kiosk with one application playing to a Bluetooth speaker, that is exactly the right trade. On a desktop where several applications share audio, it is not.

The primary language is C, the licence is MIT with SPDX headers and a REUSE compliance badge, and the repository carries the usual distribution of an autotools project, with configure.ac, a Makefile.am, an AUTHORS.md, a CONTRIBUTING.md, a NEWS.md, a TROUBLESHOOTING.md, an INSTALL.md and a LICENSES/ directory.

The daemon, the plug-ins and the shape of the graph

BlueALSA consists of the daemon bluealsad, ALSA plug-ins, and a number of utilities, and the flow diagram in the README shows how they connect.

The heart is the daemon, which interfaces with the BlueZ bluetoothd daemon and the local Bluetooth adapter. It handles the profile connection and configuration logic for A2DP, HFP and HSP, and presents the resulting audio streams to applications via D-Bus. In general BlueALSA acts as a proxy between BlueZ and ALSA.

The ALSA plug-ins are the part that makes the whole thing invisible to applications. They hide all the D-Bus specifics and permit applications to use the ALSA PCM and mixer interfaces, so existing ALSA applications can access Bluetooth audio devices in the same way as they use sound card PCMs and mixers.

The diagram shows the adapter talking to both bluetoothd and bluealsad, with bluetoothd and bluealsad also talking over D-Bus. From bluealsad, the arrows go to bluealsactl for command line management, to bluealsa-aplay for playing, and to the ALSA plug-ins, which sit between libasound and the ALSA applications. The MIDI path is separate again, with bluealsad talking to the ALSA MIDI sequencer, which talks to the libasound layer and then to the MIDI application.

For BLE MIDI specifically, the daemon creates a simple MIDI port directly in the ALSA MIDI sequencer, so an ALSA MIDI application connects to the remote BLE MIDI device the way it would connect to a local one.

Using it, and the asoundrc entry that ties it together

The daemon must be running in order to pair, connect and use remote Bluetooth audio devices, and by default it runs as root during system startup. It registers the org.bluealsa service in the D-Bus system bus, which is how other components find it.

Once a device is connected, it appears as the bluealsa virtual PCM device, and any ALSA application can use it like any other PCM device:

aplay -D bluealsa Bourree_in_E_minor.wav

With more than one Bluetooth device connected, the target is selected as a parameter to the PCM, with the Bluetooth address in the middle:

aplay -D bluealsa:XX:XX:XX:XX:XX:XX, Bourree_in_E_minor.wav

There is a limitation to know about. The PCM device is based on the ALSA software PCM I/O plug-in, so it has no associated sound card and it will not be available in the ALSA Kernel proc interface. In other words, you cannot inspect it with the usual proc based tools, which is a small but confusing surprise for anyone used to debugging audio through /proc/asound.

Setup parameters for the bluealsa device are set in the local .asoundrc configuration file, with a defaults block per setting:

cat ~/.asoundrc
defaults.bluealsa.service "org.bluealsa"
defaults.bluealsa.device "XX:XX:XX:XX:XX:XX"

The utility list is short and each one covers a distinct job. bluealsactl is the command line management application for the BlueALSA system. bluealsa-aplay simplifies building a Bluetooth speaker using BlueALSA. And bluealsa-rfcomm is a command line application providing access to the RFCOMM terminal for HFP and HSP devices, which is how you read a headset's control channel from the command line.

The daemon's own options are in a manual page at doc/bluealsad.8.rst, and the pairing and connecting procedure for Linux has its own guide in the wiki.

The rename that will break your scripts

There is a warning box at the very top of the README, and it is the first thing any existing user needs to read.

The latest version uses new names for some core components. The bluealsa daemon is now called bluealsad, and the bluealsa-cli utility is now called bluealsactl. The wiki guide for migrating from release 4.3.1 or earlier has the details.

That is a small change in form and a large change in practice. The old names appear in scripts and in documentation, and every one of them has to change together. The bluealsa plug-in name is the one to be careful about, because the PCM device you pass to aplay is still called bluealsa, so the rename is not total and it is easy to half-migrate.

The change also explains why the older names still appear in the body of the README. The diagram labels the control utility with its new name, while the usage sections describe the bluealsa PCM device, and mixing the two is not an inconsistency.

The release history explains the shape of the project as well. There are no GitHub releases, so the version is tracked in the repository rather than in tags, and the last push to the master branch was on 2026-10-08. The build badge points at a build-and-test workflow, the coverage badge at codecov, and the tree is a conventional autotools layout with a src/ directory, a utils/ directory, a test/ directory, a doc/ directory and a misc/ directory.

Editorial conclusion

Adopt BlueALSA when the system you are building needs Bluetooth audio and you want to avoid a full audio server, because it registers the Bluetooth profiles in BlueZ and presents them as ALSA PCM devices, so an application that already plays sound needs no change. Do not adopt it on a desktop, where the higher-level features of PulseAudio or PipeWire are what you want, and note the renamed components, since the daemon is now bluealsad and the control utility bluealsactl, and a configuration written for release 4.3.1 or earlier will not match. Before you deploy, read the migration guide in the wiki and the troubleshooting document, because the path between a paired device and a working PCM involves a daemon running as root, a D-Bus service and an .asoundrc entry, and each step has its own failure mode.

Frequently asked questions

Official sources

1. arkq/bluez-alsa on GitHub
2. Issues
3. License: MIT
4. README