.TH "pipewire.conf" 5 "1.0.5" "PipeWire" \" -*- nroff -*- .ad l .nh .SH NAME pipewire.conf \- pipewire\&.conf .SH DESCRIPTION .PP The PipeWire server configuration file .PP .SH "SYNOPSIS" .PP .PP \fI$XDG_CONFIG_HOME/pipewire/pipewire\&.conf\fP .PP \fI/etc/pipewire/pipewire\&.conf\fP .PP \fI/usr/share/pipewire/pipewire\&.conf\fP .PP \fI/usr/share/pipewire/pipewire\&.conf\&.d/\fP .PP \fI/etc/pipewire/pipewire\&.conf\&.d/\fP .PP \fI$XDG_CONFIG_HOME/pipewire/pipewire\&.conf\&.d/\fP .PP .SH "DESCRIPTION" .PP .PP PipeWire is a service that facilitates sharing of multimedia content between devices and applications\&. .PP On startup, the daemon reads a main configuration file to configure itself\&. It executes a series of commands listed in the config file\&. .PP The config file is looked up in the order listed in the \fBSYNOPSIS\fP\&. The environment variables \fRPIPEWIRE_CONFIG_DIR\fP, \fRPIPEWIRE_CONFIG_PREFIX\fP and \fRPIPEWIRE_CONFIG_NAME\fP can be used to specify an alternative config directory, subdirectory and file respectively\&. .PP Other PipeWire configuration files generally follow the same lookup logic, replacing \fRpipewire\&.conf\fP with the name of the particular config file\&. .SH "DROP-IN CONFIGURATION FILES" .PP All \fR*\&.conf\fP files in the \fRpipewire\&.conf\&.d/\fP 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\&. .PP As the \fRpipewire\&.conf\fP configuration file contains various parts that must be present for correct functioning, using drop-in files for configuration is recommended\&. .PP .SS "Example" .PP A configuration file \fR~/\&.config/pipewire/pipewire\&.conf\&.d/custom\&.conf\fP to change the value of the \fRdefault\&.clock\&.min-quantum\fP setting in \fRpipewire\&.conf\fP: .PP .PP .nf context\&.properties = { default\&.clock\&.min\-quantum = 128 } .fi .PP .SH "CONFIGURATION FILE FORMAT" .PP The configuration file is in 'SPA' JSON format\&. .PP The configuration file contains top-level keys, which are the sections\&. The value of a section is either a dictionary, \fR{ }\fP, or an array, \fR[ ]\fP\&. Section and dictionary item declarations have \fRKEY = VALUE\fP form, and are separated by whitespace\&. For example: .PP .PP .nf 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 ] .fi .PP .PP 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: .PP .IP "\(bu" 2 \fR:\fP to delimit keys and values can be substituted by \fR=\fP or a space\&. .IP "\(bu" 2 \fR"\fP around keys and string can be omitted as long as no special characters are used in the strings\&. .IP "\(bu" 2 \fR,\fP to separate objects can be replaced with a whitespace character\&. .IP "\(bu" 2 \fR#\fP can be used to start a comment until the line end .PP .SH "CONFIGURATION FILE SECTIONS" .PP \fBcontext\&.properties\fP .RS 4 Dictionary\&. These properties configure the PipeWire instance\&. .RE .PP \fBcontext\&.spa-libs\fP .RS 4 Dictionary\&. Maps plugin features with globs to a spa library\&. .RE .PP \fBcontext\&.modules\fP .RS 4 Array of dictionaries\&. Each entry in the array is a dictionary with the \fIname\fP of the module to load, including optional \fIargs\fP and \fIflags\fP\&. Most modules support being loaded multiple times\&. .RE .PP \fBcontext\&.objects\fP .RS 4 Array of dictionaries\&. Each entry in the array is a dictionary containing the \fIfactory\fP to create an object from and optional extra arguments specific to that factory\&. .RE .PP \fBcontext\&.exec\fP .RS 4 Array of dictionaries\&. Each entry in the array is dictionary containing the \fIpath\fP of a program to execute on startup and optional \fIargs\fP\&. .PP 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\&. .RE .PP .PP \fBnode\&.rules\fP .RS 4 Array of dictionaries\&. Match rules for modifying node properties on the server\&. .RE .PP \fBdevice\&.rules\fP .RS 4 Array of dictionaries\&. Match rules for modifying device properties on the server\&. .RE .PP .SH "CONTEXT PROPERTIES" .PP Available PipeWire properties in \fRcontext\&.properties\fP and possible default values\&. .PP \fBclock\&.power-of-two-quantum = true\fP .RS 4 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\&. .RE .PP \fBcontext\&.data-loop\&.library\&.name\&.system \fP .RS 4 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\&. .RE .PP \fBcore\&.daemon = false\fP .RS 4 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\&. .RE .PP \fBcore\&.name = pipewire-0\fP .RS 4 The name of the PipeWire context\&. This will also be the name of the PipeWire socket clients can connect to\&. .RE .PP \fBcpu\&.zero\&.denormals = false\fP .RS 4 Configures the CPU to zero denormals automatically\&. This will be enabled for the data processing thread only, when enabled\&. .RE .PP \fBdefault\&.clock\&.rate = 48000\fP .RS 4 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\&. .RE .PP \fBdefault\&.clock\&.allowed-rates = [ ]\fP .RS 4 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\&. .RE .PP \fBdefault\&.clock\&.min-quantum = 32\fP .RS 4 Default minimum quantum\&. .RE .PP \fBdefault\&.clock\&.max-quantum = 8192\fP .RS 4 Default maximum quantum\&. .RE .PP \fBdefault\&.clock\&.quantum = 1024\fP .RS 4 Default quantum used when no client specifies one\&. .RE .PP \fBdefault\&.clock\&.quantum-limit = 8192\fP .RS 4 Maximum quantum to reserve space for\&. This is the maximum buffer size used in the graph, regardless of the samplerate\&. .RE .PP \fBdefault\&.clock\&.quantum-floor = 4\fP .RS 4 Minimum quantum to reserve space for\&. This is the minimum buffer size used in the graph, regardless of the samplerate\&. .RE .PP \fBdefault\&.video\&.width \fP .RS 4 Default video width .RE .PP \fBdefault\&.video\&.height \fP .RS 4 Default video height .RE .PP \fBdefault\&.video\&.rate\&.num \fP .RS 4 Default video rate numerator .RE .PP \fBdefault\&.video\&.rate\&.denom \fP .RS 4 Default video rate denominator .RE .PP \fBlibrary\&.name\&.system = support/libspa-support\fP .RS 4 The name of the shared library to use for the system functions for the main thread\&. .RE .PP \fBlink\&.max-buffers = 64\fP .RS 4 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\&. .RE .PP \fBlog\&.level = 2\fP .RS 4 The default log level used by the process\&. .RE .PP \fBmem\&.allow-mlock = true\fP .RS 4 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\&. .RE .PP \fBmem\&.warn-mlock = false\fP .RS 4 Warn about failures to lock memory\&. .RE .PP \fBmem\&.mlock-all = false\fP .RS 4 Try to mlock all current and future memory by the process\&. .RE .PP \fBsettings\&.check-quantum = false\fP .RS 4 Check if the quantum in the settings metadata update is compatible with the configured limits\&. .RE .PP \fBsettings\&.check-rate = false\fP .RS 4 Check if the rate in the settings metadata update is compatible with the configured limits\&. .RE .PP \fBsupport\&.dbus = true\fP .RS 4 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\&. .RE .PP \fBvm\&.overrides = { default\&.clock\&.min-quantum = 1024 }\fP .RS 4 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\&. .RE .PP \fBcontext\&.modules\&.allow-empty = false\fP .RS 4 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\&. .RE .PP The context properties may also contain custom values\&. For example, the \fRcontext\&.modules\fP and \fRcontext\&.objects\fP sections can declare additional conditions that control whether a module or object is loaded depending on what properties are present\&. .SH "SPA LIBRARIES" .PP 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 \fRcontext\&.spa-libs\fP section provides a mapping between the factory-name and the plugin where the factory can be found\&. .PP Factory names can contain a wildcard to group several related factories into one plugin\&. The plugin is loaded from the first matching factory-name\&. .PP .SS "Example" .PP .PP .nf 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 } .fi .PP .SH "MODULES" .PP PipeWire modules to be loaded\&. See \fBlibpipewire-modules(7)\fP\&. .PP .PP .nf context\&.modules = [ #{ name = MODULENAME # ( args = { KEY = VALUE \&.\&.\&. } ) # ( flags = [ ( ifexists ) ( nofail ) ] ) # ( condition = [ { KEY = VALUE \&.\&.\&. } \&.\&.\&. ] ) #} # ] .fi .PP .PP \fBname\fP .RS 4 Name of module to be loaded .RE .PP \fBargs = { }\fP .RS 4 Arguments passed to the module .RE .PP \fBflags = [ ]\fP .RS 4 Loading flags\&. \fRifexists\fP to only load module if it exists, and \fRnofail\fP to not fail PipeWire startup if the module fails to load\&. .RE .PP \fBcondition = [ ]\fP .RS 4 A \fBmatch rule\fP \fRmatches\fP condition\&. The module is loaded only if one of the expressions in the array matches to a context property\&. .RE .PP .SH "CONTEXT OBJECTS" .PP The \fRcontext\&.objects\fP section allows you to make some objects from factories (usually created by loading modules in \fRcontext\&.modules\fP)\&. .PP .PP .nf context\&.objects = [ #{ factory = # ( args = { = \&.\&.\&. } ) # ( flags = [ ( nofail ) ] ) # ( condition = [ { = \&.\&.\&. } \&.\&.\&. ] ) #} ] .fi .PP This section can be used to make nodes or links between nodes\&. .PP \fBfactory\fP .RS 4 Name of the factory to create the object\&. .RE .PP \fBargs = { }\fP .RS 4 Arguments passed to the factory\&. .RE .PP \fBflags = [ ]\fP .RS 4 Flag \fRnofail\fP to not fail PipeWire startup if the object fails to load\&. .RE .PP \fBcondition = [ ]\fP .RS 4 A \fBmatch rule\fP \fRmatches\fP condition\&. The object is created only if one of the expressions in the array matches to a context property\&. .RE .PP .SS "Example" .PP This fragment creates a new dummy driver node, but only if \fRcore\&.daemon\fP property is true: .PP .PP .nf 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 } ] } ] .fi .PP .SH "COMMAND EXECUTION" .PP The \fRcontext\&.exec\fP section can be used to start arbitrary commands as part of the initialization of the PipeWire program\&. .PP .PP .nf context\&.exec = [ #{ path = # ( args = "" ) # ( condition = [ { = \&.\&.\&. } \&.\&.\&. ] ) #} ] .fi .PP .PP \fBpath\fP .RS 4 Program to execute\&. .RE .PP \fBargs\fP .RS 4 Arguments to the program\&. .RE .PP \fBcondition\fP .RS 4 A \fBmatch rule\fP \fRmatches\fP condition\&. The object is created only if one of the expressions in the array matches to a context property\&. .RE .PP .SS "Example" .PP The following fragment executes a pactl command with the given arguments: .PP .PP .nf context\&.exec = [ { path = "pactl" args = "load\-module module\-always\-sink" } ] .fi .PP .SH "MATCH RULES" .PP 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\&. .PP The general rules object follows the following pattern: .PP .nf = [ { matches = [ # any of the following sets of properties are matched, if # any matches, the actions are executed { # = # 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 = { = \&.\&.\&. } } ] .fi .PP .PP The rules is an array of things to match and what actions to perform when a match is found\&. .PP The available actions and their values depend on the specific rule that is used\&. Usually it is possible to update some properties or set some quirks on the object\&. .PP .SH "AUTHORS" .PP .PP The PipeWire Developers ; PipeWire is available from .PP .SH "SEE ALSO" .PP .PP \fBpipewire(1)\fP, \fBpw-mon(1)\fP, \fBlibpipewire-modules(7)\fP \fBpipewire-pulse\&.conf(5)\fP \fBpipewire-client\&.conf(5)\fP