Debian Codegraph @

docs/rst/daemon/configuration/components_and_profiles.rst

raw
1 .. _config_components_and_profiles:
2
3 Components & Profiles
4 =====================
5
6 WirePlumber is organized in components and profiles. Components are
7 functional parts that provide a specific feature, while profiles are
8 collections of components that are loaded together to offer a certain
9 overall experience.
10
11 Components
12 ----------
13
14 Components are functional parts that provide a specific feature. They can be
15 described by a name, a type, a feature that they provide and a set of
16 dependencies, required and optional.
17
18 In the configuration file, a component is described as a SPA-JSON object,
19 in the ``wireplumber.components`` array section, like this:
20
21 .. code-block::
22
23 {
24 name = <component-name>
25 type = <component-type>
26 arguments = { <json object> }
27
28 # Feature that this component provides
29 provides = <feature>
30
31 # List of features that must be provided before this component is loaded
32 requires = [ <features> ]
33
34 # List of features that would offer additional functionality if provided
35 # but are not strictly required
36 wants = [ <features> ]
37 }
38
39 Name & arguments
40 ~~~~~~~~~~~~~~~~
41
42 The name identifies the resource that this component loads. For example,
43 it can be a file or a shared library. Depending on the type, the component
44 may also accept arguments, which are passed on to the resource when it is
45 loaded.
46
47 Types
48 ~~~~~
49
50 The main types of components are:
51
52 * **script/lua**
53
54 A Lua script, which usually contains one or more event hooks and/or
55 other custom logic. This is the main type of component as WirePlumber's
56 business logic is mostly written in Lua.
57
58 * **module**
59
60 A WirePlumber module, which is a shared library that can be loaded
61 dynamically. Modules usually provide some bundled logic to be consumed by
62 scripts or some integration between WirePlumber and an external service.
63
64 * **pw-module**
65
66 A PipeWire module, which is also a shared library that can be loaded
67 dynamically, but extends the functionality of the underlying *libpipewire*
68 library. Loading PipeWire modules in the WirePlumber context can be useful
69 to load custom protocol extensions or to offload some functionality from
70 the PipeWire daemon.
71
72 * **virtual**
73
74 Virtual components are just load targets that can be used to pull in
75 other components by defining dependencies. They do not provide any
76 functionality by themselves. Note that such components do not have a "name".
77
78 * **built-in**
79
80 These components are functional parts that are already built into the
81 WirePlumber library. They provide mostly internal support elements and checks.
82
83 Features
84 ~~~~~~~~
85
86 A "feature" is a name that we can use to refer to what is being provided
87 by a component. For example, the ``monitors/alsa.lua`` script provides the
88 ``monitor.alsa`` feature. The feature name is used to refer to the component
89 when defining dependencies between components and also when defining profiles.
90
91 When a component loads successfully, its feature is marked as provided,
92 otherwise it is not. Whether a feature is provided or not can be checked at
93 runtime in Lua scripts using the :func:`Core.test_feature` function and in C code
94 using the :c:func:`wp_core_test_feature` function.
95
96 For a list of well-known features, see :ref:`config_features`.
97
98 Dependencies
99 ~~~~~~~~~~~~
100
101 Each component can "provide" a feature. When the component is loaded, the
102 feature is marked as provided. Other components can either "require"
103 or "want" a feature.
104
105 If a component "requires" a feature, that means that this feature **must** be
106 provided before this component is loaded and WirePlumber will try to load the
107 relevant component that provides that feature if it is not already loaded
108 (i.e. it will pull in the component). If that other component fails to load,
109 hence the feature is not provided, the component that requires it will fail
110 to load as well.
111
112 If a component "wants" a feature, that means that this feature would be nice
113 to have, in the sense that it would offer additional functionality if it
114 was provided, but it's not strictly needed. WirePlumber will also try to load
115 the relevant component that provides that feature if it is not already loaded,
116 meaning that it will also pull in the component. However, if that other
117 component fails to load, the component that wants it will still be loaded
118 without error.
119
120 Profiles
121 --------
122
123 A profile is a collection of components that are loaded together to offer
124 a certain overall experience.
125
126 Profiles are defined in the configuration file as a SPA-JSON object,
127 in the ``wireplumber.profiles`` section, like this:
128
129 .. code-block::
130
131 <profile> = {
132 <feature name> = [ required | optional | disabled ]
133 ...
134 }
135
136 Each feature can be marked as *required*, *optional* or *disabled*.
137
138 * **required**: Loading this profile will pull in the component that can
139 provide this feature in and if it fails to load, the profile will fail to
140 load as well.
141 * **optional**: Loading this profile does not pull in the component that
142 can provide this feature. If any of the required components either
143 *requires* or *wants* this feature, then WirePlumber will try to load it.
144 If it fails to load, the error condition depends on whether this feature was
145 required or wanted by the component that pulled it in.
146 * **disabled**: This feature will **not** be loaded, even if it is *wanted*
147 by some component. If any required component *requires* this feature, then
148 the profile will fail to load.
149
150 By default, all the features provided by all the components in the
151 ``wireplumber.components`` section are considered to be *optional*.
152 That means that no component will be loaded on an empty profile, since optional
153 components are not pulled in automatically.
154
155 If a feature is marked as *required* in a profile, then the component that
156 provides that feature will be pulled in, together with all its dependencies,
157 both required and optional.
158
159 .. note::
160
161 In essence, all optional features are opt-in by default. To opt out,
162 you need to mark the feature as *disabled*.
163
164 Dependency chain example
165 ------------------------
166
167 Consider the following configuration file:
168
169 .. code-block::
170
171 wireplumber.components = [
172 {
173 name = libwireplumber-module-dbus-connection, type = module
174 provides = support.dbus
175 }
176 {
177 name = libwireplumber-module-reserve-device, type = module
178 provides = support.reserve-device
179 requires = [ support.dbus ]
180 }
181 {
182 name = monitors/alsa.lua, type = script/lua
183 provides = monitor.alsa
184 wants = [ support.reserve-device ]
185 }
186 ]
187
188 wireplumber.profiles = {
189 main = {
190 monitor.alsa = required
191 }
192 }
193
194 In this example, the ``main`` profile requires the ``monitor.alsa`` feature.
195 This will cause the ``monitors/alsa.lua`` script to be loaded. Now, since the
196 ``monitors/alsa.lua`` script *wants* the ``support.reserve-device`` feature,
197 the ``libwireplumber-module-reserve-device`` module will also be pulled in.
198 And since that one *requires* the ``support.dbus`` feature, the
199 ``libwireplumber-module-dbus-connection`` module will also be pulled in.
200
201 However, on a system without D-Bus, a user may want to opt out of the
202 ``libwireplumber-module-dbus-connection`` module. This can be done by marking
203 the ``support.dbus`` feature as disabled in the profile:
204
205 .. code-block::
206
207 wireplumber.profiles = {
208 main = {
209 monitor.alsa = required
210 support.dbus = disabled
211 }
212 }
213
214 Upon doing that, the ``libwireplumber-module-dbus-connection`` module will
215 not be loaded, causing the ``libwireplumber-module-reserve-device`` module
216 to not be loaded as well, since it requires the ``support.dbus`` feature.
217 The ``monitors/alsa.lua`` script will still be loaded, since it only *wants*
218 the ``support.reserve-device`` feature.