mirror of
https://gitlab.freedesktop.org/pipewire/wireplumber.git
synced 2025-12-28 05:50:06 +01:00
f3f89b8fc1
Also: - rename some files to remove redundant information from the filenames - rename many labels to match the filename and its place in the hierarchy - move lua_api under the scripting section
105 lines
5 KiB
ReStructuredText
105 lines
5 KiB
ReStructuredText
.. _design_understanding_session_management:
|
|
|
|
Understanding Session Management
|
|
================================
|
|
|
|
The PipeWire session manager is a tool that is tasked to do a lot of things.
|
|
Many people understand the term "session manager" as a tool that is responsible
|
|
for managing links between nodes, but that is only one of many tasks. To
|
|
understand the entirety of its operation, we need to discuss how PipeWire works,
|
|
first.
|
|
|
|
When PipeWire starts, it loads a set of modules that are defined in its
|
|
configuration file. These modules provide functionality to PipeWire, otherwise
|
|
it is just an empty process that does nothing. Under normal circumstances,
|
|
the modules that are loaded on PipeWire's startup contain object *factories*,
|
|
plus the native protocol module that allows inter-process communication.
|
|
Other than that, PipeWire does not really load or do anything else. This is
|
|
where session management begins.
|
|
|
|
Session management is basically about setting up PipeWire to do something
|
|
useful. This is achieved by utilizing PipeWire's exposed object factories to
|
|
create some useful objects, then work with their methods to modify and later
|
|
destroy them. Such objects include devices, nodes, ports, links and others.
|
|
This is a task that requires continuous monitoring and action taking, reacting
|
|
on a large number of different events that happen as the system is being used.
|
|
|
|
High-level areas of operation
|
|
-----------------------------
|
|
|
|
The session management logic, in WirePlumber, is divided into 6 different areas
|
|
of operation:
|
|
|
|
1. Device Enablement
|
|
^^^^^^^^^^^^^^^^^^^^
|
|
|
|
Enabling devices is a fundamental area of operation. It is achieved by using
|
|
the device monitor objects (or just "monitors"), which are typically
|
|
implemented as SPA plugins in PipeWire, but they are loaded by WirePlumber.
|
|
Their task is to discover available media devices and create objects in PipeWire
|
|
that offer a way to interact with them.
|
|
|
|
Well-known monitors include:
|
|
|
|
- The ALSA monitor, which enables audio devices
|
|
- The ALSA MIDI monitor, which enables MIDI devices
|
|
- The libcamera monitor, which enables cameras
|
|
- The Video4Linux2 (V4L2) monitor, which also enables cameras, but also
|
|
other video capture devices through the V4L2 Linux API
|
|
- The BlueZ monitor, which enables bluetooth audio devices
|
|
|
|
2. Device Configuration
|
|
^^^^^^^^^^^^^^^^^^^^^^^
|
|
|
|
Most devices expose complex functionality, from the computer's perspective, that
|
|
needs to be managed in order to provide a simple and smooth user experience.
|
|
For that reason, for example, audio devices are organized into *profiles* and
|
|
*routes*, which allow setting them up to serve a specific use case. These
|
|
need to be configured and managed by the session manager.
|
|
|
|
3. Client Access Control
|
|
^^^^^^^^^^^^^^^^^^^^^^^^
|
|
|
|
When client applications connect to PipeWire, they need to obtain permissions
|
|
in order to be able to access the objects exposed by PipeWire and interact
|
|
with them. In some circumstances and configurations, the session manager is also
|
|
tasked with deciding which permissions should be granted to each client.
|
|
|
|
4. Node Configuration
|
|
^^^^^^^^^^^^^^^^^^^^^
|
|
|
|
Nodes are the fundamental elements of media processing. They are typically
|
|
created either by the device monitors or by client applications. When they are
|
|
created, they are in a state where they cannot be linked. Linking them requires
|
|
some configuration, such as configuring the media format and subsequently
|
|
the number and the type of ports that should be exposed. Additionally, some
|
|
properties and metadata related to the node might need to be set according to
|
|
user preferences. All of this is taken care of by the session manager.
|
|
|
|
5. Link Management
|
|
^^^^^^^^^^^^^^^^^^
|
|
|
|
When nodes are finally ready to use, the session manager is also tasked to
|
|
decide how they should be linked together in order for media to flow though.
|
|
For instance, an audio playback stream node most likely needs to be linked to
|
|
the default audio output device node. The session manager then also needs to
|
|
create all these links and monitor all conditions that may affect them so that
|
|
dynamic re-linking is possible in case something changes
|
|
(ex. if a device disconnects). In some cases, device and node configuration
|
|
may also need to change as a result of links being created or destroyed.
|
|
|
|
6. Metadata Management
|
|
^^^^^^^^^^^^^^^^^^^^^^
|
|
|
|
While in operation, PipeWire and WirePlumber both store some additional
|
|
properties about objects and their operation in storage that lives outside
|
|
these objects. These properties are referred to as "metadata" and they are
|
|
stored in "metadata objects". This metadata can be changed externally by tools
|
|
such as `pw-metadata`, but also others.
|
|
|
|
In some circumstances, this metadata needs to interact with logic inside
|
|
the session manager. Most notably, selecting the default audio and video inputs
|
|
and outputs is done by setting metadata. The session manager then needs to
|
|
validate this information, store it and restore it on the next restart, but also
|
|
ensure that the default inputs and outputs stay valid and reasonable when
|
|
devices are plugged and unplugged dynamically.
|