Skip to content

Expose selected ICE candidate pair changes through Room eventsFeat/selected ice candidate pair event - #1065

Open
seyedalirahimi wants to merge 3 commits into
livekit:mainfrom
seyedalirahimi:feat/selected-ice-candidate-pair-event
Open

seyedalirahimi wants to merge 3 commits into
livekit:mainfrom
seyedalirahimi:feat/selected-ice-candidate-pair-event

Conversation

@seyedalirahimi

Copy link
Copy Markdown

Fixes #1033

Summary

Exposes libwebrtc's onSelectedCandidatePairChanged callback through the public SDK as a new RoomEvent.SelectedIceCandidatePairChanged event, so applications can observe every ICE candidate pair switch — the initial selection, Wi-Fi↔cellular handovers,anges, and re-selections after reconnection — without polling getPublisherRTCStats/getSubscriberRTCStats and diffing selectedCandidatePairId between samples.
As noted in the issue, both transport observlectedCandidatePairChanged` in v2.29.0 withempty bodies; this wires those callbacks through.

What's included

  • RoomEvent.SelectedIceCandidatePairChanged(room, pair) — emitted from room.events for both the publisher and subscriber peer connections.
  • SelectedIceCandidatePair — the newly selected pair:
    • target: IceTarget.PUBLISHER or `IceT connections run independent ICE sessions andmay pick different paths)
    • local / remote: IceCandidateInfo —RFC 5245 §15.1) parsed into type,protocol, address, port, foundation, component, priority (plus its RFC 5245 decomposition: typePreference, localPreference, componddress/relatedPort, tcpType, remainingextension attributes, sdpMid, sdpMLineIndex, serverUrl, adapterType, and the raw SDP line
    • reason, lastDataReceivedMs, `estimatbwebrtc's change reason and disconnectionestimate
    • isRelayed — true when media goes throu side
    • summary() / describe() — single-line and full-dump formatting for logging
  • Behavior: emitted for the initial selech, and continues after full reconnects. Theevent is posted with tryPostEvent (synchronous), so ordering between consecutive changes is preserved. Callbacks
    are dispatched on the RTC thread, consistentsport observers.
  • Parsing is defensive: unparseable fields come back null instead of throwing, so logging never breaks on an
    unexpected candidate line.
  • Changeset: minor bump.
  • Docs: new guide at `docs/ice-selected-g log output, app consumption, behavior notes, and testing.

Usage

room.events
    .filterIsInstance<RoomEvent.SelectedIceCandidatePairChanged>()
    .onEach { event ->
        val pair = event.pair
        Log.i("Ice", "pair changed: ${pair.s
        if (pair.isRelayed) {
            Log.w("Ice", "media now relayed get}")
        }
    }
    .launchIn(lifecycleScope)

Testing

  • SelectedIceCandidatePairTest — parses srates with/without the a= prefix, malformedcandidate lines don't throw, change-event conversion, isRelayed detection.
  • RoomSelectedIceCandidatePairMockE2ETest ublisher and subscriber, null native eventignored, emission works after a full reconnect.
  • New MockIceCandidates test fixtures.

@changeset-bot

changeset-bot Bot commented Nov 7, 2026 •

Copy link
Copy Markdown

🦋 Changeset detected

Latest commit: 1d9bf55

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 1 package
Name Type
client-sdk-android Minor

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

@CLAassistant

CLAassistant commented Nov 7, 2026 •

Copy link
Copy Markdown

CLA assistant check
All committers have signed the CLA.

@devin-ai-integration devin-ai-integration Bot left a comment

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.

Devin Review found 2 potential issues.

1 flag not posted on this PR by your GitHub settings — view it in Devin Review. (Configure)

Devin Review

Comment on lines +49 to +54
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?,

@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.

🟡 Public candidate fields lack KDoc

The public IceCandidateInfo fields address, port, foundation, component, and priority lack required KDoc. Several SelectedIceCandidatePair fields also lack it, leaving the new API's field-level reference incomplete.

Learn more

The repository requires KDoc for every public API. IceCandidateInfo leaves address, port, foundation, component, priority, relatedPort, sdpMid, and sdpMLineIndex undocumented. SelectedIceCandidatePair also lacks field-level KDoc for target, local, and remote.

Example: A consumer browsing the generated reference for IceCandidateInfo.component sees its Kotlin type but not what 1 and 2 mean.

Recommended fix: Add concise KDoc to each undocumented public property on both types, including units or nullable meanings where applicable.

Devin Review


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

Comment on lines +1521 to +1526
/**
* @suppress
*/
override fun onSelectedIceCandidatePairChanged(pair: SelectedIceCandidatePair) {
// Posted synchronously so that ordering between consecutive changes is preserved.
eventBus.tryPostEvent(RoomEvent.SelectedIceCandidatePairChanged(this, pair))

@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.

seyedalirahimi and others added 3 commits November 7, 2026 14:40
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 <noreply@anthropic.com>
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 <noreply@anthropic.com>
@seyedalirahimi
seyedalirahimi force-pushed the feat/selected-ice-candidate-pair-event branch from 76bc078 to 1d9bf55 Compare November 7, 2026 11:10
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Expose selected ICE candidate pair changes through Room events

2 participants