pwctl

A PipeWire management tool designed to browse and manage PipeWire state from the terminal. It provides both an interactive TUI with a graph view for real-time browsing and control, and a non-interactive CLI for one-off information access and scripting.

• TUI — Tabbed interface for browsing and managing PipeWire state in real-time
• CLI — Scriptable commands for devices, nodes, links, and clients
• Two backends — Live native PipeWire connection, or offline JSON from pw-dump

Run with no arguments to launch the TUI:

pwctl

Run a subcommand for non-interactive CLI output:

pwctl device list
pwctl node list
pwctl link create <out-port> <in-port>

By default, pwctl connects to PipeWire natively. Use -i to read from a pw-dump snapshot instead (useful for inspection and testing):

# From a saved file
pwctl -i dump.json device list

# From live pw-dump on stdin
pw-dump | pwctl -i - node list

The file-based backend is read-only and does not support mutations (link creation, profile changes, etc.).

pwctl device list [-v]
pwctl device set-profile <serial> <index|name>
pwctl device set-route <serial> <index|name>

Lists devices grouped by API (ALSA, Bluetooth, V4L2, libcamera). -v includes all enumerated profiles and routes. set-profile and set-route change the active profile or route on a device.

pwctl node list
pwctl node set-default <category> <name|serial>

Lists nodes organized by media type and role (sinks, sources, streams). The default sink and source are marked with *. Categories for set-default are audio-sink, audio-source, and video-source.

pwctl link create <out-port> <in-port>
pwctl link destroy <serial>

Ports can be specified by serial number or by <node.name>:<port.name>.

pwctl client list

Lists all connected PipeWire clients with their PIDs and associated objects (nodes, devices).

pwctl info <serial>

Shows all properties and params for any PipeWire object by serial number.

Launch with pwctl. The TUI provides the following tabs:

Navigate with arrow keys or vim-style keys (h/j/k/l). Use / to enter a context-aware slash command (e.g., /link, /set-profile). Press q or Ctrl+C to quit.

Requires Rust (edition 2024) and PipeWire development libraries.

cargo build --release

# Run from source
cargo run -- device list -i dump.json

See doc/SPEC.md for the full design specification.

The codebase is structured around a Backend trait with two implementations:

• NativeBackend — Communicates with PipeWire via its native socket protocol using pipewire-native-rs. Supports all mutations and real-time updates.
• PwDumpBackend — Parses JSON from pw-dump output. Read-only; useful for inspection and offline development.

The TUI is built with ratatui and crossterm.