wpctl(1)
SYNOPSIS
wpctl [COMMAND] [COMMAND_OPTIONS]
DESCRIPTION
wpctl 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.
WirePlumber manages audio and video routing, device configuration, and session policies. wpctl allows users to interact with these components, change volume levels, set default devices, inspect object properties, and modify settings.
COMMANDS
status
wpctl status [-k|--nick] [-n|--name]
Displays the current state of objects in PipeWire, including devices, sinks, sources, filters, and streams. Shows a hierarchical view of the audio/video system.
- Options:
- -k, --nick
Display device and node nicknames instead of descriptions
- -n, --name
Display device and node names instead of descriptions
get-volume
wpctl get-volume ID
Displays volume information about the specified node, including current volume level and mute state.
- Arguments:
- ID
Node ID or special identifier (see SPECIAL IDENTIFIERS)
inspect
wpctl inspect ID [-r|--referenced] [-a|--associated]
Displays detailed information about the specified object, including all properties and metadata.
- Arguments:
- ID
Object ID or special identifier
- Options:
- -r, --referenced
Show objects that are referenced in properties
- -a, --associated
Show associated objects
set-default
wpctl set-default ID
Sets the specified device node to be the default target of its kind (capture or playback) for new streams that require auto-connection.
- Arguments:
- ID
Sink or source node ID
set-volume
wpctl set-volume ID VOL[%][-|+] [-p|--pid] [-l LIMIT|--limit LIMIT]
Sets the volume of the specified node.
- Arguments:
- ID
Node ID, special identifier, or PID (with --pid)
- VOL[%][-|+]
Volume specification:
VOL - Set volume to specific value (1.0 = 100%)
VOL% - Set volume to percentage (50% = 0.5)
VOL+ - Increase volume by value
VOL- - Decrease volume by value
VOL%+ - Increase volume by percentage
VOL%- - Decrease volume by percentage
- Options:
- -p, --pid
Treat ID as a process ID and affect all nodes associated with it
- -l LIMIT, --limit LIMIT
Limit final volume to below this value (floating point, 1.0 = 100%)
- Examples:
Set volume to 50%:
wpctl set-volume @DEFAULT_SINK@ 0.5Increase volume by 10%:
wpctl set-volume 42 10%+Set volume for all nodes of PID 1234:
wpctl set-volume --pid 1234 0.8
set-mute
wpctl set-mute ID 1|0|toggle [-p|--pid]
Changes the mute state of the specified node.
- Arguments:
- ID
Node ID, special identifier, or PID (with --pid)
- 1|0|toggle
Mute state: 1 (mute), 0 (unmute), or toggle current state
- Options:
- -p, --pid
Treat ID as a process ID and affect all nodes associated with it
set-profile
wpctl set-profile ID INDEX
Sets the profile of the specified device to the given index.
- Arguments:
- ID
Device ID or special identifier
- INDEX
Profile index (integer, 0 typically means 'off')
set-route
wpctl set-route ID INDEX
Sets the route of the specified device to the given index.
- Arguments:
- ID
Device node ID or special identifier
- INDEX
Route index (integer, 0 typically means 'off')
clear-default
wpctl clear-default [ID]
Clears the default configured node. If no ID is specified, clears all default nodes.
- Arguments:
- ID (optional)
Settings ID to clear (0-2 for Audio/Sink, Audio/Source, Video/Source). If omitted, clears all defaults.
settings
wpctl settings [KEY] [VAL] [-d|--delete] [-s|--save] [-r|--reset]
Shows, changes, or removes WirePlumber settings.
- Arguments:
- KEY (optional)
Setting key name
- VAL (optional)
Setting value (JSON format)
- Options:
- -d, --delete
Delete the saved setting value (no KEY means delete all)
- -s, --save
Save the setting value (no KEY means save all, no VAL means current value)
- -r, --reset
Reset the setting to its default value
- Behavior:
No arguments: Show all settings
KEY only: Show specific setting value
KEY and VAL: Set specific setting value
set-log-level
wpctl set-log-level [ID] LEVEL
Sets the log level of a client.
- Arguments:
- ID (optional)
Client ID. If omitted, applies to WirePlumber. Use 0 for PipeWire server.
- LEVEL
Log level (e.g.,
0,1,2,3,4,5,E,W,N,I,D,T). Use-to unset the log level.
SPECIAL IDENTIFIERS
Instead of numeric IDs, wpctl accepts these special identifiers for commonly used defaults:
- @DEFAULT_SINK@, @DEFAULT_AUDIO_SINK@
The current default audio sink (playback device)
- @DEFAULT_SOURCE@, @DEFAULT_AUDIO_SOURCE@
The current default audio source (capture device)
- @DEFAULT_VIDEO_SOURCE@
The current default video source (camera)
These identifiers are resolved at runtime to the appropriate node IDs.
EXIT STATUS
wpctl returns the following exit codes:
- 0
Success
- 1
General error (e.g., invalid arguments, connection failure)
- 2
Could not connect to PipeWire
- 3
Command-specific error (e.g., object not found)
EXAMPLES
Display system status:
wpctl status
Set default audio sink:
wpctl set-default 42
Set volume to 75% on default sink:
wpctl set-volume @DEFAULT_SINK@ 75%
Increase volume by 5% on a specific node:
wpctl set-volume 42 5%+
Mute the default source:
wpctl set-mute @DEFAULT_SOURCE@ 1
Toggle mute on default sink:
wpctl set-mute @DEFAULT_SINK@ toggle
Inspect a device with associated objects:
wpctl inspect --associated 30
Show all WirePlumber settings:
wpctl settings
Set a specific setting:
wpctl settings bluetooth.autoswitch true
Save all current settings:
wpctl settings --save
Set log level for WirePlumber to debug:
wpctl set-log-level D
Set log level for a specific client:
wpctl set-log-level 42 W
NOTES
Object IDs can be found using the status command. The hierarchical display shows IDs for devices, nodes, and other objects.
Volume values are floating-point numbers where 1.0 represents 100% volume. Values can exceed 1.0 to introduce volume amplification.
When using the --pid option, wpctl will find all audio nodes associated with the specified process ID and apply the operation to all of them.
SEE ALSO
pipewire(1), pw-cli(1), pw-dump(1), wireplumber(1)
WirePlumber Documentation: https://pipewire.pages.freedesktop.org/wireplumber/