A time structure. More...

#include <pipewire/stream.h>

Data Fields
int64_t	now
	the monotonic time in nanoseconds.

struct spa_fraction	rate
	the rate of ticks and delay.

uint64_t	ticks
	the ticks at now.

int64_t	delay
	delay to device.

uint64_t	queued
	data queued in the stream, this is the sum of the size fields in the pw_buffer that are currently queued

uint64_t	buffered
	for audio/raw streams, this contains the extra number of frames buffered in the resampler.

uint32_t	queued_buffers
	The number of buffers that are queued.

uint32_t	avail_buffers
	The number of buffers that can be dequeued.

Detailed Description

A time structure.

Use pw_stream_get_time_n() to get an updated time snapshot of the stream. The time snapshot can give information about the time in the driver of the graph, the delay to the edge of the graph and the internal queuing in the stream.

pw_time.ticks gives a monotonic increasing counter of the time in the graph driver. I can be used to generate a timetime to schedule samples as well as detect discontinuities in the timeline caused by xruns.

pw_time.delay is expressed as pw_time.rate, the time domain of the graph. This value, and pw_time.ticks, were captured at pw_time.now and can be extrapolated to the current time like this:

struct timespec ts;
clock_gettime(CLOCK_MONOTONIC, &ts);
int64_t diff = SPA_TIMESPEC_TO_NSEC(&ts) - pw_time.now;
int64_t elapsed = (pw_time.rate.denom * diff) / (pw_time.rate.num * SPA_NSEC_PER_SEC);

pw_time.delay contains the total delay that a signal will travel through the graph. This includes the delay caused by filters in the graph as well as delays caused by the hardware. The delay is usually quite stable and should only change when the topology, quantum or samplerate of the graph changes.

pw_time.queued and pw_time.buffered is expressed in the time domain of the stream, or the format that is used for the buffers of this stream.

pw_time.queued is the sum of all the pw_buffer.size fields of the buffers that are currently queued in the stream but not yet processed. The application can choose the units of this value, for example, time, samples, frames or bytes (below expressed as app.rate).

pw_time.buffered is format dependent, for audio/raw it contains the number of frames that are buffered inside the resampler/converter.

The total delay of data in a stream is the sum of the queued and buffered data (not yet processed data) and the delay to the edge of the graph, usually a playback or capture device.

For an audio playback stream, if you were to queue a buffer, the total delay in milliseconds for the first sample in the newly queued buffer to be played by the hardware can be calculated as:

(pw_time.buffered * 1000 / stream.samplerate) +
  (pw_time.queued * 1000 / app.rate) +
   ((pw_time.delay - elapsed) * 1000 * pw_time.rate.num / pw_time.rate.denom)

The current extrapolated time (in ms) in the source or sink can be calculated as:

(pw_time.ticks + elapsed) * 1000 * pw_time.rate.num / pw_time.rate.denom

Below is an overview of the different timing values:

          stream time domain           graph time domain
        /-----------------------\/-----------------------------\
 
queue     +-+ +-+  +-----------+                 +--------+
---->     | | | |->| converter | ->   graph  ->  | kernel | -> speaker
<----     +-+ +-+  +-----------+                 +--------+
dequeue   buffers                \-------------------/\--------/
                                    graph              internal
                                   latency             latency
        \--------/\-------------/\-----------------------------/
          queued      buffered            delay

Field Documentation

◆ now

int64_t pw_time::now

the monotonic time in nanoseconds.

This is the time when this time report was updated. It is usually updated every graph cycle. You can use the current monotonic time to calculate the elapsed time between this report and the current state and calculate updated ticks and delay values.

◆ rate

struct spa_fraction pw_time::rate

the rate of ticks and delay.

This is usually expressed in 1/<samplerate>.

◆ ticks

uint64_t pw_time::ticks

the ticks at now.

This is the current time that the remote end is reading/writing. This is monotonicaly increasing.

◆ delay

int64_t pw_time::delay

delay to device.

This is the time it will take for the next output sample of the stream to be presented by the playback device or the time a sample traveled from the capture device. This delay includes the delay introduced by all filters on the path between the stream and the device. The delay is normally constant in a graph and can change when the topology of the graph or the quantum changes. This delay does not include the delay caused by queued buffers.

◆ queued

uint64_t pw_time::queued

data queued in the stream, this is the sum of the size fields in the pw_buffer that are currently queued

◆ buffered

uint64_t pw_time::buffered

for audio/raw streams, this contains the extra number of frames buffered in the resampler.

Since 0.3.50.

◆ queued_buffers

uint32_t pw_time::queued_buffers

The number of buffers that are queued.

Since 0.3.50

◆ avail_buffers

uint32_t pw_time::avail_buffers

The number of buffers that can be dequeued.