wpctl(1) — WirePlumber 0.5.17 documentation

# 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` 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.

### 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/