1pw-top(1)                   General Commands Manual                  pw-top(1)
2
3
4

NAME

6       pw-top - The PipeWire process viewer
7

SYNOPSIS

9       pw-top [options]
10

DESCRIPTION

12       The pw-top program provides a dynamic real-time view of the pipewire
13       node and device statistics.
14
15       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
20       The columns presented are as follows:
21
22       S
23           Node status.
24
25           • E = ERROR
26
27           • C = CREATING
28
29           • S = SUSPENDED
30
31           • I = IDLE
32
33           • R = RUNNING
34
35       ID
36           The ID of the pipewire node/device, as found in pw-dump and pw-cli
37
38       QUANT
39           The current quantum (for drivers) and the suggested quantum for
40           follower nodes.
41
42           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
46           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
49           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
53           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
57           The QUANT on the drivers usually translates directly into the
58           number of audio samples processed per processing cycle of the
59           graph.
60
61           See also
62           https://gitlab.freedesktop.org/pipewire/pipewire/-/wikis/FAQ#pipewire-
63           buffering-explained
64
65       RATE
66           The current rate (for drivers) and the suggested rate for follower
67           nodes.
68
69           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
73           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
79           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
85       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
90           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
95           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
100           A value of --- means that the node was not signaled. A value of +++
101           means that the node was signaled but not awake.
102
103       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
107           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
110       W/Q
111           Ratio of WAIT / QUANT.
112
113           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
117           Values of --- and +++ are copied from the WAIT column.
118
119       B/Q
120           Ratio of BUSY / QUANT
121
122           This is a good measure of the load of a particular driver or
123           follower node.
124
125           Values of --- and +++ are copied from the BUSY column.
126
127       ERR
128           Total of Xruns and Errors
129
130           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
135           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
139       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
143           If the stream of driver has a different rate than the graph,
144           resampling will be done.
145
146           For raw audio formats, the layout is <sampleformat> <channels>
147           <samplerate>.
148
149           For IEC958 passthrough audio formats, the layout is IEC958 <codec>
150           <samplerate>.
151
152           For DSD formats, the layout is <dsd-rate> <channels>.
153
154           For Video formats, the layout is <pixelformat> <width>x<height>.
155
156       NAME
157           Name assigned to the device/node, as found in pw-dump node.name
158
159           Names are prefixed by + when they are linked to a driver (entry
160           above with no +)
161

OPTIONS

163       -h | --help
164           Show help.
165
166       -b | --batch-mode
167           Run in non-interactive batch mode, similar to top\'s batch mode.
168
169       -n | --iterations=NUMBER
170           Exit after NUMBER of batch iterations. Only used in batch mode.
171
172       -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
176       -V | --version
177           Show version information.
178

AUTHORS

180       The PipeWire Developers
181       <https://gitlab.freedesktop.org/pipewire/pipewire/issues>; PipeWire is
182       available from <https://pipewire.org>
183

SEE ALSO

185       pipewire(1), pw-dump(1), pw-cli(1), pw-profiler(1)
186
187
188
189
190PipeWire                             1.0.0                           pw-top(1)
Impressum