BLUEALSA(8)

📦
version 4.3.1 · 5 versions
, in alpine 3.24, debian trixie, ubuntu questing

🎀 BLUEALSA(8) 🎀

System Manager's Manual · the manual page for bluealsa 💖

okay bestie, sit down, hydrate, because we're about to talk about the daemon that makes Bluetooth audio on Linux actually, like, work. no cap. 🫶

✨ NAME ✨

bluealsa — Bluetooth Audio ALSA Backend 🌈

like. that's the whole name. short, iconic, does exactly what it says on the tin. 💅

🦋 SYNOPSIS 🦋

bluealsa -p PROFILE [OPTION]...

that's it. that's the whole vibe. you give it a profile with -p, you can pile on [OPTION]... after it, and off it goes. ✨

💜 DESCRIPTION 💜

okay so, bluealsa is a Linux daemon — a lil background main character that just lives on your system doing its thing — and what it does is give applications access to Bluetooth audio streams. 🔥

and which streams? so glad you asked. it does this using these profiles:

  • A2DP
  • HFP
  • HSP
  • and/or BLE-MIDI 🎹

(that "and/or" is doing a lot of work there and we respect it.)

it hands applications a D-Bus API to talk to, so apps can get in on the Bluetooth audio action. 🫶

and also — because it's not just one-trick — it can be used by ALSA applications through libasound plugins. so your regular ALSA-using apps get access too, no extra drama. 💖

lowkey important: for the deets on that plugin situation, go look at bluealsa-plugins(7). that's where the details live. iykyk. 👑

still with me? good, because this page keeps going and you're gonna want to stay for the rest. 🌸

✨ OPTIONS ✨

okay bestie, this is the part where we pick our ✨settings✨. every flag, every value, every default — it's all here, no skips, no cap. let's get into it 💅

  • -h, --help — prints a usage message and then dips out. that's it, that's the whole job 🫶
  • -V, --version — prints the version number and exits. short, sweet, iconic ✨
  • -S, --syslog — sends output to the system logger, aka syslogd(8). by default, log output goes to stderr. so if you want it in syslog instead, this is your girl 💖
  • --loglevel=LEVEL — sets the priority level threshold for log messages. only messages of the given level or higher get logged. the LEVELs are, in decreasing order:
    • error — error conditions
    • warning — warning conditions
    • info — informational messages If bluealsa was built with debug enabled, then an additional, lowest, level is available:
    • debug — debug messages If this option is not given, the default is to use the lowest level (i.e., all messages are logged). so yeah, default is maximum yapping 😭
  • -B NAME, --dbus=NAME — BlueALSA D-Bus service name suffix. without this option, bluealsa registers itself as an org.bluealsa D-Bus service. for more info, see the EXAMPLES below. lowkey important if you're running multiple instances 👑
  • -i hciX, --device=hciX — HCI device to use. can be specified multiple times to select more than one HCI. because HCI numbering can change after a system reboot, this option also accepts HCI MAC address for the hciX value, for example: --device=00:11:22:33:44:55. without this option, the default is to use all available HCI devices. so if you don't pick, it picks everything for you 🦋
  • -p NAME, --profile=NAME — enable NAME Bluetooth profile. may be given multiple number of times to enable multiple profiles. it is mandatory to enable at least one Bluetooth profile. for the list of supported profiles see Profiles in the NOTES section below. no profile, no party 🎀
  • -c NAME, --codec=NAME — enable or disable NAME Bluetooth audio codec. may be given multiple number of times to enable (or disable) multiple codecs. in order to disable given audio codec (remove it from the list of audio codecs enabled by default), the NAME has to be prefixed with - (minus) character. it is not possible to disable SBC and CVSD codecs which are mandatory for A2DP and HFP/HSP respectively. by default BlueALSA enables SBC, AAC (if AAC support is compiled-in), CVSD, mSBC (if mSBC support is compiled-in) and LC3-SWB (if LC3-SWB support is compiled-in). for the list of supported audio codecs see the "Available BT audio codecs" section of the bluealsa command-line help message. slay those codecs 💖
  • --initial-volume=NUM — set the initial volume to NUM % when a device is first connected. NUM must be an integer in the range from 0 to 100. by default the volume of all PCMs of a device is set to 100% (full volume) when the device is first connected. for some devices, particularly headphones, this can lead to an unpleasant experience. this option allows the user to choose an alternative initial volume level. only one value can be specified and each device on first connect will have the volume level of all its PCMs set to this value. however, a device with native volume control may then immediately override this level. on subsequent connects the volume will be set to the remembered value from the last disconnection. see Volume control in the NOTES section below for more information. protect your ears bestie 🫶
  • --keep-alive=SEC — keep Bluetooth transport alive for SEC number of seconds after streaming was closed. this option is required when using bluealsa with applications that close and then immediately re-open the same PCM as part of their initialization; for example applications built with the portaudio portability library and many other "portable" applications. it can also be useful when playing short audio files in quick succession. it will reduce the gap between playbacks caused by Bluetooth audio transport acquisition. no awkward silence between tracks ✨
  • --io-rt-priority=NUM — set the FIFO scheduler real-time priority of the I/O threads to NUM. by default all I/O threads run at the same priority as the main thread. this option allows the user to increase the priority of the I/O threads. this can be useful when playing audio with a low latency requirement. it is recommended to use this option when using the HFP profile with the mSBC codec, as the Linux kernel does not provide any buffering for the mSBC SCO socket. if the data are not read from the socket in time, the kernel will drop them. this can lead to lots of "Missing mSBC packets" warnings which will be audible as clicks in the audio. for more information about scheduling policies and priorities see sched(7). give those threads main character energy 🔥
  • --disable-realtek-usb-fix — since Linux kernel 5.14 Realtek USB adapters have required bluealsa to apply a fix for mSBC. this option disables that fix and may be necessary when using an earlier kernel. vintage kernel vibes 💀
  • --a2dp-force-mono — force monophonic sound for A2DP profile. one channel, one vibe 🎧
  • --a2dp-force-audio-cd — force 44.1 kHz sampling frequency for A2DP profile. some Bluetooth devices can handle streams sampled at either 48kHz or 44.1kHz, in which case they normally default to using 48kHz. with this option, bluealsa will request such a device uses only 44.1 kHz sample rate. old-school CD energy 💿
  • --a2dp-volume — enable native A2DP volume control. by default bluealsa will use its own internal scaling algorithm to attenuate the volume. this option disables that internal scaling and instead passes the volume change request to the A2DP device. this feature can also be controlled during runtime for individual PCMs via the BlueALSA D-Bus API or by the BlueALSA ALSA plugins; and if so the changed setting will be remembered. see Volume control in the NOTES section below for more information. note that this feature might not work with all Bluetooth headsets. so like, your mileage may vary bestie 🙈
  • --sbc-quality=MODE — set SBC encoder quality. default value is high. the MODE can be one of:
    • low — low audio quality (mono: 114 kbps, stereo: 213 kbps)
    • medium — medium audio quality (mono: 132 kbps, stereo: 237 kbps)
    • high — high audio quality (mono: 198 kbps, stereo: 345 kbps)
    • xq — SBC Dual Channel HD (SBC XQ) (452 kbps)
    • xq+ — SBC Dual Channel HD (SBC XQ+) (551 kbps)
  • --mp3-algorithm=TYPE — select LAME encoder internal algorithm. default value is expensive. the TYPE can be one of:
    • fast — OK quality, really fast
    • cheap — good quality, fast
    • expensive — near-best quality, not too slow
    • best — best quality, slow If CPU power consumption is not an issue, one might safely select best as the algorithm type. also, please note that the true quality is determined by the selected bit rate or used VBR quality option (--mp3-vbr-quality). so like, don't just trust the algorithm name, okay? 💅
  • --mp3-vbr-quality=MODE — set variable bit rate (VBR) quality. default value is standard. the MODE can be one of:
    • low — low audio quality (100-130 kbps)
    • medium — medium audio quality (140-185 kbps)
    • standard — standard audio quality (170-210 kbps)
    • high — high audio quality (190-250 kbps)
    • extreme — best audio quality, no low-pass filter (220-260 kbps)
  • --aac-afterburner — enables Fraunhofer AAC afterburner feature, which is a type of analysis by synthesis algorithm. this feature increases the audio quality at the cost of increased processing power and overall memory consumption. glow-up for your ears, but your CPU is gonna feel it 😭
  • --aac-bitrate=BPS — set the target bit rate for constant bit rate (CBR) mode or the maximum peak bit rate for variable bit rate (VBR) mode. default value is 220000 bits per second. numbers, numbers, numbers ✨
  • --aac-latm-version=NUM — select LATM syntax version used for AAC audio transport. default value is 1. the NUM can be one of:
    • 0 — LATM syntax specified by ISO-IEC 14496-3 (2001), should work with all older BT devices
    • 1 — LATM syntax specified by ISO-IEC 14496-3 (2005), should work with newer BT devices
  • --aac-true-bps — enable true "bit per second" bit rate. A2DP AAC specification requires that for the constant bit rate (CBR) mode every RTP frame has the same bit rate and for the variable bit rate (VBR) mode the maximum peak bit rate limit is also per RTP frame. however, a single RTP frame does not contain a single full second of audio. this option enables true bit rate calculation (per second), which means that per RTP frame bit rate may vary even for CBR mode. this feature is not enabled by default, because it violates A2DP AAC specification. enabling it should result in an enhanced audio quality, but will for sure produce fragmented RTP frames. if RTP fragmentation is not supported by used A2DP sink device (e.g., headphones) one might hear clearly audible clicks in the playback audio. in such case, please do not enable this option. seriously bestie, read the room 💀
  • --aac-vbr — prefer variable bit rate mode over constant bit rate mode. please note, that this option does not necessarily mean that the variable bit rate (VBR) mode will be used. used AAC configuration depends on a remote Bluetooth device capabilities. so it's giving "we'll see" energy 🙈
  • --lc3plus-bitrate=BPS — set LC3plus encoder bit rate for constant bit rate mode (CBR) as BPS. default value is 396800 bits per second. another number, another slay 💅
  • --ldac-abr — enables LDAC adaptive bit rate, which will dynamically adjust encoder quality based on the connection stability. it's reading the vibes and adapting, periodt 🔥
  • --ldac-quality=MODE — specifies LDAC encoder quality. default value is standard. the MODE can be one of:
    • mobile — mobile quality (44.1 kHz: 303 kbps, 48 kHz: 330 kbps)
    • standard — standard quality (44.1 kHz: 606 kbps, 48 kHz: 660 kbps)
    • high — high quality (44.1 kHz: 909 kbps, 48 kHz: 990 kbps)
  • --midi-advertisement — advertise BLE-MIDI service using Bluetooth LE advertising. MIDI girlies rise up 🎹
  • --xapl-resp-name=NAME — set the product name send in the XAPL response message. by default, the name is set as "BlueALSA". however, some devices (reported with e.g., Sony WM-1000XM4) will not provide battery level notification unless the product name is set as "iPhone". so yeah, sometimes you gotta cosplay as an iPhone for the battery tea 🍓

✨ NOTES ✨

🎧 Profiles 🎧

okay so bestie, bluealsa is out here supporting Bluetooth Advanced Audio Distribution Profile (A2DP), Hands-Free Profile (HFP), Headset Profile (HSP) and Bluetooth Low Energy MIDI (BLE-MIDI). And no, they are NOT all the same vibe:

  • A2DP is the one dedicated for streaming music — think stereo, 48 kHz or more sampling frequency. the whole point is it bops 💃
  • HFP and HSP are for two-way voice transmission — mono, 8 kHz or 16 kHz sampling frequency, so, like, phone call energy 📞
  • BLE-MIDI, on the other hand, is used for transmitting MIDI messages over Bluetooth LE 🎹

The Bluetooth audio profiles are not peer-to-peer — the way that they work is each one has a source or gateway role (a2dp-source, hfp-ag, or hsp-ag) and a sink or target role (a2dp-sink, hfp-hf, hsp-hs). The source/gateway role is the audio player (e.g., mobile phone), the sink/target role is the audio renderer (e.g., headphones or speaker). And the bluealsa daemon can perform any combination of profiles and roles, although it is most common to use it either as a source/gateway:

bluealsa -p a2dp-source -p hfp-ag -p hsp-ag

or as a sink/target:

bluealsa -p a2dp-sink -p hfp-hf -p hsp-hs

or with oFono for HFP support,

source/gateway:

bluealsa -p a2dp-source -p hfp-ofono -p hsp-ag

sink/target:

bluealsa -p a2dp-sink -p hfp-ofono -p hsp-hs

With A2DP, bluealsa always includes the mandatory SBC codec and may also include various optional codecs like AAC, aptX, and other. With HFP, bluealsa always includes the mandatory CVSD codec and may also include the optional mSBC and LC3-SWB codecs. The full list of available optional codecs, which depends on selected compilation options, will be shown with the bluealsa command-line help message. iykyk ✨

The list of profile NAME-s accepted by the --profile=NAME option:

  • a2dp-source — Advanced Audio Source (streaming audio to connected device) 🎶
  • a2dp-sink — Advanced Audio Sink (receiving audio from connected device) 🎧
  • hfp-ofono — Hands-Free AG/HF handled by oFono
  • hfp-ag — Hands-Free Audio Gateway
  • hfp-hf — Hands-Free
  • hsp-ag — Headset Audio Gateway
  • hsp-hs — Headset
  • midi — Bluetooth LE MIDI
The hfp-ofono and midi profiles are available only when bluealsa was compiled respectively with oFono and BLE-MIDI support. so if you're like "where is it 😭" — that's why. compilation options, bestie.

Enabling HFP over oFono will automatically disable hfp-hf and hfp-ag. Also, it is important to note that BlueZ permits only one service to register the HFP profile, and that service is automatically registered with every HCI device. no sharing, no splitting, it's giving exclusive 💅

For the A2DP profile, BlueZ allows each HCI device to be registered to a different service, so it is possible to have multiple instances of bluealsa offering A2DP support, each with a unique service name given with the --dbus= option, so long as they are registered to different HCI devices using the --device= option. See the EXAMPLES below. 👀

A profile connection does not immediately initiate the audio stream(s); audio can only flow when the profile transport is "acquired". Acquisition can only be performed by the source/gateway role. When acting as source/gateway, bluealsa acquires the profile transport (i.e., initiates the audio connection) when a client opens a PCM. When bluealsa is acting as target, a client can open a PCM as soon as the profile is connected, but the audio stream(s) will not begin until the remote source/gateway has acquired the transport. periodt 🫶

🔊 Volume control 🔊

The Bluetooth specifications for HFP and HSP include optional support for volume control of the target by the gateway device. For A2DP, volume control is optionally provided by the AVRCP profile. And bluealsa? bluealsa provides a single, consistent, abstracted interface for volume control of PCMs. main character energy honestly 👑

This interface can use the native Bluetooth features — or alternatively, bluealsa also implements its own internal volume control, called "soft-volume". For A2DP the default is to use soft-volume, but this can be overridden to use the Bluetooth native support where available by using the --a2dp-volume command line option. For HFP/HSP the default is to use Bluetooth native volume control.

When using soft-volume, bluealsa scales PCM samples before encoding, and after decoding, and does not interact with the Bluetooth AVRCP volume property or HFP/HSP volume control. Volume can only be modified by local clients.

(Note that Bluetooth headphones or speakers with their own volume controls will still be able to alter their own volume, but this change will not be notified to bluealsa local clients — they will only see the soft-volume setting. so like, two parallel universes of volume fr fr 🌈)

When using native volume control, bluealsa links the PCM volume setting to the AVRCP volume property or HFP/HSP volume control. No scaling of PCM samples is applied. Volume can be modified by both local clients and the remote device. Local clients will be notified of volume changes made by controls on the remote device. slay, bidirectional 💖

A2DP native volume control does not permit independent values for left and right channels, so when a client sets such values bluealsa will set the Bluetooth volume as the average of the two channels. math is math 🧮

Volume level, mute status, and soft-volume selection can all be controlled for each PCM by using the D-Bus API (or by using ALSA plugins, see bluealsa-plugins(7) for more information). The current value of these settings for each PCM is stored in the filesystem so that the device can be disconnected and later re-connected without losing its volume settings. it remembers. iconic behaviour 💾

When a device is connected, the volume level of its PCMs is set according to the following criteria (highest priority first):

  1. saved value from previous connection of the device
  2. value set by the --initial-volume command line option
  3. 100%

its mute status according to:

  1. saved value from previous connection
  2. false

and its soft-volume status according to:

  1. saved value from previous connection
  2. false for SCO (i.e., use native volume control).
  3. false for A2DP if the --a2dp-volume command line option is given
  4. true for A2DP (i.e., use soft-volume control).

When native volume control is enabled, then the remote device may also modify the volume level after this initial setting. Mute and soft-volume are implemented locally by the bluealsa daemon and cannot be modified by the remote device. local business only 🔒

Heads up bestie: note that bluealsa relies on support from BlueZ to implement native volume control for A2DP using AVRCP, and BlueZ has not always provided robust support here. It is recommended to use BlueZ release 5.65 or later to be certain that native A2DP volume control will always be available with those devices which provide it. do not come for me if you're on an ancient BlueZ, I warned you 💀

📁 FILES 📁

  • /etc/dbus-1/system.d/bluealsa.conf
  • /usr/share/dbus-1/system.d/bluealsa.conf

BlueALSA service D-Bus policy file. D-Bus will deny all access to the org.bluealsa service (even to root) unless permission is granted by a policy file. The default file permits only root to own this service, and only members of the audio group to exchange messages with it. BlueALSA installs its default file into the directory /usr/share/dbus-1/system.d, but the distribution or local administrator may override that by placing a modified policy file into /etc/dbus-1/system.d. the permissions said no thank you 🚫✨

  • /var/lib/bluealsa/XX:XX:XX:XX:XX:XX — BlueALSA volume persistent state storage. Files are named after the Bluetooth device address to which they refer. yes, one lil file per device address, cute 🎀

🌟 EXAMPLES 🌟

Emulate Bluetooth headset with A2DP and HSP support:

bluealsa -p a2dp-sink -p hsp-hs

On systems with more than one HCI device, it is possible to expose different profiles on different HCI devices. A system with three HCI devices might (for example) use hci0 for an A2DP sink service named "org.bluealsa.sink" and both hci1 and hci2 for an A2DP source service named "org.bluealsa.source". Such a setup might be created as follows:

bluealsa -B sink -i hci0 -p a2dp-sink &
bluealsa -B source -i hci1 -i hci2 -p a2dp-source &

Setup like this will also require a change to the BlueALSA D-Bus configuration file in order to allow connection with BlueALSA services with suffixed names. Please add following lines to the BlueALSA D-Bus policy:

...
<allow send_destination="org.bluealsa.sink" />
<allow send_destination="org.bluealsa.source" />
...

copy those lines exactly, no typos, the D-Bus is not forgiving bestie 😭

Copyright (c) 2016-2024 Arkadiusz Bokowy.

The bluez-alsa project is licensed under the terms of the MIT license. respect the license, it's the law 🫡

👀 SEE ALSO 👀

Project web site <https://github.com/arkq/bluez-alsa>

and that's the whole page bestie!! 🎀✨ this was BlueALSA v4.3.1, dated May 2024 — go forth and stream, you absolute legend 💅💖🦋

📦 where this page comes from