Skip to content
Merged
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/single-peer-connection.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,5 @@
---
"client-sdk-android": minor
---

Add `ConnectOptions.singlePeerConnection`, which joins through the `/rtc/v1` signal path and publishes and receives on one peer connection instead of a publisher and a subscriber. The client makes every offer; the server's media sections requirement adds receive-only transceivers, and the answer's mid-to-track mapping resolves received tracks. A server without `/rtc/v1` answers that handshake with 404, in which case the join retries on the legacy path with dual peer connections and later reconnects stay there. The option is off by default.
1 change: 1 addition & 0 deletions livekit-android-sdk/detekt-baseline-release.xml
Original file line number Diff line number Diff line change
Expand Up @@ -24,6 +24,7 @@
<ID>CyclomaticComplexMethod:RTCEngine.kt$RTCEngine$@Synchronized @VisibleForTesting(otherwise = VisibleForTesting.PACKAGE_PRIVATE) fun reconnect()</ID>
<ID>CyclomaticComplexMethod:RTCEngine.kt$RTCEngine$fun onMessage(dataChannel: DataChannel, buffer: DataChannel.Buffer?)</ID>
<ID>CyclomaticComplexMethod:RTCEngine.kt$RTCEngine$private fun makeRTCConfig( serverResponse: Either&lt;JoinResponse, ReconnectResponse>, connectOptions: ConnectOptions, ): RTCConfiguration</ID>
<ID>CyclomaticComplexMethod:RTCEngine.kt$RTCEngine$private suspend fun configure(joinResponse: JoinResponse, connectOptions: ConnectOptions)</ID>
<ID>CyclomaticComplexMethod:Room.kt$Room$@Throws(Exception::class) suspend fun connect(url: String, token: String, options: ConnectOptions = ConnectOptions())</ID>
<ID>CyclomaticComplexMethod:RoomEvent.kt$fun LivekitModels.DisconnectReason?.convert(): DisconnectReason</ID>
<ID>CyclomaticComplexMethod:SignalClient.kt$SignalClient$override fun onFailure(webSocket: WebSocket, t: Throwable, response: Response?)</ID>
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -62,6 +62,15 @@ data class ConnectOptions(
* version supported by this SDK build.
*/
val clientProtocol: ClientProtocolVersion = ClientProtocolVersion.DATA_STREAM_V2,

/**
* Use a single peer connection instead of one subscriber and one publisher.
*
* ```
* room.connect(url, token, ConnectOptions(singlePeerConnection = true))
* ```
*/
val singlePeerConnection: Boolean = false,
Comment thread
xianshijing-lk marked this conversation as resolved.
Resolved
) {
internal var reconnect: Boolean = false
internal var participantSid: String? = null
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -111,6 +111,10 @@ internal class DualPeerConnectionTransport(
return null
}

override suspend fun attachBoundTracks() {
// Not needed for dual transport.
}

override suspend fun handleMediaSectionsRequirement(requirement: LivekitRtc.MediaSectionsRequirement) {
// Not needed for dual transport.
}
Expand Down
Original file line number Diff line number Diff line change
@@ -0,0 +1,47 @@
/*
* 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.util.LKLog
import io.livekit.android.webrtc.peerconnection.RTCThreadToken
import io.livekit.android.webrtc.peerconnection.executeOnRTCThread
import livekit.org.webrtc.MediaStream
import livekit.org.webrtc.MediaStreamTrack
import livekit.org.webrtc.RtpReceiver
import livekit.org.webrtc.RtpTransceiver

internal class DuplexTransportObserver(engine: RTCEngine, client: SignalClient, rtcThreadToken: RTCThreadToken) :
PublisherTransportObserver(engine, client, rtcThreadToken) {

override fun onTrack(transceiver: RtpTransceiver?) {
when (transceiver?.mediaType) {
MediaStreamTrack.MediaType.MEDIA_TYPE_AUDIO -> LKLog.v { "peerconn started receiving audio" }
MediaStreamTrack.MediaType.MEDIA_TYPE_VIDEO -> LKLog.v { "peerconn started receiving video" }
else -> LKLog.d { "peerconn started receiving unknown media type: ${transceiver?.mediaType}" }
}
}

override fun onAddTrack(receiver: RtpReceiver?, streams: Array<out MediaStream>?) {
executeOnRTCThread(rtcThreadToken) {
if (receiver != null && streams != null) {
val track = receiver.track() ?: return@executeOnRTCThread
LKLog.v { "onAddTrack: ${track.kind()}, ${track.id()}, ${streams.fold("") { sum, it -> "$sum, $it" }}" }
engine.listener?.onAddTrack(receiver, track, streams)
}
}
}
}
Original file line number Diff line number Diff line change
Expand Up @@ -135,11 +135,18 @@ constructor(
}
}

/**
* @return whether an answer for [offerId] answers an offer older than the latest one sent.
*/
fun isStaleAnswer(offerId: Int): Boolean {
val currentOfferId = latestOfferId.get()
return currentOfferId > 0 && offerId > 0 && currentOfferId > offerId
}

suspend fun setRemoteDescription(sd: SessionDescription, offerId: Int): Either<Unit, String?> {
val result = launchRTCIfNotClosed {
val currentOfferId = latestOfferId.get()
if (sd.type == SessionDescription.Type.ANSWER && currentOfferId > 0 && offerId > 0 && currentOfferId > offerId) {
return@launchRTCIfNotClosed Either.Right("Old offer, ignoring. Expected: $currentOfferId, actual: $offerId")
if (sd.type == SessionDescription.Type.ANSWER && isStaleAnswer(offerId)) {
return@launchRTCIfNotClosed Either.Right("Old offer, ignoring. Expected: ${latestOfferId.get()}, actual: $offerId")
}
val result = peerConnection.setRemoteDescription(sd)
if (result is Either.Left) {
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 @@ -32,18 +32,18 @@ import livekit.org.webrtc.RtpReceiver
import livekit.org.webrtc.RtpTransceiver
import livekit.org.webrtc.SessionDescription

internal class PublisherTransportObserver(
private val engine: RTCEngine,
private val client: SignalClient,
private val rtcThreadToken: RTCThreadToken,
internal open class PublisherTransportObserver(
protected val engine: RTCEngine,
protected val client: SignalClient,
protected val rtcThreadToken: RTCThreadToken,
) : PeerConnection.Observer, PeerConnectionTransport.Listener, PeerConnectionStateObservable {

var connectionChangeListener: PeerConnectionStateListener? = null

@FlowObservable
@get:FlowObservable
override var connectionState by flowDelegate(PeerConnection.PeerConnectionState.NEW)
private set
protected set

override fun onIceCandidate(iceCandidate: IceCandidate?) {
executeOnRTCThread(rtcThreadToken) {
Expand Down Expand Up @@ -107,6 +107,6 @@ internal class PublisherTransportObserver(
override fun onTrack(transceiver: RtpTransceiver?) {
}

override fun onAddTrack(p0: RtpReceiver?, p1: Array<out MediaStream>?) {
override fun onAddTrack(receiver: RtpReceiver?, streams: Array<out MediaStream>?) {
}
}
Original file line number Diff line number Diff line change
Expand Up @@ -205,7 +205,7 @@ internal constructor(
internal val serverInfo: ServerInfo?
get() = client.serverInfo

private val publisherObserver = PublisherTransportObserver(this, client, rtcThreadToken)
private var publisherObserver: PublisherTransportObserver? = null
private val subscriberObserver = SubscriberTransportObserver(this, client, rtcThreadToken)

internal var transport: Transport? = null
Expand Down Expand Up @@ -298,7 +298,25 @@ internal constructor(
if (connectionState == ConnectionState.DISCONNECTED) {
connectionState = ConnectionState.CONNECTING
}
val joinResponse = client.join(url, token, options, roomOptions)
var effectiveOptions = options
val joinResponse = try {
client.join(url, token, options, roomOptions)
} catch (e: RoomException.ConnectException) {
// A server that predates /rtc/v1 answers that handshake with 404.
if (!options.singlePeerConnection || e.statusCode != 404) {
onError(e)
throw e
}
LKLog.w { "server has no /rtc/v1 path, retrying on the legacy path with dual peer connections" }
effectiveOptions = options.copy(singlePeerConnection = false)
connectOptions = effectiveOptions
try {
client.join(url, token, effectiveOptions, roomOptions)
} catch (e: RoomException.ConnectException) {
onError(e)
throw e
}
}
ensureActive()

if (joinResponse.hasParticipant()) {
Expand All @@ -318,9 +336,9 @@ internal constructor(
isClosed = false
listener?.onSignalConnected(false)

isSubscriberPrimary = joinResponse.subscriberPrimary
isSubscriberPrimary = !effectiveOptions.singlePeerConnection && joinResponse.subscriberPrimary

configure(joinResponse, options)
configure(joinResponse, effectiveOptions)
// The publisher created above needs the attempt's start time before its first offer, in
// case video is published before the primary transport connects.
transport?.publisher?.setConnectStartedAt(startedAtMs)
Expand All @@ -347,6 +365,13 @@ internal constructor(
}
},
) {
val publisherObserver = if (connectOptions.singlePeerConnection) {
DuplexTransportObserver(this@RTCEngine, client, rtcThreadToken)
} else {
PublisherTransportObserver(this@RTCEngine, client, rtcThreadToken)
}
this@RTCEngine.publisherObserver = publisherObserver

participantSid = if (joinResponse.hasParticipant()) {
joinResponse.participant.sid
} else {
Expand All @@ -360,9 +385,6 @@ internal constructor(
publisherObserver,
publisherObserver,
)
val subscriber = runCatching { pctFactory.create(rtcConfig, subscriberObserver, null) }
.onFailure { publisher.close() }
.getOrThrow()

val connectionStateListener: PeerConnectionStateListener = { newState ->
LKLog.v { "onIceConnection new state: $newState" }
Expand All @@ -373,7 +395,7 @@ internal constructor(
}
}

if (joinResponse.subscriberPrimary) {
if (this@RTCEngine.isSubscriberPrimary) {
// in subscriber primary mode, server side opens sub data channels.
subscriberObserver.dataChannelListener = onDataChannel@{ dataChannel: DataChannel ->
when (dataChannel.label()) {
Expand All @@ -396,14 +418,27 @@ internal constructor(
publisherObserver.connectionChangeListener = connectionStateListener
}

transport = DualPeerConnectionTransport(
publisher,
subscriber,
publisherObserver,
subscriberObserver,
joinResponse.subscriberPrimary,
joinResponse.fastPublish,
)
if (connectOptions.singlePeerConnection) {
transport = SinglePeerConnectionTransport(
publisher,
publisherObserver,
) { receiver, track, trackSid ->
listener?.onTrackBound(receiver, track, trackSid) == true
}
} else {
val subscriber = runCatching { pctFactory.create(rtcConfig, subscriberObserver, null) }
.onFailure { publisher.close() }
.getOrThrow()

transport = DualPeerConnectionTransport(
publisher,
subscriber,
publisherObserver,
subscriberObserver,
joinResponse.subscriberPrimary,
joinResponse.fastPublish,
)
}

ensureActive()
// data channels
Expand Down Expand Up @@ -551,7 +586,7 @@ internal constructor(
executeBlockingOnRTCThread(rtcThreadToken) {
runBlocking {
configurationLock.withLock {
publisherObserver.connectionChangeListener = null
publisherObserver?.connectionChangeListener = null
subscriberObserver.connectionChangeListener = null
transport?.close()
transport = null
Expand Down Expand Up @@ -969,7 +1004,7 @@ internal constructor(
}

throw RoomException.ConnectException(
"could not establish publisher connection: publisher state: ${publisherObserver.connectionState}, channel state: ${channelManager.state}",
"could not establish publisher connection: publisher state: ${publisherObserver?.connectionState}, channel state: ${channelManager.state}",
)
}

Expand Down Expand Up @@ -1149,6 +1184,14 @@ internal constructor(
fun onJoinResponse(response: JoinResponse)
fun reattachRemoteDataTracks() {}
fun onAddTrack(receiver: RtpReceiver, track: MediaStreamTrack, streams: Array<out MediaStream>)

/**
* The server bound [receiver] to the publication [trackSid] without the peer connection
* reporting a new track.
*
* @return whether [track] is attached to that publication.
*/
fun onTrackBound(receiver: RtpReceiver, track: MediaStreamTrack, trackSid: String): Boolean = false
fun onUpdateParticipants(updates: List<LivekitModels.ParticipantInfo>)
fun onActiveSpeakersUpdate(speakers: List<LivekitModels.SpeakerInfo>)
fun onRemoteMuteChanged(trackSid: String, muted: Boolean)
Expand Down Expand Up @@ -1401,6 +1444,8 @@ internal constructor(
override fun onMediaSectionsRequirement(requirement: LivekitRtc.MediaSectionsRequirement) {
coroutineScope.launch {
transport?.handleMediaSectionsRequirement(requirement)
// The server asks for an offer this way, including when it needs no new section.
negotiatePublisher()
}
}

Expand Down Expand Up @@ -1637,6 +1682,15 @@ internal constructor(
return transport?.trackIdForReceiver(receiver)
}

/**
* Attaches the tracks the server has bound to publications that have since arrived.
*/
internal fun attachBoundTracks() {
coroutineScope.launch {
transport?.attachBoundTracks()
}
}

fun createStatsGetter(receiver: RtpReceiver): RTCStatsGetter {
val p = transport?.subscriber
return { statsCallback: RTCStatsCollectorCallback ->
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -1305,12 +1305,31 @@ constructor(
return
}

val statsGetter = engine.createStatsGetter(receiver)
attachTrack(participant, receiver, track, trackSid!!)
}

/**
* @suppress
*/
override fun onTrackBound(receiver: RtpReceiver, track: MediaStreamTrack, trackSid: String): Boolean {
val participant = remoteParticipants.values.firstOrNull { it.getTrackPublication(trackSid) != null }
if (participant == null) {
LKLog.d { "no publication yet for bound track $trackSid" }
return false
Comment thread
devin-ai-integration[bot] marked this conversation as resolved.
Resolved
}
attachTrack(participant, receiver, track, trackSid)
return true
}

private fun attachTrack(participant: RemoteParticipant, receiver: RtpReceiver, track: MediaStreamTrack, trackSid: String) {
if (participant.getTrackPublication(trackSid)?.track?.rtcTrack === track) {
return
}
participant.addSubscribedMediaTrack(
track,
trackSid!!,
trackSid,
autoManageVideo = adaptiveStream,
statsGetter = statsGetter,
statsGetter = engine.createStatsGetter(receiver),
receiver = receiver,
)
}
Expand Down Expand Up @@ -1353,6 +1372,8 @@ constructor(
}
}
}
// A track can be bound before the update that announces its publication.
engine.attachBoundTracks()
}

/**
Expand Down Expand Up @@ -1731,7 +1752,12 @@ constructor(

sealed class RoomException(message: String? = null, cause: Throwable? = null) :
Exception(message, cause) {
class ConnectException(message: String? = null, cause: Throwable? = null) :
/**
* @param statusCode HTTP status of the rejected signal connection: the validate endpoint's
* status when it reported an error, otherwise the websocket handshake's. Null when the
* failure did not come with an HTTP response, such as a network error.
*/
class ConnectException(message: String? = null, cause: Throwable? = null, val statusCode: Int? = null) :
RoomException(message, cause)
}

Expand Down
Loading
Loading