Debian Codegraph @

docs/rst/tools/wpctl.rst

raw
1 wpctl(1)
2 ========
3
4 SYNOPSIS
5 --------
6
7 **wpctl** [*COMMAND*] [*COMMAND_OPTIONS*]
8
9 DESCRIPTION
10 -----------
11
12 **wpctl** is a command-line control tool for WirePlumber, the PipeWire session
13 manager. It provides an interface to inspect, control, and configure audio and
14 video devices, nodes, and their properties within a PipeWire media server.
15
16 WirePlumber manages audio and video routing, device configuration, and session
17 policies. **wpctl** allows users to interact with these components, change
18 volume levels, set default devices, inspect object properties, and modify
19 settings.
20
21 COMMANDS
22 --------
23
24 status
25 ^^^^^^
26
27 **wpctl status** [**-k**\|\ **--nick**] [**-n**\|\ **--name**]
28
29 Displays the current state of objects in PipeWire, including devices, sinks,
30 sources, filters, and streams. Shows a hierarchical view of the audio/video
31 system.
32
33 Options:
34 **-k**, **--nick**
35 Display device and node nicknames instead of descriptions
36 **-n**, **--name**
37 Display device and node names instead of descriptions
38
39 get-volume
40 ^^^^^^^^^^
41
42 **wpctl get-volume** *ID*
43
44 Displays volume information about the specified node, including current volume
45 level and mute state.
46
47 Arguments:
48 *ID*
49 Node ID or special identifier (see `SPECIAL IDENTIFIERS`_)
50
51 inspect
52 ^^^^^^^
53
54 **wpctl inspect** *ID* [**-r**\|\ **--referenced**] [**-a**\|\ **--associated**]
55
56 Displays detailed information about the specified object, including all
57 properties and metadata.
58
59 Arguments:
60 *ID*
61 Object ID or special identifier
62
63 Options:
64 **-r**, **--referenced**
65 Show objects that are referenced in properties
66 **-a**, **--associated**
67 Show associated objects
68
69 set-default
70 ^^^^^^^^^^^
71
72 **wpctl set-default** *ID*
73
74 Sets the specified device node to be the default target of its kind (capture or
75 playback) for new streams that require auto-connection.
76
77 Arguments:
78 *ID*
79 Sink or source node ID
80
81 set-volume
82 ^^^^^^^^^^
83
84 **wpctl set-volume** *ID* *VOL*\ [**%**]\ [**-**\|\ **+**] [**-p**\|\ **--pid**] [**-l** *LIMIT*\|\ **--limit** *LIMIT*]
85
86 Sets the volume of the specified node.
87
88 Arguments:
89 *ID*
90 Node ID, special identifier, or PID (with --pid)
91 *VOL*\ [**%**]\ [**-**\|\ **+**]
92 Volume specification:
93
94 - *VOL* - Set volume to specific value (1.0 = 100%)
95 - *VOL*\ **%** - Set volume to percentage (50% = 0.5)
96 - *VOL*\ **+** - Increase volume by value
97 - *VOL*\ **-** - Decrease volume by value
98 - *VOL*\ **%+** - Increase volume by percentage
99 - *VOL*\ **%-** - Decrease volume by percentage
100
101 Options:
102 **-p**, **--pid**
103 Treat ID as a process ID and affect all nodes associated with it
104 **-l** *LIMIT*, **--limit** *LIMIT*
105 Limit final volume to below this value (floating point, 1.0 = 100%)
106
107 Examples:
108 Set volume to 50%: ``wpctl set-volume @DEFAULT_SINK@ 0.5``
109
110 Increase volume by 10%: ``wpctl set-volume 42 10%+``
111
112 Set volume for all nodes of PID 1234: ``wpctl set-volume --pid 1234 0.8``
113
114 set-mute
115 ^^^^^^^^
116
117 **wpctl set-mute** *ID* **1**\|\ **0**\|\ **toggle** [**-p**\|\ **--pid**]
118
119 Changes the mute state of the specified node.
120
121 Arguments:
122 *ID*
123 Node ID, special identifier, or PID (with --pid)
124 **1**\|\ **0**\|\ **toggle**
125 Mute state: 1 (mute), 0 (unmute), or toggle current state
126
127 Options:
128 **-p**, **--pid**
129 Treat ID as a process ID and affect all nodes associated with it
130
131 set-profile
132 ^^^^^^^^^^^
133
134 **wpctl set-profile** *ID* *INDEX*
135
136 Sets the profile of the specified device to the given index.
137
138 Arguments:
139 *ID*
140 Device ID or special identifier
141 *INDEX*
142 Profile index (integer, 0 typically means 'off')
143
144 set-route
145 ^^^^^^^^^
146
147 **wpctl set-route** *ID* *INDEX*
148
149 Sets the route of the specified device to the given index.
150
151 Arguments:
152 *ID*
153 Device node ID or special identifier
154 *INDEX*
155 Route index (integer, 0 typically means 'off')
156
157 clear-default
158 ^^^^^^^^^^^^^
159
160 **wpctl clear-default** [*ID*]
161
162 Clears the default configured node. If no ID is specified, clears all default
163 nodes.
164
165 Arguments:
166 *ID* (optional)
167 Settings ID to clear (0-2 for Audio/Sink, Audio/Source, Video/Source).
168 If omitted, clears all defaults.
169
170 settings
171 ^^^^^^^^
172
173 **wpctl settings** [*KEY*] [*VAL*] [**-d**\|\ **--delete**] [**-s**\|\ **--save**] [**-r**\|\ **--reset**]
174
175 Shows, changes, or removes WirePlumber settings.
176
177 Arguments:
178 *KEY* (optional)
179 Setting key name
180 *VAL* (optional)
181 Setting value (JSON format)
182
183 Options:
184 **-d**, **--delete**
185 Delete the saved setting value (no KEY means delete all)
186 **-s**, **--save**
187 Save the setting value (no KEY means save all, no VAL means current value)
188 **-r**, **--reset**
189 Reset the setting to its default value
190
191 Behavior:
192 - No arguments: Show all settings
193 - KEY only: Show specific setting value
194 - KEY and VAL: Set specific setting value
195
196 set-log-level
197 ^^^^^^^^^^^^^
198
199 **wpctl set-log-level** [*ID*] *LEVEL*
200
201 Sets the log level of a client.
202
203 Arguments:
204 *ID* (optional)
205 Client ID. If omitted, applies to WirePlumber. Use 0 for PipeWire server.
206 *LEVEL*
207 Log level (e.g., ``0``, ``1``, ``2``, ``3``, ``4``, ``5``, ``E``, ``W``, ``N``, ``I``, ``D``, ``T``).
208 Use ``-`` to unset the log level.
209
210 SPECIAL IDENTIFIERS
211 -------------------
212
213 Instead of numeric IDs, **wpctl** accepts these special identifiers for
214 commonly used defaults:
215
216 **@DEFAULT_SINK@**, **@DEFAULT_AUDIO_SINK@**
217 The current default audio sink (playback device)
218
219 **@DEFAULT_SOURCE@**, **@DEFAULT_AUDIO_SOURCE@**
220 The current default audio source (capture device)
221
222 **@DEFAULT_VIDEO_SOURCE@**
223 The current default video source (camera)
224
225 These identifiers are resolved at runtime to the appropriate node IDs.
226
227 EXIT STATUS
228 -----------
229
230 **wpctl** returns the following exit codes:
231
232 0
233 Success
234 1
235 General error (e.g., invalid arguments, connection failure)
236 2
237 Could not connect to PipeWire
238 3
239 Command-specific error (e.g., object not found)
240
241 EXAMPLES
242 --------
243
244 Display system status::
245
246 wpctl status
247
248 Set default audio sink::
249
250 wpctl set-default 42
251
252 Set volume to 75% on default sink::
253
254 wpctl set-volume @DEFAULT_SINK@ 75%
255
256 Increase volume by 5% on a specific node::
257
258 wpctl set-volume 42 5%+
259
260 Mute the default source::
261
262 wpctl set-mute @DEFAULT_SOURCE@ 1
263
264 Toggle mute on default sink::
265
266 wpctl set-mute @DEFAULT_SINK@ toggle
267
268 Inspect a device with associated objects::
269
270 wpctl inspect --associated 30
271
272 Show all WirePlumber settings::
273
274 wpctl settings
275
276 Set a specific setting::
277
278 wpctl settings bluetooth.autoswitch true
279
280 Save all current settings::
281
282 wpctl settings --save
283
284 Set log level for WirePlumber to debug::
285
286 wpctl set-log-level D
287
288 Set log level for a specific client::
289
290 wpctl set-log-level 42 W
291
292 NOTES
293 -----
294
295 Object IDs can be found using the **status** command. The hierarchical display
296 shows IDs for devices, nodes, and other objects.
297
298 Volume values are floating-point numbers where 1.0 represents 100% volume.
299 Values can exceed 1.0 to introduce volume amplification.
300
301 When using the **--pid** option, **wpctl** will find all audio nodes associated
302 with the specified process ID and apply the operation to all of them.
303
304 SEE ALSO
305 --------
306
307 **pipewire**\ (1), **pw-cli**\ (1), **pw-dump**\ (1), **wireplumber**\ (1)
308
309 WirePlumber Documentation: https://pipewire.pages.freedesktop.org/wireplumber/