player agent gui script for exe

scribblings/rkt-web-player.scrbl

@@ -124,6 +124,21 @@ renderers. The server can prefetch the next track to an agent for gapless
 transitions. A 256-bit application ID identifies the agent; the server's
 @tt{[playback-agents]} allowlist decides which agents may connect.
 
+Both agents retain downloaded tracks in a local disk cache with a budget of
+1 GB (1,000,000,000 bytes), evicting the least recently used tracks first.
+Selecting a cached track reuses its local file when the server address, source
+path, file size and modification time still match. Changing the source file's
+size or modification time causes a new download. Older servers without this
+metadata only allow reuse for the same media token.
+Files in use for playback or prefetch are protected, so those files and an
+in-progress download can temporarily exceed the budget. The cache lasts until
+the agent exits; it is not retained across restarts.
+
+A track that is not cached is still downloaded completely before playback.
+The next track is fetched after the play command completes. Commands are
+processed in server order, so a pending prefetch can still delay a later manual
+track selection.
+
 @defproc[(run-web-player
           [music-paths (listof (or/c path-string?
                                      (list/c string? path-string?)))]