pw-top

Monitor PipeWire server resource usage

TLDR

Display an interactive view of PipeWire nodes and devices

$ pw-top

Monitor a remote instance

$ pw-top [[-r|--remote]] [remote_name]

Print information periodically instead of running in interactive mode

$ pw-top [[-b|--batch-mode]]

Print information periodically for a specific number of times

$ pw-top [[-b|--batch-mode]] [[-n|--iterations]] [3]

-h, --help
    Show program help message and exit.

-r interval, --rate=interval
    Set the update interval in seconds. The default interval is 1 second. interval can be a floating-point number (e.g., 0.5 for half a second).

-P pid, --pid=pid
    Filter the displayed statistics to only show nodes and links associated with a specific process ID (pid).

DESCRIPTION

pw-top is a console-based utility that displays real-time statistics about the PipeWire sound and video server. It provides a dynamic, constantly updated view of active PipeWire nodes, links, and their resource usage. This includes crucial information such as node ID, name, media type (audio/video), direction (input/output), latency, busy time, and CPU usage. It serves as an invaluable tool for diagnosing audio/video routing issues, identifying high-latency components, or understanding the overall health and performance of a PipeWire system. By monitoring the flow of media data, pw-top helps users and developers pinpoint potential bottlenecks and ensure smooth multimedia operation.

CAVEATS

pw-top requires the PipeWire multimedia server to be running to display any information. The CPU usage reported by pw-top typically reflects the CPU time spent by the PipeWire server's thread handling a specific node or link, not necessarily the total CPU usage of the application owning that node. Understanding the output columns and interactive controls benefits from basic knowledge of PipeWire concepts (nodes, links, ports).

INTERACTIVE CONTROLS

Like top, pw-top offers interactive controls within the running application to change the displayed view and modify sorting. Common keys include:

n: Switch to nodes view (default).
l: Switch to links view.
p: Switch to ports view.
m: Switch to monitor nodes view.
s: Cycle through sorting columns.
q: Quit the application.

The exact available views and interactive keys might vary slightly between PipeWire versions.

OUTPUT COLUMNS

When running pw-top, the displayed information is organized into several columns providing detailed statistics for each PipeWire component. Typical columns include:

ID: The unique PipeWire object ID.
NAME: The name of the node, link, or port.
PRIORITY: The priority of the node (relevant for scheduling).
STATE: The current state of the node (e.g., running, suspended).
LATENCY: The measured audio/video latency.
BUSY: The percentage of time the node is busy processing data.
B/S: Bytes per second throughput (for links).
ERRORS: Number of processing errors.
CPU: CPU usage percentage for the PipeWire thread handling this component.

HISTORY

pw-top is an integral part of the PipeWire project, which was initiated by Wim Taymans at Red Hat in 2017. PipeWire was developed to modernize Linux multimedia by providing a robust framework for professional audio, video, and hardware access, addressing limitations of predecessors like PulseAudio and JACK. As PipeWire evolved into a critical component of the Linux desktop ecosystem, pw-top emerged as an essential debugging and monitoring utility. It provides direct introspection into PipeWire's real-time operations, much like top does for system processes, mirroring the development and increasing adoption of the PipeWire server itself.