| 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" ]``) |