docs: move well-known settings docs from src/scripts/lib to where they belong
These were documented in src/scripts/lib initially because the settings-manager scripts used to be also there and it made sense to keep them close together.
This commit is contained in:
George Kiagiadakis
@@ -12,4 +12,202 @@ configured dynamically at runtime by using metadata.
|
||||
For more information on what "settings" are and how they work, refer to the
|
||||
previous section: :ref:`config_configuration_option_types`.
|
||||
|
||||
.. include:: ../../../../src/scripts/lib/SETTINGS.rst
|
||||
.. 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:: 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.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.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``
|
||||
|
||||
@@ -1,7 +1,6 @@
|
||||
scripts_doc_files_relative = [
|
||||
'default-nodes'/'README.rst',
|
||||
'device'/'README.rst',
|
||||
'lib'/'SETTINGS.rst',
|
||||
'linking'/'README.rst',
|
||||
]
|
||||
|
||||
|
||||
@@ -1,200 +0,0 @@
|
||||
|
||||
.. 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:: 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.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.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``
|
||||
Reference in New Issue
Block a user