179 lines
5.4 KiB
ReStructuredText
179 lines
5.4 KiB
ReStructuredText
pw-top
|
|
######
|
|
|
|
---------------------------
|
|
The PipeWire process viewer
|
|
---------------------------
|
|
|
|
:Manual section: 1
|
|
:Manual group: General Commands Manual
|
|
|
|
SYNOPSIS
|
|
========
|
|
|
|
| **pw-top** [*options*]
|
|
|
|
DESCRIPTION
|
|
===========
|
|
|
|
The *pw-top* program provides a dynamic real-time view of the pipewire
|
|
node and device statistics.
|
|
|
|
A hierarchical view is shown of Driver nodes and follower nodes. The Driver
|
|
nodes are actively using a timer to schedule dataflow in the followers. The
|
|
followers of a driver node as shown below their driver with a + sign in
|
|
a tree-like representation.
|
|
|
|
The columns presented are as follows:
|
|
|
|
S
|
|
Node status.
|
|
E = ERROR
|
|
C = CREATING
|
|
S = SUSPENDED
|
|
I = IDLE
|
|
R = RUNNING
|
|
|
|
ID
|
|
The ID of the pipewire node/device, as found in *pw-dump* and *pw-cli*
|
|
|
|
QUANT
|
|
The current quantum (for drivers) and the suggested quantum for follower
|
|
nodes.
|
|
|
|
The quantum by itself needs to be divided by the RATE column to calculate
|
|
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 that the node does not
|
|
have a suggestion for the quantum and thus uses what the driver selected.
|
|
|
|
The driver will use the lowest quantum of any of the followers. If none of
|
|
the followers select a quantum, the default quantum in the pipewire configuration
|
|
file will be used.
|
|
|
|
The QUANT on the drivers 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 needs to be combined with
|
|
the QUANT value to derive the duration of a processing cycle in the graph.
|
|
|
|
Some nodes can have a 0 RATE, which means that they don't have any rate
|
|
suggestion for the graph. Nodes that suggest a rate can make the graph switch
|
|
rates 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 is 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. The WAIT time for driver is thus the elapsed time
|
|
processing the graph.
|
|
|
|
For follower nodes, it is the time spent between being woken up (when all
|
|
dependencies of the node are satisfied) and when processing starts. The
|
|
WAIT time for follower nodes is thus mostly caused by context switching.
|
|
|
|
A value of --- means that the node was not signaled. A value of +++
|
|
means that the node was signaled but not awake.
|
|
|
|
BUSY
|
|
The processing time is started when the node starts processing until it
|
|
completes and wakes up the next nodes in the graph.
|
|
|
|
A value of --- means that the node was not started. A value of +++
|
|
means that 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 of driver has a different rate than the graph, resampling will
|
|
be done.
|
|
|
|
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, as found in *pw-dump* node.name
|
|
|
|
Names are prefixed by *+* when they are linked to a driver (entry above with no +)
|
|
|
|
|
|
OPTIONS
|
|
=======
|
|
|
|
-h | --help
|
|
Show help.
|
|
|
|
-r | --remote=NAME
|
|
The name the *remote* instance to monitor. If left unspecified,
|
|
a connection is made to the default PipeWire instance.
|
|
|
|
--version
|
|
Show version information.
|
|
|
|
|
|
AUTHORS
|
|
=======
|
|
|
|
The PipeWire Developers <@PACKAGE_BUGREPORT@>; PipeWire is available from @PACKAGE_URL@
|
|
|
|
SEE ALSO
|
|
========
|
|
|
|
``pipewire(1)``,
|
|
``pw-dump(1)``,
|
|
``pw-cli(1)``,
|
|
``pw-profiler(1)``,
|
|
|