PipeWire: pw_time Struct Reference

PipeWire 1.6.8

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

A time structure. More...

`#include <pipewire/stream.h>`

## Data Fields
int64_t | now
| the 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.
uint64_t | size
| for audio/raw playback streams, this contains the number of samples requested by the resampler for the current quantum.

## 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. This function should only be called in the STREAMING state and will return an error when called in any other state.

pw_time.ticks gives a monotonic increasing counter of the time in the graph driver. I can be used to generate a timeline 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:

uint64_t now = pw_stream_get_nsec(stream);
int64_t diff = now - pw_time.now;
int64_t elapsed = (pw_time.rate.denom * diff) / (pw_time.rate.num * SPA_NSEC_PER_SEC);
pw_stream_get_nsec
uint64_t pw_stream_get_nsec(struct pw_stream *stream)
Get the current time in nanoseconds.
Definition stream.c:2519
SPA_NSEC_PER_SEC
#define SPA_NSEC_PER_SEC
Definition defs.h:253
pw_time
A time structure.
Definition stream.h:382
pw_time::rate
struct spa_fraction rate
the rate of ticks and delay.
Definition stream.h:389
pw_time::now
int64_t now
the time in nanoseconds.
Definition stream.h:383
spa_fraction::num
uint32_t num
Definition defs.h:138
spa_fraction::denom
uint32_t denom
Definition defs.h:139

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 and extra delay offsets added to this. The delay is usually quite stable and should only change when the topology, quantum or samplerate of the graph changes.

The (positive) delay requires the application to send the stream early relative to other synchronized streams in order to arrive at the edge of the graph in time. This is usually done by delaying the other streams with the given delay.

A delay offset is sometimes added (by the user) to improve synchronization of the streams when the reported latency is incorrect in some way. This means that with a large enough negative offset, the delay can become negative as well. A negative delay in this context means that the user would like this stream to be delayed with the (positive) delay amount in order to synchronize it with other streams. Streams are in general not expected to be able to delay themselves and it is acceptable to clamp negative delays to 0.

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 time in nanoseconds.

This is the time when this time report was updated. It is usually updated every graph cycle. You can use pw_stream_get_nsec() to calculate the elapsed time between this report and the current time 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 and extra delay offsets. 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. The delay can be negative, see pw_time .

## ◆ 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.

Since 0.3.50

## ◆ size

uint64_t pw_time::size

for audio/raw playback streams, this contains the number of samples requested by the resampler for the current quantum.

for audio/raw capture streams this will be the number of samples available for the current quantum. Since 1.1.0

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

- pipewire/stream.h