============
bluealsa-cli
============

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

:Date: July 2024
:Manual section: 1
:Manual group: General Commands Manual
:Version: $VERSION$

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
=========

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
