Debian Codegraph @

docs/rst/policies/linking.rst

raw
1 .. _policies_linking:
2
3 Linking Policy
4 ==============
5
6 Introduction
7 ------------
8
9 The linking policy in WirePlumber is the logic charged to link a PipeWire stream
10 node with a PipeWire device node (most cases), or with another PipeWire stream
11 node (monitoring applications).
12
13 PipeWire stream nodes always have one of the following media classes:
14
15 - Stream/Output/Audio: For audio playback applications (Eg pw-play).
16 - Stream/Input/Audio: For audio capture applications (Eg pw-record).
17 - Stream/Input/Video: For video capture applications (Eg cheese).
18
19 And Pipewire device nodes always have one of the following media classes:
20
21 - Audio/Sink: For audio playback devices (Eg Speakers).
22 - Audio/Source: For audio capture devices (Eg Microphones).
23 - Video/Source: For video capture devices (Eg Cameras).
24
25 By default, since in most cases we want to link a stream node with a device
26 node, the linking policy logic when linking 2 nodes always follows the following
27 assignments:
28
29 .. graphviz::
30
31 digraph nodes {
32 rankdir=LR;
33 APS [shape=box label=<audio playback stream<BR/>(Stream/Output/Audio)>];
34 APD [shape=box label=<audio playback device<BR/>(Audio/Sink)>];
35 ACS [shape=box label=<audio capture stream<BR/>(Stream/Input/Audio)>];
36 ACD [shape=box label=<audio capture device<BR/>(Audio/Source)>];
37 VCS [shape=box label=<video capture stream<BR/>(Stream/Input/Video)>];
38 VCD [shape=box label=<video capture device<BR/>(Video/Source)>];
39 APS -> APD;
40 ACD -> ACS;
41 VCD -> VCS;
42 }
43
44
45 After that, once the media class of a device node has been selected for a
46 particular stream node, and there are more than 1 device node matching such
47 media class, WirePlumber will select one based on a set of priorities:
48
49 First, it will check if there is a default configured device node for the
50 selected device media class. If there is one, and the node exists, it will link
51 the stream node with such configured default node. Users can easily configure
52 default device nodes for all the 3 different device media classes using tools
53 such as ``pavucontrol`` or ``wpctl``. The logic is implemented in the
54 ``linking/find-default-target.lua`` Lua script.
55
56 If there isn't any default node configured, or there is a default node
57 configured but the node does not exist, WirePlumber will instead select the
58 best device node available. The best device node is the node with highest
59 session priority and available routes to the physical device. The logic is
60 implemented in the ``linking/find-best-target.lua`` Lua script.
61
62 If the best node could not be found because the system does not have any,
63 WirePlumber won't link the stream and will send a "no target node available"
64 error to the client.
65
66
67 Stream node linking properties
68 ------------------------------
69
70 The above default linking logic behavior can be changed by setting specific
71 properties on the nodes.
72
73 .. note::
74
75 These properties must be set in the **stream** nodes (not the device nodes),
76 otherwise they won't have any effect.
77
78 - **target.object**:
79
80   The name of the desired node for this stream to be linked with.
81   If this property is present, WirePlumber will try to find such node, see if it
82   can be linked with the stream, and if so, will use it instead of the default
83   node or best node. The logic is implemented in the ``linking/find-defined-target.lua``
84   Lua script. Since this property is not set by default, WirePlumber will always
85   link stream nodes to the default or best device node found. This property can be
86   easily set using tools such as ``pw-play`` with the ``--target`` flag.
87
88   Note that any node name can be specified there, even if the name is not a device
89   node name, but another stream node name. If this is the case, WirePlumber will
90   link 2 stream nodes together. An example of this case is the monitoring nodes
91   created by ``pavucontrol`` to monitor audio of all audio devices and streams.
92
93 - **node.dont-reconnect**:
94
95   Boolean indicating whether the stream node should not be reconnected to a new
96   node if its current linked node (target) was destroyed or not. By default it
97   is set to ``false``, so if the property is not present in the stream node, WirePlumber
98   will always try to reconnect the stream node to a new target instead of sending
99   an error to the client. The logic is implemented in the ``linking/prepare-link.lua``
100   Lua script.
101
102 - **node.dont-move**:
103
104   Boolean indicating whether the stream node should not be movable or not at runtime
105   using the metadata. If a stream node is not movable, it means that users cannot
106   relink the stream node to a new target at runtime (using tools such as ``pavucontrol``
107   or ``pw-metadata``) when the stream node is already linked to a different node. By
108   default it is set to ``false``, so if the property is not present, WirePlumber will
109   always move, and therefore link the stream node to a new target if it is defined and
110   updated in the ``target.object`` metadata key.
111
112 - **node.dont-fallback**:
113
114   Boolean indicating whether the stream node should not fallback to a different
115   target if its defined target does not exist (the one defined with the ``target.object``
116   property) or not. Therefore, if this property is set to ``true``, WirePlumber sends
117   a "defined target not found" error to the client and will also destroy the stream
118   node. By default it is set to ``false``, so if the property is not present in the
119   stream node, WirePlumber will always fallback to the default or best target if
120   the defined target was not found.
121
122 - **node.linger**:
123
124   Boolean indicating whether the stream node should linger or not if its defined
125   target was not found and the ``node.dont-fallback`` is set to true. Therefore, if
126   this property is set to ``true``, the defined target was not found, and the
127   ``node.dont-fallback`` is set to true, WirePlumber won't send a "defined target not found"
128   error to the client, and won't destroy the stream node. This is useful if we want
129   the stream to wait (without processing any data) until its defined target becomes
130   available. By default it is set to ``false``, so if the property is not present in the
131   stream node, WirePlumber will always destroy the node and send an error to the client
132   if its target was not found and ``node.dont-fallback`` was set to true.
133
134
135 Linking settings
136 ----------------
137
138 Apart from the above properties, there are also global settings for the linking
139 policy. See :ref:`config_settings` for more information, the linking settings
140 are prefixed with ``linking.``.