colin/wireplumber
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

docs: document components, profiles, features and settings

Browse Source
This commit is contained in:
George Kiagiadakis
2023-12-14 16:49:12 +02:00
parent 396b88e64b
commit 32b31232d1
7 changed files with 577 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

3
docs/rst/configuration.rst
View File

@@ -24,6 +24,9 @@ which are documented later in this chapter.
.. toctree::
:maxdepth: 1
configuration/components_and_profiles.rst
configuration/features.rst
configuration/settings.rst
configuration/locations.rst
configuration/main.rst
configuration/multi_instance.rst

210
docs/rst/configuration/components_and_profiles.rst Normal file
View File

@@ -0,0 +1,210 @@
.. _config_components_and_profiles:
Components & Profiles
=====================
WirePlumber is organized in components and profiles. Components are
functional parts that provide a specific feature, while profiles are
collections of components that are loaded together to offer a certain
overall experience.
Components
----------
Components are functional parts that provide a specific feature. They can be
described by a name, a type, a feature that they provide and a set of
dependencies, required and optional.
In the configuration file, a component is described as a SPA-JSON object,
in the ``wireplumber.components`` array section, like this:
.. code-block::
{
name = <component-name>
type = <component-type>
arguments = { <json object> }
# Feature that this component provides
provides = <feature>
# List of features that must be provided before this component is loaded
requires = [ <features> ]
# List of features that would offer additional functionality if provided
# but are not strictly required
wants = [ <features> ]
}
Name & arguments
~~~~~~~~~~~~~~~~
The name identifies the resource that this component loads. For example,
it can be a file or a shared library. Depending on the type, the component
may also accept arguments, which are passed on to the resource when it is
loaded.
Types
~~~~~
The main types of components are:
* **script/lua**
A Lua script, which usually contains one or more event hooks and/or
other custom logic. This is the main type of component as WirePlumber's
business logic is mostly written in Lua.
* **module**
A WirePlumber module, which is a shared library that can be loaded
dynamically. Modules usually provide some bundled logic to be consumed by
scripts or some integration between WirePlumber and an external service.
* **virtual**
Virtual components are just load targets that can be used to pull in
other components by defining dependencies. They do not provide any
functionality by themselves. Note that such components do not have a "name".
* **built-in**
These components are functional parts that are already built into the
WirePlumber library. They provide mostly internal support elements and checks.
Features
~~~~~~~~
A "feature" is a name that we can use to refer to what is being provided
by a component. For example, the ``monitors/alsa.lua`` script provides the
``monitor.alsa`` feature. The feature name is used to refer to the component
when defining dependencies between components and also when defining profiles.
When a component loads successfully, its feature is marked as provided,
otherwise it is not. Whether a feature is provided or not can be checked at
runtime in Lua scripts using the :func:`Core.test_feature` function and in C code
using the :c:func:`wp_core_test_feature` function.
For a list of well-known features, see :ref:`config_features`.
Dependencies
~~~~~~~~~~~~
Each component can "provide" a feature. When the component is loaded, the
feature is marked as provided. Other components can either "require"
or "want" a feature.
If a component "requires" a feature, that means that this feature **must** be
provided before this component is loaded and WirePlumber will try to load the
relevant component that provides that feature if it is not already loaded
(i.e. it will pull in the component). If that other component fails to load,
hence the feature is not provided, the component that requires it will fail
to load as well.
If a component "wants" a feature, that means that this feature would be nice
to have, in the sense that it would offer additional functionality if it
was provided, but it's not strictly needed. WirePlumber will also try to load
the relevant component that provides that feature if it is not already loaded,
meaning that it will also pull in the component. However, if that other
component fails to load, the component that wants it will still be loaded
without error.
Profiles
--------
A profile is a collection of components that are loaded together to offer
a certain overall experience.
Profiles are defined in the configuration file as a SPA-JSON object,
in the ``wireplumber.profiles`` section, like this:
.. code-block::
<profile> = {
<feature name> = [ required | optional | disabled ]
...
}
Each feature can be marked as *required*, *optional* or *disabled*.
* **required**: Loading this profile will pull in the component that can
provide this feature in and if it fails to load, the profile will fail to
load as well.
* **optional**: Loading this profile does not pull in the component that
can provide this feature. If any of the required components either
*requires* or *wants* this feature, then WirePlumber will try to load it.
If it fails to load, the error condition depends on whether this feature was
required or wanted by the component that pulled it in.
* **disabled**: This feature will **not** be loaded, even if it is *wanted*
by some component. If any required component *requires* this feature, then
the profile will fail to load.
By default, all the features provided by all the components in the
``wireplumber.components`` section are considered to be *optional*.
That means that no component will be loaded on an empty profile, since optional
components are not pulled in automatically.
If a feature is marked as *required* in a profile, then the component that
provides that feature will be pulled in, together with all its dependencies,
both required and optional.
.. note::
In essence, all optional features are opt-in by default. To opt out,
you need to mark the feature as *disabled*.
Dependency chain example
------------------------
Consider the following configuration file:
.. code-block::
wireplumber.components = [
{
name = libwireplumber-module-dbus-connection, type = module
provides = support.dbus
}
{
name = libwireplumber-module-reserve-device, type = module
provides = support.reserve-device
requires = [ support.dbus ]
}
{
name = monitors/alsa.lua, type = script/lua
provides = monitor.alsa
wants = [ support.reserve-device ]
}
]
wireplumber.profiles = {
main = {
monitor.alsa = required
}
}
In this example, the ``main`` profile requires the ``monitor.alsa`` feature.
This will cause the ``monitors/alsa.lua`` script to be loaded. Now, since the
``monitors/alsa.lua`` script *wants* the ``support.reserve-device`` feature,
the ``libwireplumber-module-reserve-device`` module will also be pulled in.
And since that one *requires* the ``support.dbus`` feature, the
``libwireplumber-module-dbus-connection`` module will also be pulled in.
However, on a system without D-Bus, a user may want to opt out of the
``libwireplumber-module-dbus-connection`` module. This can be done by marking
the ``support.dbus`` feature as disabled in the profile:
.. code-block::
wireplumber.profiles = {
main = {
monitor.alsa = required
support.dbus = disabled
}
}
Upon doing that, the ``libwireplumber-module-dbus-connection`` module will
not be loaded, causing the ``libwireplumber-module-reserve-device`` module
to not be loaded as well, since it requires the ``support.dbus`` feature.
The ``monitors/alsa.lua`` script will still be loaded, since it only *wants*
the ``support.reserve-device`` feature.

148
docs/rst/configuration/features.rst Normal file
View File

@@ -0,0 +1,148 @@
.. _config_features:
Well-known features
===================
This is a list of some well-known features that can be enabled or
disabled accordingly.
There are many more features actually defined in the configuration file, and it
can be confusing to go through them. This list here is meant to be a quick
reference for the most common ones that actually make sense to be toggled in
a configuration file in order to customize WirePlumber's behavior.
Hardware monitors
-----------------
Audio
~~~~~
.. describe:: hardware.audio
Enables bringing up audio hardware.
:wants: ``monitor.alsa``, ``monitor.alsa-midi``
.. describe:: monitor.alsa
Enables the ALSA device monitor.
:wants: ``monitor.alsa.reserve-device``
.. describe:: monitor.alsa.reserve-device
Enables D-Bus device reservation API for ALSA devices.
:requires: ``support.reserve-device``
.. describe:: monitor.alsa-midi
Enables the ALSA MIDI device monitor.
Bluetooth
~~~~~~~~~
.. describe:: hardware.bluetooth
Enables bringing up bluetooth hardware.
:wants: ``monitor.bluez``, ``monitor.bluez-midi``
.. describe:: monitor.bluez
Enables the BlueZ device monitor.
:wants: ``monitor.bluez.seat-monitoring``
.. describe:: monitor.bluez.seat-monitoring
Enables seat monitoring on the bluetooth monitor.
When enabled, this will make sure that the bluetooth devices are only
enabled on the active seat.
:requires: ``support.logind``
.. describe:: monitor.bluez-midi
Enables the BlueZ MIDI device monitor.
:wants: ``monitor.bluez.seat-monitoring``
Video
~~~~~
.. describe:: hardware.video-capture
Enables bringing up video capture hardware (cameras, hdmi capture devices,
etc.)
:wants: ``monitor.v4l2``, ``monitor.libcamera``
.. describe:: monitor.v4l2
Enables the V4L2 device monitor.
.. describe:: monitor.libcamera
Enables the libcamera device monitor.
Support components
------------------
.. describe:: support.dbus
Provides a D-Bus connection to the session bus. This is needed by some other
support features (see below) but it is generally optional. WirePlumber does
not require a D-Bus connection to work.
On a system where WirePlumber is configured to run system-wide (headless,
embedded, etc), this will most likely fail to load and thus disable all the
other support features that require it. On such systems it makes sense to
disable this feature explicitly, to avoid the overhead of trying to connect
to the session bus.
.. describe:: support.reserve-device
Provides support for the
`D-Bus device reservation API <http://git.0pointer.net/reserve.git/tree/reserve.txt>`_,
allowing the device monitors to reserve devices for exclusive access.
:requires: ``support.dbus``
.. describe:: support.portal-permissionstore
Integrates with the flatpak portal permission store to give appropriate
access permissions to flatpak applications.
:requires: ``support.dbus``
.. describe:: support.logind
Integrates with systemd-logind to enable specific functionality only on the
active seat.
Policies
--------
.. describe:: policy.standard
Enables the standard WirePlumber policy. This includes all the logic
for enabling devices, linking streams, granting permissions to clients,
etc, as appropriate for a desktop system.
.. describe:: policy.role-priority-system
Enables the role priority system policy. This system creates virtual sinks
that group streams based on their ``media.role`` property, and assigns a
priority to each role. Depending on the priority configuration, lower
priority roles may be corked or ducked when a higher priority role stream
is active.
This policy was designed for automotive and mobile systems and may not work
as expected on desktop systems.
Note that this policy is implemented as a superset of ``policy.standard``,
so ``policy.standard`` should not be disabled when enabling this policy.
:requires: ``policy.standard``

3
docs/rst/configuration/meson.build
View File

@@ -1,5 +1,8 @@
# you need to add here any files you add to the toc directory as well
sphinx_files += files(
'components_and_profiles.rst',
'features.rst',
'settings.rst',
'locations.rst',
'main.rst',
'multi_instance.rst',

12
docs/rst/configuration/settings.rst Normal file
View File

@@ -0,0 +1,12 @@
.. _config_settings:
WirePlumber Settings
====================
This section describes the settings that can be configured on WirePlumber.
Settings can be either configured statically in the configuration file
by setting them under the ``wireplumber.settings`` section, or they can be
configured dynamically at runtime by using metadata.
.. include:: ../../../src/scripts/lib/SETTINGS.rst

1
src/meson.build
View File

@@ -1,6 +1,7 @@
scripts_doc_files_relative = [
'default-nodes'/'README.rst',
'device'/'README.rst',
'lib'/'SETTINGS.rst',
'linking'/'README.rst',
]

200
src/scripts/lib/SETTINGS.rst Normal file
View File

@@ -0,0 +1,200 @@
.. describe:: device.restore-profile
When a device profile is changed manually (e.g. via pavucontrol), WirePlumber
stores the selected profile and restores it when the device appears again
(e.g. after a reboot). If this setting is disabled, WirePlumber will always
pick the best profile for the device based on profile priorities and
availability (or custom rules, if any).
:Default value: ``true``
.. describe:: device.restore-routes
When a device route is changed manually (e.g. via pavucontrol), WirePlumber
stores the selected route and restores it when the same profile is
selected for this device. If this setting is disabled, WirePlumber will
always pick the best route for this device profile based on route priorities
and availability (or custom rules, if any).
This setting also enables WirePlumber to restore properties of the device
route when the route is restored. This includes the volume levels of sources
and sinks, as well as the IEC958 codecs selected (for routes that support
encoded streams, such as HDMI).
:Default value: ``true``
.. describe:: device.routes.default-sink-volume
This option allows to set the default volume for sinks that are part of a
device route (e.g. ALSA PCM sinks). This is used when the route is restored
and the sink does not have a previously stored volume.
:Default value: ``0.4 ^ 3`` (40% on the cubic scale)
.. describe:: device.routes.default-source-volume
This option allows to set the default volume for sources that are part of a
device route (e.g. ALSA PCM sources). This is used when the route is restored
and the source does not have a previously stored volume.
:Default value: ``1.0`` (100%)
.. describe:: linking.allow-moving-streams
This option allows moving streams by overriding their target via metadata.
When enabled, WirePlumber monitors the "default" metadata for changes in the
``target.object`` key of streams and if this key is set to a valid node name
(``node.name``) or serial (``object.serial``), the stream is moved to that
target node.
This is used by applications such as pavucontrol and is recommended for
compatibility with PulseAudio.
.. note::
On the metadata, the ``target.node`` key is also supported for
compatibility with older versions of PipeWire, but it is deprecated.
Please use the ``target.object`` key instead.
:Default value: ``true``
:See also: ``node.stream.restore-target``
.. describe:: linking.follow-default-target
When a stream was started with the ``target.object`` property, WirePlumber
normally links that stream to that target node and ignores the "default"
target for that direction. However, if this option is enabled, WirePlumber
will check if the designated target node *is* the "default" target and if so,
it will act as if the stream did not have that property.
In practice, this means that if the "default" target changes at runtime,
the stream will be moved to the new "default" target.
This is what Pulseaudio does and is implemented here for compatibility
with some applications that do start with a ``target.object`` property
set to the "default" target and expect the stream to be moved when the
"default" target changes.
Note that this logic is only applied on client (i.e. application) streams
and *not* on filters.
:Default value: ``true``
.. describe:: linking.filter-forward-format
When a "filter" pair of nodes (such as echo-cancel or filter-chain) is
linked to a device node that has a different channel map than the filter
nodes, this option allows the channel map of the filter nodes to be changed
to match the channel map of the device node. The change is applied to both
ends of the "filter", so that any streams linked to the filter are also
reconfigured to match the target channel map.
This is useful, for instance, to make sure that an application will be
properly configured to output surround audio to a surround device, even
when going through a filter that was not explicitly configured to have
a surround channel map.
:Default value: ``false``
.. describe:: node.features.audio.no-dsp
When this option is set to ``true``, audio nodes will not be configured
in dsp mode, meaning that their channels will *not* be split into separate
ports and that the audio data will *not* be converted to the float 32 format
(F32P). Instead, devices will be configured in passthrough mode and streams
will be configured in convert mode, so that their audio data is converted
directly to the format that the device is expecting.
This may be useful if you are trying to minimize audio processing for an
embedded system, but it is not recommended for general use.
.. warning::
This option **will break** compatibility with JACK applications
and may also break certain patchbay applications. Do not enable, unless
you understand what you are doing.
:Default value: ``false``
.. describe:: node.features.audio.monitor-ports
This enables the creation of "monitor" ports for audio nodes. Monitor ports
are created on nodes that have input ports (i.e. sinks and capture streams)
and allow monitoring of the audio data that is being sent to the node.
This is mostly used by monitoring applications, such as pavucontrol.
:Default value: ``true``
.. describe:: node.features.audio.control-port
This enables the creation of a "control" port for audio nodes. Control ports
allow sending MIDI data to the node, allowing for control of certain node's
parameters (such as volume) via external controllers.
:Default value: ``false``
.. describe:: node.stream.restore-props
WirePlumber stores stream parameters such as volume and mute status for each
client (i.e. application) stream. If this setting is enabled, WirePlumber
will restore the previously stored stream parameters when the stream is
activated. If it is disabled, stream parameters will be initialized to their
default values.
:Default value: ``true``
.. describe:: node.stream.restore-target
When a client (i.e. application) stream is manually moved to a different
target node (e.g. via pavucontrol), the target node is stored by WirePlumber.
If this setting is enabled, WirePlumber will restore the previously stored
target node when the stream is activated.
.. note::
This does not restore manual links made by patchbay applications. This
is only meant to restore the ``target.object`` property in the "default"
metadata, which is manipulated by applications such as pavucontrol when
a stream is moved to a different target.
:Default value: ``true``
:See also: ``linking.allow-moving-streams``
.. describe:: node.stream.default-playback-volume
The default volume for playback streams to be applied when the stream is
activated. This is only applied when ``node.stream.restore-props`` is
``true`` and the stream does not have a previously stored volume.
:Default value: ``1.0``
:Range: ``0.0`` to ``1.0``
.. describe:: node.stream.default-capture-volume
The default volume for capture streams to be applied when the stream is
activated. This is only applied when ``node.stream.restore-props`` is
``true`` and the stream does not have a previously stored volume.
:Default value: ``1.0``
:Range: ``0.0`` to ``1.0``
.. describe:: node.restore-default-targets
This setting enables WirePlumber to store and restore the "default" source
and sink targets of the graph. In PulseAudio terminology, this is also known
as the "fallback" source and sink.
When this setting is enabled, WirePlumber will store the "default" source
and sink targets when they are changed manually (e.g. via pavucontrol) and
restore them when the available nodes change or after a reload/restart.
It will also store a history of past selected "default" targets and restore
previously selected ones if the currently selected are not available.
If this is disabled, WirePlumber will pick the best available source
and sink targets based on their priorities, but it will also respect
manual user selections that are done at runtime - it will just not remember
them so that it can restore them at a later time.
:Default value: ``true``