fix(tracks): dispose video source and stop transceiver on unpublish

LocalVideoTrack.dispose() left its VideoSource undisposed, leaking the
source's native memory for the lifetime of the process; only the track
and capturer were released. Unpublishing a video track removed the track
from its sender but never stopped the transceiver, which is created fresh
on every publish (plus one per backup codec), so transceivers accumulated
until the connection closed.

Author: adrian-niculescu

.changeset/video-track-publish-unpublish-leaks.md

@@ -0,0 +1,5 @@
+---
+"client-sdk-android": patch
+---
+
+Fix native memory leaks on video track publish/unpublish cycles (#521). `LocalVideoTrack.dispose()` now disposes its backing `VideoSource`, which was previously left undisposed and leaked for the lifetime of the process (only the track and capturer were released). Unpublishing a video track now also stops its `RtpTransceiver`, along with any extra transceivers added for backup codecs; since a new transceiver is created on every publish, removing the track from its sender alone left them retained until the connection closed.

livekit-android-sdk/src/main/java/io/livekit/android/room/RTCEngine.kt

@@ -1498,6 +1498,21 @@ internal constructor(
         }
     }
 
+    internal fun stopTransceivers(transceivers: List<RtpTransceiver>) {
+        if (transceivers.isEmpty()) {
+            return
+        }
+        runBlocking {
+            publisher?.withPeerConnection {
+                for (transceiver in transceivers) {
+                    if (!transceiver.isStopped) {
+                        transceiver.stopInternal()
+                    }
+                }
+            }
+        }
+    }
+
     @VisibleForTesting
     fun getPublisherPeerConnection() =
         publisher!!.peerConnection

livekit-android-sdk/src/main/java/io/livekit/android/room/participant/LocalParticipant.kt

@@ -953,6 +953,15 @@ internal constructor(
 
         if (engine.connectionState == ConnectionState.CONNECTED) {
             engine.removeTrack(track.rtcTrack)
+
+            // Each publish creates a new transceiver, plus one per backup codec. Removing the
+            // track from its sender doesn't release them, so they would otherwise be retained
+            // until the connection closes. Stopping them releases the native resources and frees
+            // the SDP m-sections for reuse. Limited to video, where this leak is significant.
+            if (track is LocalVideoTrack) {
+                engine.stopTransceivers(listOfNotNull(track.transceiver) + track.simulcastTransceivers)
+                track.transceiver = null
+            }
         }
         if (stopOnUnpublish) {
             track.stop()
@@ -1198,6 +1207,7 @@ internal constructor(
                 LKLog.w { "couldn't create new transceiver! $codec" }
                 return@launch
             }
+            simulcastTrack.transceiver = transceiver
             val trackRequest = AddTrackRequest.newBuilder().apply {
                 sid = existingPublication.sid
                 muted = !track.enabled

livekit-android-sdk/src/main/java/io/livekit/android/room/track/LocalVideoTrack.kt

@@ -1,5 +1,5 @@
 /*
- * Copyright 2023-2025 LiveKit, Inc.
+ * Copyright 2023-2026 LiveKit, Inc.
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.
@@ -113,6 +113,12 @@ constructor(
     internal val sender: RtpSender?
         get() = transceiver?.sender
 
+    /**
+     * The transceivers created for additional backup codecs (e.g. when using SVC with a backup codec).
+     */
+    internal val simulcastTransceivers: List<RtpTransceiver>
+        get() = simulcastCodecs.values.mapNotNull { it.transceiver }
+
     private val closeableManager = CloseableManager()
 
     /**
@@ -141,6 +147,7 @@ constructor(
     override fun dispose() {
         super.dispose()
         capturer.dispose()
+        source.dispose()
         closeableManager.close()
     }
 
@@ -543,5 +550,6 @@ internal data class SimulcastTrackInfo(
     var codec: String,
     var rtcTrack: MediaStreamTrack,
     var sender: RtpSender? = null,
+    var transceiver: RtpTransceiver? = null,
     var encodings: List<RtpParameters.Encoding>? = null,
 )

livekit-android-test/src/main/java/io/livekit/android/test/mock/MockVideoSource.kt

@@ -1,5 +1,5 @@
 /*
- * Copyright 2023-2024 LiveKit, Inc.
+ * Copyright 2023-2026 LiveKit, Inc.
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.
@@ -18,4 +18,7 @@ package io.livekit.android.test.mock
 
 import livekit.org.webrtc.VideoSource
 
-class MockVideoSource(nativeSource: Long = 100) : VideoSource(nativeSource)
+class MockVideoSource(nativeSource: Long = 100) : VideoSource(nativeSource) {
+    override fun dispose() {
+    }
+}

livekit-android-test/src/test/java/io/livekit/android/room/participant/LocalParticipantMockE2ETest.kt

@@ -219,6 +219,73 @@ class LocalParticipantMockE2ETest : MockE2ETest() {
         assertEquals(publishOptions.stream, sentRequest.addTrack.stream)
     }
 
+    @Test
+    fun unpublishStopsVideoTransceiver() = runTest {
+        connect()
+        val videoTrack = createLocalTrack()
+        room.localParticipant.publishVideoTrack(videoTrack)
+
+        val transceiver = getPublisherPeerConnection().transceivers.first()
+        room.localParticipant.unpublishTrack(videoTrack)
+
+        Mockito.verify(transceiver).stopInternal()
+    }
+
+    @Test
+    fun unpublishStopsBackupCodecTransceivers() = runTest {
+        room.videoTrackPublishDefaults = room.videoTrackPublishDefaults.copy(
+            videoCodec = VideoCodec.VP9.codecName,
+            scalabilityMode = "L3T3",
+            backupCodec = BackupVideoCodec(codec = VideoCodec.VP8.codecName),
+        )
+
+        connect()
+        val videoTrack = createLocalTrack()
+        room.localParticipant.publishVideoTrack(videoTrack)
+
+        // Server subscribes to the backup vp8 codec, adding a second transceiver for the track.
+        wsFactory.receiveMessage(
+            with(LivekitRtc.SignalResponse.newBuilder()) {
+                subscribedQualityUpdate = with(LivekitRtc.SubscribedQualityUpdate.newBuilder()) {
+                    trackSid = room.localParticipant.videoTrackPublications.first().first.sid
+                    addAllSubscribedCodecs(
+                        listOf("vp9", "vp8").map { codecName ->
+                            with(SubscribedCodec.newBuilder()) {
+                                codec = codecName
+                                addQualities(
+                                    SubscribedQuality.newBuilder()
+                                        .setQuality(LivekitModels.VideoQuality.HIGH)
+                                        .setEnabled(true)
+                                        .build(),
+                                )
+                                build()
+                            }
+                        },
+                    )
+                    build()
+                }
+                build().toOkioByteString()
+            },
+        )
+
+        val transceivers = getPublisherPeerConnection().transceivers
+        assertEquals(2, transceivers.size)
+
+        room.localParticipant.unpublishTrack(videoTrack)
+
+        transceivers.forEach { Mockito.verify(it).stopInternal() }
+    }
+
+    @Test
+    fun disposeDisposesVideoSource() {
+        val source = mock(VideoSource::class.java)
+        val videoTrack = createLocalTrack(source = source)
+
+        videoTrack.dispose()
+
+        Mockito.verify(source).dispose()
+    }
+
     @Test
     fun updateMetadata() = runTest {
         connect()
@@ -292,9 +359,14 @@ class LocalParticipantMockE2ETest : MockE2ETest() {
         )
     }
 
-    private fun createLocalTrack(width: Int = 1280, height: Int = 720, isScreencast: Boolean = false) = LocalVideoTrack(
+    private fun createLocalTrack(
+        width: Int = 1280,
+        height: Int = 720,
+        isScreencast: Boolean = false,
+        source: VideoSource = mock(VideoSource::class.java),
+    ) = LocalVideoTrack(
         capturer = MockVideoCapturer(),
-        source = mock(VideoSource::class.java),
+        source = source,
         name = "",
         options = LocalVideoTrackOptions(
             isScreencast = isScreencast,