.. _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 <state_locations>`, 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

get-profile
^^^^^^^^^^^

**wpctl get-profile** *DEVICE_ID*

Shows the active profile and the available profiles of the specified PipeWire
device. The output identifies the device by ID and description. The number on
each profile line is the profile index accepted by **set-profile**. The active
profile is marked with ``*``; its availability and priority are shown
separately.

Arguments:
  *DEVICE_ID*
    PipeWire device ID

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 displayed by **wpctl get-profile** *ID*

get-route
^^^^^^^^^

**wpctl get-route** *DEVICE_OR_NODE_ID*

Shows reported route assignments and enumerated route choices. With a device
ID, it shows the complete route inventory, including the associated profile
and logical-device indices. With a node ID, it shows the routes applicable to
that node's logical device and the currently active profile. The output also
identifies the parent device by its description and shows the active profile's
description when available. Reported assignments identify matching active
nodes by media class, node ID and description when that information is
available, and include the referenced profile's description when it can be
resolved. Directional arrows show the audio flow between logical devices and
their physical routes.

A reported route assignment can remain after the active profile changes. Only
an assignment applicable to the current profile is marked with ``*`` in the
route-choice list. The number on each route-choice line is the route index
accepted by **set-route**; availability, direction and priority are shown
separately.

Arguments:
  *DEVICE_OR_NODE_ID*
    PipeWire device or node ID, or a special node identifier (see
    `SPECIAL IDENTIFIERS`_)

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 displayed by **wpctl get-route** *ID* for the corresponding
    node. This is not a logical-device index.

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/
