Debian Codegraph @

docs/rst/daemon/configuration/alsa.rst

raw
1 .. _config_alsa:
2
3 ALSA configuration
4 ==================
5
6 One of the components of WirePlumber is the ALSA monitor. This monitor is
7 responsible for creating PipeWire devices and nodes for all the ALSA cards that
8 are available on the system. It also manages the configuration of these devices.
9
10 The ALSA monitor is enabled by default and can be disabled using the
11 ``monitor.alsa`` :ref:`feature <config_features>` in the configuration file.
12
13 The monitor, as with all device monitors, is implemented as a SPA plugin and is
14 part of PipeWire. WirePlumber merely loads the plugin and lets it do its work.
15 The plugin then monitors UDev and creates device and node objects for all the
16 ALSA cards that are available on the system.
17
18 .. note::
19
20 One thing worth remembering here is that in ALSA, a "card" represents a
21 physical sound controller device, and a "device" is a logical access point
22 that represents a set of inputs and/or outputs that are part of the card. In
23 PipeWire, a "device" is the direct equivalent of an ALSA "card" and a "node"
24 is almost equivalent (close, but not quite) of an ALSA "device".
25
26 Properties
27 ----------
28
29 The ALSA monitor SPA plugin (``api.alsa.enum.udev``) supports properties that
30 can be used to configure it when it is loaded. These properties can be set in
31 the ``monitor.alsa.properties`` section of the WirePlumber configuration file.
32
33 Example:
34
35 .. code-block::
36
37 monitor.alsa.properties = {
38 alsa.use-acp = true
39 }
40
41 .. describe:: alsa.use-acp
42
43 A boolean that controls whether the ACP (alsa card profile) code is to be
44 the default manager of the device. This will probe the device and configure
45 the available profiles, ports and mixer settings. The code to do this is
46 taken directly from PulseAudio and provides devices that look and feel
47 exactly like the PulseAudio devices.
48
49 Rules
50 -----
51
52 When device and node objects are created by the ALSA monitor, they can be
53 configured using rules. These rules allow matching the existing properties of
54 these objects and updating them with new values. This is the main way of
55 configuring ALSA device settings.
56
57 These rules can be set in the ``monitor.alsa.rules`` section of the WirePlumber
58 configuration file.
59
60 Example:
61
62 .. code-block::
63
64 monitor.alsa.rules = [
65 {
66 matches = [
67 {
68 # This matches the value of the 'device.name' property of the device.
69 device.name = "~alsa_card.*"
70 }
71 ]
72 actions = {
73 update-props = {
74 # Apply all the desired device settings here.
75 api.alsa.use-acp = true
76 }
77 }
78 }
79 {
80 matches = [
81 # This matches the value of the 'node.name' property of the node.
82 {
83 node.name = "~alsa_output.*"
84 }
85 ]
86 actions = {
87 # Apply all the desired node specific settings here.
88 update-props = {
89 node.nick = "My Node"
90 priority.driver = 100
91 session.suspend-timeout-seconds = 5
92 }
93 }
94 }
95 ]
96
97 Device properties
98 ^^^^^^^^^^^^^^^^^
99
100 The following properties can be configured on devices created by the monitor:
101
102 .. describe:: api.alsa.use-acp
103
104 Use the ACP (alsa card profile) code to manage this device. This will probe
105 the device and configure the available profiles, ports and mixer settings.
106 The code to do this is taken directly from PulseAudio and provides devices
107 that look and feel exactly like the PulseAudio devices.
108
109 :Default value: ``true``
110 :Type: boolean
111
112 .. describe:: api.alsa.use-ucm
113
114 When ACP is enabled and a UCM configuration is available for a device, by
115 default it is used instead of the ACP profiles. This option allows you to
116 disable this and use the ACP profiles instead.
117
118 This option does nothing if ``api.alsa.use-acp`` is set to ``false``.
119
120 :Default value: ``true``
121 :Type: boolean
122
123 .. describe:: api.alsa.soft-mixer
124
125 Setting this option to ``true`` will disable the hardware mixer for volume
126 control and mute. All volume handling will then use software volume and mute,
127 leaving the hardware mixer untouched. The hardware mixer will still be used
128 to mute unused audio paths in the device.
129
130 :Type: boolean
131
132 .. describe:: api.alsa.ignore-dB
133
134 Setting this option to ``true`` will ignore the decibel setting configured by
135 the driver. Use this when the driver reports wrong settings.
136
137 :Type: boolean
138
139 .. describe:: device.profile-set
140
141 This option can be used to select a custom ACP profile-set name for the
142 device. This can be configured in UDev rules, but it can also be specified
143 here. The default is to use "default.conf".
144
145 :Type: string
146
147 .. describe:: device.profile
148
149 The initial active profile name. The default is to start from the "Off"
150 profile and then let WirePlumber select the best profile based on its
151 policy.
152
153 :Type: string
154
155 .. describe:: api.acp.auto-profile
156
157 Automatically select the best profile for the device. Normally this option is
158 disabled because WirePlumber will manage the profile of the device.
159 WirePlumber can save and load previously selected profiles. Enable this in
160 custom configurations where the relevant WirePlumber components are disabled.
161
162 :Type: boolean
163
164 .. describe:: api.acp.auto-port
165
166 Automatically select the highest priority port that is available ("port" is a
167 PulseAudio/ACP term, the equivalent of a "Route" in PipeWire). This is by
168 default disabled because WirePlumber handles the task of selecting and
169 restoring Routes. Enable this in custom configurations where the relevant
170 WirePlumber components are disabled.
171
172 :Type: boolean
173
174 .. describe:: api.acp.probe-rate
175
176 Sets the samplerate used for probing the ALSA devices and collecting the
177 profiles and ports.
178
179 :Type: integer
180
181 .. describe:: api.acp.pro-channels
182
183 Sets the number of channels to use when probing the "Pro Audio" profile.
184 Normally, the maximum amount of channels will be used but with this setting
185 this can be reduced, which can make it possible to use other samplerates on
186 some devices.
187
188 :Type: integer
189
190 Some of the other properties that can be configured on devices:
191
192 .. describe:: device.nick
193
194 A short name for the device.
195
196 .. describe:: device.description
197
198 A longer, user-friendly name of the device. This will show up in most
199 user interfaces as the device's name.
200
201 .. describe:: device.disabled
202
203 Disables the device. PipeWire will remove it from the list of cards or
204 devices.
205
206 :Type: boolean
207
208 Node properties
209 ^^^^^^^^^^^^^^^
210
211 The following properties can be configured on nodes created by the monitor:
212
213 .. describe:: priority.driver
214
215 This configures the node driver priority. Nodes with higher priority will be
216 used as a driver in the graph. Other nodes with lower priority will have to
217 resample to the driver node when they are joined in the same graph. The
218 default value is set based on some heuristics.
219
220 :Type: integer
221
222 .. describe:: priority.session
223
224 This configures the priority of the node when selecting a default node
225 (default sink/source as a link target for streams). Higher priority nodes
226 will be more likely candidates for becoming the default node.
227
228 :Type: integer
229
230 .. note::
231
232 By default, sources have a ``priority.session`` value around 1600-2000 and
233 sinks have a value around 600-1000. If you are increasing the priority of
234 a sink, it is **not advised** to use a value higher than 1500, as it may
235 cause a sink's monitor to be selected as the default source.
236
237 .. describe:: node.pause-on-idle
238
239 Pause the node when nothing is linked to it anymore. This is by default false
240 because some devices make a "pop" sound when they are opened/closed.
241 The node will normally pause and suspend after a timeout (see below).
242
243 :Type: boolean
244
245 .. describe:: session.suspend-timeout-seconds
246
247 This option configures a different suspend timeout on the node. By default
248 this is ``5`` seconds. For some devices (HiFi amplifiers, for example) it
249 might make sense to set a higher timeout because they might require some time
250 to restart after being idle.
251
252 A value of ``0`` disables suspend for a node and will leave the ALSA device
253 busy. The device can then be manually suspended with
254 ``pactl suspend-sink|source``.
255
256 :Type: integer
257
258 .. describe:: audio.format
259
260 The sample format of the device. By default, PipeWire will use a 32 bits
261 sample format but a different format can be set here.
262
263 :Type: string (``"S16LE"``, ``"S32LE"``, ``"F32LE"``, ...)
264
265 .. describe:: audio.rate
266
267 The sample rate of the device. By default, the ALSA device will be configured
268 with the same samplerate as the global graph. If this is not supported, or a
269 custom value is set here, resampling will be used to match the graph rate.
270
271 :Type: integer
272
273 .. describe:: audio.channels
274
275 The number of channels of the device. By default the channels and their
276 position are determined by the selected device profile. You can override
277 this setting here.
278
279 :Type: integer
280
281 .. describe:: audio.position
282
283 The position of the channels. By default the number of channels and their
284 position are determined by the selected device profile. You can override
285 this setting here and optionally swap or reconfigure the channel positions.
286
287 :Type: array of strings (example: ``["FL", "FR", "LFE", "FC", "RL", "RR"]``)
288
289 .. describe:: api.alsa.use-chmap
290
291 Use the channel map as reported by the driver. This is disabled by default
292 because it is often wrong and the ACP code handles this better.
293
294 :Type: boolean
295
296 .. describe:: api.alsa.disable-mmap
297
298 Disable the use of mmap for the ALSA device. By default, PipeWire will access
299 the memory of the device using mmap. This can be disabled and force the usage
300 of the slower read and write access modes, in case the mmap support of the
301 device is not working properly.
302
303 :Type: boolean
304
305 .. describe:: channelmix.normalize
306
307 Normalize the channel volumes when mixing & resampling, making sure that the
308 original 0 dB level is preserved so that nothing sounds wildly
309 quieter/louder. This is disabled by default.
310
311 :Type: boolean
312
313 .. describe:: channelmix.mix-lfe
314
315 Creates a "center" channel for X.0 recordings from the front stereo on X.1
316 setups and pushes some low-frequency/bass from the "center" of X.1 recordings
317 into the front stereo on X.0 setups. This is disabled by default.
318
319 :Type: boolean
320
321 .. describe:: monitor.channel-volumes
322
323 By default, the volume of the sink/source does not influence the volume on
324 the monitor ports. Set this option to true to change this. PulseAudio has
325 inconsistent behaviour regarding this option, it applies channel-volumes only
326 when the sink/source is using software volumes.
327
328 :Type: boolean
329
330 .. describe:: node.disabled
331
332 Disables the node. Pipewire will remove it from the list of the nodes.
333
334 :Type: boolean
335
336 ALSA buffer properties
337 ......................
338
339 PipeWire by default uses a timer to consume and produce samples to/from ALSA
340 devices. After every timeout, it queries the hardware pointers of the device and
341 uses this information to set a new timeout. This works well for most devices,
342 but there is a class of devices, so called "batch" devices, that need extra
343 buffering and timing tweaks to work properly. This is because batch devices only
344 get their hardware pointers updated after each hardware interrupt. When the
345 hardware interrupt frequency and the timer frequency are aligned, it is possible
346 for the hardware pointers to be updated just after the timer has expired,
347 resulting in sometimes wrong timing information being returned by the query. In
348 contrast, non-batch devices get pointer updates independent of the interrupt.
349
350 This means that for batch devices we need to set the interrupt at a sufficiently
351 high frequency, at the cost of CPU usage, while for non-batch devices we want to
352 set the interrupt frequency as low as possible to save CPU. For batch devices
353 we also need to take the extra buffering into account caused by the delayed
354 updates of the hardware pointers.
355
356 .. note::
357
358 Most USB devices are batch devices and will be handled as such by PipeWire by
359 default.
360
361 There are 2 tunable parameters to control the buffering and timeouts in a
362 device:
363
364 .. describe:: api.alsa.period-size
365
366 This sets the device interrupt to every period-size samples for non-batch
367 devices and to half of this for batch devices. For batch devices, the other
368 half of the period-size is used as extra buffering to compensate for the
369 delayed update. So, for batch devices, there is an additional period-size/2
370 delay. It makes sense to lower the period-size for batch devices to reduce
371 this delay.
372
373 :Type: integer (samples)
374
375 .. describe:: api.alsa.headroom
376
377 This adds extra delay between the hardware pointers and software pointers.
378 In most cases this can be set to 0. For very bad devices or emulated devices
379 (like in a VM) it might be necessary to increase the headroom value.
380
381 :Type: integer (samples)
382
383 .. describe:: api.alsa.period-num
384
385 This configures the number of periods in the hardware buffer, which controls
386 its size. Note that this is multiplied by the period of the device to
387 determine the size, so for batch devices, the total buffer size is
388 effectively period-num * period-size/2.
389
390 :Type: integer
391
392 In summary, this is the overview of buffering and timings:
393
394 ============== ============================================ ==========================================
395 Property Batch Non-Batch
396 ============== ============================================ ==========================================
397 IRQ Frequency api.alsa.period-size/2 api.alsa.period-size
398 Extra Delay api.alsa.headroom + api.alsa.period-size/2 api.alsa.headroom
399 Buffer Size api.alsa.period-num * api.alsa.period-size/2 api.alsa.period-num * api.alsa.period-size
400 ============== ============================================ ==========================================
401
402 Finally, it is possible to disable the batch device tweaks with:
403
404 .. describe:: api.alsa.disable-batch
405
406 This disables the batch device tweaks. It removes the extra delay added of
407 period-size/2 if the device can support this. For batch devices it is also a
408 good idea to lower the period-size (and increase the IRQ frequency) to get
409 smaller batch updates and lower latency.
410
411 :Type: boolean
412
413 ALSA extra latency properties
414 .............................
415
416 Extra internal delay in the DAC and ADC converters of the device itself can be
417 set with the ``latency.internal.*`` properties:
418
419 .. code-block::
420
421 latency.internal.rate = 256
422 latency.internal.ns = 0
423
424 You can configure a latency in samples (relative to rate with
425 ``latency.internal.rate``) or in nanoseconds (``latency.internal.ns``).
426 This value will be added to the total reported latency by the node of the device.
427
428 You can use a tool like ``jack_iodelay`` to get the number of samples of
429 internal latency of your device.
430
431 This property is also adjustable at runtime with the ``ProcessLatency`` param.
432 You will need to find the id of the Node you want to change. For example:
433 Query the current internal latency of an ALSA node with id 58:
434
435 .. code-block:: console
436
437 $ pw-cli e 58 ProcessLatency
438 Object: size 80, type Spa:Pod:Object:Param:ProcessLatency (262156), id Spa:Enum:ParamId:ProcessLatency (16)
439 Prop: key Spa:Pod:Object:Param:ProcessLatency:quantum (1), flags 00000000
440 Float 0.000000
441 Prop: key Spa:Pod:Object:Param:ProcessLatency:rate (2), flags 00000000
442 Int 0
443 Prop: key Spa:Pod:Object:Param:ProcessLatency:ns (3), flags 00000000
444 Long 0
445
446 Set the internal latency to 256 samples:
447
448 .. code-block:: console
449
450 $ pw-cli s 58 ProcessLatency '{ rate = 256 }'
451 Object: size 32, type Spa:Pod:Object:Param:ProcessLatency (262156), id Spa:Enum:ParamId:ProcessLatency (16)
452 Prop: key Spa:Pod:Object:Param:ProcessLatency:rate (2), flags 00000000
453 Int 256
454 remote 0 node 58 changed
455 remote 0 port 70 changed
456 remote 0 port 72 changed
457 remote 0 port 74 changed
458 remote 0 port 76 changed
459
460 Startup tweaks
461 ..............
462
463 .. describe:: api.alsa.start-delay
464
465 Some devices need some time before they can report accurate hardware pointer
466 positions. In those cases, an extra start delay can be added to compensate
467 for this startup delay. This sets the startup delay in samples. The default
468 is 0.
469
470 :Type: integer (samples)
471
472 IEC958 (S/PDIF) passthrough
473 ...........................
474
475 .. describe:: iec958.codecs
476
477 S/PDIF passthrough will only be enabled when the accepted codecs are configured
478 on the ALSA device. This can be done by setting the list of supported codecs
479 on this property.
480
481 Note that it is possible to also configure this property at runtime, either
482 with tools like pavucontrol or with the ``pw-cli`` tool, like this:
483 ``pw-cli s <node-id> Props '{ iec958Codecs : [ PCM ] }'``
484
485 :Type: array of strings (example: ``[ "PCM", "DTS", "AC3", "EAC3", "TrueHD", "DTS-HD" ]``)