289 lines
11 KiB
ReStructuredText
289 lines
11 KiB
ReStructuredText
|
.. SPDX-FileCopyrightText: 2021-2025 BlueALSA developers
|
||
|
|
.. SPDX-License-Identifier: MIT
|
||
|
|
|
||
|
|
===========
|
||
|
|
bluealsactl
|
||
|
|
===========
|
||
|
|
|
||
|
|
----------------------------------------------------------
|
||
|
|
a simple command line interface for the BlueALSA D-Bus API
|
||
|
|
----------------------------------------------------------
|
||
|
|
|
||
|
|
:Date: December 2025
|
||
|
|
:Manual section: 1
|
||
|
|
:Manual group: General Commands Manual
|
||
|
|
:Version: $VERSION$
|
||
|
|
|
||
|
|
SYNOPSIS
|
||
|
|
========
|
||
|
|
|
||
|
|
**bluealsactl** [*OPTION*]... [*COMMAND* [*ARG*]...]
|
||
|
|
|
||
|
|
DESCRIPTION
|
||
|
|
===========
|
||
|
|
|
||
|
|
**bluealsactl** provides command-line access to the BlueALSA D-Bus API
|
||
|
|
"org.bluealsa.Manager1" and "org.bluealsa.PCM1" interfaces and thus allows
|
||
|
|
introspection and some control of BlueALSA PCMs while they are running.
|
||
|
|
|
||
|
|
OPTIONS
|
||
|
|
=======
|
||
|
|
|
||
|
|
-h, --help
|
||
|
|
Output a usage message. When used before the *COMMAND* prints a list of
|
||
|
|
options and commands. When used as a *COMMAND* *ARG* prints help specific
|
||
|
|
to that *COMMAND*
|
||
|
|
|
||
|
|
-V, --version
|
||
|
|
Output the version number.
|
||
|
|
|
||
|
|
-B NAME, --dbus=NAME
|
||
|
|
BlueALSA service name suffix. For more information see ``--dbus``
|
||
|
|
option of ``bluealsad(8)`` service daemon.
|
||
|
|
|
||
|
|
-q, --quiet
|
||
|
|
Do not print any error messages.
|
||
|
|
|
||
|
|
-v, --verbose
|
||
|
|
Include extra information in normal output - see COMMANDS_ for details.
|
||
|
|
This option can be used multiple times to increase verbosity.
|
||
|
|
|
||
|
|
COMMANDS
|
||
|
|
========
|
||
|
|
|
||
|
|
If no *COMMAND* is given, the default is **status**.
|
||
|
|
|
||
|
|
All commands may be given the *ARG* **--help**, other *ARGs* are described
|
||
|
|
against each command below.
|
||
|
|
|
||
|
|
The *PCM_PATH* command argument, where required, must be a BlueALSA PCM D-Bus
|
||
|
|
path. Use the command **list-pcms** to obtain a list of valid PCM D-Bus paths.
|
||
|
|
|
||
|
|
status
|
||
|
|
Print 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
|
||
|
|
Print a name list of all running BlueALSA D-Bus services, one per line.
|
||
|
|
|
||
|
|
list-pcms
|
||
|
|
Print a list of BlueALSA PCM D-Bus paths, one per line.
|
||
|
|
|
||
|
|
If the **--verbose** option is given then the properties of each connected
|
||
|
|
PCM are printed after each path, one per line, in the same format as the
|
||
|
|
**info** command.
|
||
|
|
|
||
|
|
info *PCM_PATH*
|
||
|
|
Print the properties and available codecs of the given PCM.
|
||
|
|
The properties are printed one per line, in the format
|
||
|
|
"PropertyName: Value". Values are presented in human-readable format, and
|
||
|
|
for a property with multiple values they are printed as a space-separated
|
||
|
|
list.
|
||
|
|
|
||
|
|
The Volume property is presented as two lines; "Volume:" indicating
|
||
|
|
the loudness component of each channel and "Mute:" indicating the mute
|
||
|
|
component of each channel. Both components are presented with their channel
|
||
|
|
values in the same order as the ChannelMap. For example:
|
||
|
|
::
|
||
|
|
|
||
|
|
ChannelMap: FC FL FR RL RR LFE
|
||
|
|
Volume: 127 127 127 127 127 127
|
||
|
|
Mute: off off off off off off
|
||
|
|
|
||
|
|
If the **--verbose** option is given then "Available codecs:" values include
|
||
|
|
the codec capabilities as a hexadecimal string suffix, separated by a colon.
|
||
|
|
Similarly, the "Selected codec:" value includes the current codec
|
||
|
|
configuration as a hexadecimal string separated by a colon. For example:
|
||
|
|
::
|
||
|
|
|
||
|
|
Available codecs: SBC:ffff02fa AAC:c0ffff035b60
|
||
|
|
Selected codec: AAC:400084035b60
|
||
|
|
|
||
|
|
A tool such as ``a2dpconf(1)`` can be used to decode the hex string.
|
||
|
|
|
||
|
|
The list of available A2DP codecs requires BlueZ SEP support
|
||
|
|
(BlueZ >= 5.52)
|
||
|
|
|
||
|
|
codec [-c NUM] [-r NUM] [--force] *PCM_PATH* [*CODEC*\ [:*CONFIG*]]
|
||
|
|
Get or set the Bluetooth codec used by the given PCM.
|
||
|
|
|
||
|
|
If *CODEC* is not given, print a list of additional codecs supported by the
|
||
|
|
given PCM and the currently selected codec. With the option **--verbose**
|
||
|
|
the codec capabilities and current configuration are shown in the same
|
||
|
|
format as for the **info** command.
|
||
|
|
|
||
|
|
If *CODEC* is given, change the codec to be used by the given PCM. This
|
||
|
|
command will terminate the PCM if it is currently running.
|
||
|
|
|
||
|
|
Optionally, for A2DP codecs, one can specify A2DP codec configuration which
|
||
|
|
should be selected. The *CONFIG* shall be given as a hexadecimal string. If
|
||
|
|
this parameter is omitted, BlueALSA will select default configuration based
|
||
|
|
on codec capabilities of connected Bluetooth device.
|
||
|
|
|
||
|
|
Given A2DP codec configuration shall be a valid configuration in respect to
|
||
|
|
the capabilities of connected Bluetooth device and the BlueALSA itself. If
|
||
|
|
the given configuration is not valid, this command will fail with an error.
|
||
|
|
In such case, one can use the **--force** option to force the selection of
|
||
|
|
the configuration. However, this may result in a non-working connection and
|
||
|
|
in the worst case it may crash remote Bluetooth device!
|
||
|
|
|
||
|
|
The options **-c NUM** and **-r NUM** may be used to select a specific
|
||
|
|
channel count and/or sample rate, provided that the given values are
|
||
|
|
supported by the codec. For example, if the device at path PCM_PATH
|
||
|
|
supports 5.1 surround sound and 96000 rate with the AAC codec, but is
|
||
|
|
currently configured as AAC with stereo at 48000, then the configuration
|
||
|
|
can be changed with:
|
||
|
|
::
|
||
|
|
|
||
|
|
bluealsactl codec -c6 -r96000 PCM_PATH aac
|
||
|
|
|
||
|
|
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
|
||
|
|
**bluealsactl 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 loudness value(s) of the given PCM.
|
||
|
|
|
||
|
|
If *VOLUME* is given, set the loudness component of the volume property of
|
||
|
|
the given PCM.
|
||
|
|
|
||
|
|
If only one value *VOLUME* is given it is applied to all channels.
|
||
|
|
|
||
|
|
For multi-channel PCMs, if multiple *VOLUME* values are given, then each
|
||
|
|
given value is applied to the corresponding channel of the ChannelMap (see
|
||
|
|
the **info** command). If the number of values given is less than the
|
||
|
|
number of channels, then the remaining channels are set to the first given
|
||
|
|
value.
|
||
|
|
|
||
|
|
Valid A2DP and ASHA values for *VOLUME* are 0-127, valid HFP/HSP values are
|
||
|
|
0-15.
|
||
|
|
|
||
|
|
Note that A2DP does not support independent channel volumes, so such a
|
||
|
|
setting is better suited to use with soft-volume enabled. See
|
||
|
|
``bluealsad(8)`` for more details.
|
||
|
|
|
||
|
|
mute *PCM_PATH* [*STATE* [*STATE*]...]
|
||
|
|
Get or set the mute switch of the given PCM.
|
||
|
|
|
||
|
|
If *STATE* argument(s) are given, set mute component of the volume property
|
||
|
|
of the given PCM. Multiple *STATE* arguments are used for multi-channel
|
||
|
|
PCMs 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, set the SoftVolume property for the given
|
||
|
|
PCM. This property determines whether BlueALSA will make volume control
|
||
|
|
internally or will delegate this task to BlueALSA PCM client or 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.
|
||
|
|
|
||
|
|
client-delay *PCM_PATH* [[-]\ *DELAY*]
|
||
|
|
Get or set the ClientDelay property of the given PCM.
|
||
|
|
|
||
|
|
If the *DELAY* argument is given, set the ClientDelay property for the
|
||
|
|
given PCM. This property may be used by clients to
|
||
|
|
adjust the reported audio delay and may be useful with PCM devices that do
|
||
|
|
not report an accurate Delay property.
|
||
|
|
|
||
|
|
The *DELAY* value is in milliseconds and must be a decimal number with
|
||
|
|
optional sign prefix (e.g. **250**, **-500**, **+360.4**). The permitted
|
||
|
|
range is [-3276.8, 3276.7].
|
||
|
|
|
||
|
|
monitor [-p[PROPS] | --properties[=PROPS]]
|
||
|
|
Listen for D-Bus signals indicating adding/removing BlueALSA interfaces.
|
||
|
|
Also detect service running and service stopped events, and optionally
|
||
|
|
PCM property change events. Print a line on standard output for each one
|
||
|
|
received.
|
||
|
|
|
||
|
|
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 this 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 also detect changes
|
||
|
|
to certain PCM properties. Print a line on standard output for each
|
||
|
|
property change. The output lines are formed as:
|
||
|
|
|
||
|
|
``PropertyChanged PCM_PATH PROPERTY_NAME VALUE``
|
||
|
|
|
||
|
|
Property names that can be monitored are **Codec**, **Delay**,
|
||
|
|
**ClientDelay**, **Running**, **SoftVolume** and **Volume**.
|
||
|
|
|
||
|
|
Volume is an array of values, each showing the loudness and mute components
|
||
|
|
of a channel. The order of the values corresponds to the ChannelMap
|
||
|
|
property (see the **info** command). The loudness is shown as a decimal
|
||
|
|
integer value, with an optional suffix ``[M]`` indicating that the channel
|
||
|
|
is muted. For example, for a 2-channel (stereo) A2DP PCM at path PCM_PATH
|
||
|
|
with both channels at full volume and the right channel muted, the event
|
||
|
|
would be displayed as:
|
||
|
|
::
|
||
|
|
|
||
|
|
PropertyChanged PCM_PATH Volume 127 127[M]
|
||
|
|
|
||
|
|
*PROPS* is an optional comma-separated list of property names to be
|
||
|
|
monitored. If given, only changes to those properties listed will be
|
||
|
|
printed. If this argument is not given then changes to any of the above
|
||
|
|
properties are printed.
|
||
|
|
|
||
|
|
open [--hex] *PCM_PATH*
|
||
|
|
Transfer 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 sample rate must match the properties
|
||
|
|
of the PCM, as no format conversions are performed by this tool.
|
||
|
|
|
||
|
|
With the **--hex** option, the data is read or written as hexadecimal
|
||
|
|
strings.
|
||
|
|
|
||
|
|
SEE ALSO
|
||
|
|
========
|
||
|
|
|
||
|
|
``a2dpconf(1)``, ``bluealsa-aplay(1)``, ``bluealsa-rfcomm(1)``,
|
||
|
|
``bluealsad(8)``
|
||
|
|
|
||
|
|
Project web site
|
||
|
|
https://github.com/arkq/bluez-alsa
|