1libpipewire-module-protoMcioslc-eplullasnee(o7u)s InformlaitbipoinpeMwainruea-lmodule-protocol-pulse(7)
2
6 libpipewire-module-protocol-pulse - Protocol Pulse
7
9 This module implements a complete PulseAudio server on top of PipeWire.
10 This is only the server implementation, client are expected to use the
12 original PulseAudio client library. This provides a high level of
13 compatibility with existing applications; in fact, all usual PulseAudio
14 tools such as pavucontrol, pactl, pamon, paplay should continue to work
15 as they did before.
16 This module is usually loaded as part of a standalone pipewire process,
18 called pipewire-pulse, with the pipewire-pulse.conf config file.
19 The pulse server implements a sample cache that is otherwise not
21 available in PipeWire.
22
24 libpipewire-module-protocol-pulse
25
27 The module arguments can be the contents of the pulse.properties but it
28 is recommended to make a separate pulse.properties section in the
29 config file so that overrides can be done.
30
32 A config section with server properties can be given.
33 pulse.properties = {
35 # the addresses this server listens on
36 server.address = [
37 "unix:native"
38 #"unix:/tmp/something" # absolute paths may be used
39 #"tcp:4713" # IPv4 and IPv6 on all addresses
40 #"tcp:[::]:9999" # IPv6 on all addresses
41 #"tcp:127.0.0.1:8888" # IPv4 on a single address
42 #
43 #{ address = "tcp:4713" # address
44 # max-clients = 64 # maximum number of clients
45 # listen-backlog = 32 # backlog in the server listen queue
46 # client.access = "restricted" # permissions for clients
47 #}
48 ]
49 #pulse.min.req = 128/48000 # 2.7ms
50 #pulse.default.req = 960/48000 # 20 milliseconds
51 #pulse.min.frag = 128/48000 # 2.7ms
52 #pulse.default.frag = 96000/48000 # 2 seconds
53 #pulse.default.tlength = 96000/48000 # 2 seconds
54 #pulse.min.quantum = 128/48000 # 2.7ms
55 #pulse.default.format = F32
56 #pulse.default.position = [ FL FR ]
57 # These overrides are only applied when running in a vm.
58 vm.overrides = {
59 pulse.min.quantum = 1024/48000 # 22ms
60 }
61 }
62 Connection options
64 ...
65 server.address = [
66 "unix:native"
67 # "tcp:4713"
68 ]
69 ...
70 The addresses the server listens on when starting. Uncomment the
72 tcp:4713 entry to also make the server listen on a tcp socket. This is
73 equivalent to loading libpipewire-module-native-protocol-tcp.
74 There is also a slightly more verbose syntax with more options:
76 ....
78 server.address = [
79 { address = "tcp:4713" # address
80 max-clients = 64 # maximum number of clients
81 listen-backlog = 32 # backlog in the server listen queue
82 client.access = "restricted" # permissions for clients
83 }
84 ....
85 Use client.access to use one of the access methods to restrict the
87 permissions given to clients connected via this address.
88 By default network access is given the 'restricted' permissions. The
90 session manager is responsible for assigning permission to clients with
91 restricted permissions (usually read-only permissions).
92 Playback buffering options
94 pulse.min.req = 128/48000 # 2.7ms
95 The minimum amount of data to request for clients. The client requested
97 values will be clamped to this value. Lowering this value together with
98 tlength can decrease latency if the client wants this, but increase CPU
99 overhead.
100 pulse.default.req = 960/48000 # 20 milliseconds
102 The default amount of data to request for clients. If the client does
104 not specify any particular value, this default will be used. Lowering
105 this value together with tlength can decrease latency but increase CPU
106 overhead.
107 pulse.default.tlength = 96000/48000 # 2 seconds
109 The target amount of data to buffer on the server side. If the client
111 did not specify a value, this default will be used. Lower values can
112 decrease the latency.
113 Record buffering options
115 pulse.min.frag = 128/48000 # 2.7ms
116 The minimum allowed size of the capture buffer before it is sent to a
118 client. The requested value of the client will be clamped to this.
119 Lowering this value can reduce latency at the expense of more CPU
120 usage.
121 pulse.default.frag = 96000/48000 # 2 seconds
123 The default size of the capture buffer before it is sent to a client.
125 If the client did not specify any value, this default will be used.
126 Lowering this value can reduce latency at the expense of more CPU
127 usage.
128 Scheduling options
130 pulse.min.quantum = 128/48000 # 2.7ms
131 The minimum quantum (buffer size in samples) to use for pulseaudio
133 clients. This value is calculated based on the frag and req/tlength for
134 record and playback streams respectively and then clamped to this value
135 to ensure no pulseaudio client asks for too small quantums. Lowering
136 this value might decrease latency at the expense of more CPU usage.
137 Format options
139 pulse.default.format = F32
140 Some modules will default to this format when no other format was
142 given. This is equivalent to the PulseAudio default-sample-format
143 option in /etc/pulse/daemon.conf.
144 pulse.default.position = [ FL FR ]
146 Some modules will default to this channelmap (with its number of
148 channels). This is equivalent to the PulseAudio default-sample-channels
149 and default-channel-map options in /etc/pulse/daemon.conf.
150 VM options
152 vm.overrides = {
153 pulse.min.quantum = 1024/48000 # 22ms
154 }
155 When running in a VM, the vm.override section will override the
157 properties in pulse.properties with the given values. This might be
158 interesting because VMs usually can't support the low latency settings
159 that are possible on real hardware.
160 Quirk options
162 pulse.fix.format = "S16LE"
163 When a stream uses the FIX_FORMAT flag, fixate the format to this
165 value. Normally the format would be fixed to the sink/source that the
166 stream connects to. When an invalid format (null or '') is set, the
167 FIX_FORMAT flag is ignored.
168 pulse.fix.rate = 48000
170 When a stream uses the FIX_RATE flag, fixate the sample rate to this
172 value. Normally the rate would be fixed to the sink/source that the
173 stream connects to. When a 0 rate is set, the FIX_RATE flag is ignored.
174 pulse.fix.position = "[ FL FR ]"
176 When a stream uses the FIX_CHANNELS flag, fixate the channels to this
178 value. Normally the channels would be fixed to the sink/source that the
179 stream connects to. When an invalid position (null or '') is set, the
180 FIX_CHANNELS flag is ignored.
181
183 As part of the server startup sequence, a set of commands can be
184 executed. Currently, this can be used to load additional modules into
185 the server.
186 # Extra commands can be executed here.
188 # load-module : loads a module with args and flags
189 # args = "<module-name> <module-args>"
190 # flags = [ "no-fail" ]
191 pulse.cmd = [
192 { cmd = "load-module" args = "module-always-sink" flags = [ ] }
193 #{ cmd = "load-module" args = "module-switch-on-connect" }
194 #{ cmd = "load-module" args = "module-gsettings" flags = [ "nofail" ] }
195 ]
196
198 Streams created by module-protocol-pulse will use the stream.properties
199 section and stream.rules sections as usual.
200
202 The pulse protocol module supports generic config rules. It supports a
203 pulse.rules section with a quirks and an update-props action.
204 pulse.rules = [
206 {
207 # skype does not want to use devices that don't have an S16 sample format.
208 matches = [
209 { application.process.binary = "teams" }
210 { application.process.binary = "teams-insiders" }
211 { application.process.binary = "skypeforlinux" }
212 ]
213 actions = { quirks = [ force-s16-info ] }
214 }
215 {
216 # speech dispatcher asks for too small latency and then underruns.
217 matches = [ { application.name = "~speech-dispatcher*" } ]
218 actions = {
219 update-props = {
220 pulse.min.req = 1024/48000 # 21ms
221 pulse.min.quantum = 1024/48000 # 21ms
222 }
223 }
224 }
225 ]
226 Quirks
228 The quirks action takes an array of quirks to apply for the client.
229 • force-s16-info makes the sink and source introspect code pretend that
231 the sample format is S16 (16 bits) samples. Some application refuse
232 the sink/source if this is not the case.
233 • remove-capture-dont-move Removes the DONT_MOVE flag on capture
235 streams. Some applications set this flag so that the stream can't be
236 moved anymore with tools such as pavucontrol.
237 • block-source-volume blocks the client from updating any source
239 volumes. This can be used to disable things like automatic gain
240 control.
241 • block-sink-volume blocks the client from updating any sink volumes.
243 update-props
245 Takes an object with the properties to update on the client. Common
246 actions are to tweak the quantum values.
247
249 context.modules = [
250 { name = libpipewire-module-protocol-pulse
251 args = { }
252 }
253 ]
254 pulse.properties = {
256 server.address = [ "unix:native" ]
257 }
258 pulse.rules = [
260 {
261 # skype does not want to use devices that don't have an S16 sample format.
262 matches = [
263 { application.process.binary = "teams" }
264 { application.process.binary = "teams-insiders" }
265 { application.process.binary = "skypeforlinux" }
266 ]
267 actions = { quirks = [ force-s16-info ] }
268 }
269 {
270 # speech dispatcher asks for too small latency and then underruns.
271 matches = [ { application.name = "~speech-dispatcher*" } ]
272 actions = {
273 update-props = {
274 pulse.min.req = 1024/48000 # 21ms
275 pulse.min.quantum = 1024/48000 # 21ms
276 }
277 }
278 }
279 ]
280PipeWire 1.0.0libpipewire-module-protocol-pulse(7)