BLUEALSA-APLAY(1)

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

BLUEALSA-APLAY 💅✨

okay bestie, welcome to bluealsa-aplay(1) — that's section 1 of the General Commands Manual, and she is that girl. A simple bluealsa player. Let's get into it 🎀

✨ NAME ✨

bluealsa-aplay — a simple bluealsa player 🦋

🌸 SYNOPSIS 🌸

bluealsa-aplay [OPTION]... [BT-ADDR]...

💖 DESCRIPTION 💖

So basically: it captures audio streams from Bluetooth devices (by way of bluealsa(8), iykyk) and plays them out to an ALSA playback device. That's the whole job. She's a relay. A little audio girlboss 🫶

By default, bluealsa-aplay captures audio from all connected Bluetooth devices. Not picky. Loves everybody.

But if you are feeling picky, you can select specific Bluetooth devices by handing her a list of BT-ADDR MAC addresses. And if you use the special MAC address 00:00:00:00:00:00, that disables device filtering — which is literally the same as the default behavior. So it's giving "all of the above, but make it explicit" 💀

👑 OPTIONS 👑

  • -h, --help — output a usage message and exit. Short, sweet, helpful.
  • -V, --version — output the version number and exit. Iconic.
  • -S, --syslog — send output to the system logger, aka syslogd(8). By default, log output goes to stderr instead.
  • --loglevel=LEVEL — set the priority level threshold for log messages. Only messages at that level or higher get logged. The LEVELs are, in decreasing order:
    • error — error conditions
    • warning — warning conditions
    • info — informational messages

And if bluealsa-aplay was built with debug enabled, then there's one more, lowest, level available:

  • debug — debug messages

If you don't give this option at all, the default is to use the lowest level, meaning all messages are logged. Max verbosity, no cap 🌈

  • -v, --verbose — make the output more verbose. more words. more lore.
  • -l, --list-devices — list connected Bluetooth audio devices 👀
  • -L, --list-pcms — list available Bluetooth audio PCMs on connected devices.
  • -B NAME, --dbus=NAME — BlueALSA service name suffix. For more info, go see the --dbus=NAME option of the bluealsa(8) service daemon.
  • -D NAME, --pcm=NAME — select the ALSA playback PCM device to use for audio output. The default is default.

So here's the tea: internally, bluealsa-aplay does not perform any audio transformations, and it does not do streams mixing. If multiple Bluetooth devices are connected, it just opens a new connection to the ALSA PCM device for each stream. Selected hardware parameters like sampling frequency and number of channels are taken from the audio profile of a particular Bluetooth connection. And note — each connection can have a different setup. Every stream is her own main character.

Now, if playing multiple streams at the same time is not the vibe, you can change that behavior by using the --single-audio option.

For more information see the EXAMPLES section below.

  • --pcm-buffer-time=INT — set the playback PCM buffer duration time to INT microseconds. The default is 500000. It is recommended to choose a buffer time that is an exact multiple of the period time to avoid potential issues with some ALSA plugins (see the --pcm-period-time option below). ALSA may choose the nearest available alternative if the requested value is not supported.

If you're experiencing underruns on the ALSA device, then a larger buffer may help. However — a larger buffer will also increase the latency. So pick your fighter. For reliable performance, the buffer time should be at least 3 times the period time.

  • --pcm-period-time=INT — set the playback PCM period duration time to INT microseconds. The default is 100000. ALSA may choose the nearest available alternative if the requested value is not supported.

Okay this one's a whole essay, stay with me 📖 The ALSA rate plugin, which may be invoked by plug, does not always produce the exact required effective sample rate, because of rounding errors in the conversion between period time and period size. This can have a significant impact on synchronization "drift", especially with small period sizes, and can also result in stream underruns (if the effective rate is too fast) or dropped A2DP frames in the bluealsa(8) server (if the effective rate is too slow). This effect is avoided if the selected period time results in an exact integer number of frames for both the source rate (Bluetooth) and the sink rate (hardware card). For example, in the case of a Bluetooth stream sampled at 44100Hz playing to a hardware device that supports only 48000Hz, choosing a period time that is a multiple of 10000 microseconds will result in zero rounding error. (10000 µs at 44100Hz is 441 frames, and at 48000Hz is 480 frames). Math girlies stay winning 🧮✨

See also dmix in the NOTES section below for more information on rate calculation rounding errors.

  • --volume=TYPE — select the desired method of implementing remote volume control. TYPE may be one of four values:
    • auto — the volume control method is determined by the BlueALSA PCM. This is the default when this option is not given. bluealsa-aplay operates its configured ALSA mixer control to apply volume change requests received from the remote Bluetooth device if and only if the PCM is using native ("pass-through") volume control.
    • mixer — bluealsa-aplay will force the BlueALSA PCM volume mode setting to native ("pass-through") before starting the PCM stream, and then operate the same as for auto above.
    • none — bluealsa-aplay will force the BlueALSA PCM volume mode setting to native ("pass-through") before starting the PCM stream. It will not operate its configured ALSA mixer. This can be used to effectively disable remote volume control; or it can be used to allow some other application to apply remote volume change requests.
    • software — bluealsa-aplay will force the BlueALSA PCM volume mode setting to soft-volume ("software") and then will not operate its configured ALSA mixer. This can be used to enable remote volume control without using an ALSA mixer.

See Volume control in the NOTES section below for more info on volume control 💜

  • -M NAME, --mixer-device=NAME — select the ALSA mixer device to use for controlling audio output mute state and volume level. In order to use this feature, BlueALSA PCM can not use software volume. The default is default.
  • --mixer-name=NAME — set the name of the ALSA simple mixer control to use. The default is Master.

To work with bluealsa-aplay, this simple control must provide decibel scaling information for the volume control. Most, but not all, modern sound cards do provide this information. (So if yours doesn't... that's a you-and-your-soundcard problem, bestie 😭)

  • --mixer-index=NUM — set the index of the ALSA simple mixer control. The default is 0.

This is required only if the simple mixer control name applies to multiple simple controls on the same card. This is most common with HDMI devices, for which the index indicates the controlled HDMI PCM device.

  • --profile-a2dp — use the A2DP profile (default). ✨
  • --profile-sco — use the SCO profile.
Note: Only one of A2DP or SCO can be used. If both are specified, the last one given will be selected. No take-backs, she goes with the most recent answer 💅
  • --single-audio — allow only one Bluetooth device to play audio at a time. If multiple devices are connected, only the first to start will play, the others will be paused. When that first device stops, then the next to send audio will be played.

Without this option, bluealsa-aplay plays audio from all selected Bluetooth devices. Please note that playing from all Bluetooth devices at a time requires the used PCM to be able to mix audio from multiple sources (i.e., it can be opened more than once; for example the ALSA dmix plugin). Sharing is caring, but it also has requirements 🫠

📝 NOTES 📝

Volume control 🎚️

If the Bluetooth PCM is using BlueALSA soft-volume volume control, then volume adjustment will have been applied to the PCM stream within the bluealsa daemon; so bluealsa-aplay does not operate the mixer control in this case. She's off duty. Not her shift.

When using --volume=none or --volume=software, then the mixer options --mixer-device, --mixer-name and --mixer-index are ignored, and bluealsa-aplay will not operate any mixer controls — even if some other application changes the PCM volume mode to native while in use. Zero mixer touching. None. Not even a little 🙈

When using --volume=auto or --volume=mixer, the ALSA mixer control will be operated only when the PCM stream is active, i.e. the remote device is sending audio. If a connected remote device requests a volume change when no active stream is playing, then bluealsa-aplay will ignore that request. And when the audio stream starts, then bluealsa-aplay will change the Bluetooth volume to match the current setting of the ALSA mixer control. Sync queen 👑

Native Bluetooth volume control for A2DP relies on AVRCP volume control in BlueZ, which has not always been reliably implemented. 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. So like... update your BlueZ, fr fr ⭐

See bluealsa(8) for more information on native and soft-volume volume control.

dmix 🌊

The ALSA dmix plugin will ignore the period and buffer times selected by the application (because it has to allow connections from multiple applications). Instead it will choose its own values, which can lead to rounding errors in the period size calculation when used with the ALSA rate plugin. To avoid this, it is recommended to explicitly define the hardware period size and buffer size for dmix in your ALSA configuration.

For example, suppose we want a period time of 100000 µs and a buffer holding 5 periods with an Intel 'PCH' card:

defaults.dmix.PCH.period_time 100000
defaults.dmix.PCH.periods 5

Alternatively we can define a PCM with the required setting:

pcm.dmix_rate_fix {
    type plug
    slave.pcm {
        type dmix
        ipc_key 12345
        slave {
            pcm "hw:0,0"
            period_time 100000
            periods 5
        }
    }
}

🌈 EXAMPLES ✨

Okay bestie, let's get practical. The simplest way to use bluealsa-aplay is literally just... run it with no arguments at all. That's it. That's the whole vibe. It'll play audio from all connected Bluetooth devices straight to the default ALSA playback PCM. 💅

bluealsa-aplay

Now, if you've got more than one sound card attached, you can lowkey create a whole setup where the audio from a particular Bluetooth device gets played to a specific sound card. The setup below shows how to do this using the --pcm=NAME option and known Bluetooth device addresses. 🎀

Heads up bestie 💖 — in the following example we're assuming the second card is named "USB" and the appropriate mixer control is named "Speaker". To get the real names of your attached sound cards, just run aplay -l. And for a list of control names for a card called "USB", run amixer -c USB scontrols. 🫶
bluealsa-aplay --pcm=default 94:B8:6D:AF:CD:EF F8:87:F1:B8:30:85 &
bluealsa-aplay --pcm=default:USB C8:F7:33:66:F0:DE &

Also? It might be desired to specify the ALSA mixer device and/or control element for each ALSA playback PCM device. This is mostly useful when BlueALSA PCM does not use software volume (for more info, peep the --volume option above, iykyk 👀).

bluealsa-aplay --pcm=default 94:B8:6D:AF:CD:EF F8:87:F1:B8:30:85 &
bluealsa-aplay --pcm=default:USB --mixer-device=hw:USB --mixer-name=Speaker C8:F7:33:66:F0:DE &

So what does that whole setup do, you ask? 🦋 It routes the 94:B8:6D:AF:CD:EF and F8:87:F1:B8:30:85 Bluetooth devices to the default ALSA playback PCM device, and the C8:F7:33:66:F0:DE device to the USB sound card. For that USB sound card, the Speaker control element gets used as a hardware volume control knob. Iconic, honestly. 👑

Copyright (c) 2016-2023 Arkadiusz Bokowy.

The bluez-alsa project is licensed under the terms of the MIT license. ✨

🌸 SEE ALSO 🌸

Project web site

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

And that's a wrap bestie!! 🎀 This lil' page is from BlueALSA v4.3.1, dated February 2024, and it lives at BLUEALSA-APLAY(1). Go forth and slay your Bluetooth audio setup, no cap. 💜🦋✨

📦 where this page comes from