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.

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

context.spa-libs

context.modules

context.objects

context.exec

node.rules

device.rules

CONTEXT PROPERTIES¶

Available PipeWire properties in context.properties and possible default values.

clock.power-of-two-quantum = true

context.data-loop.library.name.system

loop.rt-prio = -1

loop.class = [ data.rt .. ]

context.num-data-loops = 1

context.data-loops = [ ... ]

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 ]


    }


    ...
]

core.daemon = false

core.name = pipewire-0

cpu.zero.denormals = false

cpu.vm.name = null

default.clock.rate = 48000

default.clock.allowed-rates = [ ]

default.clock.min-quantum = 32

default.clock.max-quantum = 8192

default.clock.quantum = 1024

default.clock.quantum-limit = 8192

default.clock.quantum-floor = 4

default.video.width

default.video.height

default.video.rate.num

default.video.rate.denom

library.name.system = support/libspa-support

link.max-buffers = 64

log.level = 2

mem.allow-mlock = true

mem.warn-mlock = false

mem.mlock-all = false

settings.check-quantum = false

settings.check-rate = false

support.dbus = true

vm.overrides = { default.clock.min-quantum = 1024 }

context.modules.allow-empty = false

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.

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

context.modules = [


    #{ name = MODULENAME


    #    ( args  = { KEY = VALUE ... } )


    #    ( flags = [ ( ifexists ) ( nofail ) ] )


    #    ( condition = [ { KEY = VALUE ... } ... ] )


    #}


    #
]

name

args = { }

flags = [ ]

condition = [ ]

CONTEXT OBJECTS¶

The context.objects section allows you to make some objects from factories (usually created by loading modules in context.modules).

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

args = { }

flags = [ ]

condition = [ ]

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.

context.exec = [


    #{   path = <program-name>


    #    ( args = "<arguments>" | [ <arg1> <arg2> ... ] )


    #    ( condition = [ { <key> = <value> ... } ... ] )


    #}
]

path

args

condition

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:

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:

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:

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)