mirror of
https://gitlab.freedesktop.org/pipewire/pipewire.git
synced 2025-11-21 07:00:08 -05:00
doc: add reference docs + index for config and env variables
Add reference documentation for configuration settings & node/device properties. We should have boring & exhaustive reference lists of all the options, and an index where they can be looked up as needed. The content is mostly stolen from the Wiki. Add pipewire-client.conf.5, pipewire-jack.conf.5, and pipewire-device.7 that try to explain all available configuration settings for native/ALSA/JACK clients, and parameters & properties devices. Expand pipewire.conf.5 and pipewire-pulse.conf.5 with lists of supported properties. Also explain environment variables. Doxygen doesn't have an indexing mechanism suitable for configuration settings, so add a simple one using an input filter and use it here. Tweak styling a bit.
This commit is contained in:
Pauli Virtanen
parent
715315cbcd
commit
fd58eec7f8
14 changed files with 2237 additions and 13 deletions
|
|
@ -2,6 +2,8 @@
|
|||
|
||||
The PipeWire server configuration file
|
||||
|
||||
\tableofcontents
|
||||
|
||||
# SYNOPSIS
|
||||
|
||||
*$XDG_CONFIG_HOME/pipewire/pipewire.conf*
|
||||
|
|
@ -37,7 +39,9 @@ order and the contents of the `*.conf` files inside them are appended to
|
|||
the main configuration file as overrides. Object sections are merged and
|
||||
array sections are appended.
|
||||
|
||||
# CONFIGURATION FILE FORMAT
|
||||
# CONFIGURATION FILE FORMAT @IDX@ pipewire.conf
|
||||
|
||||
The configuration file is in (SPA) JSON format.
|
||||
|
||||
The configuration file format is grouped into sections. A section is
|
||||
either a dictionary, {}, or an array, \[\]. Dictionary and array entries
|
||||
|
|
@ -53,7 +57,7 @@ or a dictionary. For example:
|
|||
name = [ { k = v1 } { k = v2 } ] # an array of dictionaries
|
||||
```
|
||||
|
||||
The configuration files can be expressed in full JSON syntax but for
|
||||
The configuration files can be expressed in standard JSON syntax but for
|
||||
ease of use, a relaxed format may be used where:
|
||||
|
||||
- `:` to delimit keys and values can be substuted by `=` or a space.
|
||||
|
|
@ -90,6 +94,284 @@ this mode of operation has since been demoted to development aid. Avoid
|
|||
starting a session manager in this way in production environment.
|
||||
\endparblock
|
||||
|
||||
# CONTEXT PROPERTIES @IDX@ pipewire.conf
|
||||
|
||||
Available PipeWire properties in `context.properties` and possible
|
||||
default values.
|
||||
|
||||
@PAR@ pipewire.conf 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.
|
||||
|
||||
@PAR@ pipewire.conf 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.
|
||||
|
||||
@PAR@ pipewire.conf 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.
|
||||
|
||||
@PAR@ pipewire.conf core.name = pipewire-0
|
||||
The name of the PipeWire context. This will also be the name of the
|
||||
PipeWire socket clients can connect to.
|
||||
|
||||
@PAR@ pipewire.conf cpu.zero.denormals = false
|
||||
Configures the CPU to zero denormals automatically. This will be
|
||||
enabled for the data processing thread only, when enabled.
|
||||
|
||||
@PAR@ pipewire.conf 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.
|
||||
|
||||
@PAR@ pipewire.conf 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.
|
||||
|
||||
@PAR@ pipewire.conf default.clock.min-quantum = 32
|
||||
Default minimum quantum.
|
||||
|
||||
@PAR@ pipewire.conf default.clock.max-quantum = 8192
|
||||
Default maximum quantum.
|
||||
|
||||
@PAR@ pipewire.conf default.clock.quantum = 1024
|
||||
Default quantum used when no client specifies one.
|
||||
|
||||
@PAR@ pipewire.conf default.clock.quantum-limit = 8192
|
||||
Maximum quantum to reserve space for.
|
||||
|
||||
@PAR@ pipewire.conf default.video.width
|
||||
|
||||
@PAR@ pipewire.conf default.video.height
|
||||
|
||||
@PAR@ pipewire.conf default.video.rate.num
|
||||
|
||||
@PAR@ pipewire.conf default.video.rate.denom
|
||||
|
||||
@PAR@ pipewire.conf library.name.system = support/libspa-support
|
||||
The name of the shared library to use for the system functions for the main thread.
|
||||
|
||||
@PAR@ pipewire.conf 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.
|
||||
|
||||
@PAR@ pipewire.conf log.level = 2
|
||||
The default log level used by the process.
|
||||
|
||||
@PAR@ pipewire.conf 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.
|
||||
|
||||
@PAR@ pipewire.conf mem.warn-mlock = false
|
||||
Warn about failures to lock memory.
|
||||
|
||||
@PAR@ pipewire.conf mem.mlock-all = false
|
||||
Try to mlock all current and future memory by the process.
|
||||
|
||||
@PAR@ pipewire.conf settings.check-quantum = false
|
||||
Check if the quantum in the settings metadata update is compatible
|
||||
with the configured limits.
|
||||
|
||||
@PAR@ pipewire.conf settings.check-rate = false
|
||||
Check if the rate in the settings metadata update is compatible
|
||||
with the configured limits.
|
||||
|
||||
@PAR@ pipewire.conf 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.
|
||||
|
||||
@PAR@ pipewire.conf 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.
|
||||
|
||||
\par CONDITION = true / false
|
||||
The `context.modules` and `context.objects` sections can declare
|
||||
additional condition variables, which control whether a specific
|
||||
module or object to be loaded on startup.
|
||||
|
||||
# SPA LIBRARIES @IDX@ pipewire.conf
|
||||
|
||||
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
|
||||
|
||||
```json
|
||||
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 @IDX@ pipewire.conf
|
||||
|
||||
PipeWire modules to be loaded. See
|
||||
\ref page_man_libpipewire-modules_7 "libpipewire-modules(7)".
|
||||
|
||||
```json
|
||||
context.modules = [
|
||||
#{ name = MODULENAME
|
||||
# ( args = { KEY = VALUE ... } )
|
||||
# ( flags = [ ( ifexists ) ( nofail ) ] )
|
||||
# ( condition = [ { KEY = VALUE ... } ... ] )
|
||||
#}
|
||||
#
|
||||
]
|
||||
```
|
||||
|
||||
\par name
|
||||
Name of module to be loaded
|
||||
|
||||
\par args = { KEY = VALUE }
|
||||
Argument to the module
|
||||
|
||||
\par flags = [ ]
|
||||
Loading flags. `ifexists` to only load module if it exists,
|
||||
and `nofail` to not fail PipeWire startup if the module fails to load.
|
||||
|
||||
\par condition = [ { KEY = VALUE }, ... ]
|
||||
Named condition variables, which control whether a module is loaded.
|
||||
|
||||
# CONTEXT OBJECTS @IDX@ pipewire.conf
|
||||
|
||||
The `context.objects` section allows you to make some objects from factories (usually created
|
||||
by loading modules in `context.modules`).
|
||||
|
||||
```json
|
||||
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.
|
||||
|
||||
\par name
|
||||
Name of module to be loaded
|
||||
|
||||
\par args = { KEY = VALUE }
|
||||
Argument to the module
|
||||
|
||||
\par flags = [ ]
|
||||
Loading flags. `ifexists` to only load module if it exists,
|
||||
and `nofail` to not fail PipeWire startup if the module fails to load.
|
||||
|
||||
\par condition = [ { KEY = VALUE }, ... ]
|
||||
Named condition variables, which control whether a module is loaded.
|
||||
|
||||
## Example
|
||||
|
||||
This fragment creates a new dummy driver node:
|
||||
|
||||
```json
|
||||
context.objects = [
|
||||
{ factory = spa-node-factory
|
||||
args = {
|
||||
factory.name = support.node.driver
|
||||
node.name = Dummy-Driver
|
||||
node.group = pipewire.dummy
|
||||
priority.driver = 20000
|
||||
}
|
||||
}
|
||||
]
|
||||
```
|
||||
|
||||
# COMMAND EXECUTION @IDX@ pipewire.conf
|
||||
|
||||
The `context.exec` section can be used to start arbitrary commands as
|
||||
part of the initialization of the PipeWire program.
|
||||
|
||||
```json
|
||||
context.exec = [
|
||||
#{ path = <program-name>
|
||||
# ( args = "<arguments>" )
|
||||
# ( condition = [ { <key> = <value> ... } ... ] )
|
||||
#}
|
||||
]
|
||||
```
|
||||
|
||||
\par path
|
||||
Program to execute.
|
||||
|
||||
\par args
|
||||
Arguments to the program.
|
||||
|
||||
\par condition
|
||||
Condition variable definition.
|
||||
|
||||
## Example
|
||||
|
||||
The following fragment executes a pactl command with the given arguments:
|
||||
|
||||
```json
|
||||
context.exec = [
|
||||
{ path = "pactl" args = "load-module module-always-sink" }
|
||||
]
|
||||
```
|
||||
|
||||
# MATCH RULES @IDX@ pipewire.conf
|
||||
|
||||
Some configuration files can 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:
|
||||
```json
|
||||
<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.*"
|
||||
}
|
||||
{
|
||||
# more matches here...
|
||||
}
|
||||
...
|
||||
]
|
||||
actions = {
|
||||
<action-name> = <action value>
|
||||
...
|
||||
}
|
||||
}
|
||||
]
|
||||
```
|
||||
|
||||
The rules is an array of things to match and what actions to perform
|
||||
when a match is found.
|
||||
|
||||
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.
|
||||
|
||||
# AUTHORS
|
||||
|
||||
The PipeWire Developers <$(PACKAGE_BUGREPORT)>;
|
||||
|
|
@ -100,3 +382,5 @@ PipeWire is available from <$(PACKAGE_URL)>
|
|||
\ref page_man_pipewire_1 "pipewire(1)",
|
||||
\ref page_man_pw-mon_1 "pw-mon(1)",
|
||||
\ref page_man_libpipewire-modules_7 "libpipewire-modules(7)"
|
||||
\ref page_man_pipewire-pulse_conf_5 "pipewire-pulse.conf(5)"
|
||||
\ref page_man_pipewire-client_conf_5 "pipewire-client.conf(5)"
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue