Ubuntu Manpage: bluealsa-cli - a simple command line interface for the BlueALSA D-Bus API

Provided by: bluez-alsa-utils_4.3.1-3_amd64

NAME

       bluealsa-cli - a simple command line interface for the BlueALSA D-Bus API

SYNOPSIS

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

DESCRIPTION

       bluealsa-cli  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 bluealsa(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 - for
example the Volume property is printed as:

Volume: L: 127 R: 127

The list of available A2DP codecs requires 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, change the codec to be used by the given PCM. This command will terminate the
PCM if it is currently running.

If CODEC is not given, print a list of additional codecs supported by the given PCM and the
currently selected codec. The level of detail in the output depends on the verbosity level.

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!

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, 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 stereo (2-channel) PCMs the
first value VOLUME is applied to channel 1 (Left), and the second value VOLUME is applied to
channel 2 (Right). For mono (1-channel) PCMs the second value VOLUME is 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, set mute component of the volume property of the given PCM. The
second STATE argument is used for stereo 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.

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, set the DelayAdjustment property for the current codec in 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 ADJUSTMENT 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 than 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, channel 2 is stored in the lower byte. The highest bit of both bytes determines
whether channel is muted.

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 sampling 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.

COPYRIGHT