Debian Codegraph @

docs/rst/policies/smart_filters.rst

raw
1 .. _policies_smart_filters:
2
3 Smart Filters
4 =============
5
6 Introduction
7 ------------
8
9 The smart filters policy allows automatically linking filters together, in a
10 chain, and tied to a specific target node. This is useful when we want to apply
11 a specific processing chain to a specific device, for example. When a stream is
12 about to be linked to a target node that is associated with a smart filter
13 chain, the policy will automatically link the stream with the first filter in
14 the chain, and the last filter in the chain with the target node. This is done
15 transparently to the client, allowing users to define a specific processing
16 chain for a specific device without having to create setups with virtual sinks
17 (or sources) that must be explicitly targeted by the clients.
18
19 Filters, in general, are nodes that are placed in the middle of the graph and
20 are used to modify the data that passes through them. For example, the
21 *echo-cancel*, the *filter-chain*, or the *loopback* nodes are filters.
22 Filters can be implemented either as a single node or as a pair of nodes with
23 opposite directions. For example, the *null-audio-sink* node can be configured
24 to be a single-node filter. On the other hand, the *filter-chain* is a pair of
25 nodes with opposite directions, where one node captures the audio from the graph
26 and the other node sends the modified audio back to the graph.
27
28 For the purpose of the **smart filters** policy, WirePlumber will only consider
29 pairs of nodes as filters, not single-node ones. More specifically, a pair of
30 nodes will be considered to be a filter by WirePlumber if they have the
31 ``node.link-group`` property set to a common value. This property is always set
32 on pairs of nodes that are internally linked together and is a good indicator
33 that the nodes are implementing a filter.
34
35 That pair of nodes **must** always consist of a *stream* node and a *main* node.
36 The main node acts as a virtual device, where the data is sent or captured
37 to/from, and the stream node acts as a regular stream, where the data is sent
38 or received to/from the next node in the graph. This is designated by their
39 media class, as shown in the table below:
40
41 .. list-table::
42 :widths: 30 35 35
43 :header-rows: 1
44 :stub-columns: 1
45
46 * -
47 - Input filter (virtual sink)
48 - Output filter (virtual source)
49 * - Main node
50 - ``Audio/Sink`` (capture)
51 - ``Audio/Source`` (playback)
52 * - Stream node
53 - ``Stream/Output/Audio`` (playback)
54 - ``Stream/Input/Audio`` (capture)
55
56 For instance, if a smart filter is used between an application playback stream
57 and the default audio sink, the graph would look like this:
58
59 .. graphviz::
60
61 digraph nodes {
62 rankdir=LR;
63 A [shape=box label=<application stream node<BR/>(Stream/Output/Audio)>];
64 FM [shape=box label=<filter main node<BR/>(Audio/Sink)>];
65 FS [shape=box label=<filter stream node<BR/>(Stream/Output/Audio)>];
66 D [shape=box label=<default device node<BR/>(Audio/Sink)>];
67 A -> FM;
68 FS -> D;
69 subgraph cluster_filter {
70 style="dotted";
71 FM; FS;
72 }
73 }
74
75 The same logic is applied if the smart filter is used between an application
76 capture stream and the default audio source, it is just all in the opposite
77 direction. This is how the graph would look like in this case:
78
79 .. graphviz::
80
81 digraph nodes {
82 rankdir=LR;
83 A [shape=box label=<application stream node<BR/>(Stream/Input/Audio)>];
84 FM [shape=box label=<filter main node<BR/>(Audio/Source)>];
85 FS [shape=box label=<filter stream node<BR/>(Stream/Input/Audio)>];
86 D [shape=box label=<default device node<BR/>(Audio/Source)>];
87 D -> FS;
88 FM -> A;
89 subgraph cluster_filter {
90 style="dotted";
91 FM; FS;
92 }
93 }
94
95 When multiple filters have the same direction, they can also be chained together
96 so that the output of one filter is sent to the input of the next filter. The
97 next section describes how these chains can be described with properties so that
98 they are automatically linked by WirePlumber in any way we want.
99
100 Filter properties
101 -----------------
102
103 When a filter node is created, WirePlumber will check for the presence of the
104 following optional node properties on the **main** node:
105
106 - **filter.smart**
107
108 Boolean indicating whether smart policy will be used for these filter nodes or
109 not. This is disabled by default, therefore filter nodes will be treated as
110 regular nodes, without applying any kind of extra logic. On the other hand, if
111 this property is set to ``true``, automatic (smart) filter policy will be used
112 when linking them. The properties below will then also apply, providing
113 further instructions.
114
115 - **filter.smart.name**
116
117 The unique name of the filter. WirePlumber will use the value of the
118 ``node.link-group`` property as the filter name if this property is not set.
119
120 - **filter.smart.disabled**
121
122 Boolean indicating whether the filter should be disabled or not. A disabled
123 filter will never be used under any circumstances. If the property is not set,
124 WirePlumber will consider the filter as enabled (i.e. disabled = false).
125
126 - **filter.smart.targetable**
127
128 Boolean indicating whether the filter can be directly linked with clients that
129 have it defined as a target (Eg: ``pw-play --target <filter-name>``) or not.
130 This can be useful when a client wants to be linked with a filter that is in
131 the middle of the chain in order to bypass the filters that are placed before
132 the selected one. If the property is not set, WirePlumber will consider the
133 filter not targetable by default, meaning filters will never by bypassed by
134 clients, and clients will always be linked with the first filter in the chain.
135
136 - **filter.smart.target**
137
138 A JSON object that defines the matching properties of the filter's target
139 node. A filter target can never be another filter node (WirePlumber will
140 ignore it), it must be a device or virtual sink (or source, depending on the
141 direction of the filter). If this property is not set, WirePlumber will use
142 the default sink/source as the target.
143
144 - **filter.smart.before**
145
146 A JSON array containing the names of the filters that are supposed to be
147 chained after this filter (i.e. this filter here should be chained *before*
148 those). If not set, WirePlumber will link the filters by order of creation.
149
150 - **filter.smart.after**
151
152 A JSON array containing the names of the filters that are supposed to be
153 chained before this filter (i.e. this filter here should be chained *after*
154 those). If not set, WirePlumber will link the filters by order of creation.
155
156 .. note::
157
158 These properties must be set on the filter's **main** node, not the stream
159 node.
160
161 As an example, we will describe here how to create 2 loopback filters in
162 PipeWire's configuration, with names loopback-1 and loopback-2, that will be
163 linked with the default audio device, and use loopback-2 filter as the last
164 filter in the chain.
165
166 The PipeWire configuration files for the 2 filters should be like this:
167
168 - ~/.config/pipewire/pipewire.conf.d/loopback-1.conf:
169
170 .. code-block::
171 :emphasize-lines: 8-11
172
173 context.modules = [
174 { name = libpipewire-module-loopback
175 args = {
176 node.name = loopback-1-sink
177 node.description = "Loopback 1 Sink"
178 capture.props = {
179 audio.position = [ FL FR ]
180 media.class = Audio/Sink
181 filter.smart = true
182 filter.smart.name = loopback-1
183 filter.smart.before = [ loopback-2 ]
184 }
185 playback.props = {
186 audio.position = [ FL FR ]
187 node.passive = true
188 stream.dont-remix = true
189 }
190 }
191 }
192 ]
193
194 - ~/.config/pipewire/pipewire.conf.d/loopback-2.conf:
195
196 .. code-block::
197 :emphasize-lines: 8-10
198
199 context.modules = [
200 { name = libpipewire-module-loopback
201 args = {
202 node.name = loopback-2-sink
203 node.description = "Loopback 2 Sink"
204 capture.props = {
205 audio.position = [ FL FR ]
206 media.class = Audio/Sink
207 filter.smart = true
208 filter.smart.name = loopback-2
209 }
210 playback.props = {
211 audio.position = [ FL FR ]
212 node.passive = true
213 stream.dont-remix = true
214 }
215 }
216 }
217 ]
218
219 After restarting PipeWire to apply the configuration changes, playing a test
220 wave audio file with paplay to the default device should result in the following
221 graph:
222
223 .. graphviz::
224
225 digraph nodes {
226 rankdir=LR;
227 paplay [shape=box label=<paplay node<BR/>(Stream/Output/Audio)>];
228 L1M [shape=box label=<loopback-1 main node<BR/>(Audio/Sink)>];
229 L1S [shape=box label=<loopback-1 stream node<BR/>(Stream/Output/Audio)>];
230 L2M [shape=box label=<loopback-2 main node<BR/>(Audio/Sink)>];
231 L2S [shape=box label=<loopback-2 stream node<BR/>(Stream/Output/Audio)>];
232 device [shape=box label=<default device node<BR/>(Audio/Sink)>];
233 paplay -> L1M;
234 L1S -> L2M;
235 L2S -> device;
236 subgraph cluster_filter1 {
237 style="dotted";
238 L1M; L1S;
239 }
240 subgraph cluster_filter2 {
241 style="dotted";
242 L2M; L2S;
243 }
244 }
245
246 Now, if we remove the ``filter.smart.before = [ loopback-2 ]`` property from the
247 loopback-1 filter, and add a ``filter.smart.before = [ loopback-1 ]`` property
248 in the loopback-2 filter configuration file, WirePlumber should link the
249 loopback-1 filter as the last filter in the chain, like this:
250
251 .. graphviz::
252
253 digraph nodes {
254 rankdir=LR;
255 paplay [shape=box label=<paplay node<BR/>(Stream/Output/Audio)>];
256 L1M [shape=box label=<loopback-1 main node<BR/>(Audio/Sink)>];
257 L1S [shape=box label=<loopback-1 stream node<BR/>(Stream/Output/Audio)>];
258 L2M [shape=box label=<loopback-2 main node<BR/>(Audio/Sink)>];
259 L2S [shape=box label=<loopback-2 stream node<BR/>(Stream/Output/Audio)>];
260 device [shape=box label=<default device node<BR/>(Audio/Sink)>];
261 paplay -> L2M;
262 L2S -> L1M;
263 L1S -> device;
264 subgraph cluster_filter1 {
265 style="dotted";
266 L1M; L1S;
267 }
268 subgraph cluster_filter2 {
269 style="dotted";
270 L2M; L2S;
271 }
272 }
273
274 In addition, the filters can have different targets. For example, we can define
275 the filters like this:
276
277 - ~/.config/pipewire/pipewire.conf.d/loopback-1.conf:
278
279 .. code-block::
280 :emphasize-lines: 12
281
282 context.modules = [
283 { name = libpipewire-module-loopback
284 args = {
285 node.name = loopback-1-sink
286 node.description = "Loopback 1 Sink"
287 capture.props = {
288 audio.position = [ FL FR ]
289 media.class = Audio/Sink
290 filter.smart = true
291 filter.smart.name = loopback-1
292 filter.smart.after = [ loopback-2 ]
293 filter.smart.target = { node.name = "not-default-audio-device" }
294 }
295 playback.props = {
296 audio.position = [ FL FR ]
297 node.passive = true
298 stream.dont-remix = true
299 }
300 }
301 }
302 ]
303
304 - ~/.config/pipewire/pipewire.conf.d/loopback-2.conf:
305
306 .. code-block::
307
308 context.modules = [
309 { name = libpipewire-module-loopback
310 args = {
311 node.name = loopback-2-sink
312 node.description = "Loopback 2 Sink"
313 capture.props = {
314 audio.position = [ FL FR ]
315 media.class = Audio/Sink
316 filter.smart = true
317 filter.smart.name = loopback-2
318 }
319 playback.props = {
320 audio.position = [ FL FR ]
321 node.passive = true
322 stream.dont-remix = true
323 }
324 }
325 }
326 ]
327
328 In this case, playing a test wave audio file with paplay to the
329 ``not-default-audio-device`` device should result in the following graph:
330
331 .. graphviz::
332
333 digraph nodes {
334 rankdir=LR;
335 paplay [shape=box label=<paplay node<BR/>(Stream/Output/Audio)>];
336 L1M [shape=box label=<loopback-1 main node<BR/>(Audio/Sink)>];
337 L1S [shape=box label=<loopback-1 stream node<BR/>(Stream/Output/Audio)>];
338 L2M [shape=box label=<loopback-2 main node<BR/>(Audio/Sink)>];
339 L2S [shape=box label=<loopback-2 stream node<BR/>(Stream/Output/Audio)>];
340 device [shape=box label=<not-default-audio-device node<BR/>(Audio/Sink)>];
341 paplay -> L2M;
342 L2S -> L1M;
343 L1S -> device;
344 subgraph cluster_filter1 {
345 style="dotted";
346 L1M; L1S;
347 }
348 subgraph cluster_filter2 {
349 style="dotted";
350 L2M; L2S;
351 }
352 }
353
354 In this configuration, the loopback-1 filter will only be linked if the
355 application stream is targeting the device node called
356 "not-default-audio-device".
357
358 Filters metadata
359 ----------------
360
361 Similar to the default metadata, it is also possible to override the filter
362 properties using the "filters" metadata object. This allow users to change the
363 filters policy at runtime.
364
365 For example, assuming the id of the *loopback-1* main node is ``40``, we can
366 disable the filter by setting its ``filter.smart.disabled`` metadata key to
367 ``true`` using the ``pw-metadata`` tool like this:
368
369 .. code-block:: bash
370
371 $ pw-metadata -n filters 40 "filter.smart.disabled" true Spa:String:JSON
372
373 We can also change the target of a filter at runtime:
374
375 .. code-block:: bash
376
377 $ pw-metadata -n filters 40 "filter.smart.target" "{ node.name = new-target-node-name }" Spa:String:JSON
378
379 Every time a key in the filters metadata changes, all filters are unlinked and
380 re-linked properly, following the new policy.