diff options
Diffstat (limited to '')
| -rw-r--r-- | doc/pipewire-daemon.dox | 175 |
1 files changed, 175 insertions, 0 deletions
diff --git a/doc/pipewire-daemon.dox b/doc/pipewire-daemon.dox new file mode 100644 index 0000000..c1a0649 --- /dev/null +++ b/doc/pipewire-daemon.dox @@ -0,0 +1,175 @@ +/** \page page_daemon PipeWire Daemon + +The PipeWire daemon is the central process that manages data exchange between +devices and clients. + +Typically general, users run one PipeWire daemon that listens for incoming +connections and manages devices. Clients (including the \ref +page_session_manager) are separate processes that talk to the daemon using the +PipeWire socket (default: `$XDG_RUNTIME_DIR/pipewire-0`). This approach +provides address-space separation between the privileged daemon and +non-privileged clients. + +\dot +digraph pw { + compound=true; + node [shape="box"]; + + subgraph cluster_pw { + rankdir="TB"; + label="PipeWire daemon"; + style="dashed"; + + subgraph cluster_prot_native { + label="pipewire-module-protocol-native"; + style="solid"; + socket [label="$XDG_RUNTIME_DIR/pipewire-0"]; + mod_impl [label="module implementation"]; + + socket -> mod_impl; + } + core [label="PipeWire Core"]; + alsa [label="PipeWire ALSA support"]; + + mod_impl -> core; + core -> alsa; + } + + kernel + + client1 [ label="Media Player" ]; + client2 [ label="Audio Software" ]; + sm [ label="Session Manager", style="dotted" ]; + + client1 -> socket; + client2 -> socket; + sm -> socket; + alsa -> kernel; +} +\enddot + +As shown above, the protocol is handled by the \ref +page_module_protocol_native. From PipeWire's point-of-view this module is just +another module. + +# Configuration Files + +On startup, the daemon reads a configuration file to configure itself. +It executes a series of commands listed in the config file. The lookup order +for configuration files are: + +- `$XDG_CONFIG_HOME/pipewire/pipewire.conf` (usually `$HOME/.config/pipewire/pipewire.conf`) +- `$sysconfdir/pipewire/pipewire.conf` (usually `/etc/pipewire/pipewire.conf`) +- `$datadir/pipewire/pipewire.conf` (usually `/usr/share/pipewire/pipewire.conf`) + +The first configuration file found is loaded as the base configuration. + +Next, configuration sections are collected in the directories in this +order: + +- `$datadir/pipewire/pipewire.conf.d/` (usually `/usr/share/pipewire/pipewire.conf.d/`) +- `$sysconfdir/pipewire/pipewire.conf.d/` (usually `/etc/pipewire/pipewire.conf.d/`) +- `$XDG_CONFIG_HOME/pipewire/pipewire.conf.d/` (usually `$HOME/.config/pipewire/pipewire.conf.d/`) + +They are applied to the global configuration file. Properties are overwritten +and array elements are appended. This makes it possible to make small custom customizations +or additions to the main configuration file. + +The environment variables `PIPEWIRE_CONFIG_DIR`, `PIPEWIRE_CONFIG_PREFIX`, +and `PIPEWIRE_CONFIG_NAME`. Can be used to specify an alternative configuration +directory, subdirectory, and filename respectively. + +## Configuration File Format + +PipeWire's configuration file format is JSON. In addition to true JSON +PipeWire also understands a more compact JSON representation. Where +`"` can be omitted around strings, no trailing commas are required and +`:` or `=` can be used to separate object keys from their values. +Also, `#` can be used to start a comment until the end of the line. + +The configuration file format is grouped into sections. A section is +either a dictionary (`{}`) or an array (`[]`). Dictionary and array entries +are separated by whitespace and may be simple value assignment, an array or +a dictionary. For example: + +``` +# A dictionary section +context.properties = { + # Keys often have a dot notation + core.daemon = true +} + +# An array section containing three dictionary objects +context.modules = [ + # a dictionary object with one key assigned to a string + { name = libpipewire-module-protocol-native } + { name = libpipewire-module-profiler } + + # a dictionary object with two keys, one assigned to a string + # the other one to an array of strings + { name = libpipewire-module-portal + flags = [ ifexists nofail ] + } +] +``` + +Allowed configuration file sections are: + +- **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): 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): Each entry in the array is a dictionary con‐ + taining the factory to create an object from and optional extra argu‐ + ments specific to that factory. +- **context.exec** (array): Each entry in the array is dictionary containing + the path of a program to execute on startup and optional args. This ar‐ + ray usually contains an entry to start the session manager. + + +# Logging + +The `PIPEWIRE_DEBUG` environment variable can be used to enable +more debugging. This variable supports the following format: + +- `PIPEWIRE_DEBUG=[<level>][,<glob1>:<level1>][,<glob2>:<level2>,...]` where the globs are + shell globs to match on log topics and the levels are the respective + log level to set for that topic. Globs are applied in order and a matching + glob overrides an earlier glob for that category. A level without a glob + prefix will set the global log level and is a more preformant version of + `*:<level>`. For example, `PIPEWIRE_DEBUG=E,mod.*:D,mod.foo:X` enables global error messages, + debugging on all modules but no messages on the foo module. +- `<level>` specifies the log level: + + + `X` or `0`: No logging is enabled. + + `E` or `1`: Error logging is enabled. + + `W` or `2`: Warnings are enabled. + + `I` or `3`: Informational messages are enabled. + + `D` or `4`: Debug messages are enabled. + + `T` or `5`: Trace messages are enabled. These messages can be logged + from the realtime threads. + +PipeWire uses a `category.topic` naming scheme, with the following categories: + +- `pw.*`: PipeWire internal topics. +- `mod.*`: Module topics, for example `mod.foo` would usually refer to the + `foo` module. +- `ms.*`: Media session topics. +- `ms.mod.*`: Media session modules, for example `ms.foo` would usually refer + to the `media-session-foo` module. +- `conn.*`: Connection specific topics such as printing raw messages sent over + a communication socket. These are in a separate namespace as they are + usually vastly more verbose than the normal debugging topics. + This namespace must be explicitly enabled with a `conn.<glob>` glob. + +The behavior of the logging can be further controlled with the following +environment variables: + +- `PIPEWIRE_LOG_SYSTEMD=false`: Disable logging to the systemd journal. +- `PIPEWIRE_LOG=<filename>`: Redirect the log to the given filename. +- `PIPEWIRE_LOG_LINE=false`: Don't log filename, function, and source code line. + +*/ |