pw-top(1)

📦
version 1.6.11 · 13 versions
, in fedora 44

💅 pw-top — the PipeWire process viewer (manual, section 1)

okay so bestie, sit down, hydrate, and let me tell you about pw-top 🎀 it lives in the general commands manual, it's section 1, and it is literally the moment your terminal becomes a little aquarium of PipeWire nodes. 🌊

✨ SYNOPSIS ✨

pw-top [options]

that's it. that's the whole vibe. 🫶

🦋 DESCRIPTION 🦋

pw-top gives you a dynamic, real-time view of your pipewire node and device statistics. live. continuously updating. main character energy for your audio graph. ✨

What you get is a hierarchical view: Driver nodes up top, follower nodes hanging below them.

  • The Driver nodes are the ones actively using a timer to schedule the dataflow in the followers.
  • The followers of a driver node show up below their driver, marked with a + sign — or an = for async nodes — in a little tree-like representation. 🌳

Now, the columns. Here's the tea, one by one:

S

Node status. the mood ring of your node:

  • E = ERROR 💀
  • C = CREATING
  • S = SUSPENDED 😴
  • I = IDLE
  • R = RUNNING 🔥
  • t = RUNNING + transport starting
  • T = RUNNING + transport running

ID

The ID of the pipewire node/device — the same one you'd find in pw-dump and pw-cli. iykyk 🔍

QUANT

The current quantum (for drivers) and the suggested quantum for follower nodes.

Heads up bestie: the quantum by itself needs to be divided by the RATE column to get the duration of a scheduling period, in fractions of a second.

For a QUANT of 1024 and a RATE of 48000, the duration of one period in the graph is 1024/48000 — or 21.3 milliseconds. 🧮

Follower nodes can have a 0 QUANT field, which means the node has no suggestion for the quantum and so it just uses whatever the driver selected. no thoughts, head empty.

The driver will use the lowest quantum of any of the followers. And if none of the followers select a quantum, the default quantum in the pipewire configuration file gets used.

For drivers, the QUANT usually translates directly into the number of audio samples processed per processing cycle of the graph. 🎧

See also https://gitlab.freedesktop.org/pipewire/pipewire/-/wikis/FAQ#pipewire-buffering-explained

RATE

The current rate (for drivers) and the suggested rate for follower nodes.

This is the rate at which the graph processes data, and you need to combine it with the QUANT value to derive the duration of a processing cycle in the graph. ⏱️

Some nodes can have a 0 RATE, which means they don't have any rate suggestion for the graph. Nodes that do suggest a rate can make the graph switch rates — but only if the graph is otherwise idle and the new rate is allowed as a possible graph rate (see the pipewire configuration file).

The RATE on (audio) driver nodes usually also translates directly to the samplerate used by the device. although... some devices might not be able to operate at the given samplerate, in which case resampling will need to be done 🙈. The negotiated samplerate with the device and stream can be found in the FORMAT column.

WAIT

The waiting time of a node = the elapsed time between when the node is ready to start processing and when it actually started processing.

  • For Driver nodes, this is the time between when the node wakes up to start processing the graph and when the driver (and thus also the graph) completes a cycle. So the WAIT time for a driver is the elapsed time processing the graph.
  • For follower nodes, it's the time spent between being woken up (when all dependencies of the node are satisfied) and when processing starts. So the WAIT time for followers is mostly caused by context switching.

A value of --- means the node was not signaled. A value of +++ means the node was signaled but not awake. 💤

BUSY

The processing time: started when the node starts processing, until it completes and wakes up the next nodes in the graph.

A value of --- means the node was not started. A value of +++ means the node was started but did not complete. 😭

W/Q

Ratio of WAIT / QUANT.

The W/Q time of the driver node is a good measure of the graph load. The running averages of the driver W/Q ratios are used as the DSP load in other (JACK) tools. 📊

Values of --- and +++ are copied from the WAIT column.

B/Q

Ratio of BUSY / QUANT.

This is a good measure of the load of a particular driver or follower node. 👑

Values of --- and +++ are copied from the BUSY column.

ERR

Total of Xruns and Errors. 💀

  • Xruns for drivers are when the graph did not complete a cycle. This can be because a node in the graph also has an Xrun. It can also be caused when scheduling delays cause a deadline to be missed, causing a hardware Xrun.
  • Xruns for followers are incremented when the node started processing but did not complete before the end of the graph cycle deadline.

FORMAT

The format used by the driver node or the stream. This is the hardware format negotiated with the device or stream.

If the stream or driver has a different rate than the graph, resampling will be done. 🔁

Here's how the layouts go:

  • For raw audio formats, the layout is <sampleformat> <channels> <samplerate>.
  • For IEC958 passthrough audio formats, the layout is IEC958 <codec> <samplerate>.
  • For DSD formats, the layout is <dsd-rate> <channels>.
  • For Video formats, the layout is <pixelformat> <width>x<height>.

NAME

Name assigned to the device/node — same as pw-dump node.name 🔖

Names get prefixed by +/*=* when they are linked to a driver (the entry above with no +/=). 🌈

🎀 COMMANDS 🎀

These keys work in interactive mode:

  • q — Quit. bye bestie 👋
  • c — Clear the ERR counters. Lowkey important: this does not clear the counters globally, it will only reset the counters in this instance of pw-top. 🧼

💖 OPTIONS 💖

  • -h | --help — Show help.
  • -b | --batch-mode — Run in non-interactive batch mode, similar to top's batch mode.
  • -n | --iterations=NUMBER — Exit after NUMBER of batch iterations. Only used in batch mode.
  • -r | --remote=NAME — The name the remote instance to monitor. If left unspecified, a connection is made to the default PipeWire instance.
  • -V | --version — Show version information.

👑 AUTHORS 👑

The PipeWire Developers — https://gitlab.freedesktop.org/pipewire/pipewire/issues — and PipeWire is available from https://pipewire.org 🫶

🌸 SEE ALSO 🌸

pipewire(1), pw-dump(1), pw-cli(1), pw-profiler(1)

and that's the whole page, bestie ✨ this was PipeWire, version 1.6.11, and it's filed under the section 1 manual pages — slay, have fun graphing, mwah 💅🎀🦋

📦 where this page comes from