.\" Man page generated from reStructuredText.
.
.
.nr rst2man-indent-level 0
.
.de1 rstReportMargin
\\$1 \\n[an-margin]
level \\n[rst2man-indent-level]
level margin: \\n[rst2man-indent\\n[rst2man-indent-level]]
-
\\n[rst2man-indent0]
\\n[rst2man-indent1]
\\n[rst2man-indent2]
..
.de1 INDENT
.\" .rstReportMargin pre:
. RS \\$1
. nr rst2man-indent\\n[rst2man-indent-level] \\n[an-margin]
. nr rst2man-indent-level +1
.\" .rstReportMargin post:
..
.de UNINDENT
. RE
.\" indent \\n[an-margin]
.\" old: \\n[rst2man-indent\\n[rst2man-indent-level]]
.nr rst2man-indent-level -1
.\" new: \\n[rst2man-indent\\n[rst2man-indent-level]]
.in \\n[rst2man-indent\\n[rst2man-indent-level]]u
..
.TH "WPCTL" "1" "Oct 10, 2025" "0.5.12" "WirePlumber"
.SH NAME
wpctl \- WirePlumber Control CLI
.SH SYNOPSIS
.sp
\fBwpctl\fP [\fICOMMAND\fP] [\fICOMMAND_OPTIONS\fP]
.SH DESCRIPTION
.sp
\fBwpctl\fP is a command\-line control tool for WirePlumber, the PipeWire session
manager. It provides an interface to inspect, control, and configure audio and
video devices, nodes, and their properties within a PipeWire media server.
.sp
WirePlumber manages audio and video routing, device configuration, and session
policies. \fBwpctl\fP allows users to interact with these components, change
volume levels, set default devices, inspect object properties, and modify
settings.
.SH COMMANDS
.SS status
.sp
\fBwpctl status\fP [\fB\-k\fP|\fB\-\-nick\fP] [\fB\-n\fP|\fB\-\-name\fP]
.sp
Displays the current state of objects in PipeWire, including devices, sinks,
sources, filters, and streams. Shows a hierarchical view of the audio/video
system.
.INDENT 0.0
.TP
.B Options:
.INDENT 7.0
.TP
\fB\-k\fP, \fB\-\-nick\fP
Display device and node nicknames instead of descriptions
.TP
\fB\-n\fP, \fB\-\-name\fP
Display device and node names instead of descriptions
.UNINDENT
.UNINDENT
.SS get\-volume
.sp
\fBwpctl get\-volume\fP \fIID\fP
.sp
Displays volume information about the specified node, including current volume
level and mute state.
.INDENT 0.0
.TP
.B Arguments:
.INDENT 7.0
.TP
.B \fIID\fP
Node ID or special identifier (see \fI\%SPECIAL IDENTIFIERS\fP)
.UNINDENT
.UNINDENT
.SS inspect
.sp
\fBwpctl inspect\fP \fIID\fP [\fB\-r\fP|\fB\-\-referenced\fP] [\fB\-a\fP|\fB\-\-associated\fP]
.sp
Displays detailed information about the specified object, including all
properties and metadata.
.INDENT 0.0
.TP
.B Arguments:
.INDENT 7.0
.TP
.B \fIID\fP
Object ID or special identifier
.UNINDENT
.TP
.B Options:
.INDENT 7.0
.TP
\fB\-r\fP, \fB\-\-referenced\fP
Show objects that are referenced in properties
.TP
\fB\-a\fP, \fB\-\-associated\fP
Show associated objects
.UNINDENT
.UNINDENT
.SS set\-default
.sp
\fBwpctl set\-default\fP \fIID\fP
.sp
Sets the specified device node to be the default target of its kind (capture or
playback) for new streams that require auto\-connection.
.INDENT 0.0
.TP
.B Arguments:
.INDENT 7.0
.TP
.B \fIID\fP
Sink or source node ID
.UNINDENT
.UNINDENT
.SS set\-volume
.sp
\fBwpctl set\-volume\fP \fIID\fP \fIVOL\fP[\fB%\fP][\fB\-\fP|\fB+\fP] [\fB\-p\fP|\fB\-\-pid\fP] [\fB\-l\fP \fILIMIT\fP|\fB\-\-limit\fP \fILIMIT\fP]
.sp
Sets the volume of the specified node.
.INDENT 0.0
.TP
.B Arguments:
.INDENT 7.0
.TP
.B \fIID\fP
Node ID, special identifier, or PID (with \-\-pid)
.TP
\fIVOL\fP[\fB%\fP][\fB\-\fP|\fB+\fP]
Volume specification:
.INDENT 7.0
.IP \(bu 2
\fIVOL\fP \- Set volume to specific value (1.0 = 100%)
.IP \(bu 2
\fIVOL\fP\fB%\fP \- Set volume to percentage (50% = 0.5)
.IP \(bu 2
\fIVOL\fP\fB+\fP \- Increase volume by value
.IP \(bu 2
\fIVOL\fP\fB\-\fP \- Decrease volume by value
.IP \(bu 2
\fIVOL\fP\fB%+\fP \- Increase volume by percentage
.IP \(bu 2
\fIVOL\fP\fB%\-\fP \- Decrease volume by percentage
.UNINDENT
.UNINDENT
.TP
.B Options:
.INDENT 7.0
.TP
\fB\-p\fP, \fB\-\-pid\fP
Treat ID as a process ID and affect all nodes associated with it
.TP
\fB\-l\fP \fILIMIT\fP, \fB\-\-limit\fP \fILIMIT\fP
Limit final volume to below this value (floating point, 1.0 = 100%)
.UNINDENT
.TP
.B Examples:
Set volume to 50%: \fBwpctl set\-volume @DEFAULT_SINK@ 0.5\fP
.sp
Increase volume by 10%: \fBwpctl set\-volume 42 10%+\fP
.sp
Set volume for all nodes of PID 1234: \fBwpctl set\-volume \-\-pid 1234 0.8\fP
.UNINDENT
.SS set\-mute
.sp
\fBwpctl set\-mute\fP \fIID\fP \fB1\fP|\fB0\fP|\fBtoggle\fP [\fB\-p\fP|\fB\-\-pid\fP]
.sp
Changes the mute state of the specified node.
.INDENT 0.0
.TP
.B Arguments:
.INDENT 7.0
.TP
.B \fIID\fP
Node ID, special identifier, or PID (with \-\-pid)
.TP
\fB1\fP|\fB0\fP|\fBtoggle\fP
Mute state: 1 (mute), 0 (unmute), or toggle current state
.UNINDENT
.TP
.B Options:
.INDENT 7.0
.TP
\fB\-p\fP, \fB\-\-pid\fP
Treat ID as a process ID and affect all nodes associated with it
.UNINDENT
.UNINDENT
.SS set\-profile
.sp
\fBwpctl set\-profile\fP \fIID\fP \fIINDEX\fP
.sp
Sets the profile of the specified device to the given index.
.INDENT 0.0
.TP
.B Arguments:
.INDENT 7.0
.TP
.B \fIID\fP
Device ID or special identifier
.TP
.B \fIINDEX\fP
Profile index (integer, 0 typically means \(aqoff\(aq)
.UNINDENT
.UNINDENT
.SS set\-route
.sp
\fBwpctl set\-route\fP \fIID\fP \fIINDEX\fP
.sp
Sets the route of the specified device to the given index.
.INDENT 0.0
.TP
.B Arguments:
.INDENT 7.0
.TP
.B \fIID\fP
Device node ID or special identifier
.TP
.B \fIINDEX\fP
Route index (integer, 0 typically means \(aqoff\(aq)
.UNINDENT
.UNINDENT
.SS clear\-default
.sp
\fBwpctl clear\-default\fP [\fIID\fP]
.sp
Clears the default configured node. If no ID is specified, clears all default
nodes.
.INDENT 0.0
.TP
.B Arguments:
.INDENT 7.0
.TP
.B \fIID\fP (optional)
Settings ID to clear (0\-2 for Audio/Sink, Audio/Source, Video/Source).
If omitted, clears all defaults.
.UNINDENT
.UNINDENT
.SS settings
.sp
\fBwpctl settings\fP [\fIKEY\fP] [\fIVAL\fP] [\fB\-d\fP|\fB\-\-delete\fP] [\fB\-s\fP|\fB\-\-save\fP] [\fB\-r\fP|\fB\-\-reset\fP]
.sp
Shows, changes, or removes WirePlumber settings.
.INDENT 0.0
.TP
.B Arguments:
.INDENT 7.0
.TP
.B \fIKEY\fP (optional)
Setting key name
.TP
.B \fIVAL\fP (optional)
Setting value (JSON format)
.UNINDENT
.TP
.B Options:
.INDENT 7.0
.TP
\fB\-d\fP, \fB\-\-delete\fP
Delete the saved setting value (no KEY means delete all)
.TP
\fB\-s\fP, \fB\-\-save\fP
Save the setting value (no KEY means save all, no VAL means current value)
.TP
\fB\-r\fP, \fB\-\-reset\fP
Reset the setting to its default value
.UNINDENT
.TP
.B Behavior:
.INDENT 7.0
.IP \(bu 2
No arguments: Show all settings
.IP \(bu 2
KEY only: Show specific setting value
.IP \(bu 2
KEY and VAL: Set specific setting value
.UNINDENT
.UNINDENT
.SS set\-log\-level
.sp
\fBwpctl set\-log\-level\fP [\fIID\fP] \fILEVEL\fP
.sp
Sets the log level of a client.
.INDENT 0.0
.TP
.B Arguments:
.INDENT 7.0
.TP
.B \fIID\fP (optional)
Client ID. If omitted, applies to WirePlumber. Use 0 for PipeWire server.
.TP
.B \fILEVEL\fP
Log level (e.g., \fB0\fP, \fB1\fP, \fB2\fP, \fB3\fP, \fB4\fP, \fB5\fP, \fBE\fP, \fBW\fP, \fBN\fP, \fBI\fP, \fBD\fP, \fBT\fP).
Use \fB\-\fP to unset the log level.
.UNINDENT
.UNINDENT
.SH SPECIAL IDENTIFIERS
.sp
Instead of numeric IDs, \fBwpctl\fP accepts these special identifiers for
commonly used defaults:
.INDENT 0.0
.TP
\fB@DEFAULT_SINK@\fP, \fB@DEFAULT_AUDIO_SINK@\fP
The current default audio sink (playback device)
.TP
\fB@DEFAULT_SOURCE@\fP, \fB@DEFAULT_AUDIO_SOURCE@\fP
The current default audio source (capture device)
.TP
\fB@DEFAULT_VIDEO_SOURCE@\fP
The current default video source (camera)
.UNINDENT
.sp
These identifiers are resolved at runtime to the appropriate node IDs.
.SH EXIT STATUS
.sp
\fBwpctl\fP returns the following exit codes:
.INDENT 0.0
.TP
.B 0
Success
.TP
.B 1
General error (e.g., invalid arguments, connection failure)
.TP
.B 2
Could not connect to PipeWire
.TP
.B 3
Command\-specific error (e.g., object not found)
.UNINDENT
.SH EXAMPLES
.sp
Display system status:
.INDENT 0.0
.INDENT 3.5
.sp
.EX
wpctl status
.EE
.UNINDENT
.UNINDENT
.sp
Set default audio sink:
.INDENT 0.0
.INDENT 3.5
.sp
.EX
wpctl set\-default 42
.EE
.UNINDENT
.UNINDENT
.sp
Set volume to 75% on default sink:
.INDENT 0.0
.INDENT 3.5
.sp
.EX
wpctl set\-volume @DEFAULT_SINK@ 75%
.EE
.UNINDENT
.UNINDENT
.sp
Increase volume by 5% on a specific node:
.INDENT 0.0
.INDENT 3.5
.sp
.EX
wpctl set\-volume 42 5%+
.EE
.UNINDENT
.UNINDENT
.sp
Mute the default source:
.INDENT 0.0
.INDENT 3.5
.sp
.EX
wpctl set\-mute @DEFAULT_SOURCE@ 1
.EE
.UNINDENT
.UNINDENT
.sp
Toggle mute on default sink:
.INDENT 0.0
.INDENT 3.5
.sp
.EX
wpctl set\-mute @DEFAULT_SINK@ toggle
.EE
.UNINDENT
.UNINDENT
.sp
Inspect a device with associated objects:
.INDENT 0.0
.INDENT 3.5
.sp
.EX
wpctl inspect \-\-associated 30
.EE
.UNINDENT
.UNINDENT
.sp
Show all WirePlumber settings:
.INDENT 0.0
.INDENT 3.5
.sp
.EX
wpctl settings
.EE
.UNINDENT
.UNINDENT
.sp
Set a specific setting:
.INDENT 0.0
.INDENT 3.5
.sp
.EX
wpctl settings bluetooth.autoswitch true
.EE
.UNINDENT
.UNINDENT
.sp
Save all current settings:
.INDENT 0.0
.INDENT 3.5
.sp
.EX
wpctl settings \-\-save
.EE
.UNINDENT
.UNINDENT
.sp
Set log level for WirePlumber to debug:
.INDENT 0.0
.INDENT 3.5
.sp
.EX
wpctl set\-log\-level D
.EE
.UNINDENT
.UNINDENT
.sp
Set log level for a specific client:
.INDENT 0.0
.INDENT 3.5
.sp
.EX
wpctl set\-log\-level 42 W
.EE
.UNINDENT
.UNINDENT
.SH NOTES
.sp
Object IDs can be found using the \fBstatus\fP command. The hierarchical display
shows IDs for devices, nodes, and other objects.
.sp
Volume values are floating\-point numbers where 1.0 represents 100% volume.
Values can exceed 1.0 to introduce volume amplification.
.sp
When using the \fB\-\-pid\fP option, \fBwpctl\fP will find all audio nodes associated
with the specified process ID and apply the operation to all of them.
.SH SEE ALSO
.sp
\fBpipewire\fP(1), \fBpw\-cli\fP(1), \fBpw\-dump\fP(1), \fBwireplumber\fP(1)
.sp
WirePlumber Documentation: \X'tty: link https://pipewire.pages.freedesktop.org/wireplumber/'\fI\%https://pipewire.pages.freedesktop.org/wireplumber/\fP\X'tty: link'
.SH AUTHOR
The WirePlumber Developers
.SH COPYRIGHT
2020-2025, Collabora & contributors
.\" Generated by docutils manpage writer.
.