Debian Codegraph @

docs/rst/policies/software_dsp.rst

raw
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.