1pw-top(1) General Commands Manual pw-top(1)
2
6 pw-top - The PipeWire process viewer
7
9 pw-top [options]
10
12 The pw-top program provides a dynamic real-time view of the pipewire
13 node and device statistics.
14 A hierarchical view is shown of Driver nodes and follower nodes. The
16 Driver nodes are actively using a timer to schedule dataflow in the
17 followers. The followers of a driver node as shown below their driver
18 with a + sign in a tree-like representation.
19 The columns presented are as follows:
21 S
23 Node status.
24 • E = ERROR
26 • C = CREATING
28 • S = SUSPENDED
30 • I = IDLE
32 • R = RUNNING
34 ID
36 The ID of the pipewire node/device, as found in pw-dump and pw-cli
37 QUANT
39 The current quantum (for drivers) and the suggested quantum for
40 follower nodes.
41 The quantum by itself needs to be divided by the RATE column to
43 calculate the duration of a scheduling period in fractions of a
44 second.
45 For a QUANT of 1024 and a RATE of 48000, the duration of one period
47 in the graph is 1024/48000 or 21.3 milliseconds.
48 Follower nodes can have a 0 QUANT field, which means that the node
50 does not have a suggestion for the quantum and thus uses what the
51 driver selected.
52 The driver will use the lowest quantum of any of the followers. If
54 none of the followers select a quantum, the default quantum in the
55 pipewire configuration file will be used.
56 The QUANT on the drivers usually translates directly into the
58 number of audio samples processed per processing cycle of the
59 graph.
60 See also
62 https://gitlab.freedesktop.org/pipewire/pipewire/-/wikis/FAQ#pipewire-
63 buffering-explained
64 RATE
66 The current rate (for drivers) and the suggested rate for follower
67 nodes.
68 This is the rate at which the graph processes data and needs to be
70 combined with the QUANT value to derive the duration of a
71 processing cycle in the graph.
72 Some nodes can have a 0 RATE, which means that they don\'t have any
74 rate suggestion for the graph. Nodes that suggest a rate can make
75 the graph switch rates if the graph is otherwise idle and the new
76 rate is allowed as a possible graph rate (see the pipewire
77 configuration file).
78 The RATE on (audio) driver nodes usually also translates directly
80 to the samplerate used by the device. Although some devices might
81 not be able to operate at the given samplerate, in which case
82 resampling will need to be done. The negotiated samplerate with the
83 device and stream can be found in the FORMAT column.
84 WAIT
86 The waiting time of a node is the elapsed time between when the
87 node is ready to start processing and when it actually started
88 processing.
89 For Driver nodes, this is the time between when the node wakes up
91 to start processing the graph and when the driver (and thus also
92 the graph) completes a cycle. The WAIT time for driver is thus the
93 elapsed time processing the graph.
94 For follower nodes, it is the time spent between being woken up
96 (when all dependencies of the node are satisfied) and when
97 processing starts. The WAIT time for follower nodes is thus mostly
98 caused by context switching.
99 A value of --- means that the node was not signaled. A value of +++
101 means that the node was signaled but not awake.
102 BUSY
104 The processing time is started when the node starts processing
105 until it completes and wakes up the next nodes in the graph.
106 A value of --- means that the node was not started. A value of +++
108 means that the node was started but did not complete.
109 W/Q
111 Ratio of WAIT / QUANT.
112 The W/Q time of the driver node is a good measure of the graph
114 load. The running averages of the driver W/Q ratios are used as the
115 DSP load in other (JACK) tools.
116 Values of --- and +++ are copied from the WAIT column.
118 B/Q
120 Ratio of BUSY / QUANT
121 This is a good measure of the load of a particular driver or
123 follower node.
124 Values of --- and +++ are copied from the BUSY column.
126 ERR
128 Total of Xruns and Errors
129 Xruns for drivers are when the graph did not complete a cycle. This
131 can be because a node in the graph also has an Xrun. It can also be
132 caused when scheduling delays cause a deadline to be missed,
133 causing a hardware Xrun.
134 Xruns for followers are incremented when the node started
136 processing but did not complete before the end of the graph cycle
137 deadline.
138 FORMAT
140 The format used by the driver node or the stream. This is the
141 hardware format negotiated with the device or stream.
142 If the stream of driver has a different rate than the graph,
144 resampling will be done.
145 For raw audio formats, the layout is <sampleformat> <channels>
147 <samplerate>.
148 For IEC958 passthrough audio formats, the layout is IEC958 <codec>
150 <samplerate>.
151 For DSD formats, the layout is <dsd-rate> <channels>.
153 For Video formats, the layout is <pixelformat> <width>x<height>.
155 NAME
157 Name assigned to the device/node, as found in pw-dump node.name
158 Names are prefixed by + when they are linked to a driver (entry
160 above with no +)
161
163 -h | --help
164 Show help.
165 -b | --batch-mode
167 Run in non-interactive batch mode, similar to top\'s batch mode.
168 -n | --iterations=NUMBER
170 Exit after NUMBER of batch iterations. Only used in batch mode.
171 -r | --remote=NAME
173 The name the remote instance to monitor. If left unspecified, a
174 connection is made to the default PipeWire instance.
175 -V | --version
177 Show version information.
178
180 The PipeWire Developers
181 <https://gitlab.freedesktop.org/pipewire/pipewire/issues>; PipeWire is
182 available from <https://pipewire.org>
183
185 pipewire(1), pw-dump(1), pw-cli(1), pw-profiler(1)
186PipeWire 1.0.0 pw-top(1)