[pulseaudio-discuss] [PATCH] mention the sound card clock and system clock difference in libpulse docs

[Georg Chini]

On 19.10.2017 20:22, Tanu Kaskinen wrote:
> ---
>   src/pulse/def.h    | 19 +++++++++++++------
>   src/pulse/stream.h |  8 ++++++--
>   2 files changed, 19 insertions(+), 8 deletions(-)
>
> diff --git a/src/pulse/def.h b/src/pulse/def.h
> index 680bdc981..87b7dd40a 100644
> --- a/src/pulse/def.h
> +++ b/src/pulse/def.h
> @@ -641,8 +641,8 @@ typedef enum pa_subscription_event_type {
>    * pa_stream_update_timing_info() and pa_stream_get_timing_info(). The
>    * total output latency a sample that is written with
>    * pa_stream_write() takes to be played may be estimated by
> - * sink_usec+buffer_usec+transport_usec. (where buffer_usec is defined
> - * as pa_bytes_to_usec(write_index-read_index)) The output buffer
> + * sink_usec+buffer_usec+transport_usec (where buffer_usec is defined
> + * as pa_bytes_to_usec(write_index-read_index)). The output buffer
>    * which buffer_usec relates to may be manipulated freely (with
>    * pa_stream_write()'s seek argument, pa_stream_flush() and friends),
>    * the buffers sink_usec and source_usec relate to are first-in
> @@ -652,12 +652,19 @@ typedef enum pa_subscription_event_type {
>    * source_usec+buffer_usec+transport_usec-sink_usec. (Take care of
>    * sign issues!) When connected to a monitor source sink_usec contains
>    * the latency of the owning sink. The two latency estimations
> - * described here are implemented in pa_stream_get_latency(). Please
> - * note that this structure can be extended as part of evolutionary
> - * API updates at any time in any new release.*/
> + * described here are implemented in pa_stream_get_latency().
> + *
> + * All time values are in the sound card clock domain, unless noted
> + * otherwise. The sound card clock usually runs at a slightly different
> + * rate than the system clock.
> + *
> + * Please note that this structure can be extended as part of evolutionary
> + * API updates at any time in any new release.
> + * */
>   typedef struct pa_timing_info {
>       struct timeval timestamp;
> -    /**< The time when this timing info structure was current */
> +    /**< The system clock time when this timing info structure was
> +     * current. */
>   
>       int synchronized_clocks;
>       /**< Non-zero if the local and the remote machine have
> diff --git a/src/pulse/stream.h b/src/pulse/stream.h
> index 5dfdee1a0..7b9ba98b9 100644
> --- a/src/pulse/stream.h
> +++ b/src/pulse/stream.h
> @@ -706,7 +706,9 @@ pa_operation* pa_stream_set_name(pa_stream *s, const char *name, pa_stream_succe
>   
>   /** Return the current playback/recording time. This is based on the
>    * data in the timing info structure returned by
> - * pa_stream_get_timing_info().
> + * pa_stream_get_timing_info(). The returned time is in the sound card
> + * clock domain, which usually runs at a slightly different rate than
> + * the system clock.
>    *
>    * This function will usually only return new data if a timing info
>    * update has been received. Only if timing interpolation has been
> @@ -738,7 +740,9 @@ pa_operation* pa_stream_set_name(pa_stream *s, const char *name, pa_stream_succe
>   int pa_stream_get_time(pa_stream *s, pa_usec_t *r_usec);
>   
>   /** Determine the total stream latency. This function is based on
> - * pa_stream_get_time().
> + * pa_stream_get_time(). The returned time is in the sound card clock
> + * domain, which usually runs at a slightly different rate than the
> + * system clock.
>    *
>    * The latency is stored in \a *r_usec. In case the stream is a
>    * monitoring stream the result can be negative, i.e. the captured

Looks good to me.