pipewire.conf(5) File Formats Manual pipewire.conf(5)
NAME
pipewire.conf - pipewire.conf
DESCRIPTION
The PipeWire server configuration file
SYNOPSIS
$XDG_CONFIG_HOME/pipewire/pipewire.conf
/etc/pipewire/pipewire.conf
/usr/share/pipewire/pipewire.conf
/usr/share/pipewire/pipewire.conf.d/
/etc/pipewire/pipewire.conf.d/
$XDG_CONFIG_HOME/pipewire/pipewire.conf.d/
DESCRIPTION
PipeWire is a service that facilitates sharing of multimedia content
between devices and applications.
On startup, the daemon reads a main configuration file to configure
itself. It executes a series of commands listed in the config file.
The config file is looked up in the order listed in the SYNOPSIS. The
environment variables PIPEWIRE_CONFIG_DIR, PIPEWIRE_CONFIG_PREFIX and
PIPEWIRE_CONFIG_NAME can be used to specify an alternative config
directory, subdirectory and file respectively.
Other PipeWire configuration files generally follow the same lookup
logic, replacing pipewire.conf with the name of the particular config
file.
DROP-IN CONFIGURATION FILES
All *.conf files in the pipewire.conf.d/ directories are loaded and
merged into the configuration. Dictionary sections are merged,
overriding properties if they already existed, and array sections are
appended to. The drop-in files have same format as the main
configuration file, but only contain the settings to be modified.
As the pipewire.conf configuration file contains various parts that must
be present for correct functioning, using drop-in files for
configuration is recommended.
Example
A configuration file ~/.config/pipewire/pipewire.conf.d/custom.conf to
change the value of the default.clock.min-quantum setting in
pipewire.conf:
# ~/.config/pipewire/pipewire.conf.d/custom.conf
context.properties = {
default.clock.min-quantum = 128
}
CONFIGURATION FILE FORMAT
The configuration file is in 'SPA' JSON format.
The configuration file contains top-level keys, which are the sections.
The value of a section is either a dictionary, { }, or an array, [ ].
Section and dictionary item declarations have KEY = VALUE form, and are
separated by whitespace. For example:
context.properties = { # top-level dictionary section
key1 = value # a simple value
key2 = { key1 = value1 key2 = value2 } # a dictionary with two entries
key3 = [ value1 value2 ] # an array with two entries
key4 = [ { k = v1 } { k = v2 } ] # an array of dictionaries
}
context.modules = [ # top-level array section
value1
value2
]
The configuration files can also be written in standard JSON syntax, but
for easier manual editing, the relaxed 'SPA' variant is allowed. In
'SPA' JSON:
• : to delimit keys and values can be substituted by = or a space.
• " around keys and string can be omitted as long as no special
characters are used in the strings.
• , to separate objects can be replaced with a whitespace character.
• # can be used to start a comment until the line end
CONFIGURATION FILE SECTIONS
context.properties
Dictionary. These properties configure the PipeWire instance.
context.spa-libs
Dictionary. Maps plugin features with globs to a spa library.
context.modules
Array of dictionaries. Each entry in the array is a dictionary with
the name of the module to load, including optional args and flags.
Most modules support being loaded multiple times.
context.objects
Array of dictionaries. Each entry in the array is a dictionary
containing the factory to create an object from and optional extra
arguments specific to that factory.
context.exec
Array of dictionaries. Each entry in the array is dictionary
containing the path of a program to execute on startup and optional
args.
This array used to contain an entry to start the session manager but
this mode of operation has since been demoted to development aid.
Avoid starting a session manager in this way in production
environment.
node.rules
Array of dictionaries. Match rules for modifying node properties on
the server.
device.rules
Array of dictionaries. Match rules for modifying device properties
on the server.
CONTEXT PROPERTIES
Available PipeWire properties in context.properties and possible default
values.
clock.power-of-two-quantum = true
The quantum requests from the clients and the final graph quantum
are rounded down to a power of two. A power of two quantum can be
more efficient for many processing tasks.
context.data-loop.library.name.system
The name of the shared library to use for the system functions for
the data processing thread. This can typically be changed if the
data thread is running on a realtime kernel such as EVL.
loop.rt-prio = -1
The priority of the data loops. The data loops are used to schedule
the nodes in the graph. A value of -1 uses the default realtime
priority from the module-rt. A value of 0 disables realtime
scheduling for the data loops.
loop.class = [ data.rt .. ]
An array of classes of the data loops. Normally nodes are assigned
to a loop by name or by class. Nodes are by default assigned to the
data.rt class so it is good to have a data loop of this class as
well.
context.num-data-loops = 1
The number of data loops to create. By default 1 data-loop is
created and all nodes are scheduled in this thread. A value of 0
disables the real-time data loops and schedules all nodes in the
main thread. A value of -1 spawns as many data threads as there are
cpu cores.
context.data-loops = [ ... ]
This controls the data loops that will be created for the context.
Is is an array of data loop specifications, one entry for each data
loop to start:
# ~/.config/pipewire/pipewire.conf.d/custom.conf
context.data-loops = [
{
#library.name.system = support/libspa-support
loop.rt-prio = -1
loop.class = [ data.rt .. ]
thread.name = data-loop.0
thread.affinity = [ 0 1 ]
}
...
]
A specific priority, classes and name can be given with loop.rt-
prio, loop.class and thread.name respectively. It is also possible
to pin the data loop to specific CPU cores with the thread.affinity
property.
core.daemon = false
Makes the PipeWire process, started with this config, a daemon
process. This means that it will manage and schedule a graph for
clients. You would also want to configure a core.name to give it a
well known name.
core.name = pipewire-0
The name of the PipeWire context. This will also be the name of the
PipeWire socket clients can connect to.
cpu.zero.denormals = false
Configures the CPU to zero denormals automatically. This will be
enabled for the data processing thread only, when enabled.
cpu.vm.name = null
This will be set automatically when the context is created and will
contain the name of the VM. It is typically used to write match
rules to set extra properties.
default.clock.rate = 48000
The default clock rate determines the real time duration of the
min/max/default quantums. You might want to change the quantums when
you change the default clock rate to maintain the same duration for
the quantums.
default.clock.allowed-rates = [ ]
It is possible to specify up to 32 alternative sample rates. The
graph sample rate will be switched when devices are idle. Note that
this is not enabled by default for now because of various kernel and
Bluetooth issues. Note that the min/max/default quantum values are
scaled when the samplerate changes.
default.clock.min-quantum = 32
Default minimum quantum.
default.clock.max-quantum = 8192
Default maximum quantum.
default.clock.quantum = 1024
Default quantum used when no client specifies one.
default.clock.quantum-limit = 8192
Maximum quantum to reserve space for. This is the maximum buffer
size used in the graph, regardless of the samplerate.
default.clock.quantum-floor = 4
Minimum quantum to reserve space for. This is the minimum buffer
size used in the graph, regardless of the samplerate.
default.video.width
Default video width
default.video.height
Default video height
default.video.rate.num
Default video rate numerator
default.video.rate.denom
Default video rate denominator
library.name.system = support/libspa-support
The name of the shared library to use for the system functions for
the main thread.
link.max-buffers = 64
The maximum number of buffers to negotiate between nodes. Note that
version < 3 clients can only support 16 buffers. More buffers is
almost always worse than less, latency and memory wise.
log.level = 2
The default log level used by the process.
mem.allow-mlock = true
Try to mlock the memory for the realtime processes. Locked memory
will not be swapped out by the kernel and avoid hickups in the
processing threads.
mem.warn-mlock = false
Warn about failures to lock memory.
mem.mlock-all = false
Try to mlock all current and future memory by the process.
settings.check-quantum = false
Check if the quantum in the settings metadata update is compatible
with the configured limits.
settings.check-rate = false
Check if the rate in the settings metadata update is compatible with
the configured limits.
support.dbus = true
Enable DBus support. This will enable DBus support in the various
modules that require it. Disable this if you want to globally
disable DBus support in the process.
vm.overrides = { default.clock.min-quantum = 1024 }
Any property in the vm.overrides property object will override the
property in the context.properties when PipeWire detects it is
running in a VM. This is deprecated, use the
context.properties.rules instead.
context.modules.allow-empty = false
By default, a warning is logged when there are no context.modules
loaded because this likely indicates there is a problem. Some
applications might load the modules themselves and when they set
this property to true, no warning will be logged.
The context properties may also contain custom values. For example, the
context.modules and context.objects sections can declare additional
conditions that control whether a module or object is loaded depending
on what properties are present.
SPA LIBRARIES
SPA plugins are loaded based on their factory-name. This is a well known
name that uniquely describes the features that the plugin should have.
The context.spa-libs section provides a mapping between the factory-name
and the plugin where the factory can be found.
Factory names can contain a wildcard to group several related factories
into one plugin. The plugin is loaded from the first matching factory-
name.
Example
# ~/.config/pipewire/pipewire.conf.d/custom.conf
context.spa-libs = {
audio.convert.* = audioconvert/libspa-audioconvert
avb.* = avb/libspa-avb
api.alsa.* = alsa/libspa-alsa
api.v4l2.* = v4l2/libspa-v4l2
api.libcamera.* = libcamera/libspa-libcamera
api.bluez5.* = bluez5/libspa-bluez5
api.vulkan.* = vulkan/libspa-vulkan
api.jack.* = jack/libspa-jack
support.* = support/libspa-support
video.convert.* = videoconvert/libspa-videoconvert
}
MODULES
PipeWire modules to be loaded. See libpipewire-modules(7).
# ~/.config/pipewire/pipewire.conf.d/custom.conf
context.modules = [
#{ name = MODULENAME
# ( args = { KEY = VALUE ... } )
# ( flags = [ ( ifexists ) ( nofail ) ] )
# ( condition = [ { KEY = VALUE ... } ... ] )
#}
#
]
name
Name of module to be loaded
args = { }
Arguments passed to the module
flags = [ ]
Loading flags. ifexists to only load module if it exists, and nofail
to not fail PipeWire startup if the module fails to load.
condition = [ ]
A match rule matches condition. The module is loaded only if one of
the expressions in the array matches to a context property.
CONTEXT OBJECTS
The context.objects section allows you to make some objects from
factories (usually created by loading modules in context.modules).
# ~/.config/pipewire/pipewire.conf.d/custom.conf
context.objects = [
#{ factory = <factory-name>
# ( args = { <key> = <value> ... } )
# ( flags = [ ( nofail ) ] )
# ( condition = [ { <key> = <value> ... } ... ] )
#}
]
This section can be used to make nodes or links between nodes.
factory
Name of the factory to create the object.
args = { }
Arguments passed to the factory.
flags = [ ]
Flag nofail to not fail PipeWire startup if the object fails to
load.
condition = [ ]
A match rule matches condition. The object is created only if one of
the expressions in the array matches to a context property.
Example
This fragment creates a new dummy driver node, but only if core.daemon
property is true:
# ~/.config/pipewire/pipewire.conf.d/custom.conf
context.objects = [
{ factory = spa-node-factory
args = {
factory.name = support.node.driver
node.name = Dummy-Driver
node.group = pipewire.dummy
priority.driver = 20000
},
condition = [ { core.daemon = true } ]
}
]
COMMAND EXECUTION
The context.exec section can be used to start arbitrary commands as part
of the initialization of the PipeWire program.
# ~/.config/pipewire/pipewire.conf.d/custom.conf
context.exec = [
#{ path = <program-name>
# ( args = "<arguments>" | [ <arg1> <arg2> ... ] )
# ( condition = [ { <key> = <value> ... } ... ] )
#}
]
path
Program to execute.
args
Arguments to the program.
condition
A match rule matches condition. The object is created only if one of
the expressions in the array matches to a context property.
Example
The following fragment executes a pactl command with the given
arguments:
# ~/.config/pipewire/pipewire.conf.d/custom.conf
context.exec = [
{ path = "pactl" args = "load-module module-always-sink" }
]
MATCH RULES
Some configuration file sections contain match rules. This makes it
possible to perform some action when an object (usually a node or
stream) is created/updated that matches certain properties.
The general rules object follows the following pattern:
<rules> = [
{
matches = [
# any of the following sets of properties are matched, if
# any matches, the actions are executed
{
# <key> = <value>
# all keys must match the value. ! negates. ~ starts regex.
#application.process.binary = "teams"
#application.name = "~speech-dispatcher.*"
# Absence of property can be tested by comparing to null
#pipewire.sec.flatpak = null
}
{
# more matches here...
}
...
]
actions = {
<action-name> = <action value>
...
}
}
]
Match rules are an array of rules.
A rule is always a JSON object with two keys: matches and actions. The
matches key is used to define the conditions that need to be met for the
rule to be evaluated as true, and the actions key is used to define the
actions that are performed when the rule is evaluated as true.
The matches key is always a JSON array of objects, where each object
defines a condition that needs to be met. Each condition is a list of
key-value pairs, where the key is the name of the property that is being
matched, and the value is the value that the property needs to have.
Within a condition, all the key-value pairs are combined with a logical
AND, and all the conditions in the matches array are combined with a
logical OR.
The actions key is always a JSON object, where each key-value pair
defines an action that is performed when the rule is evaluated as true.
The action name is specific to the rule and is defined by the rule’s
documentation, but most frequently you will see the update-props action,
which is used to update the properties of the matched object.
In the matches array, it is also possible to use regular expressions to
match property values. For example, to match all nodes with a name that
starts with my_, you can use the following condition:
matches = [
{
node.name = "~my_.*"
}
]
The ~ character signifies that the value is a regular expression. The
exact syntax of the regular expressions is the POSIX extended regex
syntax, as described in the regex (7) man page.
In addition to regular expressions, you may also use the ! character to
negate a condition. For example, to match all nodes with a name that
does not start with my_, you can use the following condition:
matches = [
{
node.name = "!~my_.*"
}
]
The ! character can be used with or without a regular expression. For
example, to match all nodes with a name that is not equal to my_node,
you can use the following condition:
matches = [
{
node.name = "!my_node"
}
]
The null value has a special meaning; it checks if the property is not
available (or unset). To check if a property is not set:
matches = [
{
node.name = null
}
]
To check the existence of a property, one can use the !null condition,
for example:
matches = [
{
node.name = "!null"
}
{
node.name = !null # simplified syntax
}
]
To handle the 'null' string, one needs to escape the string. For
example, to check if a property has the string value 'null', use:
matches = [
{
node.name = "null"
}
]
To handle anything but the 'null' string, use:
matches = [
{
node.name = "!\"null\""
}
{
node.name = !"null" # simplified syntax
}
]
CONTEXT PROPERTIES RULES
context.properties.rules can be used to dynamically update the
properties based on other properties.
A typical case is to update custom settings when running inside a VM.
The cpu.vm.name is automatically set when running in a VM with the name
of the VM. A match rule can be written to set custom properties like
this:
# ~/.config/pipewire/pipewire.conf.d/custom.conf
context.properties.rules = [
{ matches = [ { cpu.vm.name = !null } ]
actions = {
update-props = {
# These overrides are only applied when running in a vm.
default.clock.min-quantum = 1024
}
}
}
}
NODE RULES
The node.rules are evaluated every time the properties on a node are set
or updated. This can be used on the server side to override client set
properties on arbitrary nodes.
node.rules provides an update-props action that takes an object with
properties that are updated on the node object.
Add a node.rules section in the config file like this:
# ~/.config/pipewire/pipewire.conf.d/custom.conf
node.rules = [
{
matches = [
{
# all keys must match the value. ! negates. ~ starts regex.
client.name = "jack_simple_client"
}
]
actions = {
update-props = {
node.force-quantum = 512
}
}
}
]
Will set the node.force-quantum property of jack_simple_client to 512.
DEVICE RULES
The device.rules are evaluated every time the properties on a device are
set or updated. This can be used on the server side to override client
set properties on arbitrary devices.
device.rules provides an update-props action that takes an object with
properties that are updated on the device object.
Add a device.rules section in the config file like this:
# ~/.config/pipewire/pipewire.conf.d/custom.conf
device.rules = [
{
matches = [
{
# all keys must match the value. ! negates. ~ starts regex.
device.name = ""v4l2_device.pci-0000_00_14.0-usb-0_1.2_1.0
}
]
actions = {
update-props = {
device.description = "My Webcam"
}
}
}
]
Will set the device.description property of the device with the given
device.name to 'My Webcam'.
AUTHORS
The PipeWire Developers
<https://gitlab.freedesktop.org/pipewire/pipewire/issues>; PipeWire is
available from <https://pipewire.org>
SEE ALSO
pipewire(1), pw-mon(1), libpipewire-modules(7) pipewire-pulse.conf(5)
pipewire-client.conf(5)
PipeWire 1.4.2 pipewire.conf(5)
Generated by dwww version 1.16 on Sat Oct 3 06:51:01 CEST 2026.