Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
5 changes: 5 additions & 0 deletions .changeset/selected-ice-candidate-pair-event.md
Original file line number Diff line number Diff line change
@@ -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.
210 changes: 210 additions & 0 deletions docs/ice-selected-candidate-pair.md
Original file line number Diff line number Diff line change
@@ -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 <Error module>`.
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down Expand Up @@ -324,6 +325,21 @@ 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,
/**
* The newly selected candidate pair, including both of its parsed candidates.
*/
val pair: SelectedIceCandidatePair,
) : RoomEvent(room)
}

enum class DisconnectReason {
Expand Down
Original file line number Diff line number Diff line change
@@ -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.
Expand Down Expand Up @@ -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?) {
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -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 {
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -166,6 +166,21 @@ constructor(

private lateinit var coroutineScope: CoroutineScope
private val eventBus = BroadcastEventBus<RoomEvent>()

/**
* 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 {
Expand Down Expand Up @@ -1518,6 +1533,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))
Comment on lines +1536 to +1541

@devin-ai-integration devin-ai-integration Bot Nov 7, 2026 •

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🟡 Room event lacks entry-point example

The new RoomEvent.SelectedIceCandidatePairChanged API has no usage example on Room. Its example exists only in a separate guide, contrary to the entry-point documentation rule.

Learn more

The repository requires short examples for new APIs at their entry point. Room.events is where apps consume this event, but its entry-point property has no example, and the new callback only has @suppress.

Example: An app author browsing Room discovers events but cannot see how to filter for selected ICE candidate pair changes without finding the separate guide.

Recommended fix: Add a short KDoc snippet to the Room entry point showing collection of RoomEvent.SelectedIceCandidatePairChanged from room.events.

Devin Review


Was this helpful? React with 👍 or 👎 to provide feedback.

}

/**
* @suppress
*/
Expand Down
Loading