[pulseaudio-discuss] [PATCH v2 3/3] client API: Document buffer_attr.maxlength

[Tanu Kaskinen]

On Thu, 2013-03-21 at 19:10 +0100, David Henningsson wrote:
> Let's officially support that people use maxlength to put an upper
> bound on playback latency.
> 
> Signed-off-by: David Henningsson <david.henningsson at canonical.com>
> ---
>  src/pulse/def.h |    8 +++++++-
>  1 file changed, 7 insertions(+), 1 deletion(-)
> 
> diff --git a/src/pulse/def.h b/src/pulse/def.h
> index 495302f..79d93e1 100644
> --- a/src/pulse/def.h
> +++ b/src/pulse/def.h
> @@ -360,7 +360,13 @@ typedef struct pa_buffer_attr {
>      uint32_t maxlength;
>      /**< Maximum length of the buffer in bytes. Setting this to (uint32_t) -1
>       * will initialize this to the maximum value supported by server,
> -     * which is recommended. */
> +     * which is recommended.
> +     *
> +     * In strict low-latency playback scenarios you might want to set this to
> +     * a lower value, likely together with the PA_STREAM_ADJUST_LATENCY flag.
> +     * If you do so, you will get underflows instead of increasing latency
> +     * if PulseAudio cannot deliver the latency you requested, so this is not
> +     * recommended unless you know what you're doing. */

"Underflows instead of increasing latency" sounds like there wouldn't be
underruns at all if maxlength is big enough, and also like the latency
wouldn't still increase if maxlength is low (currently, the sink latency
will increase regardless of the stream buffer settings, it's only
tlength that will stop increasing). I think it would be better to say
that maxlength sets the upper limit for tlength. When tlength reaches
maxlength, device underruns won't increase the tlength anymore.

So, maxlength doesn't currently set any cap for the sink latency. The
stream buffer maxlength parameter only limits the stream buffer size.
Perhaps we should limit the sink buffering too based on the stream
buffer maxlength, though?

Another thing is that we don't increase tlength on stream buffer
underruns (not even on "real" stream underruns, as long as we don't have
an alsa underrun). Since it looks like we already have a mechanism for
applications to state the absolute maximum latency that they are ready
to accept, perhaps we should be more liberal in increasing the tlength,
and bump it whenever a stream underrun happens?

-- 
Tanu