Debian Codegraph @

docs/rst/daemon/configuration/settings.rst

raw
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``