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

[David Henningsson]

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. */
 
     uint32_t tlength;
     /**< Playback only: target length of the buffer. The server tries
-- 
1.7.9.5