From 360b9eea471f0d8cae6568852233aa95701bfd4b Mon Sep 17 00:00:00 2001
From: Hans Dijkema <hans@dijkewijk.nl>
Date: Tue, 19 May 2026 13:35:40 +0200
Subject: [PATCH] documented some new functions

---
 scrbl/audio-player.scrbl | 34 ++++++++++++++++++++++++++++++++++
 1 file changed, 34 insertions(+)

diff --git a/scrbl/audio-player.scrbl b/scrbl/audio-player.scrbl
index d59d215..127b5a4 100644
--- a/scrbl/audio-player.scrbl
+++ b/scrbl/audio-player.scrbl
@@ -157,6 +157,40 @@ is lowered to @racket[10].  A @racket[max] below @racket[min] is changed to
 @racket[30].  The worker side applies its own safe ordering and clamping before
 using the values.  In normal use the return value is @racket['ok].}
 
+@deftogether[
+(@defproc[(audio-ao-buf-ms! [handle audio-play?]
+                            [ms integer?])
+          (or/c integer? boolean?)]
+ @defproc[(audio-ao-buf-ms [handle audio-play?])
+          (or/c integer? boolean?)])
+]{
+
+Sets or queries the libao output buffer size, expressed in milliseconds.
+
+The @racket[audio-ao-buf-ms!] procedure forwards @racket[ms] to the audio
+player backend by sending the @racket['ao-buf-ms] RPC command.  This hooks
+into the libao-side buffer configuration and can be used to tune the amount of
+audio data that the output layer keeps ahead of playback.
+
+The @racket[audio-ao-buf-ms] procedure queries the currently configured value
+by sending the same RPC command without a new value.
+
+The returned value is the value reported by the backend.  Normally this is an
+integer number of milliseconds.  A boolean result indicates that the value could
+not be set or queried, or that the backend reported a non-numeric status.
+
+Larger buffer values can make playback more robust against short scheduling
+delays, but also increase latency.  Smaller values reduce latency, but may make
+drop-outs more likely when the decoder or GUI thread is temporarily delayed.
+
+The value is clamped between 50 and 1000ms. 
+
+@racketblock[
+(audio-ao-buf-ms! player 500)
+(audio-ao-buf-ms player)
+]
+}
+
 @section{State snapshots}
 
 The player keeps a local cache of the most recent state snapshot received from