Pipewire migration guide

pipewire.md

Why

Because the Pipewire config semantics don't really match the NixOS module semantics, so it's extremely awkward to override the default config, especially when lists are involved. Also, upstream added a lot of accomodations to allow doing most of the things you'd want to do with a config edit in better ways.

Migrating your configuration

Compare your settings to the defaults. Note what your configuration changes.

Now, create a drop-in JSON file in /etc/pipewire/pipewire.conf.d/99-custom.conf (feel free to choose the filename) and migrate your changes to it according to the following sections.

Repeat for every file you've modified, changing the directory accordingly.

Things you can just copy over

If you are:

• setting properties via *.properties
• loading a new module to context.modules
• creating new objects with context.objects
• declaring SPA libraries with context.spa-libs
• running custom commands with context.exec
• adding new rules with *.rules
• running custom PulseAudio commands with pulse.cmd

Simply move the definitions into the drop-in.

Note that the use of context.exec is not recommended and other methods of running your thing are likely a better option.

{
  "context.properties": {
    "your.property.name": "your.property.value"
  },
  "context.modules": [
    { "name": "libpipewire-module-my-cool-thing" }
  ],
  "context.objects": [
    { "factory": { ... } }
  ],
  "alsa.rules": [
    { "matches: { ... }, "actions": { ... } }
  ]
}

Removing a module from context.modules

Look for an option to disable it via context.properties ("module.x11.bell": "false" is likely the most common use case here). If one is not available, proceed to Nuclear option.

Modifying a module's parameters in context.modules

For most modules (e.g. libpipewire-module-rt) it's enough to load the module again with the new arguments, e.g.:

{
  "context.modules": [
    {
      "name": "libpipewire-module-rt",
      "args": {
        "rt.prio": 90
      }
    }
  ]
}

Note that module-rt specifically will generally use the highest values available by default, so setting limits on the pipewire systemd service is preferable to reloading.

If reloading the module is not an option, proceed to Nuclear option.

Nuclear option

If all else fails, you can still manually copy the contents of the default configuration file from ${pkgs.pipewire.lib}/share/pipewire to /etc/pipewire and edit it to fully override the default. However, this should be done only as a last resort. Please talk to the Pipewire maintainers if you ever need to do this.