PipeWire: pw-top

PipeWire 0.3.69

Loading...
Searching...
No Matches
pw-top

    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)``,