| 1 |
.. _design_understanding_wireplumber: |
| 2 |
|
| 3 |
Understanding WirePlumber |
| 4 |
========================= |
| 5 |
|
| 6 |
Knowing the fundamentals of session management, let's see here how WirePlumber |
| 7 |
is structured. |
| 8 |
|
| 9 |
The library |
| 10 |
----------- |
| 11 |
|
| 12 |
WirePlumber is built on top of the `libwireplumber` library, which provides |
| 13 |
fundamental building blocks for expressing all the session management logic. |
| 14 |
Libwireplumber, which is written in C and based on GObject, wraps the PipeWire |
| 15 |
API and offers a higher level and more convenient API. While the WirePlumber |
| 16 |
daemon implements the session management logic, the underlying library can also |
| 17 |
be utilized outside the scope of the WirePlumber daemon. This allows for the |
| 18 |
creation of external tools and GUIs that interact with PipeWire. |
| 19 |
|
| 20 |
Being GObject based, the library is introspectable and can be used from any |
| 21 |
language that supports `GObject Introspection <https://gi.readthedocs.io/en/latest/>`_. |
| 22 |
The library is also available as a C API. |
| 23 |
|
| 24 |
The object model |
| 25 |
^^^^^^^^^^^^^^^^ |
| 26 |
|
| 27 |
The most fundamental code contained in the WirePlumber library is the object |
| 28 |
model, i.e. its representation of PipeWire's objects. |
| 29 |
|
| 30 |
PipeWire exposes several objects, such nodes and ports, via the IPC protocol |
| 31 |
in a manner that is hard to interact with using standard object-oriented |
| 32 |
principles, because it is asynchronous. For example, when an object is created, |
| 33 |
its existence is announced over the protocol, but its properties are announced |
| 34 |
later, on a secondary message. If something needs to react on this object |
| 35 |
creation event, it typically needs to access the object's properties, so it |
| 36 |
must wait until the properties have been sent. Doing this might sound simple, |
| 37 |
and it is, but it becomes a tedious repetitive process to be doing this |
| 38 |
everywhere instead of focusing on writing the actual event handling logic. |
| 39 |
|
| 40 |
WirePlumber's library solves this by creating proxy objects that cache all the |
| 41 |
information and updates received from PipeWire throughout each object's lifetime. |
| 42 |
Then, it makes them available via the :ref:`WpObjectManager <obj_manager_api>` |
| 43 |
API, which has the ability to wait until certain information (ex, the |
| 44 |
properties) has been cached on each object before announcing it. |
| 45 |
|
| 46 |
Session management utilities |
| 47 |
^^^^^^^^^^^^^^^^^^^^^^^^^^^^ |
| 48 |
|
| 49 |
The library also provides a set of utilities that are useful for session |
| 50 |
management. For example, it provides the :ref:`WpSessionItem <session_item_api>` |
| 51 |
class that can be used to abstract a part of the graph with some logic attached |
| 52 |
to it. It also provides the :ref:`Events & Hooks API <design_events_and_hooks>`, |
| 53 |
which is a way to express event handling logic in a declarative way. |
| 54 |
|
| 55 |
Misc utilities |
| 56 |
^^^^^^^^^^^^^^ |
| 57 |
|
| 58 |
The library also provides a set of miscellaneous utilities that bridge the |
| 59 |
PipeWire API with the GObject API, such as :ref:`WpProperties <properties_api>`, |
| 60 |
:ref:`WpSpaPod <spa_pod_api>`, :ref:`WpSpaJson <spa_json_api>` and others. |
| 61 |
These complement the object model and make it easier to interact with PipeWire |
| 62 |
objects. |
| 63 |
|
| 64 |
The daemon |
| 65 |
---------- |
| 66 |
|
| 67 |
The WirePlumber daemon is implemented on top of the library API and its job is |
| 68 |
to host components that implement the session management logic. By itself, it |
| 69 |
doesn't do anything except load and activate these components. The actual logic |
| 70 |
is implemented inside them. |
| 71 |
|
| 72 |
Modular design ensures that it is possible to swap the implementation of |
| 73 |
specific functionality without having to re-implement the rest of it, allowing |
| 74 |
flexibility on target-sensitive parts, such as policy management and |
| 75 |
making use of non-standard hardware. |
| 76 |
|
| 77 |
There are several kinds of components, each with a different purpose. The two |
| 78 |
main kinds are `modules` and `Lua scripts`. See also |
| 79 |
:ref:`config_components_and_profiles`. |
| 80 |
|
| 81 |
Modules |
| 82 |
^^^^^^^ |
| 83 |
|
| 84 |
Modules extend the libwireplumber API for specific purposes, usually to provide |
| 85 |
support code or to allow WirePlumber to communicate with external services (ex |
| 86 |
D-Bus APIs). They either expose their own APIs via GObject signals (i.e. dynamic |
| 87 |
APIs that do not require linking at compile time) or implement certain objects |
| 88 |
through interfaces. They are written in C. |
| 89 |
|
| 90 |
Lua scripts |
| 91 |
^^^^^^^^^^^ |
| 92 |
|
| 93 |
Lua scripts implement most of the session management. The libwireplumber API is |
| 94 |
made available in Lua with idiomatic bindings that make it very easy to write |
| 95 |
session management logic. |
| 96 |
|
| 97 |
Lua has been chosen because it is a very lightweight scripting language that is |
| 98 |
suitable for embedding. It is also very easy to learn and use, as well as bind |
| 99 |
it to C code. However, WirePlumber can be easily extended to support scripting |
| 100 |
languages other than Lua. The entire Lua scripting system is implemented as a |
| 101 |
module. |