| 1 |
.. _design_understanding_session_management: |
| 2 |
|
| 3 |
Understanding Session Management |
| 4 |
================================ |
| 5 |
|
| 6 |
The PipeWire session manager is a tool that is tasked to do a lot of things. |
| 7 |
Many people understand the term "session manager" as a tool that is responsible |
| 8 |
for managing links between nodes, but that is only one of many tasks. To |
| 9 |
understand the entirety of its operation, we need to discuss how PipeWire works, |
| 10 |
first. |
| 11 |
|
| 12 |
When PipeWire starts, it loads a set of modules that are defined in its |
| 13 |
configuration file. These modules provide functionality to PipeWire, otherwise |
| 14 |
it is just an empty process that does nothing. Under normal circumstances, |
| 15 |
the modules that are loaded on PipeWire's startup contain object *factories*, |
| 16 |
plus the native protocol module that allows inter-process communication. |
| 17 |
Other than that, PipeWire does not really load or do anything else. This is |
| 18 |
where session management begins. |
| 19 |
|
| 20 |
Session management is basically about setting up PipeWire to do something |
| 21 |
useful. This is achieved by utilizing PipeWire's exposed object factories to |
| 22 |
create some useful objects, then work with their methods to modify and later |
| 23 |
destroy them. Such objects include devices, nodes, ports, links and others. |
| 24 |
This is a task that requires continuous monitoring and action taking, reacting |
| 25 |
on a large number of different events that happen as the system is being used. |
| 26 |
|
| 27 |
High-level areas of operation |
| 28 |
----------------------------- |
| 29 |
|
| 30 |
The session management logic, in WirePlumber, is divided into 6 different areas |
| 31 |
of operation: |
| 32 |
|
| 33 |
1. Device Enablement |
| 34 |
^^^^^^^^^^^^^^^^^^^^ |
| 35 |
|
| 36 |
Enabling devices is a fundamental area of operation. It is achieved by using |
| 37 |
the device monitor objects (or just "monitors"), which are typically |
| 38 |
implemented as SPA plugins in PipeWire, but they are loaded by WirePlumber. |
| 39 |
Their task is to discover available media devices and create objects in PipeWire |
| 40 |
that offer a way to interact with them. |
| 41 |
|
| 42 |
Well-known monitors include: |
| 43 |
|
| 44 |
- The ALSA monitor, which enables audio devices |
| 45 |
- The ALSA MIDI monitor, which enables MIDI devices |
| 46 |
- The libcamera monitor, which enables cameras |
| 47 |
- The Video4Linux2 (V4L2) monitor, which also enables cameras, but also |
| 48 |
other video capture devices through the V4L2 Linux API |
| 49 |
- The BlueZ monitor, which enables bluetooth audio devices |
| 50 |
|
| 51 |
2. Device Configuration |
| 52 |
^^^^^^^^^^^^^^^^^^^^^^^ |
| 53 |
|
| 54 |
Most devices expose complex functionality, from the computer's perspective, that |
| 55 |
needs to be managed in order to provide a simple and smooth user experience. |
| 56 |
For that reason, for example, audio devices are organized into *profiles* and |
| 57 |
*routes*, which allow setting them up to serve a specific use case. These |
| 58 |
need to be configured and managed by the session manager. |
| 59 |
|
| 60 |
3. Client Access Control |
| 61 |
^^^^^^^^^^^^^^^^^^^^^^^^ |
| 62 |
|
| 63 |
When client applications connect to PipeWire, they need to obtain permissions |
| 64 |
in order to be able to access the objects exposed by PipeWire and interact |
| 65 |
with them. In some circumstances and configurations, the session manager is also |
| 66 |
tasked with deciding which permissions should be granted to each client. |
| 67 |
|
| 68 |
4. Node Configuration |
| 69 |
^^^^^^^^^^^^^^^^^^^^^ |
| 70 |
|
| 71 |
Nodes are the fundamental elements of media processing. They are typically |
| 72 |
created either by the device monitors or by client applications. When they are |
| 73 |
created, they are in a state where they cannot be linked. Linking them requires |
| 74 |
some configuration, such as configuring the media format and subsequently |
| 75 |
the number and the type of ports that should be exposed. Additionally, some |
| 76 |
properties and metadata related to the node might need to be set according to |
| 77 |
user preferences. All of this is taken care of by the session manager. |
| 78 |
|
| 79 |
5. Link Management |
| 80 |
^^^^^^^^^^^^^^^^^^ |
| 81 |
|
| 82 |
When nodes are finally ready to use, the session manager is also tasked to |
| 83 |
decide how they should be linked together in order for media to flow though. |
| 84 |
For instance, an audio playback stream node most likely needs to be linked to |
| 85 |
the default audio output device node. The session manager then also needs to |
| 86 |
create all these links and monitor all conditions that may affect them so that |
| 87 |
dynamic re-linking is possible in case something changes |
| 88 |
(ex. if a device disconnects). In some cases, device and node configuration |
| 89 |
may also need to change as a result of links being created or destroyed. |
| 90 |
|
| 91 |
6. Metadata Management |
| 92 |
^^^^^^^^^^^^^^^^^^^^^^ |
| 93 |
|
| 94 |
While in operation, PipeWire and WirePlumber both store some additional |
| 95 |
properties about objects and their operation in storage that lives outside |
| 96 |
these objects. These properties are referred to as "metadata" and they are |
| 97 |
stored in "metadata objects". This metadata can be changed externally by tools |
| 98 |
such as `pw-metadata`, but also others. |
| 99 |
|
| 100 |
In some circumstances, this metadata needs to interact with logic inside |
| 101 |
the session manager. Most notably, selecting the default audio and video inputs |
| 102 |
and outputs is done by setting metadata. The session manager then needs to |
| 103 |
validate this information, store it and restore it on the next restart, but also |
| 104 |
ensure that the default inputs and outputs stay valid and reasonable when |
| 105 |
devices are plugged and unplugged dynamically. |