.. _man_wpctl: 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 list ^^^^ **wpctl list** [**audio**\|\ **video**] [**devices**\|\ **sinks**\|\ **sources**] Displays a machine-readable list of PipeWire objects, optionally filtered by media type and object type. Each line of output contains tab-separated fields: object ID, name, media type/object type, and a ``*`` marker if the node is the current default. Arguments: **audio**\|\ **video** (optional) Filter by media type **devices**\|\ **sinks**\|\ **sources** (optional) Filter by object type (requires media type to be specified first) 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. The selection is remembered across restarts, in the ``default-nodes`` :ref:`state file `, and takes precedence over the automatic, priority-based selection that WirePlumber would otherwise make. Use **clear-default** to undo it. 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.5`` Increase 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. This forgets the current and all previous **set-default** selections of that kind, so that WirePlumber goes back to choosing the default node automatically, based on the ``priority.session`` property of each node. It is needed whenever a configured priority appears to have no effect, since a saved selection outranks any priority. The saved selections are listed in the "Default Configured Devices" section of **status**. 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. .. _man_wpctl_reset: reset ^^^^^ **wpctl reset** [**-c**\|\ **--wireplumber-config**] [**-p**\|\ **--pipewire-config**] [**-a**\|\ **--all**] [**-n**\|\ **--no-restart**] [**-d**\|\ **--dry-run**] [**-y**\|\ **--yes**] Resets WirePlumber (and optionally PipeWire) to defaults by removing state and configuration files. By default, only the WirePlumber state directory (``~/.local/state/wireplumber``) is removed. WirePlumber is automatically stopped before removal and restarted afterwards, unless **--no-restart** is given. A confirmation prompt is shown before any files are deleted, unless **--yes** is given. This command does not require a running PipeWire session. Options: **-c**, **--wireplumber-config** Also remove WirePlumber user configuration files (``~/.config/wireplumber``) **-p**, **--pipewire-config** Also remove PipeWire user configuration files (``~/.config/pipewire``) and restart the PipeWire service **-a**, **--all** Remove all state and configuration files (equivalent to combining **-c** and **-p**) **-n**, **--no-restart** Do not stop or restart services after removing files **-d**, **--dry-run** Show which files would be deleted without actually deleting anything or restarting services **-y**, **--yes** Proceed without prompting for confirmation 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 List all audio sinks:: wpctl list audio sinks Reset WirePlumber state (dry run):: wpctl reset --dry-run Reset WirePlumber state and config without prompting:: wpctl reset --wireplumber-config --yes Reset everything (WirePlumber and PipeWire state and config):: wpctl reset --all 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 -------- **wireplumber**\ (1), **wpexec**\ (1), **pipewire**\ (1), **pw-cli**\ (1), **pw-dump**\ (1) WirePlumber Documentation: https://pipewire.pages.freedesktop.org/wireplumber/