Debian Codegraph @

docs/rst/design/understanding_session_management.rst

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