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 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.