diff --git a/docs/rst/daemon/configuration/bluetooth.rst b/docs/rst/daemon/configuration/bluetooth.rst index 7fea02be..39b07e2e 100644 --- a/docs/rst/daemon/configuration/bluetooth.rst +++ b/docs/rst/daemon/configuration/bluetooth.rst @@ -4,8 +4,8 @@ Bluetooth configuration ======================= Using the same format as the :ref:`ALSA monitor `, the -configuration file ``wireplumber.conf.d/bluetooth.conf`` is charged -to configure the Bluetooth devices and nodes created by WirePlumber. +configuration file ``wireplumber.conf.d/bluetooth.conf`` configures +the Bluetooth devices and nodes created by WirePlumber. * *Settings* @@ -13,56 +13,35 @@ to configure the Bluetooth devices and nodes created by WirePlumber. .. code-block:: - wireplumber.properties = { - bluez5.enable-msbc = true, + monitor.bluez.properties = { + bluez5.roles = "[ a2dp_sink a2dp_source bap_sink bap_source hsp_hs hsp_ag hfp_hf hfp_ag ]" } - This example will enable the MSBC codec in connected Bluetooth devices that - support it. + Enabled headset roles (default: [ a2dp_sink a2dp_source bap_sink bap_source hsp_hs hsp_ag hfp_hf hfp_ag ]). + Some headsets (e.g. Sony WH-1000XM3) do not work with both hsp_ag and hfp_ag enabled, + so `hsp_ag` and `hfp_ag` are disabled by default. - The list of all valid properties are: + Supported roles: - .. code-block:: - - bluez5.enable-sbc-xq = true - - Enables the SBC-XQ codec in connected Blueooth devices that support it - - .. code-block:: - - bluez5.enable-msbc = true - - Enables the MSBC codec in connected Blueooth devices that support it - - .. code-block:: - - bluez5.enable-hw-volume = true - - Enables hardware volume controls in Bluetooth devices that support it - - .. code-block:: - - bluez5.headset-roles = "[ hsp_hs hsp_ag hfp_hf hfp_ag ]" - - Enabled headset roles (default: [ hsp_hs hfp_ag ]), this property only applies - to native backend. Currently some headsets (Sony WH-1000XM3) are not working - with both hsp_ag and hfp_ag enabled, disable either hsp_ag or hfp_ag to work - around it. - - Supported headset roles: ``hsp_hs`` (HSP Headset), ``hsp_ag`` (HSP Audio - Gateway), ``hfp_hf`` (HFP Hands-Free) and ``hfp_ag`` (HFP Audio Gateway) + - ``hsp_hs`` (HSP Headset) + - ``hsp_ag`` (HSP Audio Gateway), + - ``hfp_hf`` (HFP Hands-Free), + - ``hfp_ag`` (HFP Audio Gateway) + - ``a2dp_sink`` (A2DP Audio Sink) + - ``a2dp_source`` (A2DP Audio Source) + - ``bap_sink`` (LE Audio Basic Audio Profile Sink) + - ``bap_source`` (LE Audio Basic Audio Profile Source) .. code-block:: bluez5.codecs = "[ sbc sbc_xq aac ]" - Enables ``sbc``, ``sbc_zq`` and ``aac`` A2DP codecs. + Enables the specified A2DP codecs. All codecs are enabled by default. - Supported codecs: ``sbc``, ``sbc_xq``, ``aac``, ``ldac``, ``aptx``, + Supported codecs:``sbc``, ``sbc_xq``, ``aac``, ``ldac``, ``aptx``, ``aptx_hd``, ``aptx_ll``, ``aptx_ll_duplex``, ``faststream``, - ``faststream_duplex``. - - All codecs are supported by default. + ``faststream_duplex``, ``lc3plus_h3``, ``opus_05``, ``opus_05_51``, ``opus_05_71``, + ``opus_05_duplex``, ``opus_05_pro``, ``lc3``. .. code-block:: @@ -71,6 +50,24 @@ to configure the Bluetooth devices and nodes created by WirePlumber. HFP/HSP backend (default: native). Available values: ``any``, ``none``, ``hsphfpd``, ``ofono`` or ``native``. + .. code-block:: + + bluez5.hfphsp-backend-native-modem = "none" + + Modem to use for native HFP/HSP backend ModemManager support. When enabled, + PipeWire will forward HFP commands to the specified ModemManager device. + This corresponds to the 'Device' property of the org.freedesktop.ModemManager1.Modem + interface. May also be ``any`` to use any available modem device. + + .. code-block:: + + bluez5.hw-offload-sco = false + + HFP/HSP hardware offload SCO support (default: false). Using this + feature requires a custom WirePlumber script that handles audio + routing in a platform-specific way. See + ``tests/examples/bt-pinephone.lua`` for an example. + .. code-block:: bluez5.default.rate = 48000 @@ -81,7 +78,54 @@ to configure the Bluetooth devices and nodes created by WirePlumber. bluez5.default.channels = 2 - The bluetooth default number of channels. + The Bluetooth default number of channels. + + .. code-block:: + + bluez5.dummy-avrcp-player = false + + Register dummy AVRCP player. Some devices have wrongly functioning + volume or playback controls if this is not enabled. Disabled by default. + + .. code-block:: + + bluez5.enable-msbc = true, + bluez5.enable-sbc-xq = true + bluez5.enable-hw-volume = true + + By default MSBC and SBC-XQ codecs and hardware volume is enabled, + except if disabled by a hardware quirk database. You can force + them to be enabled regardless also for devices where the database disables + it with these options. + + .. code-block:: + + bluez5.a2dp.opus.pro.channels = 3 + bluez5.a2dp.opus.pro.coupled-streams = 1 + bluez5.a2dp.opus.pro.locations = "FL,FR,LFE" + bluez5.a2dp.opus.pro.max-bitrate = 600000 + bluez5.a2dp.opus.pro.frame-dms = 50 + bluez5.a2dp.opus.pro.bidi.channels = 1 + bluez5.a2dp.opus.pro.bidi.coupled-streams = 0 + bluez5.a2dp.opus.pro.bidi.locations = "FC" + bluez5.a2dp.opus.pro.bidi.max-bitrate = 160000 + bluez5.a2dp.opus.pro.bidi.frame-dms = 400 + + Options for a custom multichannel Opus codec, which can be used to + transport audio between devices running PipeWire. + +* *MIDI Settings* + + Example: + + .. code-block:: + + monitor.bluez-midi.servers = [ "bluez_midi.server" ] + + List of MIDI server node names. Each node name given will create a new instance + of a BLE MIDI service. Typical BLE MIDI instruments have on service instance, + so adding more than one here may confuse some clients. The node property matching + rules below apply also to these servers. * *Rules* @@ -89,8 +133,7 @@ to configure the Bluetooth devices and nodes created by WirePlumber. .. code-block:: - wireplumber.settings = { - bluez_monitor = [ + monitor.bluez.rules = [ { matches = [ { @@ -122,7 +165,6 @@ to configure the Bluetooth devices and nodes created by WirePlumber. } } ] - } This will set the auto-connect property to ``hfp_hf``, ``hsp_hs`` and ``a2dp_sink`` on bluetooth devices whose name matches the ``bluez_card.*`` @@ -174,3 +216,42 @@ to configure the Bluetooth devices and nodes created by WirePlumber. Profile connected first. Available values: ``a2dp-sink`` (default) or ``headset-head-unit``. + +* *MIDI Rules* + + Example: + + .. code-block:: + + monitor.bluez-midi.rules = [ + { + matches = [ + { + node.name = "~bluez_midi*" + } + ] + actions = { + update-props = { + node.nick = "My Node" + priority.driver = 100 + priority.session = 100 + node.pause-on-idle = false + session.suspend-timeout-seconds = 5 + monitor.channel-volumes = false + node.latency-offset-msec = 0 + } + } + } + ] + + Allows changing well-known node settings. + + In addition, allows changing some MIDI-specific settings: + + .. code-block:: + + node.latency-offset-msec = 0 + + Latency adjustment to apply on the node. Larger values add a + constant latency, but reduces timing jitter caused by Bluetooth + transport.