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
11

DESCRIPTION

13       The  pw-top  program  provides a dynamic real-time view of the pipewire
14       node and device statistics.
15
16       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
21       The columns presented are as follows:
22
23       S
24
25              Node status.
26                     E = ERROR C = CREATING S = SUSPENDED I = IDLE R = RUNNING
27
28       ID     The  ID  of  the  pipewire  node/device, as found in pw-dump and
29              pw-cli
30
31       QUANT  The current quantum (for drivers) and the suggested quantum  for
32              follower nodes.
33
34              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
38              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
41              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
45              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
49              The QUANT on the drivers usually translates  directly  into  the
50              number  of  audio  samples processed per processing cycle of the
51              graph.
52
53              See                                                         also
54              https://gitlab.freedesktop.org/pipewire/pipewire/-/wikis/FAQ#pipewire-buffering-explained
55
56       RATE   The current rate (for drivers) and the suggested rate  for  fol‐
57              lower nodes.
58
59              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
63              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
69              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
76       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
80              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
85              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
90              A value of --- means that the node was not signaled.  A value of
91              +++ means that the node was signaled but not awake.
92
93       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
96              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
99       W/Q    Ratio of WAIT / QUANT.
100
101              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
105              Values of --- and +++ are copied from the WAIT column.
106
107       B/Q    Ratio of BUSY / QUANT
108
109              This  is  a  good  measure of the load of a particular driver or
110              follower node.
111
112              Values of --- and +++ are copied from the BUSY column.
113
114       ERR    Total of Xruns and Errors
115
116              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
121              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
125       FORMAT The  format  used  by the driver node or the stream. This is the
126              hardware format negotiated with the device or stream.
127
128              If the stream of driver has a different rate than the graph, re‐
129              sampling will be done.
130
131              For  raw  audio formats, the layout is <sampleformat> <channels>
132              <samplerate>.
133
134              For IEC958 passthrough  audio  formats,  the  layout  is  IEC958
135              <codec> <samplerate>.
136
137              For DSD formats, the layout is <dsd-rate> <channels>.
138
139              For Video formats, the layout is <pixelformat> <width>x<height>.
140
141       NAME   Name assigned to the device/node, as found in pw-dump node.name
142
143              Names  are prefixed by + when they are linked to a driver (entry
144              above with no +)
145

OPTIONS

147       -h | --help
148              Show help.
149
150       -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
154       --version
155              Show version information.
156

AUTHORS

158       The                PipeWire                Developers                <‐
159       https://gitlab.freedesktop.org/pipewire/pipewire/issues>;  PipeWire  is
160       available from https://pipewire.org
161

SEE ALSO

163       pipewire(1), pw-dump(1), pw-cli(1), pw-profiler(1),
164
165
166
167
168                                                                     PW-TOP(1)
Impressum