Debian Codegraph @

docs/rst/daemon/configuration/bluetooth.rst

raw
1 .. _config_bluetooth:
2
3 Bluetooth configuration
4 =======================
5
6 Bluetooth audio and MIDI devices are managed by the BlueZ and BlueZ-MIDI
7 monitors, respectively.
8
9 Both monitors are enabled by default and can be disabled using the
10 ``monitor.bluez`` and ``monitor.bluez-midi`` :ref:`features <config_features>`
11 in the configuration file.
12
13 As with all device monitors, both of these monitors are implemented as SPA
14 plugins and are part of PipeWire. WirePlumber merely loads the plugins and lets
15 them do their work. These plugins then monitor the BlueZ system-wide D-Bus
16 service and create device and node objects for all the connected Bluetooth audio
17 and MIDI devices.
18
19 Logind integration
20 ------------------
21
22 The BlueZ monitors are integrated with logind to ensure that only one user at a
23 time can use the Bluetooth audio devices. This is because on most Linux desktop
24 systems, the graphical login manager (GDM, SDDM, etc.) is running as a separate
25 user and runs its own instance of PipeWire and Wireplumber. This means that if a
26 user logs in graphically, the Bluetooth audio devices will be automatically
27 grabbed by the PipeWire/WirePlumber instance of the graphical login manager,
28 and the user that logs in will not get access to them.
29
30 To overcome this, the BlueZ monitors are integrated with logind and are only
31 allowed to create device and node objects for Bluetooth audio devices if the
32 user is currently on the "active" logind session.
33
34 In some cases, however, this behavior is not desired. For example, if you
35 manually switch to a TTY and log in there, you may want to keep the Bluetooth
36 audio devices connected to the now inactive graphical session. Or you may want
37 to have a dedicated user that is always allowed to use the Bluetooth audio
38 devices, regardless of the active logind session, for example for a (possibly
39 headless) music player daemon.
40
41 To disable this behavior, you can set the ``monitor.bluez.seat-monitoring``
42 :ref:`feature <config_features>` to ``disabled``.
43
44 Example configuration :ref:`fragment <config_conf_file_fragments>` file:
45
46 .. code-block::
47
48 wireplumber.profiles = {
49 main = {
50 monitor.bluez.seat-monitoring = disabled
51 }
52 }
53
54 .. note::
55
56 If logind is not installed on the system, this functionality is disabled
57 automatically.
58
59 Monitor Properties
60 ------------------
61
62 The BlueZ monitor SPA plugin (``api.bluez5.enum.dbus``) supports properties that
63 can be used to configure it when it is loaded. These properties can be set in
64 the ``monitor.bluez.properties`` section of the WirePlumber configuration file.
65
66 Example:
67
68 .. code-block::
69
70 monitor.bluez.properties = {
71 bluez5.roles = [ a2dp_sink a2dp_source bap_sink bap_source hsp_hs hsp_ag hfp_hf hfp_ag ]
72 bluez5.codecs = [ sbc sbc_xq aac ]
73 bluez5.enable-sbc-xq = true
74 bluez5.hfphsp-backend = "native"
75 }
76
77 .. describe:: bluez5.roles
78
79 Enabled roles.
80
81 Currently some headsets (e.g. Sony WH-1000XM3) do not work with both
82 ``hsp_ag`` and ``hfp_ag`` enabled, so by default we enable only HFP.
83
84 Supported roles:
85
86 - ``hsp_hs`` (HSP Headset)
87 - ``hsp_ag`` (HSP Audio Gateway),
88 - ``hfp_hf`` (HFP Hands-Free),
89 - ``hfp_ag`` (HFP Audio Gateway)
90 - ``a2dp_sink`` (A2DP Audio Sink)
91 - ``a2dp_source`` (A2DP Audio Source)
92 - ``bap_sink`` (LE Audio Basic Audio Profile Sink)
93 - ``bap_source`` (LE Audio Basic Audio Profile Source)
94
95 :Default value: ``[ a2dp_sink a2dp_source bap_sink bap_source hfp_hf hfp_ag ]``
96 :Type: array of strings
97
98 .. describe:: bluez5.codecs
99
100 Enabled A2DP codecs.
101
102 Supported codecs: ``sbc``, ``sbc_xq``, ``aac``, ``ldac``, ``aptx``,
103 ``aptx_hd``, ``aptx_ll``, ``aptx_ll_duplex``, ``faststream``,
104 ``faststream_duplex``, ``lc3plus_h3``, ``opus_05``, ``opus_05_51``,
105 ``opus_05_71``, ``opus_05_duplex``, ``opus_05_pro``, ``lc3``.
106
107 :Default value: all available codecs
108 :Type: array of strings
109
110 .. describe:: bluez5.enable-msbc
111
112 Enable mSBC codec (wideband speech codec for HFP/HSP).
113
114 This does not work on all headsets, so it is enabled based on the hardware
115 quirks database. By explicitly setting this option you can force it to be
116 enabled or disabled regardless.
117
118 :Default value: ``true``
119 :Type: boolean
120
121 .. describe:: bluez5.enable-sbc-xq
122
123 Enable SBC-XQ codec (high quality SBC codec for A2DP).
124
125 This does not work on all headsets, so it is enabled based on the hardware
126 quirks database. By explicitly setting this option you can force it to be
127 enabled or disabled regardless.
128
129 :Default value: ``true``
130 :Type: boolean
131
132 .. describe:: bluez5.enable-hw-volume
133
134 Enable hardware volume controls.
135
136 This does not work on all headsets, so it is enabled based on the hardware
137 quirks database. By explicitly setting this option you can force it to be
138 enabled or disabled regardless.
139
140 :Default value: ``true``
141 :Type: boolean
142
143 .. describe:: bluez5.hfphsp-backend
144
145 HFP/HSP backend.
146
147 Available values: ``any``, ``none``, ``hsphfpd``, ``ofono`` or ``native``.
148
149 :Default value: ``native``
150 :Type: string
151
152 .. describe:: bluez5.hfphsp-backend-native-modem
153
154 Modem to use for native HFP/HSP backend ModemManager support. When enabled,
155 PipeWire will forward HFP commands to the specified ModemManager device.
156 This corresponds to the 'Device' property of the
157 ``org.freedesktop.ModemManager1.Modem`` interface. May also be ``any`` to
158 use any available modem device.
159
160 :Default value: ``none``
161 :Type: string
162
163 .. describe:: bluez5.hw-offload-sco
164
165 HFP/HSP hardware offload SCO support.
166
167 Using this feature requires a custom WirePlumber script that handles audio
168 routing in a platform-specific way. See ``tests/examples/bt-pinephone.lua``
169 for an example.
170
171 :Default value: ``false``
172 :Type: boolean
173
174 .. describe:: bluez5.default.rate
175
176 The default audio rate for the A2DP codec configuration.
177
178 :Default value: ``48000``
179 :Type: integer
180
181 .. describe:: bluez5.default.channels
182
183 The default number of channels for the A2DP codec configuration.
184
185 :Default value: ``2``
186 :Type: integer
187
188 .. describe:: bluez5.dummy-avrcp-player
189
190 Register dummy AVRCP player. Some devices have wrongly functioning volume or
191 playback controls if this is not enabled. Disabled by default.
192
193 :Default value: ``false``
194 :Type: boolean
195
196 .. describe:: Opus Pro Audio mode settings
197
198 .. code-block::
199
200 bluez5.a2dp.opus.pro.channels = 3
201 bluez5.a2dp.opus.pro.coupled-streams = 1
202 bluez5.a2dp.opus.pro.locations = [ FL,FR,LFE ]
203 bluez5.a2dp.opus.pro.max-bitrate = 600000
204 bluez5.a2dp.opus.pro.frame-dms = 50
205 bluez5.a2dp.opus.pro.bidi.channels = 1
206 bluez5.a2dp.opus.pro.bidi.coupled-streams = 0
207 bluez5.a2dp.opus.pro.bidi.locations = [ FC ]
208 bluez5.a2dp.opus.pro.bidi.max-bitrate = 160000
209 bluez5.a2dp.opus.pro.bidi.frame-dms = 400
210
211 Options for the PipeWire-specific multichannel Opus codec, which can be used
212 to transport audio over Bluetooth between devices running PipeWire.
213
214 MIDI Monitor Properties
215 -----------------------
216
217 The BlueZ MIDI monitor SPA plugin (``api.bluez5.midi.enum``) may, in the future,
218 support properties that can be used to configure it when it is loaded. These
219 properties can be set in the ``monitor.bluez-midi.properties`` section of the
220 WirePlumber configuration file. At the moment of writing, there are no
221 properties that can be set there.
222
223 In addition, the BlueZ MIDI monitor supports a list of MIDI server node names
224 that can be used to create Bluetooth LE MIDI service instances. These
225 server node names can be set in the ``monitor.bluez-midi.servers`` section of
226 the WirePlumber configuration file.
227
228 Example:
229
230 .. code-block::
231
232 monitor.bluez-midi.servers = [ "bluez_midi.server" ]
233
234 .. note::
235
236 Typical BLE MIDI instruments have one service instance, so adding more than
237 one here may confuse some clients.
238
239 Rules
240 -----
241
242 When device and node objects are created by the BlueZ monitor, they can be
243 configured using rules. These rules allow matching the existing properties of
244 these objects and updating them with new values. This is the main way of
245 configuring Bluetooth device settings.
246
247 These rules can be set in the ``monitor.bluez.rules`` section of the WirePlumber
248 configuration file.
249
250 Example:
251
252 .. code-block::
253
254 monitor.bluez.rules = [
255 {
256 matches = [
257 {
258 ## This matches all bluetooth devices.
259 device.name = "~bluez_card.*"
260 }
261 ]
262 actions = {
263 update-props = {
264 bluez5.auto-connect = [ hfp_hf hsp_hs a2dp_sink hfp_ag hsp_ag a2dp_source ]
265 bluez5.hw-volume = [ hfp_hf hsp_hs a2dp_sink hfp_ag hsp_ag a2dp_source ]
266 bluez5.a2dp.ldac.quality = "auto"
267 bluez5.a2dp.aac.bitratemode = 0
268 bluez5.a2dp.opus.pro.application = "audio"
269 bluez5.a2dp.opus.pro.bidi.application = "audio"
270 }
271 }
272 }
273 {
274 matches = [
275 {
276 ## Matches all sources.
277 node.name = "~bluez_input.*"
278 }
279 {
280 ## Matches all sinks.
281 node.name = "~bluez_output.*"
282 }
283 ]
284 actions = {
285 update-props = {
286 bluez5.media-source-role = "input"
287
288 # Common node & audio adapter properties may also be set here
289 node.nick = "My Node"
290 priority.driver = 100
291 priority.session = 100
292 node.pause-on-idle = false
293 resample.quality = 4
294 channelmix.normalize = false
295 channelmix.mix-lfe = false
296 session.suspend-timeout-seconds = 5
297 monitor.channel-volumes = false
298 }
299 }
300 }
301 ]
302
303 Device properties
304 ^^^^^^^^^^^^^^^^^
305
306 The following properties can be set on device objects:
307
308 .. describe:: bluez5.auto-connect
309
310 Auto-connect device profiles on start up or when only partial profiles have
311 connected. Disabled by default if the property is not specified.
312
313 Supported values are: ``hfp_hf``, ``hsp_hs``, ``a2dp_sink``, ``hfp_ag``,
314 ``hsp_ag`` and ``a2dp_source``.
315
316 :Default value: ``[]``
317 :Type: array of strings
318
319 .. describe:: bluez5.hw-volume
320
321 Enable hardware volume controls on these profiles.
322
323 Supported values are: ``hfp_hf``, ``hsp_hs``, ``a2dp_sink``, ``hfp_ag``,
324 ``hsp_ag`` and ``a2dp_source``.
325
326 :Default value: ``[ hfp_ag hsp_ag a2dp_source ]``
327 :Type: array of strings
328
329 .. describe:: bluez5.a2dp.ldac.quality
330
331 LDAC encoding quality.
332
333 Available values: ``auto`` (Adaptive Bitrate, default), ``hq`` (High
334 Quality, 990/909kbps), ``sq`` (Standard Quality, 660/606kbps) and ``mq``
335 (Mobile use Quality, 330/303kbps).
336
337 :Default value: ``auto``
338 :Type: string
339
340 .. describe:: bluez5.a2dp.aac.bitratemode
341
342 AAC variable bitrate mode.
343
344 Available values: 0 (cbr, default), 1-5 (quality level).
345
346 :Default value: ``0``
347 :Type: integer
348
349 .. describe:: bluez5.a2dp.opus.pro.application
350
351 Opus Pro Audio encoding mode.
352
353 Available values: ``audio``, ``voip``, ``lowdelay``.
354
355 :Default value: ``audio``
356 :Type: string
357
358 .. describe:: bluez5.a2dp.opus.pro.bidi.application
359
360 Opus Pro Audio encoding mode for bidirectional audio.
361
362 Available values: ``audio``, ``voip``, ``lowdelay``.
363
364 :Default value: ``audio``
365 :Type: string
366
367 .. describe:: device.profile
368
369 The profile that is activated initially when the device is connected.
370
371 Available values: ``a2dp-sink`` (default) or ``headset-head-unit``.
372
373 :Default value: ``a2dp-sink``
374 :Type: string
375
376 Node properties
377 ^^^^^^^^^^^^^^^
378
379 The following properties can be set on node objects:
380
381 .. describe:: bluez5.media-source-role
382
383 Media source role, ``input`` or ``playback``. This controls how a media
384 source device, such as a smartphone, is used by the system. Defaults to
385 ``playback``, playing the incoming stream out to speakers. Set to ``input``
386 to use the smartphone as an input for apps (like a microphone).
387
388 :Default value: ``playback``
389 :Type: string
390
391 MIDI Rules
392 ----------
393
394 Similarly to the above rules, the BlueZ MIDI monitor also supports rules that
395 can be used to configure MIDI nodes when they are created.
396
397 These rules can be set in the ``monitor.bluez-midi.rules`` section of the
398 WirePlumber configuration file.
399
400 Example:
401
402 .. code-block::
403
404 monitor.bluez-midi.rules = [
405 {
406 matches = [
407 {
408 node.name = "~bluez_midi.*"
409 }
410 ]
411 actions = {
412 update-props = {
413 node.nick = "My Node"
414 priority.driver = 100
415 priority.session = 100
416 node.pause-on-idle = false
417 session.suspend-timeout-seconds = 5
418 node.latency-offset-msec = 0
419 }
420 }
421 }
422 ]
423
424 .. note::
425
426 It is possible to also match MIDI server nodes by testing the ``node.name``
427 property against the server node names that were set in the
428 ``monitor.bluez-midi.servers`` section of the WirePlumber configuration file.
429
430 MIDI-specific properties
431 ^^^^^^^^^^^^^^^^^^^^^^^^
432
433 .. describe:: node.latency-offset-msec
434
435 Latency adjustment to apply on the node. Larger values add a
436 constant latency, but reduces timing jitter caused by Bluetooth
437 transport.
438
439 :Default value: ``0``
440 :Type: integer (milliseconds)