Skip to content

Add single peer connection mode via /rtc/v1 - #1066

Merged
changt merged 12 commits into
mainfrom
sc/single-pc-transport
Nov 13, 2026
Merged

changt merged 12 commits into
mainfrom
sc/single-pc-transport

Conversation

@changt

@changt changt commented Nov 9, 2026

Copy link
Copy Markdown
Contributor

Adds ConnectOptions.singlePeerConnection (default false). When set, the signal client joins through /rtc/v1 with a join_request and RTCEngine builds a SinglePeerConnectionTransport around one publisher peer connection observed by DuplexTransportObserver:

  • the client makes every offer; the server's media_sections_requirement adds recvonly transceivers, and mid_to_track_id from answers maps received tracks back to their track IDs
  • subscriber primary is forced off, so the publisher drives connection state and data channels
  • PublisherTransportObserver is opened up for DuplexTransportObserver to also forward remote tracks

A server that predates /rtc/v1 answers that handshake with 404. The join then retries on the legacy path with dual peer connections, and later reconnects stay there. RoomException.ConnectException gains the HTTP statusCode to make that decision, and join handshake failures now reach the join caller instead of the signal listener so a retry does not report a failure.

SignalUrlBuilder builds the /rtc/v1?join_request=<base64url WrappedJoinRequest> URL and its /validate counterpart, matching client-sdk-swift. It returns plain URLs: its only failure is OkHttp rejecting the URL, which the legacy request builder throws on as well.

Builds on #1064. Offer-on-join is not included; it follows in the next PR.

Tests: SignalUrlBuilderTest, SinglePeerConnectionTransportTest, DuplexTransportObserverTest, SinglePeerConnectionMockE2ETest (a successful single PC join end to end), and SinglePeerConnectionFallbackMockE2ETest (the 404 fallback and reconnects after it).

Builds the /rtc/v1?join_request=<base64url WrappedJoinRequest> signal URL
and its /validate counterpart, matching client-sdk-swift's
buildJoinRequestUrl and toValidateUrl.
Adds ConnectOptions.singlePeerConnection (default false). When set, the
signal client joins through /rtc/v1 with a join_request and RTCEngine
builds a SinglePeerConnectionTransport around one publisher peer
connection observed by DuplexTransportObserver:

- the client makes every offer; the server's media_sections_requirement
  adds recvonly transceivers, and mid_to_track_id from answers maps
  received tracks back to their track IDs
- subscriber primary is forced off, so the publisher drives connection
  state and data channels
- PublisherTransportObserver is opened up for DuplexTransportObserver
  to also forward remote tracks and data channels

Fallback to dual PC and offer-on-join are not included yet.
Servers older than v1.9.10 answer the /rtc/v1 handshake with 404. When a
join requested a single peer connection and fails that way, RTCEngine
retries once on /rtc with dual peer connections and keeps the fallback
options for later reconnects. Any other join failure is rethrown.

SignalClient now reports a handshake failure only through the join
continuation, taking the status from /rtc/v1/validate when it answered
with an error, so the engine can retry without the app seeing a
FailedToConnect for the probe. The engine reports the failure itself
once it decides not to retry, which keeps one event per failed attempt
as before.

ConnectException gains a documented statusCode.
Both builder functions wrapped their result in a Result whose only
failure was OkHttp rejecting the URL. SignalClient already hands the
same string to OkHttp's request builder, which throws on that input, so
the failure was never recoverable and the join-request call site's
fallback to the legacy URL could never run. The functions now return the
URL and let the parse exception propagate; the validate call site is
inside the try that already covers the validate request.
Nothing set its listener: RTCEngine only forwards server-opened data
channels in subscriber-primary mode, which single peer connection mode
forces off, and the client creates its own channels on the one peer
connection.
Connects with ConnectOptions.singlePeerConnection against a mock server
that serves /rtc/v1: the join goes out on that path with a join_request,
the engine builds a SinglePeerConnectionTransport whose publisher and
subscriber are the same peer connection, the publisher offers on join
without offering to receive, a MediaSectionsRequirement adds the
receiving sections, the answer's mid_to_track_id resolves a received
track to its publication, and a server offer is ignored.
@changeset-bot

changeset-bot Bot commented Nov 9, 2026 •

Copy link
Copy Markdown

🦋 Changeset detected

Latest commit: e2ba16a

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

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

Note

Newer findings are available below. Devin Review posted a newer report on this PR, in addition to the findings presented here.

Devin Review found 2 potential issues.

Devin Review

Comment on lines +103 to +108
for (i in 0..<requirement.numAudios) {
addTransceiver(MediaStreamTrack.MediaType.MEDIA_TYPE_AUDIO, transceiverInit)
}
for (i in 0..<requirement.numVideos) {
addTransceiver(MediaStreamTrack.MediaType.MEDIA_TYPE_VIDEO, transceiverInit)
}

@devin-ai-integration devin-ai-integration Bot Nov 9, 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.

🟡 Repeated requirements multiply receive sections

When the server repeats a media requirement, handleMediaSectionsRequirement adds the full count again. Existing receive-only transceivers remain, so repeated updates grow the offer beyond the requested number of sections.

Learn more

A media-sections requirement is a minimum number of receiving sections, not an instruction to add that many new ones. The same requirement can arrive again while the peer connection already contains receive-only transceivers. Each call currently adds the full requested count, and the extra transceivers remain for future offers.

Example: A server requests one audio section twice. The second message adds another audio transceiver, leaving two where one suffices.

Recommended fix: Inside publisher.withPeerConnection, count existing usable receiving transceivers by media type and add only each positive shortfall. Test repeated and increasing requirements.

Devin Review


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

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

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

This is the same behavior as our JS sdk.

@github-actions

github-actions Bot commented Nov 9, 2026 •

Copy link
Copy Markdown
Contributor

Diffuse output:

OLD: diffuse-source-file
NEW: livekit-android-sdk-release.aar

 AAR      │ old      │ new      │ diff      
──────────┼──────────┼──────────┼───────────
      jar │  3.1 MiB │  3.1 MiB │ +35.5 KiB 
 manifest │  1.5 KiB │  1.5 KiB │       0 B 
 lint-jar │ 12.7 KiB │ 12.7 KiB │       0 B 
    other │  2.4 KiB │  2.4 KiB │       0 B 
──────────┼──────────┼──────────┼───────────
    total │  3.1 MiB │  3.1 MiB │ +35.5 KiB 

 JAR     │ old   │ new   │ diff            
─────────┼───────┼───────┼─────────────────
 classes │  1780 │  1794 │  +14 (+19 -5)   
 methods │ 22545 │ 22659 │ +114 (+149 -35) 
  fields │  5938 │  5984 │  +46 (+61 -15)
AAR
 size    │ diff      │ path          
─────────┼───────────┼───────────────
 3.1 MiB │ +35.5 KiB │ ∆ classes.jar 
─────────┼───────────┼───────────────
 3.1 MiB │ +35.5 KiB │ (total)
JAR
CLASSES:

   old  │ new  │ diff         
  ──────┼──────┼──────────────
   1780 │ 1794 │ +14 (+19 -5) 
  
  + io.livekit.android.room.DuplexTransportObserver_WhenMappings
  + io.livekit.android.room.DuplexTransportObserver_onAddTrack_1
  + io.livekit.android.room.DuplexTransportObserver
  + io.livekit.android.room.RTCEngine_attachBoundTracks_1
  + io.livekit.android.room.RTCEngine_configure_2_2_4_1_1_1
  + io.livekit.android.room.RTCEngine_configure_2_2_4_1_1_2
  + io.livekit.android.room.RTCEngine_configure_2_2_4_1_1
  + io.livekit.android.room.RTCEngine_configure_2_2_5
  + io.livekit.android.room.SignalClient_connect_4_1_1
  + io.livekit.android.room.SignalClient_connect_4
  + io.livekit.android.room.SinglePeerConnectionTransport_applyServerAnswer_1
  + io.livekit.android.room.SinglePeerConnectionTransport_attachBoundTracks_2
  + io.livekit.android.room.SinglePeerConnectionTransport_handleMediaSectionsRequirement_2
  + io.livekit.android.room.SinglePeerConnectionTransport_syncStateDescriptions_1
  + io.livekit.android.room.SinglePeerConnectionTransport_syncStateDescriptions_2
  + io.livekit.android.room.SinglePeerConnectionTransport_trackIdForReceiver_mid_1_1
  + io.livekit.android.room.SinglePeerConnectionTransport_trackIdForReceiver_mid_1
  + io.livekit.android.room.SinglePeerConnectionTransport
  + io.livekit.android.room.util.SignalUrlBuilder
  
  - io.livekit.android.room.RTCEngine_configure_2_2_3_1_1_1
  - io.livekit.android.room.RTCEngine_configure_2_2_3_1_1_2
  - io.livekit.android.room.RTCEngine_configure_2_2_3_1_1
  - io.livekit.android.room.SignalClient_connect_3_1_1
  - io.livekit.android.room.SignalClient_connect_3
  

METHODS:

   old   │ new   │ diff            
  ───────┼───────┼─────────────────
   22545 │ 22659 │ +114 (+149 -35) 
  
  + io.livekit.android.ConnectOptions <init>(boolean, List, PeerConnection_RTCConfiguration, boolean, boolean, ProtocolVersion, ClientProtocolVersion, boolean)
  + io.livekit.android.ConnectOptions <init>(boolean, List, PeerConnection_RTCConfiguration, boolean, boolean, ProtocolVersion, ClientProtocolVersion, boolean, int, DefaultConstructorMarker)
  + io.livekit.android.ConnectOptions component8() → boolean
  + io.livekit.android.ConnectOptions copy(boolean, List, PeerConnection_RTCConfiguration, boolean, boolean, ProtocolVersion, ClientProtocolVersion, boolean) → ConnectOptions
  + io.livekit.android.ConnectOptions copy_default(ConnectOptions, boolean, List, PeerConnection_RTCConfiguration, boolean, boolean, ProtocolVersion, ClientProtocolVersion, boolean, int, Object) → ConnectOptions
  + io.livekit.android.ConnectOptions getSinglePeerConnection() → boolean
  + io.livekit.android.room.DualPeerConnectionTransport attachBoundTracks(Continuation) → Object
  + io.livekit.android.room.DuplexTransportObserver <init>(RTCEngine, SignalClient, RTCThreadToken)
  + io.livekit.android.room.DuplexTransportObserver onAddTrack(RtpReceiver, MediaStream[])
  + io.livekit.android.room.DuplexTransportObserver onTrack(RtpTransceiver)
  + io.livekit.android.room.DuplexTransportObserver_WhenMappings <clinit>()
  + io.livekit.android.room.DuplexTransportObserver_onAddTrack_1 <init>(RtpReceiver, MediaStream[], DuplexTransportObserver)
  + io.livekit.android.room.DuplexTransportObserver_onAddTrack_1 invoke() → Object
  + io.livekit.android.room.DuplexTransportObserver_onAddTrack_1 invoke()
  + io.livekit.android.room.PeerConnectionTransport isStaleAnswer(int) → boolean
  + io.livekit.android.room.PeerConnectionTransport_setRemoteDescription_result_1 <init>(SessionDescription, PeerConnectionTransport, int, Continuation)
  + io.livekit.android.room.PublisherTransportObserver getClient() → SignalClient
  + io.livekit.android.room.PublisherTransportObserver getEngine() → RTCEngine
  + io.livekit.android.room.PublisherTransportObserver getRtcThreadToken() → RTCThreadToken
  + io.livekit.android.room.RTCEngine access_isSubscriberPrimary_p(RTCEngine) → boolean
  + io.livekit.android.room.RTCEngine access_setConnectOptions_p(RTCEngine, ConnectOptions)
  + io.livekit.android.room.RTCEngine access_setPublisherObserver_p(RTCEngine, PublisherTransportObserver)
  + io.livekit.android.room.RTCEngine attachBoundTracks_livekit_android_sdk_release()
  + io.livekit.android.room.RTCEngine_Listener onTrackBound(RtpReceiver, MediaStreamTrack, String) → boolean
  + io.livekit.android.room.RTCEngine_Listener_DefaultImpls onTrackBound(RTCEngine_Listener, RtpReceiver, MediaStreamTrack, String) → boolean
  + io.live
...✂

The /rtc/v1 URL carries the whole encoded join request, including the
client metadata, so the connection log now shows the path with the
join_request value replaced. The legacy URL is logged as before.
libwebrtc reports a received track only when its media section starts
receiving. When the server binds another publication to a section that
is already receiving, the answer's mid_to_track_id changes and nothing
else happens, so that subscription stayed pending.

After each accepted answer, SinglePeerConnectionTransport now walks the
transceivers and offers every receiver whose section is mapped to a
track ID it is not attached as. Room finds the publication's owner by
track SID, since a receiver found this way has no stream to name its
participant, and attaches through the same helper the track callback
uses. A receiver whose publication is not known yet is offered again
after the next answer.

A stale answer is now rejected before its mapping is recorded. The
mapping is still recorded before the answer is applied, because track
callbacks fire while it is being applied and read it.
In single peer connection mode the server cannot offer, so it sends a
MediaSectionsRequirement whenever it needs the client to. The counts
only cover sections that do not exist yet: removing a track, or binding
a new one to an idle section, sends the requirement with both at zero.
Negotiation used to follow only from adding a transceiver, so a
zero-count requirement produced no offer and the server's change never
arrived.

RTCEngine now requests a publisher negotiation after handling the
requirement. The server only sends this message when it has no
subscriber transport, so dual peer connection mode is unaffected.
devin-ai-integration[bot]

This comment was marked as resolved.

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

lgtm, but you should take a look at the remaining devin comment to make sure we handle that corner case. like either throw an exception when that happens, or handle it gratefully

A track the server binds without a track callback is attached by
finding the participant that owns the publication. When the answer
carrying the binding arrives before the participant update announcing
that publication, there is no owner to find, and the binding was only
tried again after the next answer. With no further answer the track
stayed unsubscribed.

Room now asks the engine to attach bound tracks after every participant
update, which runs the same transceiver walk as an accepted answer.
Bindings that are already attached are skipped, and dual peer
connection mode has nothing to attach.
@changt
changt merged commit 20cd9e6 into main Nov 13, 2026
6 checks passed
@changt
changt deleted the sc/single-pc-transport branch November 13, 2026 17:23
@davidliu davidliu mentioned this pull request Nov 13, 2026
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.

2 participants