VideoView flickering (#769)

Resolves #722 

- Fixes `VideoRendererAdapter` never actually removed from the RTC
track, causing multiple tracks concurrently rendering into the same view
- The root cause is tricks like `override func isEqual(_ object: Any?)`
won't work (anymore?) on the Obj-C++ side as it uses `==` directly; it's
also pretty fragile
- `uikit-minimal` was a good example as the number of adapters exploded
after reusing cells
  - Reproduction steps:
- create multiple cells in `uikit-minimal` - multiple participants (some
of them can be muted)
    - shuffle
    - observe cell behavior and FPS
- Moves the side effects a bit, as forcing them to be synchronous:
- was kinda unexpected (and unnecessary) when running from the main
actor `Handle track removal outside of main queue`
  - can lead to deadlocks in practice

<img width="278" height="114" alt="Screenshot 2025-08-28 at 1 37 53 PM"
src="https://github.com/user-attachments/assets/281a367d-bfeb-4422-b1fa-99cda94e299f"
/>

---------

Co-authored-by: Hiroshi Horie <548776+hiroshihorie@users.noreply.github.com>

Author: pblazej

.changes/video-view-lifecycle

@@ -0,0 +1 @@
+patch type="fixed" "Renderer lifecycle in the video view causing flickering effect"

Sources/LiveKit/Extensions/Sendable.swift

@@ -48,6 +48,7 @@ extension LKRTCDefaultAudioProcessingModule: @unchecked Swift.Sendable {}
 // MARK: Collections
 
 extension NSHashTable: @unchecked Swift.Sendable {} // cannot specify Obj-C generics
+extension NSMapTable: @unchecked Swift.Sendable {} // cannot specify Obj-C generics
 #if swift(<6.2)
 extension Dictionary: Swift.Sendable where Key: Sendable, Value: Sendable {}
 #endif

Sources/LiveKit/Protocols/VideoRenderer.swift

@@ -42,32 +42,20 @@ public protocol VideoRenderer: Sendable {
     nonisolated func render(frame: VideoFrame, captureDevice: AVCaptureDevice?, captureOptions: VideoCaptureOptions?)
 }
 
-class VideoRendererAdapter: NSObject, LKRTCVideoRenderer {
-    private weak var target: VideoRenderer?
+final class VideoRendererAdapter: NSObject, LKRTCVideoRenderer {
+    weak var renderer: VideoRenderer?
 
-    init(target: VideoRenderer) {
-        self.target = target
+    init(renderer: VideoRenderer) {
+        self.renderer = renderer
     }
 
     func setSize(_ size: CGSize) {
-        target?.set?(size: size)
+        renderer?.set?(size: size)
     }
 
     func renderFrame(_ frame: LKRTCVideoFrame?) {
         guard let frame = frame?.toLKType() else { return }
-        target?.render?(frame: frame)
-        target?.render?(frame: frame, captureDevice: nil, captureOptions: nil)
-    }
-
-    // Proxy the equality operators
-
-    override func isEqual(_ object: Any?) -> Bool {
-        guard let other = object as? VideoRendererAdapter else { return false }
-        return target === other.target
-    }
-
-    override var hash: Int {
-        guard let target else { return 0 }
-        return ObjectIdentifier(target).hashValue
+        renderer?.render?(frame: frame)
+        renderer?.render?(frame: frame, captureDevice: nil, captureOptions: nil)
     }
 }

Sources/LiveKit/Track/Remote/RemoteVideoTrack.swift

@@ -40,11 +40,13 @@ extension RemoteVideoTrack: VideoTrack {
             return
         }
 
+        let adapter = VideoRendererAdapter(renderer: videoRenderer)
+
         _state.mutate {
-            $0.videoRenderers.add(videoRenderer)
+            $0.videoRendererAdapters.setObject(adapter, forKey: videoRenderer)
         }
 
-        rtcVideoTrack.add(VideoRendererAdapter(target: videoRenderer))
+        rtcVideoTrack.add(adapter)
     }
 
     public func remove(videoRenderer: VideoRenderer) {
@@ -53,10 +55,17 @@ extension RemoteVideoTrack: VideoTrack {
             return
         }
 
-        _state.mutate {
-            $0.videoRenderers.remove(videoRenderer)
+        let adapter = _state.mutate {
+            let adapter = $0.videoRendererAdapters.object(forKey: videoRenderer)
+            $0.videoRendererAdapters.removeObject(forKey: videoRenderer)
+            return adapter
+        }
+
+        guard let adapter else {
+            log("No adapter found for videoRenderer", .warning)
+            return
         }
 
-        rtcVideoTrack.remove(VideoRendererAdapter(target: videoRenderer))
+        rtcVideoTrack.remove(adapter)
     }
 }

Sources/LiveKit/Track/Track.swift

@@ -127,8 +127,8 @@ public class Track: NSObject, @unchecked Sendable, Loggable {
         var rtpSenderForCodec: [VideoCodec: LKRTCRtpSender] = [:] // simulcastSender
         var rtpReceiver: LKRTCRtpReceiver?
 
-        // Weak reference to all VideoRenderers attached to this track.
-        var videoRenderers = NSHashTable<VideoRenderer>.weakObjects()
+        // All VideoRendererAdapters attached to this track, key/value for direct removal.
+        var videoRendererAdapters = NSMapTable<VideoRenderer, VideoRendererAdapter>.weakToStrongObjects()
     }
 
     let _state: StateSync<State>

Sources/LiveKit/TrackPublications/RemoteTrackPublication.swift

@@ -340,7 +340,7 @@ extension RemoteTrackPublication {
             return
         }
 
-        let videoRenderers = track?._state.videoRenderers.allObjects ?? []
+        let videoRenderers = track?._state.videoRendererAdapters.objectEnumerator()?.allObjects.compactMap { ($0 as? VideoRendererAdapter)?.renderer } ?? []
         let isEnabled = videoRenderers.containsOneOrMoreAdaptiveStreamEnabledRenderers()
         var dimensions: Dimensions = .zero
 

Sources/LiveKit/Views/VideoView.swift

@@ -273,16 +273,21 @@ public class VideoView: NativeView, Loggable {
             let renderModeDidUpdate = newState.renderMode != oldState.renderMode
             let trackDidUpdate = !Self.track(oldState.track as? VideoTrack, isEqualWith: newState.track as? VideoTrack)
 
+            // Always add/remove from the track asynchronously - even when called on @MainActor
             if trackDidUpdate || shouldRenderDidUpdate {
-                // Handle track removal outside of main queue
-                if let track = oldState.track as? VideoTrack {
-                    track.remove(videoRenderer: self)
+                Task {
+                    if let track = oldState.track as? VideoTrack {
+                        track.remove(videoRenderer: self)
+                    }
+                    if let track = newState.track as? VideoTrack, newState.shouldRender {
+                        track.add(videoRenderer: self)
+                    }
                 }
             }
 
-            // Enter .main only if UI updates are required
+            // Recreate renderers if necessary on @MainActor
             if trackDidUpdate || shouldRenderDidUpdate || renderModeDidUpdate {
-                mainSyncOrAsync { @MainActor in
+                Task { @MainActor in
                     var didReCreateNativeRenderer = false
 
                     if trackDidUpdate || shouldRenderDidUpdate {
@@ -316,13 +321,6 @@ public class VideoView: NativeView, Loggable {
                 }
             }
 
-            // Handle track addition outside of main queue
-            if trackDidUpdate || shouldRenderDidUpdate {
-                if let track = newState.track as? VideoTrack, newState.shouldRender {
-                    track.add(videoRenderer: self)
-                }
-            }
-
             // isRendering updated
             if newState.isRendering != oldState.isRendering {
                 log("isRendering \(oldState.isRendering) -> \(newState.isRendering)")
@@ -439,7 +437,7 @@ public class VideoView: NativeView, Loggable {
             let _didRenderFirstFrame = state.didRenderFirstFrame ? "true" : "false"
             let _isRendering = state.isRendering ? "true" : "false"
             let _renderMode = String(describing: state.renderMode)
-            let _viewCount = state.track?._state.videoRenderers.allObjects.count ?? 0
+            let _viewCount = state.track?._state.videoRendererAdapters.count ?? 0
             let debugView = ensureDebugTextView()
             debugView.text = "#\(hashValue)\n" + "\(String(describing: _trackSid))\n" + "\(_dimensions.width)x\(_dimensions.height)\n" + "isEnabled: \(isEnabled)\n" + "firstFrame: \(_didRenderFirstFrame)\n" + "isRendering: \(_isRendering)\n" + "renderMode: \(_renderMode)\n" + "viewCount: \(_viewCount)\n" + "FPS: \(_currentFPS)\n"
             debugView.frame = bounds
@@ -858,18 +856,6 @@ extension LKRTCMTLVideoView: Mirrorable {
 }
 #endif
 
-private extension VideoView {
-    nonisolated func mainSyncOrAsync(operation: @MainActor @escaping () -> Void) {
-        if Thread.current.isMainThread {
-            MainActor.assumeIsolated(operation)
-        } else {
-            Task { @MainActor in
-                operation()
-            }
-        }
-    }
-}
-
 #if os(iOS)
 extension VideoView.TransitionMode {
     func toAnimationOption(fromPosition position: AVCaptureDevice.Position? = nil) -> UIView.AnimationOptions? {