pipewire-client.conf(5) | File Formats Manual | pipewire-client.conf(5) |
NAME¶
pipewire-client.conf - client.conf
DESCRIPTION¶
The PipeWire client configuration file.
SYNOPSIS¶
$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/
$XDG_CONFIG_HOME/pipewire/client-rt.conf
/etc/pipewire/client-rt.conf
/usr/share/pipewire/client-rt.conf
/usr/share/pipewire/client-rt.conf.d/
/etc/pipewire/client-rt.conf.d/
$XDG_CONFIG_HOME/pipewire/client-rt.conf.d/
DESCRIPTION¶
Configuration 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.
The ALSA plugin uses the client-rt.conf file, as do some PipeWire native clients such as pw-cat(1).
The configuration file format and lookup logic is the same as for pipewire.conf(5).
Drop-in configuration files client.conf.d/*.conf can be used, and are recommended. See pipewire.conf(5).
CONFIGURATION FILE SECTIONS¶
stream.properties
stream.rules
alsa.properties
alsa.rules
In addition, the PipeWire context configuration sections may also be specified, see pipewire.conf(5).
STREAM PROPERTIES¶
The client configuration files contain a stream.properties section that configures the options for client streams:
stream.properties = {
#node.latency = 1024/48000
#node.autoconnect = true
#resample.disable = false
#resample.quality = 4
#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:
- 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.
Identifying Properties¶
These contain properties to identify the node or to display the node in a GUI application.
node.name
node.description
media.name
media.title
media.artist
media.copyright
media.software
media.language
media.filename
media.icon
media.icon-name
media.comment
media.date
media.format
object.linger = false
Classifying Properties¶
The classifying properties of a node are use for routing the signal to its destination and for configuring the settings.
media.type
media.category
- Playback: media playback.
- Capture: media capture.
- Duplex: media capture and playback or media processing in general.
- Monitor: a media monitor application. Does not actively change media data but monitors activity.
- Manager: Will manage the media graph.
media.role
- Movie: Movie playback with audio and video.
- Music: Music listening.
- Camera: Recording video from a camera.
- Screen: Recording or sharing the desktop screen.
- Communication: VOIP or other video chat application.
- Game: Game.
- Notification: System notification sounds.
- DSP: Audio or Video filters and effect processing.
- Production: Professional audio processing and production.
- Accessibility: Audio and Visual aid for accessibility.
- Test: Test program.
media.class
- Video/Source: a producer of video, like a webcam.
- Video/Sink: a consumer of video, like a display window.
- Audio/Source: a source of audio samples like a microphone.
- Audio/Sink: a sink for audio samples, like an audio card.
- Audio/Duplex: a node that is both a sink and a source.
- Stream/Output/Audio: a playback stream.
- Stream/Input/Audio: a capture stream.
The session manager assigns special meaning to the nodes based on the media.class. Sink or Source classes are used as targets for Stream classes, etc..
Scheduling Properties¶
node.latency = 1024/48000
node.lock-quantum = false
JACK clients use this property to avoid unexpected quantum changes.
node.force-quantum = INTEGER
A value of 0 unforces the quantum.
node.rate = RATE
node.lock-rate = false
node.force-rate = RATE
A RATE of 0 means to force the rate in node.rate denominator.
node.always-process = false
This is the default for JACK nodes, that always need their process callback called.
node.want-driver = true
node.pause-on-idle = false
node.suspend-on-idle = false
When the session manager does not suspend nodes (or when there is no session manager), the node.suspend-on-idle property can be used instead.
node.loop.name = null
node.loop.class = data.rt
Other well known names are main-loop.0 and the main node.loop.class which runs the node data processing in the main loop.
Session Manager Properties¶
node.autoconnect = true
node.exclusive = false
node.target = <node.name|object.id>
target.object = <node.name|object.serial>
node.dont-reconnect = false
Note that if a stream should appear/disappear in sync with the target, a session manager (WirePlumber) script should be written instead.
node.passive = false
This is used for filter nodes that sit in front of sinks/sources and need to suspend together with the sink/source.
node.link-group = ID
stream.dont-remix = false
Audio Adapter Parameters¶
An audio stream (and also audio device nodes) contain an audio adapter that can perform, sample format, sample rate and channel mixing operations.
Merger Parameters¶
The merger is used as the input for a sink device node or a capture stream. It takes the various channels and merges them into a single stream for further processing.
The merger will also provide the monitor ports of the input channels and can apply a software volume on the monitor signal.
monitor.channel-volumes = false
Resampler Parameters¶
Source, sinks, capture and playback streams contain a high quality adaptive resampler. It uses sinc based resampling with linear interpolation of filter banks to perform arbitrary resample factors. The resampler is activated in the following cases:
- The hardware of a device node does not support the graph samplerate. Resampling will occur from the graph samplerate to the hardware samplerate.
- The hardware clock of a device does not run at the same speed as the graph clock and adaptive resampling is required to match the clocks.
- A stream does not have the same samplerate as the graph and needs to be resampled.
- An application wants to activate adaptive resampling in a stream to make it match some other clock.
PipeWire performs most of the sample conversions and resampling in the client (Or in the case of the PulseAudio server, in the pipewire-pulse server that creates the streams). This ensures all the conversions are offloaded to the clients and the server can deal with one single format for performance reasons.
Below is an explanation of the options that can be tuned in the sample converter.
resample.quality = 4
Increasing the quality will result in better cutoff and less aliasing at the expense of (much) more CPU consumption. The default quality of 4 has been selected as a good compromise between quality and performance with no artifacts that are well below the audible range.
See Infinite Wave for a comparison of the performance.
resample.disable = false
Channel Mixer Parameters¶
Source, sinks, capture and playback streams can apply channel mixing on the incoming signal.
Normally the channel mixer is not used for devices, the device channels are usually exposed as they are. This policy is usually enforced by the session manager, so we refer to its documentation there.
Playback and capture streams are usually configured to the channel layout of the sink/source they connect to and will thus perform channel mixing.
The channel mixer also implements a software volume. This volume adjustment is performed on the original channel layout. ex: A stereo playback stream that is up-mixed to 5.1 has 2 a left an right volume control.
channelmix.disable = false
channelmix.min-volume = 0.0
channelmix.max-volume = 10.0
channelmix.normalize = false
While this options prevents clipping, it can in some cases produce too low volume. Increase the volume in that case or disable normalization.
channelmix.lock-volumes = false
channelmix.mix-lfe = true
channelmix.upmix = true
Also enabled up-mixing of LFE when channelmix.lfe-cutoff is set to something else than 0 and the target has an LFE channel. The LFE channel is produced by adding the stereo channels.
If channelmix.upmix is true, the up-mixing of the rear channels is also enabled and controlled with the channelmix-upmix-method property.
channelmix.upmix-method = psd
- 1.
- none. No rear channels are produced.
- 2.
- simple. Front channels are copied to the rear. This is fast but can produce phasing effects.
- 3.
- psd. The rear channels as produced from the front left and right ambient sound (the difference between the channels). A delay and optional phase shift are added to the rear signal to make the sound bigger.
channelmix.lfe-cutoff = 150
channelmix.fc-cutoff = 12000
Since the front center contains the dialogs, a typical cutoff frequency is 12000 Hz.
This option is only active when the up-mix is enabled.
channelmix.rear-delay = 12.0
This is only active when the psd up-mix method is used.
channelmix.stereo-widen = 0.0
This is only active when up-mix is enabled and a Front Center channel is mixed.
channelmix.hilbert-taps = 0
This is only active when the psd up-mix method is used.
dither.noise = 0
This can be used to keep some amplifiers alive during silent periods. One or two bits of noise is usually enough, otherwise the noise will become audible. This is usually used together with session.suspend-timeout-seconds to disable suspend in the session manager.
Note that PipeWire uses floating point operations with 24 bits precission for all of the audio processing. Conversion to 24 bits integer sample formats is lossless and conversion to 32 bits integer sample formats are simply padded with 0 bits at the end. This means that the dither noise is always only in the 24 most significant bits.
dither.method = none
There are 6 modes available:
- 1.
- none No dithering is done.
- 2.
- rectangular Dithering with a rectangular noise distribution. This adds random bits in the [-0.5, 0.5] range to the signal with even distribution.
- 3.
- triangular Dithering with a triangular noise distribution. This add random bits in the [-1.0, 1.0] range to the signal with triangular distribution around 0.0.
- 4.
- triangular-hf Dithering with a sloped triangular noise distribution.
- 5.
- wannamaker3 Additional noise shaping is performed on the sloped triangular dithering to move the noise to the more inaudible range. This is using the 'F-Weighted' noise filter described by Wannamaker.
- 6.
- shaped5 Additional noise shaping is performed on the triangular dithering to move the noise to the more inaudible range. This is using the Lipshitz filter.
Dithering is only useful for conversion to a format with less than 24 bits and will be disabled otherwise.
Debug Parameters¶
debug.wav-path = ''
Format Properties¶
Streams and also most device nodes can be configured in a certain format with properties.
audio.rate = RATE
audio.channels = INTEGER
audio.format = FORMAT
Valid formats include: S16, S32, F32, F64, S16LE, S16BE, ...
audio.allowed-rates
STREAM RULES¶
You can add match rules, see pipewire(1) to set properties for certain streams and filters.
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:
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'.
ALSA PROPERTIES¶
An alsa.properties section can be added to configure ALSA specific client config.
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 }
alsa.deny
alsa.format
alsa.rate
alsa.channels
alsa.period-bytes
alsa.buffer-bytes
alsa.volume-method = cubic | linear
ALSA 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.
Example¶
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.
PIPEWIRE_ALSA
For example:
PIPEWIRE_ALSA='{ alsa.buffer-bytes=16384 node.name=foo }' aplay ...
Starts aplay with custom properties.
PIPEWIRE_NODE
For example:
PIPEWIRE_NODE=alsa_output.pci-0000_00_1b.0.analog-stereo aplay ...
Makes aplay play on the give audio sink.
AUTHORS¶
The PipeWire Developers <https://gitlab.freedesktop.org/pipewire/pipewire/issues>; PipeWire is available from <https://pipewire.org>
SEE ALSO¶
libpipewire-module-protocol-pulse(7), pipewire.conf(5), pipewire-pulse(1), pipewire-pulse-modules(7)
1.2.5 | PipeWire |