PipeWire: pw_time Struct Reference

PipeWire 1.0.3

Loading...
Searching...
No Matches
Data Fields
pw_time Struct Reference
Stream

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 samples 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);
SPA_NSEC_PER_SEC
#define SPA_NSEC_PER_SEC
Definition defs.h:235
SPA_TIMESPEC_TO_NSEC
#define SPA_TIMESPEC_TO_NSEC(ts)
Definition defs.h:248
pw_time
A time structure.
Definition stream.h:295
pw_time::rate
struct spa_fraction rate
the rate of ticks and delay.
Definition stream.h:302
pw_time::now
int64_t now
the monotonic time in nanoseconds.
Definition stream.h:296
spa_fraction::num
uint32_t num
Definition defs.h:124
spa_fraction::denom
uint32_t denom
Definition defs.h:125

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 or bytes (below expressed as app.rate).

pw_time.buffered is format dependent, for audio/raw it contains the number of samples 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 samples 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.

Since 0.3.50

The documentation for this struct was generated from the following file:

- pipewire/stream.h