pipewire-client.conf(5)

📦

version 1.6.8 · 13 versions

1.6.8 · alpine 3.24, ubuntu stonking (latest)
1.4.6 · opensuse-leap 16.0
1.6.6 · nixos 26.05
1.4.11 · centos-stream 9
1.6.9 · nixpkgs unstable
1.6.11 · fedora 44
1.4.7 · ubuntu questing
1.4.11 · fedora 43
1.4.8 · fedora 43
1.6.9 · centos-stream 10, fedora 44
1.0.5 · ubuntu noble
1.6.2 · fedora 44, ubuntu resolute
1.4.2 · debian trixie

💖 pipewire-client.conf(5) — your client.conf bestie guide 💖

okay so real talk, this is the manual for <pink>pipewire-client.conf(5)</pink>, aka the client.conf file. it's giving "configuration for PipeWire native clients" and honestly? iconic. let me walk you through it fr fr.

✨ NAME ✨

pipewire-client.conf — it's literally client.conf, no cap 🎀

🌸 SYNOPSIS 🌸

the way these paths are laid out, bestie — here's where this file lives:

$XDG_CONFIG_HOME/pipewire/client.conf

/etc/pipewire/client.conf

/usr/share/pipewire/client.conf

/usr/share/pipewire/client.conf.d/

/etc/pipewire/client.conf.d/

$XDG_CONFIG_HOME/pipewire/client.conf.d/

like, pick your fighter 💅

🦋 DESCRIPTION 🦋

so this is the PipeWire client configuration file, periodt.

it's the config for PipeWire native clients and for PipeWire's ALSA plugin. a PipeWire native client program selects the default config to load, and if nothing is specified, it usually loads client.conf. simple as that ✨

the configuration file format and lookup logic is the same as for pipewire.conf(5) — so if you already know that one, you're lowkey set.

drop-in configuration files client.conf.d/*.conf can be used, and are recommended. see pipewire.conf(5) for the deets 🫶

🧚 CONFIGURATION FILE SECTIONS 🧚

here's the section lineup, no skips:

stream.properties — configures options for native client streams. the main character of stream config ngl.
stream.rules — configures rules for native client streams.
alsa.properties — ALSA client configuration. yes queen.
alsa.rules — ALSA client match rules.

in addition, the PipeWire context configuration sections may also be specified — see pipewire.conf(5) for the full tea ☕

💜 STREAM PROPERTIES 💜

the client configuration files contain a stream.properties section that configures the options for client streams. here's the whole vibe:

# ~/.config/pipewire/client.conf.d/custom.conf

stream.properties = {
    #node.latency = 1024/48000
    #node.autoconnect = true
    #resample.disable = false
    #resample.quality = 4
    #resample.window = exp # blackman kaiser
    #resample.cutoff = 0.0
    #resample.n-taps = 0
    #resample.param.exp.A = 0.0
    #resample.param.blackman.alpha = 0.0
    #resample.param.kaiser.alpha = 0.0
    #resample.param.kaiser.stopband-attenuation = 0.0
    #resample.param.kaiser.transition-bandwidth = 0.0
    #monitor.channel-volumes = false
    #channelmix.disable = false
    #channelmix.min-volume = 0.0
    #channelmix.max-volume = 10.0
    #channelmix.normalize = false
    #channelmix.lock-volume = false
    #channelmix.mix-lfe = true
    #channelmix.upmix = true
    #channelmix.upmix-method = psd  # none, simple
    #channelmix.lfe-cutoff = 150.0
    #channelmix.fc-cutoff  = 12000.0
    #channelmix.rear-delay = 12.0
    #channelmix.stereo-widen = 0.0
    #channelmix.hilbert-taps = 0
    #dither.noise = 0
    #dither.method = none # rectangular, triangular, triangular-hf, wannamaker3, shaped5
    #debug.wav-path = ""
}

some of the properties refer to different aspects of the stream, bestie — here's the breakdown:

general stream properties to identify the stream.
general stream properties to classify the stream.
how it is going to be scheduled by the graph.
how it is going to be linked by the session manager.
how the internal processing will be done.
properties to configure the media format.

a list of object properties that can be applied to streams can be found in pipewire-props(7) Common Node Properties and pipewire-props(7) Audio Adapter Properties 🔥

🎀 STREAM RULES 🎀

you can add match rules — see pipewire(1) to set properties for certain streams and filters. yes bestie, we're doing rules now 💅

stream.rules and filter.rules provides an update-props action that takes an object with properties that are updated on the node object of the stream and filter.

add a stream.rules or filter.rules section in the config file like this:

# ~/.config/pipewire/client.conf.d/custom.conf

stream.rules = [
    {
        matches = [
            {
                # all keys must match the value. ! negates. ~ starts regex.
                application.process.binary = "firefox"
            }
        ]
        actions = {
            update-props = {
                node.name = "My Name"
            }
        }
    }
]

will set the node.name of Firefox to "My Name". slay 💀

🌈 ALSA CLIENT PROPERTIES 🌈

an alsa.properties section can be added to configure client applications that connect via the PipeWire ALSA plugin. okay so:

# ~/.config/pipewire/client.conf.d/custom.conf

alsa.properties = {
    #alsa.deny = false
    #alsa.format = 0
    #alsa.rate = 0
    #alsa.channels = 0
    #alsa.period-bytes = 0
    #alsa.buffer-bytes = 0
    #alsa.volume-method = cubic         # linear, cubic
}

and here's what each one does, no cap:

alsa.deny — denies ALSA access for the client. useful in rules or PIPEWIRE_ALSA environment variable. it's giving "you shall not pass" 🙈
alsa.format — the ALSA format to use for the client. this is an ALSA format name. default 0, which is to allow all formats.
alsa.rate — the samplerate to use for the client. the default is 0, which is to allow all rates.
alsa.channels — the number of channels for the client. the default is 0, which is to allow any number of channels.
alsa.period-bytes — the number of bytes per period. the default is 0 which is to allow any number of period bytes.
alsa.buffer-bytes — the number of bytes in the alsa buffer. the default is 0, which is to allow any number of bytes.
alsa.volume-method = cubic | linear — this controls the volume curve used on the ALSA mixer. possible values are cubic and linear. the default is to use cubic.

⭐ ALSA CLIENT RULES ⭐

it is possible to set ALSA client specific properties by using match rules — see pipewire(1). you can set any of the above ALSA properties or any of the stream.properties. icon behavior honestly ✨

🍓 Example 🍓

# ~/.config/pipewire/client.conf.d/custom.conf

alsa.rules = [
    {   matches = [ { application.process.binary = "resolve" } ]
        actions = {
            update-props = {
                alsa.buffer-bytes = 131072
            }
        }
    }
]

💅 ENVIRONMENT VARIABLES 💅

see pipewire(1) for common environment variables. many of these also apply to client applications. the environment variables also influence ALSA applications that are using PipeWire's ALSA plugin — so yes, they matter bestie 🫶

PIPEWIRE_ALSA — this can be an object with properties from alsa.properties or stream.properties that will be used to construct the client and streams.

for example:

PIPEWIRE_ALSA='{ alsa.buffer-bytes=16384 node.name=foo }' aplay ...

starts aplay with custom properties. cute.

PIPEWIRE_NODE — instructs the ALSA client to link to a particular sink or source object.serial or node.name.