docs: Document automatic software DSP handling

Signed-off-by: James Calligeros <jcalligeros99@gmail.com>

docs/rst/index.rst

@@ -26,6 +26,7 @@ Table of Contents
    :maxdepth: 2
    :caption: WirePlumber's Policies
 
+   policies/software_dsp.rst
    policies/linking.rst
    policies/smart_filters.rst
 

docs/rst/policies/meson.build

@@ -1,5 +1,6 @@
 # you need to add here any files you add to the toc directory as well
 sphinx_files += files(
+   'software_dsp.rst',
    'linking.rst',
    'smart_filters.rst',
 )

docs/rst/policies/software_dsp.rst

@@ -0,0 +1,91 @@
+.. _policies_software_dsp:
+
+Automatic Software DSP
+======================
+
+Introduction
+------------
+
+WirePlumber provides a mechanism for transparently handling oddball and embedded
+devices that require software DSP to be done in userspace. Devices such as smartphones,
+TVs, portable speakers, and even some laptops implement an audio subsystem designed
+under the assumption that the hardware sink/source will be "backed" by some sort
+of transparent DSP mechanism. That is, the hardware device itself should not be
+directly accessed, and expects to be sent preprocessed/pre-routed samples. Often,
+especially with Android handsets, these samples are preprocessed or pre-routed
+by the vendor's proprietary userspace.
+
+WirePlumber's automatic software DSP mechanism aims to replicate this functionality in
+a standardised and configurable way. The target sink/source is hidden from
+clients of the WirePlumber daemon, and a virtual node is linked to it. This virtual
+node is then presented to clients as *the* node, allowing implementors to specify
+any custom processing or routing in a way that is transparent to users, the kernel,
+and the hardware.
+
+
+Activating
+----------
+
+In addition to the ``node.software-dsp.rules`` section, the ``node.software-dsp``
+component must be activated in the desired profile(s).
+
+
+Matching a Node
+--------------
+
+Matching rules are specified in ``node.software-dsp.rules``. The ``create-filter``
+action specifies behaviour at node insertion. All node properties can be matched
+on, including any type-specific properties such as ``alsa.id``.
+
+
+Configurable properties
+-----------------------
+
+- **filter-graph**
+
+  SPA-JSON representing a virtual node. This is passed into
+  ``libpipewire-module-filter-chain`` by ``node/software-dsp.lua``. This property is
+  not recursed over - it is returned as a string. In a future
+  release, ``filter-graph`` will instead specify the path to a file containing the
+  SPA-JSON. The ``node.target`` property of the virtual node should point to
+  the node matched by the rule.
+
+- **hide-parent**
+
+  Boolean indicating whether or not the matched node should be hidden from
+  clients. ``node/software-dsp.lua`` will set the permissions for all clients other
+  than WirePlumber itself to ``'-'``. This prevents use of the node by any
+  userspace software except for WirePlumber itself.
+
+
+Examples
+--------
+
+``wireplumber.conf.d/99-my-dsp.conf``
+.. code-block::
+
+  node.software-dsp.rules = [
+    {
+      matches = [
+        { "node.name" = "alsa_output.platform-sound.HiFi__Speaker__sink" }
+        { "alsa.id" = "~WeirdHardware*" } # Wildcard match
+      ]
+
+      actions = {
+        create-filter = {
+          filter-graph = {} # Virtual node goes here
+          hide-parent = true
+        }
+      }
+    }
+  ]
+
+  wireplumber.profiles = [
+    main = {
+      node.software-dsp = required
+    }
+  ]
+
+
+This will match any sinks with the UCM HiFi Speaker profile set that are associated
+with cards containing the string "WeirdHardware" at the start of their name.