How to Use the Command 'pw-top' (with examples)

PipeWire is a server for handling multimedia on Linux. It can manage audio and video streams with low latency, and is essentially a modern alternative to both the JACK and PulseAudio systems. The pw-top command is a real-time tool provided by PipeWire that allows users to monitor and display the state of PipeWire nodes and devices. This command is quite similar to the widely known top command used for monitoring CPU and memory usage but is tailored for multimedia processes. By using pw-top, users can gain insights into the performance and statistics of their audio and video pipelines.

Use case 1: Display an interactive view of PipeWire nodes and devices

Code:

pw-top

Motivation: When you’re managing multimedia processes on a system running PipeWire, it’s vital to have an understanding of what’s happening in real-time. By running pw-top, users can monitor various PipeWire nodes and devices interactively, similar to how you would monitor your system resources with the top command. This is especially useful for debugging, performance monitoring, or simply learning how PipeWire is handling audio and video streams on your system.

Explanation: The command pw-top on its own initiates the interactive mode. In this mode, pw-top runs in a loop constantly updating the display with the latest information regarding various audio and video components.

Example output: You will see a table that lists active nodes and devices with their corresponding IDs, names, node type, state, and more. The view dynamically updates as the connected pipelines or devices change over time.

   ID  Name                          Type     In  Out  State   Process CPU(%) Load
  ...
    2  alsa_output.pci-0000_00_1f.3  Node     0   1    RUNNING user   1.0      0/0
    3  alsa_input.pci-0000_00_1f.3   Node     1   0    RUNNING user   0.5      0/0
  ...

Use case 2: Monitor a remote instance

Code:

pw-top --remote remote_name

Motivation: In a networked environment or when using multiple systems, sometimes it’s necessary to manage or monitor a PipeWire instance that isn’t local to your current machine. The --remote option allows you to connect to a remote PipeWire server and monitor its nodes and devices in real-time. This is invaluable for administrators or developers working in distributed systems or with networked audio/video applications, as it provides a window into remote operations without needing physical access.

Explanation: The --remote followed by remote_name tells pw-top to connect to a PipeWire instance that is not on the local machine. remote_name should be the name or address of the remote instance you wish to monitor.

Example output: Similar to the local version of pw-top, you get a dynamically updating list of nodes and devices, but this time from the remote machine identified by remote_name.

Monitoring remote instance: remote_name
   ID  Name                          Type     In  Out  State   Process CPU(%) Load
  ...
    2  alsa_output.pci-0000_00_1b.0  Node     0   1    RUNNING user   1.2      0/0
    3  alsa_input.pci-0000_00_1b.0   Node     1   0    RUNNING user   0.7      0/0
  ...

Use case 3: Print information periodically instead of running in interactive mode

Code:

pw-top --batch-mode

Motivation: Interactive mode is useful for on-the-fly monitoring, but there are scenarios where you may want pw-top to produce output periodically and exit for logging, data collection, or analysis purposes. This is where --batch-mode comes in — it allows you to print the status at intervals without the interface continually updating in real-time.

Explanation: Using --batch-mode tells pw-top to print out the current state of nodes and devices and then exit, rather than continuously updating the screen. This is helpful when you need a snapshot of the current environment or when integrating with scripts that process PipeWire data.

Example output: The output will provide a snapshot of the current state of your PipeWire nodes and devices at the time of command execution.

   ID  Name                          Type     In  Out  State   Process CPU(%) Load
  ...
    5  jack_output                   Node     2   0    RUNNING user   0.8      0/0
    6  jack_input                    Node     0   2    IDLE    idle   0.1      0/0
  ...

Use case 4: Print information periodically for a specific number of times

Code:

pw-top --batch-mode --iterations 3

Motivation: Suppose you want to track the state of your PipeWire environment not continuously but periodically, and for a defined number of times. This can be useful for short-duration monitoring tasks or collecting data samples over time. By using iterations, you can specify exactly how many snapshots you want to take before the program exits.

Explanation: --batch-mode is combined with --iterations, followed by a number, in this case, 3. This tells pw-top to take three snapshots of the current state at specified intervals and print them. Perfect for situations requiring periodic outputs rather than a continuous stream.

Example output: You will see the state of nodes and devices printed three times at intervals, capturing snapshots of the system’s state across the duration.

Iteration 1
   ID  Name                          Type     In  Out  State   Process CPU(%) Load
  ...
    7  bluetooth_output              Node     1   0    RUNNING user   1.3      0/0
    8  bluetooth_input               Node     0   1    SUSPENDED idle   0.0      0/0
  ...
Iteration 2
   ID  Name                          Type     In  Out  State   Process CPU(%) Load
  ...
Iteration 3
   ID  Name                          Type     In  Out  State   Process CPU(%) Load
  ...

Conclusion

The pw-top command is a powerful tool for monitoring and managing PipeWire nodes and devices in real-time or in snapshots. Whether for interactive view, remote monitoring, or periodic data collection, pw-top offers flexibility for audio and video pipeline management and insights. It stands as an essential utility for understanding and troubleshooting PipeWire operations both locally and across networked systems.