1PW-TOP(1) General Commands Manual PW-TOP(1)
2
6 pw-top - The PipeWire process viewer
7
9 pw-top [options]
10
13 The pw-top program provides a dynamic real-time view of the pipewire
14 node and device statistics.
15 A hierarchical view is shown of Driver nodes and follower nodes. The
17 Driver nodes are actively using a timer to schedule dataflow in the
18 followers. The followers of a driver node as shown below their driver
19 with a + sign in a tree-like representation.
20 The columns presented are as follows:
22 S
24 Node status.
26 E = ERROR C = CREATING S = SUSPENDED I = IDLE R = RUNNING
27 ID The ID of the pipewire node/device, as found in pw-dump and
29 pw-cli
30 QUANT The current quantum (for drivers) and the suggested quantum for
32 follower nodes.
33 The quantum by itself needs to be divided by the RATE column to
35 calculate the duration of a scheduling period in fractions of a
36 second.
37 For a QUANT of 1024 and a RATE of 48000, the duration of one pe‐
39 riod in the graph is 1024/48000 or 21.3 milliseconds.
40 Follower nodes can have a 0 QUANT field, which means that the
42 node does not have a suggestion for the quantum and thus uses
43 what the driver selected.
44 The driver will use the lowest quantum of any of the followers.
46 If none of the followers select a quantum, the default quantum
47 in the pipewire configuration file will be used.
48 The QUANT on the drivers usually translates directly into the
50 number of audio samples processed per processing cycle of the
51 graph.
52 See also
54 https://gitlab.freedesktop.org/pipewire/pipewire/-/wikis/FAQ#pipewire-buffering-explained
55 RATE The current rate (for drivers) and the suggested rate for fol‐
57 lower nodes.
58 This is the rate at which the graph processes data and needs to
60 be combined with the QUANT value to derive the duration of a
61 processing cycle in the graph.
62 Some nodes can have a 0 RATE, which means that they don't have
64 any rate suggestion for the graph. Nodes that suggest a rate can
65 make the graph switch rates if the graph is otherwise idle and
66 the new rate is allowed as a possible graph rate (see the
67 pipewire configuration file).
68 The RATE on (audio) driver nodes usually also translates di‐
70 rectly to the samplerate used by the device. Although some de‐
71 vices might not be able to operate at the given samplerate, in
72 which case resampling will need to be done. The negotiated sam‐
73 plerate with the device and stream can be found in the FORMAT
74 column.
75 WAIT The waiting time of a node is the elapsed time between when the
77 node is ready to start processing and when it actually started
78 processing.
79 For Driver nodes, this is the time between when the node wakes
81 up to start processing the graph and when the driver (and thus
82 also the graph) completes a cycle. The WAIT time for driver is
83 thus the elapsed time processing the graph.
84 For follower nodes, it is the time spent between being woken up
86 (when all dependencies of the node are satisfied) and when pro‐
87 cessing starts. The WAIT time for follower nodes is thus mostly
88 caused by context switching.
89 A value of --- means that the node was not signaled. A value of
91 +++ means that the node was signaled but not awake.
92 BUSY The processing time is started when the node starts processing
94 until it completes and wakes up the next nodes in the graph.
95 A value of --- means that the node was not started. A value of
97 +++ means that the node was started but did not complete.
98 W/Q Ratio of WAIT / QUANT.
100 The W/Q time of the driver node is a good measure of the graph
102 load. The running averages of the driver W/Q ratios are used as
103 the DSP load in other (JACK) tools.
104 Values of --- and +++ are copied from the WAIT column.
106 B/Q Ratio of BUSY / QUANT
108 This is a good measure of the load of a particular driver or
110 follower node.
111 Values of --- and +++ are copied from the BUSY column.
113 ERR Total of Xruns and Errors
115 Xruns for drivers are when the graph did not complete a cycle.
117 This can be because a node in the graph also has an Xrun. It can
118 also be caused when scheduling delays cause a deadline to be
119 missed, causing a hardware Xrun.
120 Xruns for followers are incremented when the node started pro‐
122 cessing but did not complete before the end of the graph cycle
123 deadline.
124 FORMAT The format used by the driver node or the stream. This is the
126 hardware format negotiated with the device or stream.
127 If the stream of driver has a different rate than the graph, re‐
129 sampling will be done.
130 For raw audio formats, the layout is <sampleformat> <channels>
132 <samplerate>.
133 For IEC958 passthrough audio formats, the layout is IEC958
135 <codec> <samplerate>.
136 For DSD formats, the layout is <dsd-rate> <channels>.
138 For Video formats, the layout is <pixelformat> <width>x<height>.
140 NAME Name assigned to the device/node, as found in pw-dump node.name
142 Names are prefixed by + when they are linked to a driver (entry
144 above with no +)
145
147 -h | --help
148 Show help.
149 -r | --remote=NAME
151 The name the remote instance to monitor. If left unspecified, a
152 connection is made to the default PipeWire instance.
153 --version
155 Show version information.
156
158 The PipeWire Developers <‐
159 https://gitlab.freedesktop.org/pipewire/pipewire/issues>; PipeWire is
160 available from https://pipewire.org
161
163 pipewire(1), pw-dump(1), pw-cli(1), pw-profiler(1),
164 PW-TOP(1)