General

One of the design goals of PipeWire is to be able to closely control and configure all aspects of the processing graph. If a configuration option is not yet available, it's a bug that should be fixed.

A large part of the initial configuration of the devices is performed by the session manager. It typically loads the alsa devices and configures the profiles, port volumes and more.

Clients that join the graph are first configured and then connected to other target nodes as defined by the policy in the session manager. Depending on the client API used, some extra configuration is possible as well.

Common Configuration

PipeWire ArchWiki

PipeWire Gentoo Wiki

PipeWire daemon configuration is performed with /etc/pipewire/pipewire.conf, which can also be placed in ~/.config/pipewire-media-session. It has some basic configuration for the graph scheduling settings and what modules to load by default. It will also launch the session manager.

The session manager has no configuration options except for enabling/disabling modules. All other variables are set in alsa-monitor.conf, bluez-monitor.conf and media-session.conf in the /etc/pipewire/media-session.d directory. Run pipewire-media-session -h for some of the options.

The clients can be configured with either client specific options and in some cases with environment variables for some aspects. See below for more info.

Set Global Sample Rate

PipeWire currently has one global sample rate used in the processing pipeline. All signals are converted to this sample rate and then converted to the sample rate of the device.

You can change the sample rate in /etc/pipewire/pipewire.conf. Find, uncomment and change this line:

set-prop default.clock.rate            48000

In later versions, alternative sample rates will be made available with automatic switching depending on client demands.

Set Resample Quality

Resampling is performed in 2 places in PipeWire.

• To convert the client sample rate to the DSP sample rate of the graph (See previous topic). This will do nothing when the client has the same sample rate as the graph.
• To convert the DSP sample rate to a supported device sample rate. This does nothing when the device supports the same sample rate of the DSP graph.

PipeWire uses a custom highly optimized and reasonably accurate resampler. See Infinite Wave for a comparison. Changing the quality uses more CPU power with (arguably) little measurable advantages.

It is not possible to configure the resampler quality of the devices at this moment. The plan is to make this available with a node property and as an option when initializing a device.

Programmers can set the resampler quality of a stream by setting the resample.quality property. pw-cat has a -q option for this. It's not possible to configure this option yet for all streams. The plan is to use an environment variable to override the options.

Setting Buffer Size

PipeWire will automatically select the lowest requested buffer size for the graph. The minimum of the requested buffer size is used. Limits can be configured in /etc/pipewire/pipewire.conf with the lines:

set-prop default.clock.min-quantum     32
set-prop default.clock.max-quantum     8192

By setting these min and max values to the same value, you can force a buffer size. It is not possible yet to configure these ranges at runtime.

If no client specifies a latency, a default is used:

set-prop default.clock.quantum         1024

Applications can specify a desired buffer size with the node.latency property.

Some applications (Ardour, guitarix, etc) have an option to change the buffer size with a menu option.

The PIPEWIRE_LATENCY environment variable can be used to configure the latency of an application:

PIPEWIRE_LATENCY=256/48000 jack_simple_client

Will run this JACK client with a 256 samples buffer size.

PipeWire Media Session

As of commit configuration variables for pipewire-media-session are now in alsa-monitor.conf, bluez-monitor.conf and media-session.conf in /etc/pipewire/media-session.d/. These files should also be able to be moved to ~/.config/pipewire-media-session/ if you would like.

api.alsa.use-acp

With alsa-pcm you basically get raw alsa with no management of the jack or hw mixer. This is not exactly the setup we ultimately target but it might do less unexpected things.

api.alsa.use.ucm

It's the default to try to use UCM first and then fall back to the profile-sets.

api.alsa.soft-mixer

Alsa soft mixer is a property that matches all devices and disables the hardware mixer and falls back to software volume/mute.

api.alsa.ignore-dB

Description coming soon

api.acp.auto-port
api.acp.auto-profile

Enable or disable the automatic port and profile switching in the acp device.

node.pause-on-idle

Pause the node when idle. When no active node is connected to the device node, the device node timer is paused and snd_pcm_drop() and snd_pcm_pause() is called on the device.

suspend-node

Suspend inactive nodes. After 5 seconds of being idle, the device is closed. Found in media-session.conf.

resample.quality

Default 4 set between 1-9.

channelmix.normalize

Makes sure that during such mixing & resampling original 0 dB level is preserved, so nothing sounds wildly quieter / louder.

channelmix.mix-lfe

Creates "center" channel for X.0 recordings from front stereo on X.1 setups and pushes some low-frequency/bass from "center" from X.1 recordings into front stereo on X.0 setups.

api.alsa.period-size

By default we disable hardware interrupts in the alsa devices because we use the reported read/write pointers in the device ringbuffer and timers to estimate when data needs to be processed. For some type of devices (batch) the read/write pointers are only updated every period. Increasing the period frequency (= reducing the size) gives more accurate estimations. For other types of devices (USB) the period size determines how much buffering is done in the kernel driver (number of packs per URB). We set the default period to 1024, which looks good and is maybe also a good compromise between latency and CPU usage. You can tweak these values if you want. You can use a latency tester (like jack_iodelay) to test the effect of period size. Taken from comment.

api.alsa.headroom

To increase the distance (and latency) between the application and hardware pointers.

api.alsa.disable-mmap

Description coming soon

PIPEWIRE_LATENCY=768/48000
PULSE_LATENCY_MSEC=16

These options change the PipeWire and PulseAudio application latency and can be set in /etc/environment, or ~/.bashrc depending on distribution. In the example both are set to 16 msec.

May also want to check the comments in this thread for a configuration beyond the defaults.

Bluetooth

Bluez should now be enabled by default in the media-session.conf file if you have need of the following options you just have to uncomment them in /etc/pipewire/media-session.d/bluez-monitor.conf.

#bluez5.msbc-support = true
#bluez5.sbc-xq-support = true

JACK

At this time there are still package dependency issues with JACK the packages you need are pipewire-jack-audio-connection-kit and pipewire-libjack you also need to to create a file /etc/ld.so.conf.d/pipewire-jack-x86_64.conf containing:

/usr/lib64/pipewire-0.3/jack/

Then sudo ldconfig. This configuration issue should be fixed in later versions but as of 0.3.18 it is still an issue.

Filters and Effects

For now it is recommended to use a script to configure extra sink/sources and effect chains. There are also many JACK tools to load and save custom graphs.

In the future we plan to add a session manager module to set up these processing chains more easily.

You need to create a node with a media.class property set to Audio/Sink, Audio/Source or Audio/Duplex in order to make it visible to PulseAudio applications as a sink, source or sink/source respectively. You can't in general route PulseAudio streams directly to (JACK) effect nodes.

We recommend to use the JACK effects, like calfjackhost, jalv, carla, etc.

After creating a node to connect the PulseAudio streams to, you can set up and link the filters to a device. We currently recommend to use jack_connect for this. If you set the PIPEWIRE_LINK_PASSIVE=1 environment variable between the effects and the sinks, all nodes will be able to suspend when the device goes idle.

Calfjackhost Example

PIPEWIRE_PROPS="media.class=Audio/Sink" calfjackhost

This makes a sink of the calf rack, you can insert effects, set the sink as the default device with PulseAudio and use pavucontrol to send streams to it.

Create a Sink

Create a new node that can be selected as sink in PulseAudio applications:

pactl load-module module-null-sink object.linger=1 media.class=Audio/Sink sink_name=my-sink channel_map=surround-51

Create a Source

Create a new node that can be selected as source in PulseAudio applications:

pactl load-module module-null-sink object.linger=1 media.class=Audio/Source sink_name=my-source channel_map=front-left,front-right

Create a Duplex Node

Create a new node that can be selected as source and sink in PulseAudio applications:

pactl load-module module-null-sink object.linger=1 media.class=Audio/Duplex sink_name=my-tunnel audio.position=FL,FR,RL,RR

You can use this to send data from one pulseaudio application to another directly.

Create a Combined Sink/Source

This is how you can make a sink/source that sends the output to multiple sinks/sources.

Create a new sink with:

pactl load-module module-null-sink object.linger=1 media.class=Audio/Sink sink_name=my-combined-sink channel_map=stereo

Link the output ports (with qjackctl or jack_connect to the sinks/sources). We hope to make it easier to link to the sink/sources in the future.

Create an Aggregate Sink/Source

Here is how you can make a big multichannel audio device from multiple stereo devices.

Create a new sink with:

pactl load-module module-null-sink object.linger=1 media.class=Audio/Sink sink_name=my-combined-sink channel_map=surround-51

Link the output ports (with qjackctl or jack_connect) to the sinks/sources. We hope to make it easier to link to the sink/sources in the future.

Multichannel Cards

When your card has multiple mono channels that you want to use separately, like when you have a microphone plugged in one input and a guitar in the other, you can make a mono source like so:

pactl load-module module-null-sink object.linger=1 media.class=Audio/Source sink_name=my-mic channel_map=mono

Then link the input port of the source to the microphone port. You can then select my-mic in applications as a source.

Network transport

PulseAudio

You can start a new pipewire-pulse server that listens on TCP connections like this:

pipewire-pulse -a tcp:4713

You can then use

PULSE_SERVER=tcp:<ip>:4713 pactl info

to connect to it. Fill with the ip address of the host running the server.

There is not yet support for automatically making new network sink/source when a new notwork enabled server appears on the network.

JACK

Use zita-njbridge to link multiple JACK/pipewire instances in a network.