-
Notifications
You must be signed in to change notification settings - Fork 1
/
bluealsa-agent.8.rst.in
199 lines (138 loc) · 6.04 KB
/
bluealsa-agent.8.rst.in
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
===================
bluealsa-agent
===================
-------------------------------------
BlueALSA event handler helper utility
-------------------------------------
:Date: August 2024
:Manual section: 8
:Manual group: System Manager's Manual
:Version: @VERSION@
SYNOPSIS
========
**bluealsa-agent** [*OPTION*] ... *COMMAND*
DESCRIPTION
===========
**bluealsa-agent** is a simple daemon to invoke arbitrary commands in response
to BlueALSA PCM events.
OPTIONS
=======
-h, --help
Output a usage message and exit.
-V, --version
Output the version number and exit.
-B NAME, --dbus=NAME
BlueALSA service name suffix. This option can be given more than once to
add support for multiple ``bluealsa(8)`` service instances. The default
service **org.bluealsa** is always included. For example, the following
will respond to events from **org.bluealsa**, **org.bluealsa.sink** and
**org.bluealsa.source**:
::
bluealsa-agent -B sink -B source <PATH-TO-COMMAND>
For more information see the ``--dbus`` option of the ``bluealsa(8)``
service daemon.
-p PROFILE, --profile=PROFILE
Invoke commands only for PCMs having profile *PROFILE*. *PROFILE* may be
"a2dp" or "sco". The default is to invoke commands for both profiles.
-m MODE, --mode=MODE
Invoke commands only for PCMs having mode *MODE*. *MODE* may be "sink" or
"source". The default is to invoke commands for both modes.
-s, --status[=PROPLIST]
Invoke the *COMMAND* also when the status of the given PCM properties
changes. *PROPLIST* is a comma-separated list of property names. Permissible
names are "Running", "SoftVolume" and "Delay". If *PROPLIST* is not given
then only changes to the "Running" state are active. See COMMAND_ below.
COMMAND
=======
The COMMAND must be a full path, either to an executable file or to a directory
containing only executable files. The specified file(s) will be executed
whenever one of the following events is signalled by the BlueALSA D-Bus
service(s).
* PCM added
* PCM removed
* PCM codec changed
and optionally if *--status* is used:
* PCM status changed
If COMMAND is a directory then each file within the directory is executed, in
alphanumeric order, and **bluealsa-agent** waits for each file to complete
before starting the next; only one event at a time will be processed.
**bluealsa-agent** re-reads the directory on receipt of a SIGHUP signal.
If COMMAND is a file then **bluealsa-agent** does not wait for it to complete;
so it is possible that it may be invoked again by the next event before the
previous invocation has completed. In either case each executable file is
invoked by **bluealsa-agent** with two arguments as:
COMMAND *EVENT* *PCM-PATH*
where *EVENT* is one of ``add``, ``remove`` or ``update`` and *PCM-PATH* is the
D-Bus object path of the PCM associated with the event.
**bluealsa-agent** also sets environment variables to pass additional
information about the event to *COMMAND*.
These variables are set for all events:
``BLUEALSA_PCM_PROPERTY_ADDRESS``
The Bluetooth address of the device as `XX:XX:XX:XX:XX:XX`
``BLUEALSA_PCM_PROPERTY_ALSA_ID``
The ALSA name for this PCM. For example
``bluealsa:DEV=00:11:22:33:44:55,PROFILE=A2DP``
``BLUEALSA_PCM_PROPERTY_CHANNELS``
The number of audio channels, for example ``2`` for stereo, ``1`` for mono.
``BLUEALSA_PCM_PROPERTY_CODEC``
The used codec, for example ``SBC``, ``AAC``, or ``mSBC``. Note that for the
``HFP`` profile the codec may be unset when the PCM is added, but will be
reported in an ``update`` event as soon as the codec is set.
``BLUEALSA_PCM_PROPERTY_CODEC_CONFIG`` (where appropriate)
The used codec configuration "blob" as a hexadecimal string.
``BLUEALSA_PCM_PROPERTY_FORMAT``
The audio sample format. For most codecs used by Bluetooth PCMs this is
``S16_LE``.
``BLUEALSA_PCM_PROPERTY_MODE``
The stream direction, either ``sink`` or ``source``
``BLUEALSA_PCM_PROPERTY_NAME``
The ``alias`` of the device, for example ``"Jabra MOVE v2.3.0"``
``BLUEALSA_PCM_PROPERTY_PROFILE``
The Bluetooth profile, for example ``A2DP`` or ``HFP``
``BLUEALSA_PCM_PROPERTY_RATE``
The audio sample rate in frames per second, for example ``48000`` or
``16000``.
``BLUEALSA_PCM_PROPERTY_SAMPLING``
Deprecated synonym for ``BLUEALSA_PCM_PROPERTY_RATE``. Will be discontinued
in a future release.
``BLUEALSA_PCM_PROPERTY_SERVICE``
The D-Bus well-known name of the BlueALSA service handling this PCM, for
example ``org.bluealsa``.
``BLUEALSA_PCM_PROPERTY_TRANSPORT``
The Bluetooth transport role, for example ``A2DP-source`` or ``HFP-AG``.
``BLUEALSA_PCM_PROPERTY_TRANSPORT_TYPE``
The Bluetooth transport type, either ``A2DP`` or ``SCO``.
When *--status* is used, then additional environment variables are also set
for the "added" and "update" events as determined by the *PROPLIST*.
``BLUEALSA_PCM_PROPERTY_RUNNING``
``true`` if the PCM is running (i.e. when the underlying Bluetooth transport
is acquired and able to transfer audio samples), ``false`` otherwise.
``BLUEALSA_PCM_PROPERTY_SOFTVOL``
``true`` when the BlueALSA "SoftVolume" property is enabled for this PCM.
See ``bluealsa(8)`` for more information.
``BLUEALSA_PCM_PROPERTY_CLIENT_DELAY``
The current client delay adjustment, in units of 1/10 millisecond.
``BLUEALSA_PCM_PROPERTY_DELAY``
The current delay, in units of 1/10 millisecond.
To identify which properties have changed in an "update" event, one other
environment variable is set:
``BLUEALSA_PCM_PROPERTY_CHANGES``
A space-separated list indicating the changed properties, consisting of one
or more from:
CHANNELS
CLIENT_DELAY
CODEC
CODEC_CONFIG
DELAY
FORMAT
RUNNING
RATE
SOFTVOL
For compatibility with older versions, the word "SAMPLING" is also included when
the rate has changed. Use of this term is deprecated and will be discontinued in
a future release.
SEE ALSO
========
``bluealsa(8)``
Project web site
https://github.com/borine/bluealsa-autoconfig