mirrors/pipewire
1
0
Fork 0
mirror of https://gitlab.freedesktop.org/pipewire/pipewire.git synced 2026-04-09 08:21:08 -04:00
Code Issues Projects Releases Packages Wiki Activity Actions

doc: improve formatting

Browse source
This commit is contained in:
Wim Taymans 2026-04-08 11:35:52 +02:00
parent 0e0c325194
commit fbbc4271a3
1 changed files with 42 additions and 12 deletions
Download patch file Download diff file Expand all files Collapse all files

54
doc/dox/internals/running.dox
View file

@ -30,13 +30,13 @@ be scheduled and grouped using:
A Port has 4 passive modes, this depends on the value of the `port.passive` property: A Port has 4 passive modes, this depends on the value of the `port.passive` property:
* `false`, the port will make the peer active and an active peer will make this port - `false`, the port will make the peer active and an active peer will make this port
active. active.
* `true`, the port will not make the peer active and an active peer will not make this - `true`, the port will not make the peer active and an active peer will not make this
port active. port active.
* `follow`, the port will not make the peer active but an active peer will make this - `follow`, the port will not make the peer active but an active peer will make this
port active. port active.
* `follow-suspend`, the port will only make another follow-suspend peer active but any - `follow-suspend`, the port will only make another follow-suspend peer active but any
active peer will make this port active. active peer will make this port active.
The combination of these 4 modes on the output and input ports of a link results in a The combination of these 4 modes on the output and input ports of a link results in a
@ -47,16 +47,16 @@ wide range of use cases.
A Node can have 8 passive modes, `node.passive` can be set to a comma separated list A Node can have 8 passive modes, `node.passive` can be set to a comma separated list
of the following values: of the following values:
* `false`, both input and output ports have `port.passive = false` - `false`, both input and output ports have `port.passive = false`
* `in`, input ports have `port.passive = true` - `in`, input ports have `port.passive = true`
* `out`, output ports have `port.passive = true` - `out`, output ports have `port.passive = true`
* `true`, both input and output ports have `port.passive = true`. This is the same - `true`, both input and output ports have `port.passive = true`. This is the same
as `in,out`. as `in,out`.
* `in-follow`, input ports have `port.passive = follow` - `in-follow`, input ports have `port.passive = follow`
* `out-follow`, output ports have `port.passive = follow` - `out-follow`, output ports have `port.passive = follow`
* `follow`, input and output ports have `port.passive = follow`. This is the same - `follow`, input and output ports have `port.passive = follow`. This is the same
as `in-follow,out-follow`. as `in-follow,out-follow`.
* `follow-suspend`, input and output ports have `port.passive = follow-suspend` - `follow-suspend`, input and output ports have `port.passive = follow-suspend`
Node by default have the `false` mode but nodes with the `media.class` property Node by default have the `false` mode but nodes with the `media.class` property
containing `Sink` or `Source` receive the `follow-suspend` mode by default. containing `Sink` or `Source` receive the `follow-suspend` mode by default.
@ -73,6 +73,7 @@ runnable or not. A link will always make both nodes runnable or none.
The following table decides the runnability of the 2 nodes based on the port.passive The following table decides the runnability of the 2 nodes based on the port.passive
mode of the link between the 2 ports: mode of the link between the 2 ports:
```
B-false B-true B-follow B-follow-suspend B-false B-true B-follow B-follow-suspend
A-false X X X X A-false X X X X
@ -80,11 +81,13 @@ A-true
A-follow A-follow
A-follow-suspend X A-follow-suspend X
Table 1 Table 1
```
When a node is made runnable, the port passive mode will then decide if the peer ports When a node is made runnable, the port passive mode will then decide if the peer ports
should become active as well with the following table. should become active as well with the following table.
```
B-false B-true B-follow B-follow-suspend B-false B-true B-follow B-follow-suspend
A-false X X X A-false X X X
@ -92,6 +95,7 @@ A-true X X X
A-follow X X X A-follow X X X
A-follow-suspend X X X A-follow-suspend X X X
Table 2 Table 2
```
So when A is runnable, all peers are activated except those with `port.passive=true`. So when A is runnable, all peers are activated except those with `port.passive=true`.
@ -104,22 +108,26 @@ Let's check some cases that we want to solve with these node and port properties
## Device nodes ## Device nodes
```
+--------+ +--------+ +--------+ +--------+
| ALSA | | ALSA | | ALSA | | ALSA |
| Source | | Sink | | Source | | Sink |
| FL FL | | FL FL |
| FR FR | | FR FR |
+--------+ +--------+ +--------+ +--------+
```
Unlinked device nodes are supposed to stay suspended when nothing is linked to Unlinked device nodes are supposed to stay suspended when nothing is linked to
them. them.
```
+----------+ +--------+ +----------+ +--------+
| playback | | ALSA | | playback | | ALSA |
| | | Sink | | | | Sink |
| FL ------ FL | | FL ------ FL |
| FR ------ FR | | FR ------ FR |
+----------+ +--------+ +----------+ +--------+
```
An (active) player node linked to a device node should make both nodes runnable. An (active) player node linked to a device node should make both nodes runnable.
@ -135,23 +143,27 @@ driver. In the above case, that will be the ALSA Sink.
Likewise, a capture node linked to an ALSA Source should make both nodes runnable. Likewise, a capture node linked to an ALSA Source should make both nodes runnable.
```
+--------+ +---------+ +--------+ +---------+
| ALSA | | capture | | ALSA | | capture |
| Source | | | | Source | | |
| FL ------ FL | | FL ------ FL |
| FR ------ FR | | FR ------ FR |
+--------+ +---------+ +--------+ +---------+
```
The ALSA Source is now the driver. The ALSA Source is now the driver.
Also, linking 2 device nodes together should make them runnable: Also, linking 2 device nodes together should make them runnable:
```
+--------+ +--------+ +--------+ +--------+
| ALSA | | ALSA | | ALSA | | ALSA |
| Source | | Sink | | Source | | Sink |
| FL ----------------------- FL | | FL ----------------------- FL |
| FR ----------------------- FR | | FR ----------------------- FR |
+--------+ +--------+ +--------+ +--------+
```
This is the case because in Table 1, the two `port.passive = follow-suspend` ports This is the case because in Table 1, the two `port.passive = follow-suspend` ports
from the Source and Sink activate each other. from the Source and Sink activate each other.
@ -161,12 +173,14 @@ from the Source and Sink activate each other.
When there is a filter in front of the ALSA Sink, it should not make the filter and When there is a filter in front of the ALSA Sink, it should not make the filter and
sink runnable. sink runnable.
```
+--------+ +--------+ +--------+ +--------+
| filter | | ALSA | | filter | | ALSA |
| | | Sink | | | | Sink |
FL FL ------ FL | FL FL ------ FL |
FR FR ------ FR | FR FR ------ FR |
+--------+ +--------+ +--------+ +--------+
```
The links between the filter and ALSA Sink are `port.passive = true` and don't make The links between the filter and ALSA Sink are `port.passive = true` and don't make
the nodes runnable. the nodes runnable.
@ -174,12 +188,14 @@ the nodes runnable.
The filter needs to be made runnable via some other means to also make the ALSA The filter needs to be made runnable via some other means to also make the ALSA
Sink runnable, for example by linking a playback node: Sink runnable, for example by linking a playback node:
```
+----------+ +--------+ +--------+ +----------+ +--------+ +--------+
| playback | | filter | | ALSA | | playback | | filter | | ALSA |
| | | | | Sink | | | | | | Sink |
| FL ------ FL FL ------ FL | | FL ------ FL FL ------ FL |
| FR ------ FR FR ------ FR | | FR ------ FR FR ------ FR |
+----------+ +--------+ +--------+ +----------+ +--------+ +--------+
```
The input port of the filter is `port.passive = follow-suspend' and so it can be The input port of the filter is `port.passive = follow-suspend' and so it can be
activated by the playback node. activated by the playback node.
@ -187,6 +203,7 @@ activated by the playback node.
Likewise, if the ALSA Sink is runnable, it should not automatically make the Likewise, if the ALSA Sink is runnable, it should not automatically make the
filter runnable. For example: filter runnable. For example:
```
+--------+ +--------+ +--------+ +--------+
| filter | | ALSA | | filter | | ALSA |
| | | Sink | | | | Sink |
@ -200,6 +217,7 @@ filter runnable. For example:
| FL ---+| | FL ---+|
| FR ----+ | FR ----+
+----------+ +----------+
```
Here the playback node makes the ALSA Sink runnable but the filter Here the playback node makes the ALSA Sink runnable but the filter
stays not-runnable because the output port is `port.passive = true`. stays not-runnable because the output port is `port.passive = true`.
@ -209,23 +227,27 @@ stays not-runnable because the output port is `port.passive = true`.
Consider the case where we have an ALSA Sink and a monitor stream Consider the case where we have an ALSA Sink and a monitor stream
connected to the sink monitor ports. connected to the sink monitor ports.
```
+-------+ +--------++ +-------+ +--------++
| ALSA | | monitor | | ALSA | | monitor |
| Sink | | | | Sink | | |
FL FL ------ FL | FL FL ------ FL |
FR FR ------ FR | FR FR ------ FR |
+-------+ +---------+ +-------+ +---------+
```
We would like to keep the monitor stream and the ALSA sink suspended We would like to keep the monitor stream and the ALSA sink suspended
unless something else activated the ALSA Sink: unless something else activated the ALSA Sink:
```
+----------+ +-------+ +---------+ +----------+ +-------+ +---------+
| playback | | ALSA | | monitor | | playback | | ALSA | | monitor |
| | | Sink | | | | | | Sink | | |
| FL ------ FL FL ------ FL | | FL ------ FL FL ------ FL |
| FR ------ FR FR ------ FR | | FR ------ FR FR ------ FR |
+----------+ +-------+ +---------+ +----------+ +-------+ +---------+
```
We can do this by making the monitor stream input ports `port.passive = follow` We can do this by making the monitor stream input ports `port.passive = follow`
and leave the ALSA Sink monitor output ports as `port.passive = follow-suspend`. and leave the ALSA Sink monitor output ports as `port.passive = follow-suspend`.
@ -243,6 +265,7 @@ Normally when an application makes a capture and playback node, both nodes will
be scheduled in different groups, consider: be scheduled in different groups, consider:
```
+--------+ +---------+ +--------+ +---------+
| ALSA | | capture | | ALSA | | capture |
| Source | | | | Source | | |
@ -256,6 +279,7 @@ be scheduled in different groups, consider:
| FL ------ FL | | FL ------ FL |
| FR ------ FR | | FR ------ FR |
+----------+ +--------+ +----------+ +--------+
```
Here we see 2 groups with the ALSA Source and ALSA Sink respectively as the Here we see 2 groups with the ALSA Source and ALSA Sink respectively as the
drivers. Depending on the clocks of the nodes, the capture and playback will not drivers. Depending on the clocks of the nodes, the capture and playback will not
@ -278,12 +302,14 @@ When we have a filter that is constructed from two nodes, an input and an output
node, we could use the `node.group` property to make sure they are both scheduled node, we could use the `node.group` property to make sure they are both scheduled
and made runnable together. and made runnable together.
```
+--------+ +-------+ +--------+ +-------+ +--------+ +-------+ +--------+ +-------+
| ALSA | | input | | output | | ALSA | | ALSA | | input | | output | | ALSA |
| Source | | | | | | Sink | | Source | | | | | | Sink |
| FL ------ FL -- processing-- FL ------ FL | | FL ------ FL -- processing-- FL ------ FL |
| FR ------ FR | | FR ------ FR | | FR ------ FR | | FR ------ FR |
+--------+ +-------+ +--------+ +-------+ +--------+ +-------+ +--------+ +-------+
```
This would work fine but it does not describe that there is an implicit internal This would work fine but it does not describe that there is an implicit internal
link between the input and output node. This information is important for the link between the input and output node. This information is important for the
@ -306,12 +332,14 @@ be set to `node.passive = true` to make the ports passive.
When there is no driver node in the group, nothing should be scheduled. This can When there is no driver node in the group, nothing should be scheduled. This can
happen when a playback node is linked to a capture node: happen when a playback node is linked to a capture node:
```
+--------+ +---------+ +--------+ +---------+
| player | | capture | | player | | capture |
| | | | | | | |
| FL ----------- FL | | FL ----------- FL |
| FR ----------- FR | | FR ----------- FR |
+--------+ +---------+ +--------+ +---------+
```
None of these nodes is a driver so there is no driver in the group and nothing None of these nodes is a driver so there is no driver in the group and nothing
will be scheduled. will be scheduled.
@ -325,12 +353,14 @@ scheduling some other nodes.
A simple node, unlinked to anything should normally not run. A simple node, unlinked to anything should normally not run.
```
+--------+ +--------+
| player | | player |
| | | |
| FL | FL
| FR | FR
+--------+ +--------+
```
When the `node.always-process = true` property is set, the node will however be When the `node.always-process = true` property is set, the node will however be
made runnable even if unlinked. This is done by adding the node to a random driver. made runnable even if unlinked. This is done by adding the node to a random driver.