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