Struct pipewire_sys::pw_time

#[repr(C)]
pub struct pw_time {
    pub now: i64,
    pub rate: spa_fraction,
    pub ticks: u64,
    pub delay: i64,
    pub queued: u64,
    pub buffered: u64,
    pub queued_buffers: u32,
    pub avail_buffers: u32,
}

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:

\code{.c} 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); \endcode

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:

\code{.unparsed} (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) \endcode

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

\code{.unparsed} (pw_time.ticks + elapsed) * 1000 * pw_time.rate.num / pw_time.rate.denom \endcode

Below is an overview of the different timing values:

\code{.unparsed} stream time domain graph time domain /———————–/—————————–

queue +-+ +-+ +———–+ +––––+ ––> | | | |->| converter | -> graph -> | kernel | -> speaker <–– +-+ +-+ +———–+ +––––+ dequeue buffers -——————/-—––/ graph internal latency latency -—––/-————/-––––––––––––––/ queued buffered delay \endcode

Fields

now: i64

< 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: spa_fraction

< the rate of \a ticks and delay. This is usually expressed in 1/.

ticks: u64

< the ticks at \a now. This is the current time that the remote end is reading/writing. This is monotonicaly increasing.

delay: i64

< 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: u64

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

buffered: u64

< for audio/raw streams, this contains the extra number of samples buffered in the resampler. Since 0.3.50.

queued_buffers: u32

< The number of buffers that are queued. Since 0.3.50

avail_buffers: u32

< The number of buffers that can be dequeued. Since 0.3.50