doc clarity

Author: stephen-derosa

README.md

@@ -263,9 +263,9 @@ The following features are deprecated and will be removed in the next major rele
 - `Room::setOnAudioFrameCallback`, `Room::setOnVideoFrameCallback`, and
   `Room::setOnVideoFrameEventCallback` are deprecated. Use the `[[nodiscard]]`
   variants `trySetOnAudioFrameCallback`, `trySetOnVideoFrameCallback`, and
-  `trySetOnVideoFrameEventCallback` instead, which return `false` when a
-  callback is already registered rather than silently replacing it. To replace
-  an active callback, call `clearOn*FrameCallback` first. (The same rename
+  `trySetOnVideoFrameEventCallback` instead, which return `false` when a reader
+  is already active for the key (instead of silently replacing a running callback).
+  To replace an active callback, call `clearOn*FrameCallback` first. (The same rename
   applies to the corresponding `SubscriptionThreadDispatcher` methods.)
 
 ### `v1.0.0`

include/livekit/subscription_thread_dispatcher.h

@@ -384,8 +384,9 @@ class LIVEKIT_API SubscriptionThreadDispatcher {
 
   /// Select the appropriate reader startup path for @p media track.
   ///
-  /// This is called by @ref Room when a remote track is subscribed. If a reader is already active for the given key,
-  /// std::thread default constructed is returned.
+  /// This is called by @ref Room when a remote track is subscribed. If a reader for the same track SID is already
+  /// active, startup is skipped and a default-constructed thread is returned; otherwise any previous reader is
+  /// extracted and returned to the caller for joining outside the lock.
   ///
   /// Must be called with @ref lock_ held.
   std::thread startReaderLocked(const CallbackKey& key, const std::shared_ptr<Track>& track);