BLUEALSA-CLI(1)

💖 NAME 💖

okay bestie, so bluealsa-cli is a simple command line interface for the BlueALSA D-Bus API ✨ that's the whole vibe. it's a General Commands Manual situation and we're gonna walk through it together 🫶

---

🌸 SYNOPSIS 🌸

bluealsa-cli [OPTION]... [COMMAND [ARG]...]

---

🦋 DESCRIPTION 🦋

so like, bluealsa-cli gives you command-line access to the BlueALSA D-Bus API — specifically the "org.bluealsa.Manager1" and "org.bluealsa.PCM1" interfaces 👑 which means you get to do introspection and even a lil bit of control over BlueALSA PCMs while they're running. no cap, that's the whole point 💅

---

✨ OPTIONS ✨

• -h, --help — prints a usage message. if you use it before the COMMAND you get a whole list of options and commands; if you use it as a COMMAND ARG you get help that's specific to that COMMAND 🎀
• -V, --version — spits out the version number. that's it, that's the option 💖
• -B NAME, --dbus=NAME — the BlueALSA service name suffix. for the deets, go look at the --dbus option of bluealsa(8) service daemon 🔍
• -q, --quiet — do not print any error messages. shhh. silence. 🤫
• -v, --verbose — adds extra info to the normal output, check COMMANDS for the specifics. and bestie, you can stack this one multiple times to keep increasing verbosity 📈✨

---

💅 COMMANDS 💅

if you don't give a COMMAND, the default is status. easy ✨

every single command can be handed the ARG --help, and all the other ARGs are described down below next to their command 🫶

the PCM_PATH command argument, wherever it's required, must be a BlueALSA PCM D-Bus path. use the list-pcms command to get yourself a list of valid PCM D-Bus paths 💫

---

• status — prints the properties of the service: service name, build version, in-use Bluetooth adapters, available profiles and codecs. example output:

Service: org.bluealsa
Version: v4.1.1
Adapters: hci0 hci1
Profiles:
  A2DP-source : SBC AAC
  HFP-AG      : CVSD mSBC
  HSP-AG      : CVSD

• list-services — prints a name list of all the running BlueALSA D-Bus services, one per line 📋
• list-pcms — prints a list of BlueALSA PCM D-Bus paths, one per line 📋

if the --verbose option is given, then the properties of each connected PCM get printed after each path, one per line, in the same format as the info command 👀

• info PCM_PATH — prints the properties and available codecs of the given PCM. properties come out one per line, in the format 'PropertyName: Value'. values are shown in human-readable format — for example the Volume property is printed as:

Volume: L: 127 R: 127

just so you know, the list of available A2DP codecs needs BlueZ SEP support (BlueZ >= 5.52) 🧚

• codec [-c NUM] [-s NUM] [--force] PCM_PATH [CODEC[:CONFIG]] — get or set the Bluetooth codec used by the given PCM.

if CODEC is given, it changes the codec to be used by the given PCM. heads up: this command will terminate the PCM if it's currently running 💀

if CODEC is not given, it prints a list of additional codecs supported by the given PCM plus the currently selected codec. how detailed the output is depends on the verbosity level 🔍

optionally, for A2DP codecs, you can specify the A2DP codec configuration you want selected. the CONFIG shall be given as a hexadecimal string. if you leave this parameter out, BlueALSA will pick a default configuration based on the codec capabilities of the connected Bluetooth device 🎀

any given A2DP codec configuration shall be a valid configuration with respect to the capabilities of the connected Bluetooth device and BlueALSA itself. if the config you gave isn't valid, this command will fail with an error. in that case you can use the --force option to force the selection of the configuration. however — and bestie listen to me — this may result in a non-working connection and in the worst case it may crash the remote Bluetooth device! 😭

⚠️ seriously, --force is giving main-character-reckless energy. it can break the connection and can crash the remote device. be careful.

selecting an A2DP codec and listing available A2DP codecs requires BlueZ SEP support (BlueZ >= 5.52) 🧚

BlueALSA does not support changing the HFP codec from an HFP-HF node. the codec can only be changed from the HFP-AG node. using the bluealsa-cli codec command to set the codec from an HFP-HF node fails, reporting an input/output error 🙈

selecting the HFP codec when using oFono is not supported 🚫

• volume PCM_PATH [VOLUME [VOLUME]] — get or set the volume value of the given PCM.

if VOLUME is given, it sets the loudness component of the volume property of the given PCM 🔊

if only one value VOLUME is given, it gets applied to all channels. for stereo (2-channel) PCMs the first value VOLUME goes to channel 1 (Left), and the second value VOLUME goes to channel 2 (Right). for mono (1-channel) PCMs the second value VOLUME is just ignored 🙈

valid A2DP values for VOLUME are 0-127, valid HFP/HSP values are 0-15 🔢

• mute PCM_PATH [STATE [STATE]] — get or set the mute switch of the given PCM.

if STATE argument(s) are given, it sets the mute component of the volume property of the given PCM. the second STATE argument is used for stereo PCMs, exactly as described for the volume command 🎧

the STATE value can be one of on, yes, true, y or 1 for mute on, or off, no, false, n or 0 for mute off 🤐

• soft-volume PCM_PATH [STATE] — get or set the SoftVolume property of the given PCM.

if the STATE argument is given, it sets the SoftVolume property for the given PCM. this property determines whether BlueALSA will do volume control internally, or will delegate that task to the BlueALSA PCM client or the connected Bluetooth device respectively for PCM sink or PCM source 🎚️

the STATE value can be one of on, yes, true, y or 1 for soft-volume on, or off, no, false, n or 0 for soft-volume off ✨

• delay-adjustment PCM_PATH [ADJUSTMENT] — get or set the DelayAdjustment property of the given PCM for the current codec.

if the ADJUSTMENT argument is given, it sets the DelayAdjustment property for the current codec in the given PCM. clients may use this property to adjust the reported audio delay, and it can be useful with PCM devices that don't report an accurate Delay property ⏱️

the ADJUSTMENT value is in milliseconds and must be a decimal number with an optional sign prefix (e.g. 250, -500, +360.4). the permitted range is [-3276.8, 3276.7] 📏

• monitor [-p[PROPS] | --properties[=PROPS]] — listens for D-Bus signals indicating adding/removing BlueALSA interfaces. it also detects service running and service stopped events, and optionally PCM property change events. it prints a line on standard output for each one it receives 👂✨

PCM event output lines are formed as:

PCMAdded PCM_PATH

PCMRemoved PCM_PATH

if the --verbose option is given, then the properties of each added PCM are printed after the PCMAdded line, one per line, in the same format as the info command. in that case a blank line is printed after the last property 📝

RFCOMM event output lines are formed as:

RFCOMMAdded RFCOMM_PATH

RFCOMMRemoved RFCOMM_PATH

service start/stop event lines are formed as:

ServiceRunning SERVICE_NAME

ServiceStopped SERVICE_NAME

when the monitor starts, it begins by printing a ServiceRunning or ServiceStopped message according to the current state of the service 🌈

if the -p or --properties option is given, then it also detects changes to certain PCM properties. it prints a line on standard output for each property change. the output lines are formed as:

PropertyChanged PCM_PATH PROPERTY_NAME VALUE

the property names that can be monitored are Codec, Running, SoftVolume and Volume 👑

the value for Volume is a hexadecimal 16-bit encoding where data for channel 1 is stored in the upper byte, and channel 2 is stored in the lower byte. the highest bit of both bytes determines whether that channel is muted 🔇

PROPS is an optional comma-separated list of property names to be monitored. if it's given, only changes to those listed properties will be printed. if this argument isn't given, then changes to any of the above properties are printed 💫

• open [--hex] PCM_PATH — transfers raw audio frames to or from the given PCM. for sink PCMs the frames are read from standard input and written to the PCM. for source PCMs the frames are read from the PCM and written to standard output. the format, channels and sampling rate must match the properties of the PCM, because this tool performs no format conversions at all 🎵

with the --hex option, the data is read or written as hexadecimal strings 🔢

---

🎀 COPYRIGHT 🎀

Copyright (c) 2016-2023 Arkadiusz Bokowy.

the bluez-alsa project is licensed under the terms of the MIT license 📜

---

🌈 SEE ALSO 🌈

bluealsa(8), bluealsa-aplay(1), bluealsa-rfcomm(1)

Project web site

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

---

and that's the whole page bestie 💖 this was BlueALSA v4.3.1, from July 2024, and yes the manual section is BLUEALSA-CLI(1) — slay, go read the source, ily 🫶✨