| 1 |
.. _policies_software_dsp: |
| 2 |
|
| 3 |
Automatic Software DSP |
| 4 |
====================== |
| 5 |
|
| 6 |
Introduction |
| 7 |
------------ |
| 8 |
|
| 9 |
WirePlumber provides a mechanism for transparently handling oddball and embedded |
| 10 |
devices that require software DSP to be done in userspace. Devices such as smartphones, |
| 11 |
TVs, portable speakers, and even some laptops implement an audio subsystem designed |
| 12 |
under the assumption that the hardware sink/source will be "backed" by some sort |
| 13 |
of transparent DSP mechanism. That is, the hardware device itself should not be |
| 14 |
directly accessed, and expects to be sent preprocessed/pre-routed samples. Often, |
| 15 |
especially with Android handsets, these samples are preprocessed or pre-routed |
| 16 |
by the vendor's proprietary userspace. |
| 17 |
|
| 18 |
WirePlumber's automatic software DSP mechanism aims to replicate this functionality in |
| 19 |
a standardised and configurable way. The target device sink/source is hidden from |
| 20 |
other PipeWire clients, and a virtual node is linked to it. This virtual |
| 21 |
node is then presented to clients as *the* node, allowing implementers to specify |
| 22 |
any custom processing or routing in a way that is transparent to users, the kernel, |
| 23 |
and the hardware. |
| 24 |
|
| 25 |
|
| 26 |
Activating |
| 27 |
---------- |
| 28 |
|
| 29 |
In addition to the ``node.software-dsp.rules`` section, the ``node.software-dsp`` |
| 30 |
:ref:`feature <config_features>` must be enabled in the desired profile(s). |
| 31 |
|
| 32 |
|
| 33 |
Matching a node |
| 34 |
--------------- |
| 35 |
|
| 36 |
Matching rules are specified in ``node.software-dsp.rules``. The ``create-filter`` |
| 37 |
action specifies behaviour at node insertion. All node properties can be matched |
| 38 |
on, including any type-specific properties such as ``alsa.id``. |
| 39 |
|
| 40 |
|
| 41 |
Configurable properties |
| 42 |
----------------------- |
| 43 |
|
| 44 |
.. describe:: filter-graph |
| 45 |
|
| 46 |
SPA-JSON object describing the software DSP node. This is passed as-is as |
| 47 |
an argument to ``libpipewire-module-filter-chain``. See the |
| 48 |
`filter-chain documentation <https://docs.pipewire.org/page_module_filter_chain.html>`_ |
| 49 |
for details on what options can be set in this object. |
| 50 |
|
| 51 |
.. note:: |
| 52 |
|
| 53 |
The ``target.object`` property of the virtual node should be configured |
| 54 |
statically to point to the node matched by the rule. |
| 55 |
|
| 56 |
.. describe:: filter-path |
| 57 |
|
| 58 |
Absolute path to a file on disk storing a SPA-JSON object as plain text. This will be |
| 59 |
parsed by WirePlumber into a WpConf object with a single section called |
| 60 |
``node.software-dsp.graph``, then passed as-is into ``libpipewire-module-filter-chain``. |
| 61 |
|
| 62 |
.. note:: |
| 63 |
|
| 64 |
``filter-graph`` and ``filter-path`` are mutually exclusive, with the former taking |
| 65 |
precedence if both are present in the matched rule. |
| 66 |
|
| 67 |
.. describe:: hide-parent |
| 68 |
|
| 69 |
Boolean indicating whether or not the matched node should be hidden from |
| 70 |
clients. ``node/software-dsp.lua`` will set the permissions for all clients other |
| 71 |
than WirePlumber itself to ``'-'``. This prevents use of the node by any |
| 72 |
userspace software except for WirePlumber itself. |
| 73 |
|
| 74 |
|
| 75 |
Examples |
| 76 |
-------- |
| 77 |
|
| 78 |
.. code-block:: |
| 79 |
:caption: wireplumber.conf.d/99-my-dsp.conf |
| 80 |
|
| 81 |
node.software-dsp.rules = [ |
| 82 |
{ |
| 83 |
matches = [ |
| 84 |
{ "node.name" = "alsa_output.platform-sound.HiFi__Speaker__sink" } |
| 85 |
{ "alsa.id" = "~WeirdHardware*" } # Wildcard match |
| 86 |
] |
| 87 |
|
| 88 |
actions = { |
| 89 |
create-filter = { |
| 90 |
filter-graph = {} # Virtual node goes here |
| 91 |
filter-path = "/path/to/spa.json" |
| 92 |
hide-parent = true |
| 93 |
} |
| 94 |
} |
| 95 |
} |
| 96 |
] |
| 97 |
|
| 98 |
wireplumber.profiles = { |
| 99 |
main = { |
| 100 |
node.software-dsp = required |
| 101 |
} |
| 102 |
} |
| 103 |
|
| 104 |
|
| 105 |
This will match any sinks with the UCM HiFi Speaker profile set or cards |
| 106 |
containing the string "WeirdHardware" at the start of their name. |