From cb4f221ef93857fcae0c8687479f173a45329bc9 Mon Sep 17 00:00:00 2001
From: Christopher Head <chead@chead.ca>
Date: Mon, 13 Jan 2025 08:24:29 -0800
Subject: [PATCH] Document poor UX of sample cache for non-events

---
 src/pulse/scache.h | 6 ++++++
 1 file changed, 6 insertions(+)

diff --git a/src/pulse/scache.h b/src/pulse/scache.h
index 1be719837..66eec877f 100644
--- a/src/pulse/scache.h
+++ b/src/pulse/scache.h
@@ -37,6 +37,12 @@
  * should be played, it is stored on the server and only the command to start
  * playing it needs to be sent.
  *
+ * \note The sample cache is generally not a good choice for anything except
+ * system notification sounds (the “event” media role). While sounds in other
+ * roles technically work, playback of cached samples is done via short-lived
+ * streams which, in non-system-notification roles, may provide a poor user
+ * experience in volume control software.
+ *
  * \section create_sec Creation
  *
  * To create a sample, the normal stream API is used (see \ref streams). The