| 1 |
.. _config_settings: |
| 2 |
|
| 3 |
Well-known settings |
| 4 |
=================== |
| 5 |
|
| 6 |
This section describes the settings that can be configured on WirePlumber. |
| 7 |
|
| 8 |
Settings can be either configured statically in the configuration file |
| 9 |
by setting them under the ``wireplumber.settings`` section, or they can be |
| 10 |
configured dynamically at runtime by using metadata. |
| 11 |
|
| 12 |
For more information on what "settings" are and how they work, refer to the |
| 13 |
previous section: :ref:`config_configuration_option_types`. |
| 14 |
|
| 15 |
.. describe:: device.restore-profile |
| 16 |
|
| 17 |
When a device profile is changed manually (e.g. via pavucontrol), WirePlumber |
| 18 |
stores the selected profile and restores it when the device appears again |
| 19 |
(e.g. after a reboot). If this setting is disabled, WirePlumber will always |
| 20 |
pick the best profile for the device based on profile priorities and |
| 21 |
availability (or custom rules, if any). |
| 22 |
|
| 23 |
:Default value: ``true`` |
| 24 |
|
| 25 |
.. describe:: device.restore-routes |
| 26 |
|
| 27 |
When a device route is changed manually (e.g. via pavucontrol), WirePlumber |
| 28 |
stores the selected route and restores it when the same profile is |
| 29 |
selected for this device. If this setting is disabled, WirePlumber will |
| 30 |
always pick the best route for this device profile based on route priorities |
| 31 |
and availability (or custom rules, if any). |
| 32 |
|
| 33 |
This setting also enables WirePlumber to restore properties of the device |
| 34 |
route when the route is restored. This includes the volume levels of sources |
| 35 |
and sinks, as well as the IEC958 codecs selected (for routes that support |
| 36 |
encoded streams, such as HDMI). |
| 37 |
|
| 38 |
:Default value: ``true`` |
| 39 |
|
| 40 |
.. describe:: device.routes.default-sink-volume |
| 41 |
|
| 42 |
This option allows to set the default volume for sinks that are part of a |
| 43 |
device route (e.g. ALSA PCM sinks). This is used when the route is restored |
| 44 |
and the sink does not have a previously stored volume. |
| 45 |
|
| 46 |
It is possible to override the value on a per-device basis with a property |
| 47 |
(*not* a setting, so this would go into a configuration file) on the device |
| 48 |
named ``device.routes.default-sink-volume``. |
| 49 |
|
| 50 |
:Default value: ``0.4 ^ 3`` (40% on the cubic scale) |
| 51 |
|
| 52 |
.. describe:: device.routes.default-source-volume |
| 53 |
|
| 54 |
This option allows to set the default volume for sources that are part of a |
| 55 |
device route (e.g. ALSA PCM sources). This is used when the route is restored |
| 56 |
and the source does not have a previously stored volume. |
| 57 |
|
| 58 |
It is possible to override the value on a per-device basis with a property |
| 59 |
(*not* a setting, so this would go into a configuration file) on the device |
| 60 |
named ``device.routes.default-source-volume``. |
| 61 |
|
| 62 |
:Default value: ``1.0`` (100%) |
| 63 |
|
| 64 |
.. describe:: linking.allow-moving-streams |
| 65 |
|
| 66 |
This option allows moving streams by overriding their target via metadata. |
| 67 |
When enabled, WirePlumber monitors the "default" metadata for changes in the |
| 68 |
``target.object`` key of streams and if this key is set to a valid node name |
| 69 |
(``node.name``) or serial (``object.serial``), the stream is moved to that |
| 70 |
target node. |
| 71 |
|
| 72 |
This is used by applications such as pavucontrol and is recommended for |
| 73 |
compatibility with PulseAudio. |
| 74 |
|
| 75 |
.. note:: |
| 76 |
|
| 77 |
On the metadata, the ``target.node`` key is also supported for |
| 78 |
compatibility with older versions of PipeWire, but it is deprecated. |
| 79 |
Please use the ``target.object`` key instead. |
| 80 |
|
| 81 |
:Default value: ``true`` |
| 82 |
:See also: ``node.stream.restore-target`` |
| 83 |
|
| 84 |
.. describe:: linking.follow-default-target |
| 85 |
|
| 86 |
When a stream was started with the ``target.object`` property, WirePlumber |
| 87 |
normally links that stream to that target node and ignores the "default" |
| 88 |
target for that direction. However, if this option is enabled, WirePlumber |
| 89 |
will check if the designated target node *is* the "default" target and if so, |
| 90 |
it will act as if the stream did not have that property. |
| 91 |
|
| 92 |
In practice, this means that if the "default" target changes at runtime, |
| 93 |
the stream will be moved to the new "default" target. |
| 94 |
|
| 95 |
This is what Pulseaudio does and is implemented here for compatibility |
| 96 |
with some applications that do start with a ``target.object`` property |
| 97 |
set to the "default" target and expect the stream to be moved when the |
| 98 |
"default" target changes. |
| 99 |
|
| 100 |
Note that this logic is only applied on client (i.e. application) streams |
| 101 |
and *not* on filters. |
| 102 |
|
| 103 |
:Default value: ``true`` |
| 104 |
|
| 105 |
.. describe:: linking.pause-playback |
| 106 |
|
| 107 |
When an audio sink is removed, pause media players that have streams |
| 108 |
playing to it. Pausing is done via MPRIS interface. |
| 109 |
|
| 110 |
:Default value: ``true`` |
| 111 |
|
| 112 |
.. describe:: node.features.audio.no-dsp |
| 113 |
|
| 114 |
When this option is set to ``true``, audio nodes will not be configured |
| 115 |
in dsp mode, meaning that their channels will *not* be split into separate |
| 116 |
ports and that the audio data will *not* be converted to the float 32 format |
| 117 |
(F32P). Instead, devices will be configured in passthrough mode and streams |
| 118 |
will be configured in convert mode, so that their audio data is converted |
| 119 |
directly to the format that the device is expecting. |
| 120 |
|
| 121 |
This may be useful if you are trying to minimize audio processing for an |
| 122 |
embedded system, but it is not recommended for general use. |
| 123 |
|
| 124 |
.. warning:: |
| 125 |
|
| 126 |
This option **will break** compatibility with JACK applications |
| 127 |
and may also break certain patchbay applications. Do not enable, unless |
| 128 |
you understand what you are doing. |
| 129 |
|
| 130 |
:Default value: ``false`` |
| 131 |
|
| 132 |
.. describe:: node.features.audio.monitor-ports |
| 133 |
|
| 134 |
This enables the creation of "monitor" ports for audio nodes. Monitor ports |
| 135 |
are created on nodes that have input ports (i.e. sinks and capture streams) |
| 136 |
and allow monitoring of the audio data that is being sent to the node. |
| 137 |
|
| 138 |
This is mostly used by monitoring applications, such as pavucontrol. |
| 139 |
|
| 140 |
:Default value: ``true`` |
| 141 |
|
| 142 |
.. describe:: node.features.audio.control-port |
| 143 |
|
| 144 |
This enables the creation of a "control" port for audio nodes. Control ports |
| 145 |
allow sending MIDI data to the node, allowing for control of certain node's |
| 146 |
parameters (such as volume) via external controllers. |
| 147 |
|
| 148 |
:Default value: ``false`` |
| 149 |
|
| 150 |
.. describe:: node.stream.restore-props |
| 151 |
|
| 152 |
WirePlumber stores stream parameters such as volume and mute status for each |
| 153 |
client (i.e. application) stream. If this setting is enabled, WirePlumber |
| 154 |
will restore the previously stored stream parameters when the stream is |
| 155 |
activated. If it is disabled, stream parameters will be initialized to their |
| 156 |
default values. |
| 157 |
|
| 158 |
:Default value: ``true`` |
| 159 |
|
| 160 |
.. describe:: node.stream.restore-target |
| 161 |
|
| 162 |
When a client (i.e. application) stream is manually moved to a different |
| 163 |
target node (e.g. via pavucontrol), the target node is stored by WirePlumber. |
| 164 |
If this setting is enabled, WirePlumber will restore the previously stored |
| 165 |
target node when the stream is activated. |
| 166 |
|
| 167 |
.. note:: |
| 168 |
|
| 169 |
This does not restore manual links made by patchbay applications. This |
| 170 |
is only meant to restore the ``target.object`` property in the "default" |
| 171 |
metadata, which is manipulated by applications such as pavucontrol when |
| 172 |
a stream is moved to a different target. |
| 173 |
|
| 174 |
:Default value: ``true`` |
| 175 |
:See also: ``linking.allow-moving-streams`` |
| 176 |
|
| 177 |
.. describe:: node.stream.default-playback-volume |
| 178 |
|
| 179 |
The default volume for playback streams to be applied when the stream is |
| 180 |
activated. This is only applied when ``node.stream.restore-props`` is |
| 181 |
``true`` and the stream does not have a previously stored volume. |
| 182 |
|
| 183 |
:Default value: ``1.0`` |
| 184 |
:Range: ``0.0`` to ``1.0`` |
| 185 |
|
| 186 |
.. describe:: node.stream.default-capture-volume |
| 187 |
|
| 188 |
The default volume for capture streams to be applied when the stream is |
| 189 |
activated. This is only applied when ``node.stream.restore-props`` is |
| 190 |
``true`` and the stream does not have a previously stored volume. |
| 191 |
|
| 192 |
:Default value: ``1.0`` |
| 193 |
:Range: ``0.0`` to ``1.0`` |
| 194 |
|
| 195 |
.. describe:: node.filter.forward-format |
| 196 |
|
| 197 |
When a "filter" pair of nodes (such as echo-cancel or filter-chain) is |
| 198 |
linked to a device node that has a different channel map than the filter |
| 199 |
nodes, this option allows the channel map of the filter nodes to be changed |
| 200 |
to match the channel map of the device node. The change is applied to both |
| 201 |
ends of the "filter", so that any streams linked to the filter are also |
| 202 |
reconfigured to match the target channel map. |
| 203 |
|
| 204 |
This is useful, for instance, to make sure that an application will be |
| 205 |
properly configured to output surround audio to a surround device, even |
| 206 |
when going through a filter that was not explicitly configured to have |
| 207 |
a surround channel map. |
| 208 |
|
| 209 |
:Default value: ``false`` |
| 210 |
|
| 211 |
.. describe:: node.restore-default-targets |
| 212 |
|
| 213 |
This setting enables WirePlumber to store and restore the "default" source |
| 214 |
and sink targets of the graph. In PulseAudio terminology, this is also known |
| 215 |
as the "fallback" source and sink. |
| 216 |
|
| 217 |
When this setting is enabled, WirePlumber will store the "default" source |
| 218 |
and sink targets when they are changed manually (e.g. via pavucontrol) and |
| 219 |
restore them when the available nodes change or after a reload/restart. |
| 220 |
It will also store a history of past selected "default" targets and restore |
| 221 |
previously selected ones if the currently selected are not available. |
| 222 |
|
| 223 |
If this is disabled, WirePlumber will pick the best available source |
| 224 |
and sink targets based on their priorities, but it will also respect |
| 225 |
manual user selections that are done at runtime - it will just not remember |
| 226 |
them so that it can restore them at a later time. |
| 227 |
|
| 228 |
:Default value: ``true`` |