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