From 213fbc943b5219ce4be44b53c50d8d7e9862f7da Mon Sep 17 00:00:00 2001
From: Jannis Braun <151788261+TheZwiss@users.noreply.github.com>
Date: Tue, 28 Apr 2026 15:03:22 +0200
Subject: [PATCH] docs(sounds): correct self-stream-end suppression note
 (synchronous, not deferred)

---
 docs/systems/sounds.md | 11 +++++++----
 1 file changed, 7 insertions(+), 4 deletions(-)

diff --git a/docs/systems/sounds.md b/docs/systems/sounds.md
index 842bc670..e7d59a8c 100644
--- a/docs/systems/sounds.md
+++ b/docs/systems/sounds.md
@@ -99,10 +99,13 @@ disconnecting participant identity from every watcher set
 side at that point.
 
 **Self-stream-end suppression.** When the streamer themselves stops sharing,
-SoundController detects this in the same set-diff that fires `stream_ended`.
-For that one tick, both the previous and current watcher sets are treated as
-empty (no per-watcher sounds), and the store entry is cleared via a deferred
-`clearStreamWatchers` call so the next subscribe tick sees prev=current=∅.
+SoundController detects this in the same set-diff that fires `stream_ended`
+and synchronously calls `clearStreamWatchers(myUserId)`. The watcher diff is
+gated on `selfIsSharing` (which is now false), so neither the outer
+subscriber tick nor the re-entered subscriber tick triggered by the clear
+fires any per-watcher sound. The same gate also makes a stop-then-restart
+cycle fire `clearStreamWatchers` on `selfStreamJustStarted`, dropping any
+stale watcher entries from the previous run.
 
 **Why not `LocalTrackSubscribed`?** Insufficient: fires only for the first
 subscriber and has no unsubscribe counterpart in LiveKit JS 2.17.