Debian Codegraph @

docs/rst/design/understanding_wireplumber.rst

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