From 2fef791fecfab9bda9a4f129f7db3b60cbb524ce Mon Sep 17 00:00:00 2001 From: divar Date: Sat, 7 Nov 2026 14:39:59 +0330 Subject: [PATCH 1/3] Add selected ICE candidate pair change event --- .../selected-ice-candidate-pair-event.md | 5 + .../io/livekit/android/events/RoomEvent.kt | 13 ++ .../room/PublisherTransportObserver.kt | 8 +- .../java/io/livekit/android/room/RTCEngine.kt | 1 + .../main/java/io/livekit/android/room/Room.kt | 8 + .../android/room/SelectedIceCandidatePair.kt | 191 ++++++++++++++++++ .../room/SubscriberTransportObserver.kt | 8 +- .../android/test/mock/MockIceCandidates.kt | 61 ++++++ ...RoomSelectedIceCandidatePairMockE2ETest.kt | 114 +++++++++++ .../room/SelectedIceCandidatePairTest.kt | 128 ++++++++++++ 10 files changed, 535 insertions(+), 2 deletions(-) create mode 100644 .changeset/selected-ice-candidate-pair-event.md create mode 100644 livekit-android-sdk/src/main/java/io/livekit/android/room/SelectedIceCandidatePair.kt create mode 100644 livekit-android-test/src/main/java/io/livekit/android/test/mock/MockIceCandidates.kt create mode 100644 livekit-android-test/src/test/java/io/livekit/android/room/RoomSelectedIceCandidatePairMockE2ETest.kt create mode 100644 livekit-android-test/src/test/java/io/livekit/android/room/SelectedIceCandidatePairTest.kt diff --git a/.changeset/selected-ice-candidate-pair-event.md b/.changeset/selected-ice-candidate-pair-event.md new file mode 100644 index 000000000..36553d2f5 --- /dev/null +++ b/.changeset/selected-ice-candidate-pair-event.md @@ -0,0 +1,5 @@ +--- +"client-sdk-android": minor +--- + +Add `RoomEvent.SelectedIceCandidatePairChanged`, emitted whenever the publisher or subscriber peer connection selects a new ICE candidate pair, including the initial selection and selections after reconnecting. The event carries a `SelectedIceCandidatePair` with the connection target, the parsed local and remote candidates (type, protocol, address, port, priority, adapter type, server URL and the raw candidate line), whether the path is relayed through TURN, and libwebrtc's change reason and estimated disconnection time. This makes network handovers and direct/relay path switches observable without polling RTC stats. diff --git a/livekit-android-sdk/src/main/java/io/livekit/android/events/RoomEvent.kt b/livekit-android-sdk/src/main/java/io/livekit/android/events/RoomEvent.kt index b49a85098..3cf579a8e 100644 --- a/livekit-android-sdk/src/main/java/io/livekit/android/events/RoomEvent.kt +++ b/livekit-android-sdk/src/main/java/io/livekit/android/events/RoomEvent.kt @@ -19,6 +19,7 @@ package io.livekit.android.events import io.livekit.android.annotations.Beta import io.livekit.android.e2ee.E2EEState import io.livekit.android.room.Room +import io.livekit.android.room.SelectedIceCandidatePair import io.livekit.android.room.datatrack.DataTrackSid import io.livekit.android.room.datatrack.RemoteDataTrack import io.livekit.android.room.participant.ConnectionQuality @@ -324,6 +325,18 @@ sealed class RoomEvent(val room: Room) : Event() { val newState: Participant.State, val oldState: Participant.State, ) : RoomEvent(room) + + /** + * The ICE candidate pair carrying media on the publisher or subscriber peer connection has changed. + * + * Emitted for the initial selection as well as every later switch, such as a Wi-Fi to cellular + * handover or a fallback to a TURN relay, and again after reconnections. The publisher and subscriber + * peer connections select their candidate pairs independently, so check [SelectedIceCandidatePair.target]. + */ + class SelectedIceCandidatePairChanged( + room: Room, + val pair: SelectedIceCandidatePair, + ) : RoomEvent(room) } enum class DisconnectReason { diff --git a/livekit-android-sdk/src/main/java/io/livekit/android/room/PublisherTransportObserver.kt b/livekit-android-sdk/src/main/java/io/livekit/android/room/PublisherTransportObserver.kt index 2dea63532..be07aedce 100644 --- a/livekit-android-sdk/src/main/java/io/livekit/android/room/PublisherTransportObserver.kt +++ b/livekit-android-sdk/src/main/java/io/livekit/android/room/PublisherTransportObserver.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. @@ -81,6 +81,12 @@ internal class PublisherTransportObserver( } override fun onSelectedCandidatePairChanged(event: CandidatePairChangeEvent?) { + val changeEvent = event ?: return + executeOnRTCThread(rtcThreadToken) { + val pair = changeEvent.toSelectedIceCandidatePair(IceTarget.PUBLISHER) + LKLog.i { "Selected ICE candidate pair changed: ${pair.summary()}" } + engine.listener?.onSelectedIceCandidatePairChanged(pair) + } } override fun onSignalingChange(p0: PeerConnection.SignalingState?) { diff --git a/livekit-android-sdk/src/main/java/io/livekit/android/room/RTCEngine.kt b/livekit-android-sdk/src/main/java/io/livekit/android/room/RTCEngine.kt index d54a613ac..d2578931f 100644 --- a/livekit-android-sdk/src/main/java/io/livekit/android/room/RTCEngine.kt +++ b/livekit-android-sdk/src/main/java/io/livekit/android/room/RTCEngine.kt @@ -1199,6 +1199,7 @@ internal constructor( fun onLocalTrackSubscribed(trackSubscribed: LivekitRtc.TrackSubscribed) fun onRpcPacketReceived(dp: LivekitModels.DataPacket) fun onDataStreamPacket(dp: LivekitModels.DataPacket, encryptionType: LivekitModels.Encryption.Type) + fun onSelectedIceCandidatePairChanged(pair: SelectedIceCandidatePair) {} } companion object { diff --git a/livekit-android-sdk/src/main/java/io/livekit/android/room/Room.kt b/livekit-android-sdk/src/main/java/io/livekit/android/room/Room.kt index 42622a36e..cffdfe8a9 100644 --- a/livekit-android-sdk/src/main/java/io/livekit/android/room/Room.kt +++ b/livekit-android-sdk/src/main/java/io/livekit/android/room/Room.kt @@ -1518,6 +1518,14 @@ constructor( eventBus.tryPostEvent(RoomEvent.FailedToConnect(this, error)) } + /** + * @suppress + */ + override fun onSelectedIceCandidatePairChanged(pair: SelectedIceCandidatePair) { + // Posted synchronously so that ordering between consecutive changes is preserved. + eventBus.tryPostEvent(RoomEvent.SelectedIceCandidatePairChanged(this, pair)) + } + /** * @suppress */ diff --git a/livekit-android-sdk/src/main/java/io/livekit/android/room/SelectedIceCandidatePair.kt b/livekit-android-sdk/src/main/java/io/livekit/android/room/SelectedIceCandidatePair.kt new file mode 100644 index 000000000..2278a46df --- /dev/null +++ b/livekit-android-sdk/src/main/java/io/livekit/android/room/SelectedIceCandidatePair.kt @@ -0,0 +1,191 @@ +/* + * 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. + * You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + */ + +package io.livekit.android.room + +import livekit.org.webrtc.CandidatePairChangeEvent +import livekit.org.webrtc.IceCandidate +import livekit.org.webrtc.PeerConnection + +/** + * Which peer connection a candidate pair belongs to. The publisher (uplink) and subscriber (downlink) + * connections run independent ICE sessions and may select different network paths. + */ +enum class IceTarget { + PUBLISHER, + SUBSCRIBER, +} + +private fun Any?.orDash() = this?.toString() ?: "-" + +/** + * A single ICE candidate, with its `a=candidate:` line parsed out into fields. + * + * Line format (RFC 5245 §15.1): + * `candidate:
typ + * [raddr rport ] *( )` + */ +data class IceCandidateInfo( + /** `host`, `srflx`, `prflx` or `relay`. */ + val type: String?, + /** `udp` or `tcp`. */ + val protocol: String?, + val address: String?, + val port: Int?, + val foundation: String?, + /** 1 for RTP, 2 for RTCP. Always 1 when rtcp-mux is in use. */ + val component: Int?, + val priority: Long?, + /** The address behind the NAT. Present for `srflx`/`prflx`/`relay` candidates. */ + val relatedAddress: String?, + val relatedPort: Int?, + /** `active`, `passive` or `so` for TCP candidates. */ + val tcpType: String?, + /** Any remaining key/value pairs on the line, e.g. `generation`, `ufrag`, `network-id`, `network-cost`. */ + val attributes: Map, + val sdpMid: String?, + val sdpMLineIndex: Int, + /** The STUN/TURN server that produced this candidate, if any. */ + val serverUrl: String?, + /** Local network interface the candidate was gathered on. Always UNKNOWN for remote candidates. */ + val adapterType: PeerConnection.AdapterType, + /** The original SDP line. */ + val raw: String, +) { + /** + * Type preference encoded into the priority. libwebrtc uses host 126 (90 for TCP), prflx 110 (80 for TCP), + * srflx 100 and relay 0-2 depending on the TURN transport. + */ + val typePreference: Long? + get() = priority?.let { (it ushr 24) and 0xFFL } + + val localPreference: Long? + get() = priority?.let { (it ushr 8) and 0xFFFFL } + + val componentPreference: Long? + get() = priority?.let { it and 0xFFL } + + private fun componentDescription() = when (component) { + 1 -> "1 (RTP)" + 2 -> "2 (RTCP)" + else -> component?.toString() ?: "-" + } + + /** Multi-line dump of every field, for logging. */ + fun describe(indent: String = " ") = buildString { + appendLine("${indent}type: ${type.orDash()} protocol: ${protocol.orDash()} tcpType: ${tcpType.orDash()}") + appendLine("${indent}address: ${address.orDash()}:${port.orDash()}") + appendLine("${indent}related: ${relatedAddress?.let { "$it:${relatedPort.orDash()}" }.orDash()}") + appendLine("${indent}foundation: ${foundation.orDash()} component: ${componentDescription()}") + appendLine( + "${indent}priority: ${priority.orDash()} " + + "(typePref=${typePreference.orDash()} localPref=${localPreference.orDash()} componentPref=${componentPreference.orDash()})", + ) + appendLine("${indent}adapter: $adapterType serverUrl: ${serverUrl.orDash()}") + appendLine("${indent}mid: ${sdpMid.orDash()} (mLineIndex=$sdpMLineIndex)") + appendLine("${indent}extra: ${attributes.entries.joinToString { "${it.key}=${it.value}" }.ifEmpty { "-" }}") + append("${indent}sdp: $raw") + } + + override fun toString() = "${type ?: "?"}/${protocol ?: "?"} ${address ?: "?"}:${port ?: "?"}" + + if (adapterType != PeerConnection.AdapterType.UNKNOWN) " via $adapterType" else "" +} + +/** + * Emitted whenever libwebrtc's ICE agent switches the candidate pair that carries media. + * + * @see io.livekit.android.events.RoomEvent.SelectedIceCandidatePairChanged + */ +data class SelectedIceCandidatePair( + val target: IceTarget, + val local: IceCandidateInfo, + val remote: IceCandidateInfo, + /** libwebrtc's description of why the pair changed. Free-form, wording varies between versions. */ + val reason: String?, + /** Monotonic timestamp (ms) of the last data received on the new pair. Only meaningful across events. */ + val lastDataReceivedMs: Int, + /** ICE's estimate of how long media was interrupted. 0 the first time a pair is selected. */ + val estimatedDisconnectedTimeMs: Int, +) { + /** True when media is going through a TURN server on either side. */ + val isRelayed: Boolean + get() = local.type == "relay" || remote.type == "relay" + + /** Single line, for high frequency logging. */ + fun summary() = "[$target] $local -> $remote relayed=$isRelayed " + + "gap=${estimatedDisconnectedTimeMs}ms reason=${reason ?: "-"}" + + /** Full dump of the change event and both candidates. */ + fun describe() = buildString { + appendLine("ICE selected candidate pair changed [$target]") + appendLine(" relayed: $isRelayed") + appendLine(" reason: ${reason ?: "-"}") + appendLine(" lastDataReceivedMs: $lastDataReceivedMs") + appendLine(" estimatedDisconnectedTimeMs: $estimatedDisconnectedTimeMs") + appendLine(" local:") + appendLine(local.describe(" ")) + appendLine(" remote:") + append(remote.describe(" ")) + } +} + +private const val CANDIDATE_ATTRIBUTE_START_INDEX = 6 +private val PARSED_CANDIDATE_ATTRIBUTES = setOf("typ", "raddr", "rport", "tcptype") + +/** + * Parses the `a=candidate:` line of an [IceCandidate]. Unparseable fields come back as null rather than + * throwing, so that logging never breaks on an unexpected candidate line. + */ +internal fun IceCandidate.toIceCandidateInfo(): IceCandidateInfo { + val tokens = sdp.trim().removePrefix("a=").split(' ').filter { it.isNotEmpty() } + + // Everything past the fixed fields is a sequence of name/value pairs, including `typ`, `raddr`, + // `rport` and `tcptype`. + val attributes = mutableMapOf() + var index = CANDIDATE_ATTRIBUTE_START_INDEX + while (index + 1 < tokens.size) { + attributes[tokens[index]] = tokens[index + 1] + index += 2 + } + + return IceCandidateInfo( + type = attributes["typ"], + protocol = tokens.getOrNull(2), + address = tokens.getOrNull(4), + port = tokens.getOrNull(5)?.toIntOrNull(), + foundation = tokens.getOrNull(0)?.removePrefix("candidate:"), + component = tokens.getOrNull(1)?.toIntOrNull(), + priority = tokens.getOrNull(3)?.toLongOrNull(), + relatedAddress = attributes["raddr"], + relatedPort = attributes["rport"]?.toIntOrNull(), + tcpType = attributes["tcptype"], + attributes = attributes.filterKeys { it !in PARSED_CANDIDATE_ATTRIBUTES }, + sdpMid = sdpMid, + sdpMLineIndex = sdpMLineIndex, + serverUrl = serverUrl?.takeIf { it.isNotEmpty() }, + adapterType = adapterType ?: PeerConnection.AdapterType.UNKNOWN, + raw = sdp, + ) +} + +internal fun CandidatePairChangeEvent.toSelectedIceCandidatePair(target: IceTarget) = SelectedIceCandidatePair( + target = target, + local = local.toIceCandidateInfo(), + remote = remote.toIceCandidateInfo(), + reason = reason, + lastDataReceivedMs = lastDataReceivedMs, + estimatedDisconnectedTimeMs = estimatedDisconnectedTimeMs, +) diff --git a/livekit-android-sdk/src/main/java/io/livekit/android/room/SubscriberTransportObserver.kt b/livekit-android-sdk/src/main/java/io/livekit/android/room/SubscriberTransportObserver.kt index 493f3f994..1fc717b61 100644 --- a/livekit-android-sdk/src/main/java/io/livekit/android/room/SubscriberTransportObserver.kt +++ b/livekit-android-sdk/src/main/java/io/livekit/android/room/SubscriberTransportObserver.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. @@ -90,6 +90,12 @@ class SubscriberTransportObserver( } override fun onSelectedCandidatePairChanged(event: CandidatePairChangeEvent?) { + val changeEvent = event ?: return + executeOnRTCThread(rtcThreadToken) { + val pair = changeEvent.toSelectedIceCandidatePair(IceTarget.SUBSCRIBER) + LKLog.i { "Selected ICE candidate pair changed: ${pair.summary()}" } + engine.listener?.onSelectedIceCandidatePairChanged(pair) + } } override fun onSignalingChange(p0: PeerConnection.SignalingState?) { diff --git a/livekit-android-test/src/main/java/io/livekit/android/test/mock/MockIceCandidates.kt b/livekit-android-test/src/main/java/io/livekit/android/test/mock/MockIceCandidates.kt new file mode 100644 index 000000000..780146571 --- /dev/null +++ b/livekit-android-test/src/main/java/io/livekit/android/test/mock/MockIceCandidates.kt @@ -0,0 +1,61 @@ +/* + * Copyright 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. + * You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + */ + +package io.livekit.android.test.mock + +import livekit.org.webrtc.CandidatePairChangeEvent +import livekit.org.webrtc.IceCandidate +import livekit.org.webrtc.PeerConnection + +/** + * Creates an [IceCandidate] with a [serverUrl] and [adapterType], which the public constructor does not allow. + */ +fun createIceCandidate( + sdp: String, + sdpMid: String = "0", + sdpMLineIndex: Int = 0, + serverUrl: String = "", + adapterType: PeerConnection.AdapterType = PeerConnection.AdapterType.UNKNOWN, +): IceCandidate = IceCandidate::class.java + .getDeclaredConstructor( + String::class.java, + Int::class.javaPrimitiveType, + String::class.java, + String::class.java, + PeerConnection.AdapterType::class.java, + ) + .apply { isAccessible = true } + .newInstance(sdpMid, sdpMLineIndex, sdp, serverUrl, adapterType) + +/** + * Creates a [CandidatePairChangeEvent], whose constructor is package-private and normally only called from native code. + */ +fun createCandidatePairChangeEvent( + local: IceCandidate, + remote: IceCandidate, + reason: String = "", + lastDataReceivedMs: Int = 0, + estimatedDisconnectedTimeMs: Int = 0, +): CandidatePairChangeEvent = CandidatePairChangeEvent::class.java + .getDeclaredConstructor( + IceCandidate::class.java, + IceCandidate::class.java, + Int::class.javaPrimitiveType, + String::class.java, + Int::class.javaPrimitiveType, + ) + .apply { isAccessible = true } + .newInstance(local, remote, lastDataReceivedMs, reason, estimatedDisconnectedTimeMs) diff --git a/livekit-android-test/src/test/java/io/livekit/android/room/RoomSelectedIceCandidatePairMockE2ETest.kt b/livekit-android-test/src/test/java/io/livekit/android/room/RoomSelectedIceCandidatePairMockE2ETest.kt new file mode 100644 index 000000000..a25dd3706 --- /dev/null +++ b/livekit-android-test/src/test/java/io/livekit/android/room/RoomSelectedIceCandidatePairMockE2ETest.kt @@ -0,0 +1,114 @@ +/* + * Copyright 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. + * You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + */ + +package io.livekit.android.room + +import io.livekit.android.events.RoomEvent +import io.livekit.android.test.MockE2ETest +import io.livekit.android.test.events.EventCollector +import io.livekit.android.test.mock.TestData +import io.livekit.android.test.mock.createCandidatePairChangeEvent +import io.livekit.android.test.mock.createIceCandidate +import kotlinx.coroutines.ExperimentalCoroutinesApi +import livekit.org.webrtc.PeerConnection +import org.junit.Assert.assertEquals +import org.junit.Assert.assertNotSame +import org.junit.Assert.assertTrue +import org.junit.Test +import org.junit.runner.RunWith +import org.robolectric.RobolectricTestRunner + +@ExperimentalCoroutinesApi +@RunWith(RobolectricTestRunner::class) +class RoomSelectedIceCandidatePairMockE2ETest : MockE2ETest() { + + private fun changeEvent(localSdp: String, reason: String = "", estimatedDisconnectedTimeMs: Int = 0) = + createCandidatePairChangeEvent( + local = createIceCandidate(localSdp, adapterType = PeerConnection.AdapterType.WIFI), + remote = createIceCandidate("candidate:3 1 udp 2130706431 34.10.0.9 7881 typ host"), + reason = reason, + estimatedDisconnectedTimeMs = estimatedDisconnectedTimeMs, + ) + + private fun collectedPairChanges(events: List) = + events.filterIsInstance().map { it.pair } + + @Test + fun emitsForPublisherAndSubscriber() = runTest { + connect() + val collector = EventCollector(room.events, coroutineRule.scope) + + getPublisherPeerConnection().observer?.onSelectedCandidatePairChanged( + changeEvent("candidate:1 1 udp 2130706431 192.168.1.5 41234 typ host", reason = "initial"), + ) + getSubscriberPeerConnection().observer?.onSelectedCandidatePairChanged( + changeEvent("candidate:2 1 udp 41885439 3.3.3.3 50000 typ relay", reason = "switch", estimatedDisconnectedTimeMs = 120), + ) + + val pairs = collectedPairChanges(collector.stopCollecting()) + assertEquals(listOf(IceTarget.PUBLISHER, IceTarget.SUBSCRIBER), pairs.map { it.target }) + + val publisherPair = pairs[0] + assertEquals("host", publisherPair.local.type) + assertEquals("192.168.1.5", publisherPair.local.address) + assertEquals(PeerConnection.AdapterType.WIFI, publisherPair.local.adapterType) + assertEquals("34.10.0.9", publisherPair.remote.address) + assertEquals("initial", publisherPair.reason) + + val subscriberPair = pairs[1] + assertTrue(subscriberPair.isRelayed) + assertEquals("switch", subscriberPair.reason) + assertEquals(120, subscriberPair.estimatedDisconnectedTimeMs) + } + + @Test + fun ignoresNullEvent() = runTest { + connect() + val collector = EventCollector(room.events, coroutineRule.scope) + + getPublisherPeerConnection().observer?.onSelectedCandidatePairChanged(null) + + assertTrue(collectedPairChanges(collector.stopCollecting()).isEmpty()) + } + + @Test + fun emitsAfterFullReconnect() = runTest { + room.setReconnectionType(ReconnectType.FORCE_FULL_RECONNECT) + connect() + val oldSubscriber = getSubscriberPeerConnection() + + disconnectPeerConnection() + // Wait so that the reconnect job properly starts first. + testScheduler.advanceTimeBy(1000) + wsFactory.listener.onOpen(wsFactory.ws, createOpenResponse(wsFactory.request)) + simulateMessageFromServer(TestData.JOIN) + connectPeerConnection() + testScheduler.advanceUntilIdle() + + val newSubscriber = getSubscriberPeerConnection() + assertNotSame(oldSubscriber, newSubscriber) + + val collector = EventCollector(room.events, coroutineRule.scope) + newSubscriber.observer?.onSelectedCandidatePairChanged( + changeEvent("candidate:1 1 udp 2130706431 10.0.0.2 41234 typ host"), + ) + + val pairs = collectedPairChanges(collector.stopCollecting()) + assertEquals(1, pairs.size) + assertEquals(IceTarget.SUBSCRIBER, pairs[0].target) + assertEquals("10.0.0.2", pairs[0].local.address) + } +} diff --git a/livekit-android-test/src/test/java/io/livekit/android/room/SelectedIceCandidatePairTest.kt b/livekit-android-test/src/test/java/io/livekit/android/room/SelectedIceCandidatePairTest.kt new file mode 100644 index 000000000..f4f23d7a5 --- /dev/null +++ b/livekit-android-test/src/test/java/io/livekit/android/room/SelectedIceCandidatePairTest.kt @@ -0,0 +1,128 @@ +/* + * Copyright 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. + * You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + */ + +package io.livekit.android.room + +import io.livekit.android.test.mock.createCandidatePairChangeEvent +import io.livekit.android.test.mock.createIceCandidate +import livekit.org.webrtc.PeerConnection +import org.junit.Assert.assertEquals +import org.junit.Assert.assertFalse +import org.junit.Assert.assertNull +import org.junit.Assert.assertTrue +import org.junit.Test + +class SelectedIceCandidatePairTest { + + @Test + fun parsesServerReflexiveCandidate() { + val sdp = "candidate:842163049 1 udp 1686052607 5.1.2.3 41234 typ srflx raddr 192.168.1.5 rport 41234 " + + "generation 0 ufrag Kd2R network-id 2 network-cost 10" + val info = createIceCandidate( + sdp = sdp, + sdpMid = "1", + sdpMLineIndex = 1, + serverUrl = "stun:stun.example.com:3478", + adapterType = PeerConnection.AdapterType.WIFI, + ).toIceCandidateInfo() + + assertEquals("srflx", info.type) + assertEquals("udp", info.protocol) + assertEquals("5.1.2.3", info.address) + assertEquals(41234, info.port) + assertEquals("842163049", info.foundation) + assertEquals(1, info.component) + assertEquals(1686052607L, info.priority) + assertEquals(100L, info.typePreference) + assertEquals(32542L, info.localPreference) + assertEquals(255L, info.componentPreference) + assertEquals("192.168.1.5", info.relatedAddress) + assertEquals(41234, info.relatedPort) + assertNull(info.tcpType) + assertEquals( + mapOf("generation" to "0", "ufrag" to "Kd2R", "network-id" to "2", "network-cost" to "10"), + info.attributes, + ) + assertEquals("1", info.sdpMid) + assertEquals(1, info.sdpMLineIndex) + assertEquals("stun:stun.example.com:3478", info.serverUrl) + assertEquals(PeerConnection.AdapterType.WIFI, info.adapterType) + assertEquals(sdp, info.raw) + } + + @Test + fun parsesTcpCandidateWithSdpPrefix() { + val info = createIceCandidate("a=candidate:1 1 tcp 1518280447 192.168.1.5 9 typ host tcptype active generation 0") + .toIceCandidateInfo() + + assertEquals("host", info.type) + assertEquals("tcp", info.protocol) + assertEquals("active", info.tcpType) + assertEquals("1", info.foundation) + assertEquals(90L, info.typePreference) + assertNull(info.relatedAddress) + assertNull(info.serverUrl) + assertEquals(mapOf("generation" to "0"), info.attributes) + } + + @Test + fun malformedCandidateDoesNotThrow() { + val info = createIceCandidate("candidate:abc").toIceCandidateInfo() + + assertEquals("abc", info.foundation) + assertNull(info.type) + assertNull(info.protocol) + assertNull(info.address) + assertNull(info.port) + assertNull(info.priority) + assertNull(info.typePreference) + assertTrue(info.attributes.isEmpty()) + assertEquals("candidate:abc", info.raw) + } + + @Test + fun convertsChangeEvent() { + val event = createCandidatePairChangeEvent( + local = createIceCandidate("candidate:2 1 udp 41885439 3.3.3.3 50000 typ relay raddr 5.1.2.3 rport 41234"), + remote = createIceCandidate("candidate:3 1 udp 2130706431 34.10.0.9 7881 typ host"), + reason = "switch to relay", + lastDataReceivedMs = 1234, + estimatedDisconnectedTimeMs = 250, + ) + + val pair = event.toSelectedIceCandidatePair(IceTarget.SUBSCRIBER) + + assertEquals(IceTarget.SUBSCRIBER, pair.target) + assertEquals("relay", pair.local.type) + assertEquals(2L, pair.local.typePreference) + assertEquals("host", pair.remote.type) + assertEquals(126L, pair.remote.typePreference) + assertEquals("switch to relay", pair.reason) + assertEquals(1234, pair.lastDataReceivedMs) + assertEquals(250, pair.estimatedDisconnectedTimeMs) + assertTrue(pair.isRelayed) + } + + @Test + fun directPairIsNotRelayed() { + val pair = createCandidatePairChangeEvent( + local = createIceCandidate("candidate:1 1 udp 2130706431 192.168.1.5 41234 typ host"), + remote = createIceCandidate("candidate:3 1 udp 2130706431 34.10.0.9 7881 typ host"), + ).toSelectedIceCandidatePair(IceTarget.PUBLISHER) + + assertFalse(pair.isRelayed) + } +} From 128d48fa7adea2abd66784b7732802000b97b583 Mon Sep 17 00:00:00 2001 From: divar Date: Sat, 7 Nov 2026 14:39:59 +0330 Subject: [PATCH 2/3] Document selected ICE candidate pair public APIs Add KDoc to SelectedIceCandidatePairChanged.pair, PeerConnectionType, and the RFC 5245 priority decomposition properties; add a guide for logging and consuming the event. Co-Authored-By: Claude Code --- docs/ice-selected-candidate-pair.md | 210 ++++++++++++++++++ .../io/livekit/android/events/RoomEvent.kt | 3 + .../android/room/SelectedIceCandidatePair.kt | 6 + 3 files changed, 219 insertions(+) create mode 100644 docs/ice-selected-candidate-pair.md diff --git a/docs/ice-selected-candidate-pair.md b/docs/ice-selected-candidate-pair.md new file mode 100644 index 000000000..730bac9aa --- /dev/null +++ b/docs/ice-selected-candidate-pair.md @@ -0,0 +1,210 @@ +# Logging the selected ICE candidate pair + +Every time libwebrtc's ICE agent switches the network path that carries media, the SDK now logs the **full +change event and both candidates**, and emits a `RoomEvent` the application can consume. + +Implemented in this repo — see [What was changed](#what-was-changed). + +## What you get + +For every switch, on either peer connection (publisher = uplink, subscriber = downlink — separate ICE +sessions): + +| Signal | Use | +| --- | --- | +| candidate `type` (`host` / `srflx` / `prflx` / `relay`) | direct path or TURN relay | +| `address:port`, `protocol`, `tcpType` | the actual 5-tuple carrying media | +| `adapterType` (`WIFI`, `CELLULAR`, `VPN`, `ETHERNET`, …) | detect wifi↔cellular handover | +| `serverUrl` | which STUN/TURN server produced the candidate | +| `priority` + decoded `typePref` / `localPref` / `componentPref` | why ICE ranked this candidate where it did | +| `raddr` / `rport` | the address behind the NAT | +| `foundation`, `component`, `generation`, `ufrag`, `network-id`, `network-cost` | full candidate line, nothing dropped | +| `reason` | libwebrtc's own explanation for the switch | +| `estimatedDisconnectedTimeMs` | how long media was interrupted before the new pair took over | +| `lastDataReceivedMs` | monotonic timestamp of last data on the new pair | + +## Log output + +The SDK logs at INFO from the observers, so it only needs `LiveKit.loggingLevel`: + +```kotlin +LiveKit.loggingLevel = LoggingLevel.INFO +``` + +``` +ICE selected candidate pair changed [PUBLISHER] + relayed: false + reason: remote candidate generation maybe old + lastDataReceivedMs: 1394857 + estimatedDisconnectedTimeMs: 0 + local: + type: srflx protocol: udp tcpType: - + address: 5.1.2.3:41234 + related: 192.168.1.5:41234 + foundation: 842163049 component: 1 (RTP) + priority: 1677729535 (typePref=100 localPref=65535 componentPref=255) + adapter: WIFI serverUrl: stun:stun.l.google.com:19302 + mid: 0 (mLineIndex=0) + extra: generation=0, ufrag=Kd2R, network-id=2, network-cost=10 + sdp: candidate:842163049 1 udp 1677729535 5.1.2.3 41234 typ srflx raddr 192.168.1.5 rport 41234 generation 0 ufrag Kd2R network-id 2 network-cost 10 + remote: + type: host protocol: udp tcpType: - + address: 34.10.0.9:7881 + related: - + foundation: 3162092614 component: 1 (RTP) + priority: 2130706431 (typePref=126 localPref=65535 componentPref=255) + adapter: UNKNOWN serverUrl: - + mid: 0 (mLineIndex=0) + extra: generation=0, ufrag=8fJx + sdp: candidate:3162092614 1 udp 2130706431 34.10.0.9 7881 typ host generation 0 ufrag 8fJx +``` + +Filter it: + +```bash +adb logcat | grep -A22 "ICE selected candidate pair changed" +``` + +## Consuming it in the app + +```kotlin +lifecycleScope.launch { + room.events.collect { event -> + if (event !is RoomEvent.SelectedIceCandidatePairChanged) return@collect + val pair = event.pair + + // One-liner, e.g. "[PUBLISHER] srflx/udp 5.1.2.3:41234 via WIFI -> host/udp 34.10.0.9:7881 + // relayed=false gap=0ms reason=..." + Log.i("IceWatch", pair.summary()) + + // Or the same block the SDK logs. + Log.i("IceWatch", pair.describe()) + + if (pair.isRelayed) { + analytics.track("ice_relay_fallback", mapOf("target" to pair.target.name)) + } + if (pair.estimatedDisconnectedTimeMs > 0) { + analytics.track("ice_media_gap_ms", mapOf("ms" to pair.estimatedDisconnectedTimeMs)) + } + if (pair.local.adapterType == PeerConnection.AdapterType.CELLULAR) { + // Uplink is on mobile data — consider dropping publish quality. + } + } +} +``` + +Field-level access, everything already parsed: + +```kotlin +pair.target // IceTarget.PUBLISHER / SUBSCRIBER +pair.local.type // "host" | "srflx" | "prflx" | "relay" +pair.local.address // "5.1.2.3" +pair.local.port // 41234 +pair.local.protocol // "udp" | "tcp" +pair.local.tcpType // "active" | "passive" | "so" | null +pair.local.relatedAddress // address behind the NAT, or null +pair.local.priority // 1677729535 +pair.local.typePreference // 100 +pair.local.adapterType // PeerConnection.AdapterType.WIFI +pair.local.serverUrl // "stun:stun.l.google.com:19302" +pair.local.attributes["ufrag"] // any remaining key/value on the candidate line +pair.local.raw // the untouched a=candidate: line +``` + +## What was changed + +| File | Change | +| --- | --- | +| `io/livekit/android/room/SelectedIceCandidatePair.kt` | **new** — `IceTarget`, `IceCandidateInfo`, `SelectedIceCandidatePair`, candidate-line parser, `describe()` / `summary()` | +| `io/livekit/android/room/PublisherTransportObserver.kt` | filled the empty `onSelectedCandidatePairChanged`, added `selectedCandidatePairListener` | +| `io/livekit/android/room/SubscriberTransportObserver.kt` | same, tagged `SUBSCRIBER` | +| `io/livekit/android/room/RTCEngine.kt` | wires both observers into `Listener.onSelectedIceCandidatePairChanged` | +| `io/livekit/android/events/RoomEvent.kt` | new `RoomEvent.SelectedIceCandidatePairChanged` | +| `io/livekit/android/room/Room.kt` | overrides the engine callback, posts the room event | + +Key parts: + +```kotlin +// PublisherTransportObserver.kt / SubscriberTransportObserver.kt +override fun onSelectedCandidatePairChanged(event: CandidatePairChangeEvent?) { + val changeEvent = event ?: return + executeOnRTCThread(rtcThreadToken) { + val pair = changeEvent.toSelectedIceCandidatePair(IceTarget.PUBLISHER) + LKLog.i { pair.describe() } + selectedCandidatePairListener?.invoke(pair) + } +} +``` + +```kotlin +// RTCEngine.kt +private val publisherObserver = PublisherTransportObserver(this, client, rtcThreadToken).apply { + selectedCandidatePairListener = { pair -> listener?.onSelectedIceCandidatePairChanged(pair) } +} +``` + +```kotlin +// Room.kt +override fun onSelectedIceCandidatePairChanged(pair: SelectedIceCandidatePair) { + // Arrives on the RTC thread, and coroutineScope may not be initialized yet, so post without a scope. + eventBus.tryPostEvent(RoomEvent.SelectedIceCandidatePairChanged(this, pair)) +} +``` + +`RTCEngine.Listener.onSelectedIceCandidatePairChanged` has a default empty body, so existing implementers and +test fakes are unaffected. + +## Behaviour notes + +- **Fires per peer connection.** Publisher and subscriber switch independently — always read `pair.target`. +- **Fires on first selection too**, with `estimatedDisconnectedTimeMs == 0`. That is the "we are connected over + this path" event. +- **Runs on the RTC thread.** Do no blocking or UI work in a `room.events` collector that handles it — the + event is delivered through a `SharedFlow`, so collect on your own dispatcher. +- **A full reconnect** (`RTCEngine.kt:625`) recreates both peer connections, so a fresh first-selection event + follows it. +- **`reason` is free-form** libwebrtc text; wording changes between versions. Log it, do not branch on it. +- **Parsing never throws.** Unknown or malformed candidate lines yield null fields and the raw line is always + kept in `IceCandidateInfo.raw`. + +## Testing + +1. **Handover** — join on wifi, disable wifi with mobile data on. Expect events on both targets, with + `estimatedDisconnectedTimeMs > 0` and `adapterType` changing to `CELLULAR`. +2. **Force relay** — a server-side `forceRelay` client configuration sets `iceTransportsType = RELAY` + (`RTCEngine.kt:1034`); every selection then reports `relayed: true`. +3. **Cross-check with native logs**: + + ```kotlin + LiveKit.enableWebRTCLogging = true + LiveKit.loggingLevel = LoggingLevel.VERBOSE + ``` + + ```bash + adb logcat | grep -iE "p2p_transport_channel|selected connection|ICE selected candidate pair" + ``` + +## Snapshot instead of events + +For "what path am I on right now", the existing stats API answers without waiting for a change: + +```kotlin +room.getPublisherRTCStats { report -> + val stats = report.statsMap + val pair = (stats.values.firstOrNull { it.type == "transport" } + ?.members?.get("selectedCandidatePairId") as? String)?.let { stats[it] } + ?: stats.values.firstOrNull { it.type == "candidate-pair" && it.members["nominated"] == true } + Log.i("IceWatch", "pair=${pair?.members}") +} +``` + +## Build note + +Building this module requires the `protocol` git submodule (it was uninitialized): + +```bash +git submodule update --init --recursive +``` + +Without it, `generateDebugProto` reports `NO-SOURCE` and Kotlin compilation fails with the unhelpful +`e: Could not load module `. diff --git a/livekit-android-sdk/src/main/java/io/livekit/android/events/RoomEvent.kt b/livekit-android-sdk/src/main/java/io/livekit/android/events/RoomEvent.kt index 3cf579a8e..450f2875a 100644 --- a/livekit-android-sdk/src/main/java/io/livekit/android/events/RoomEvent.kt +++ b/livekit-android-sdk/src/main/java/io/livekit/android/events/RoomEvent.kt @@ -335,6 +335,9 @@ sealed class RoomEvent(val room: Room) : Event() { */ class SelectedIceCandidatePairChanged( room: Room, + /** + * The newly selected candidate pair, including both of its parsed candidates. + */ val pair: SelectedIceCandidatePair, ) : RoomEvent(room) } diff --git a/livekit-android-sdk/src/main/java/io/livekit/android/room/SelectedIceCandidatePair.kt b/livekit-android-sdk/src/main/java/io/livekit/android/room/SelectedIceCandidatePair.kt index 2278a46df..c9e40217f 100644 --- a/livekit-android-sdk/src/main/java/io/livekit/android/room/SelectedIceCandidatePair.kt +++ b/livekit-android-sdk/src/main/java/io/livekit/android/room/SelectedIceCandidatePair.kt @@ -25,7 +25,10 @@ import livekit.org.webrtc.PeerConnection * connections run independent ICE sessions and may select different network paths. */ enum class IceTarget { + /** The publisher (uplink) peer connection, carrying locally published tracks. */ PUBLISHER, + + /** The subscriber (downlink) peer connection, carrying remotely published tracks. */ SUBSCRIBER, } @@ -69,12 +72,15 @@ data class IceCandidateInfo( * Type preference encoded into the priority. libwebrtc uses host 126 (90 for TCP), prflx 110 (80 for TCP), * srflx 100 and relay 0-2 depending on the TURN transport. */ + /** RFC 5245 type preference, bits 24-31 of the priority. */ val typePreference: Long? get() = priority?.let { (it ushr 24) and 0xFFL } + /** RFC 5245 local preference, bits 8-23 of the priority. */ val localPreference: Long? get() = priority?.let { (it ushr 8) and 0xFFFFL } + /** RFC 5245 component preference, bits 0-7 of the priority. */ val componentPreference: Long? get() = priority?.let { it and 0xFFL } From 1d9bf55f43f11e30c00a69b008eb960723415676 Mon Sep 17 00:00:00 2001 From: divar Date: Sat, 7 Nov 2026 14:39:59 +0330 Subject: [PATCH 3/3] Address review: document candidate fields, add Room.events example Add KDoc to the undocumented public properties of IceCandidateInfo (address, port, foundation, priority, relatedPort, sdpMid, sdpMLineIndex) and SelectedIceCandidatePair (target, local, remote), and merge the duplicated KDoc above typePreference. Add a usage example to Room.events showing how to collect RoomEvent.SelectedIceCandidatePairChanged, per the entry-point documentation rule. Co-Authored-By: Claude Code --- .../src/main/java/io/livekit/android/room/Room.kt | 15 +++++++++++++++ .../android/room/SelectedIceCandidatePair.kt | 15 ++++++++++++--- 2 files changed, 27 insertions(+), 3 deletions(-) diff --git a/livekit-android-sdk/src/main/java/io/livekit/android/room/Room.kt b/livekit-android-sdk/src/main/java/io/livekit/android/room/Room.kt index cffdfe8a9..59623cb8a 100644 --- a/livekit-android-sdk/src/main/java/io/livekit/android/room/Room.kt +++ b/livekit-android-sdk/src/main/java/io/livekit/android/room/Room.kt @@ -166,6 +166,21 @@ constructor( private lateinit var coroutineScope: CoroutineScope private val eventBus = BroadcastEventBus() + + /** + * Events emitted by this [Room], such as participant changes, track publications and connection + * state updates. + * + * For example, observing whenever the ICE candidate pair carrying media changes: + * ```kotlin + * room.events.collect { event -> + * if (event is RoomEvent.SelectedIceCandidatePairChanged) { + * LKLog.i { event.pair.summary() } + * } + * } + * ``` + * @see [RoomEvent] + */ val events = eventBus.readOnly() init { diff --git a/livekit-android-sdk/src/main/java/io/livekit/android/room/SelectedIceCandidatePair.kt b/livekit-android-sdk/src/main/java/io/livekit/android/room/SelectedIceCandidatePair.kt index c9e40217f..7ccf82b7a 100644 --- a/livekit-android-sdk/src/main/java/io/livekit/android/room/SelectedIceCandidatePair.kt +++ b/livekit-android-sdk/src/main/java/io/livekit/android/room/SelectedIceCandidatePair.kt @@ -46,20 +46,27 @@ data class IceCandidateInfo( val type: String?, /** `udp` or `tcp`. */ val protocol: String?, + /** IP address of the candidate. */ val address: String?, + /** Port of the candidate. */ val port: Int?, + /** RFC 5245 foundation. Candidates gathered from the same origin with the same transport protocol share one. */ val foundation: String?, /** 1 for RTP, 2 for RTCP. Always 1 when rtcp-mux is in use. */ val component: Int?, + /** RFC 5245 priority. Decomposed into [typePreference], [localPreference] and [componentPreference]. */ val priority: Long?, /** The address behind the NAT. Present for `srflx`/`prflx`/`relay` candidates. */ val relatedAddress: String?, + /** Port of [relatedAddress]. */ val relatedPort: Int?, /** `active`, `passive` or `so` for TCP candidates. */ val tcpType: String?, /** Any remaining key/value pairs on the line, e.g. `generation`, `ufrag`, `network-id`, `network-cost`. */ val attributes: Map, + /** Media id (`a=mid`) the candidate is associated with. Null when unset by the remote. */ val sdpMid: String?, + /** Index of the m-line in the SDP the candidate is associated with. */ val sdpMLineIndex: Int, /** The STUN/TURN server that produced this candidate, if any. */ val serverUrl: String?, @@ -69,10 +76,9 @@ data class IceCandidateInfo( val raw: String, ) { /** - * Type preference encoded into the priority. libwebrtc uses host 126 (90 for TCP), prflx 110 (80 for TCP), - * srflx 100 and relay 0-2 depending on the TURN transport. + * RFC 5245 type preference, bits 24-31 of the priority. libwebrtc uses host 126 (90 for TCP), + * prflx 110 (80 for TCP), srflx 100 and relay 0-2 depending on the TURN transport. */ - /** RFC 5245 type preference, bits 24-31 of the priority. */ val typePreference: Long? get() = priority?.let { (it ushr 24) and 0xFFL } @@ -116,8 +122,11 @@ data class IceCandidateInfo( * @see io.livekit.android.events.RoomEvent.SelectedIceCandidatePairChanged */ data class SelectedIceCandidatePair( + /** Which peer connection this pair belongs to. */ val target: IceTarget, + /** The locally gathered candidate of the pair. */ val local: IceCandidateInfo, + /** The remote peer's candidate of the pair. */ val remote: IceCandidateInfo, /** libwebrtc's description of why the pair changed. Free-form, wording varies between versions. */ val reason: String?,