1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
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.
*/
|
