feat(audio): negotiate stereo opus on the subscriber answer

.changeset/stereo-answer-munging.md

@@ -0,0 +1,5 @@
+---
+'livekit-android': patch
+---
+
+Negotiate stereo Opus on the subscriber answer: add `stereo=1` to the fmtp line for media sections where the server offer advertised `sprop-stereo=1`. Without this, a stereo track published by another participant is decoded as mono on Android. Mirrors client-sdk-js behavior.

livekit-android-sdk/src/main/java/io/livekit/android/room/RTCEngine.kt

@@ -55,6 +55,7 @@ import io.livekit.android.webrtc.DataPacketBuffer
 import io.livekit.android.webrtc.DataPacketItem
 import io.livekit.android.webrtc.RTCStatsGetter
 import io.livekit.android.webrtc.copy
+import io.livekit.android.webrtc.ensureStereoOpus
 import io.livekit.android.webrtc.isConnected
 import io.livekit.android.webrtc.isDisconnected
 import io.livekit.android.webrtc.peerconnection.RTCThreadToken
@@ -1158,20 +1159,37 @@ internal constructor(
                 return@launch
             }
 
-            run<Unit> {
-                when (val outcome = subscriber?.withPeerConnection { setLocalDescription(answer) }.nullSafe()) {
-                    is Either.Left -> Unit
-                    is Either.Right -> {
-                        LKLog.e { "error setting local description for answer: ${outcome.value}" }
-                        return@launch
-                    }
-                }
-            }
+            val stereoAnswer = answer.ensureStereoOpus(sessionDescription)
+
+            val answerToSend = setLocalDescriptionWithStereoFallback(
+                stereoAnswer = stereoAnswer,
+                fallbackAnswer = answer,
+            ) ?: return@launch
 
             if (isClosed) {
                 return@launch
             }
-            client.sendAnswer(answer, offerId)
+            client.sendAnswer(answerToSend, offerId)
+        }
+    }
+
+    private suspend fun setLocalDescriptionWithStereoFallback(
+        stereoAnswer: SessionDescription,
+        fallbackAnswer: SessionDescription,
+    ): SessionDescription? {
+        when (val outcome = subscriber?.withPeerConnection { setLocalDescription(stereoAnswer) }.nullSafe()) {
+            is Either.Left -> return stereoAnswer
+            is Either.Right -> LKLog.e { "error setting local description for munged answer: ${outcome.value}" }
+        }
+        // Fall back to the un-munged answer rather than leaving the
+        // subscriber without a local description (mirrors
+        // PeerConnectionTransport.setMungedSdp).
+        when (val fallback = subscriber?.withPeerConnection { setLocalDescription(fallbackAnswer) }.nullSafe()) {
+            is Either.Left -> return fallbackAnswer
+            is Either.Right -> {
+                LKLog.e { "error setting local description for answer: ${fallback.value}" }
+                return null
+            }
         }
     }
 

livekit-android-sdk/src/main/java/io/livekit/android/webrtc/StereoSdpMunging.kt

@@ -0,0 +1,164 @@
+/*
+ * 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.webrtc
+
+import android.javax.sdp.MediaDescription
+import android.javax.sdp.SdpException
+import android.javax.sdp.SdpFactory
+import android.javax.sdp.SdpParseException
+import androidx.annotation.VisibleForTesting
+import io.livekit.android.util.LKLog
+import livekit.org.webrtc.SessionDescription
+
+private const val OPUS_CODEC = "opus"
+private const val STEREO_FMTP_PARAM = "stereo=1"
+private const val STEREO_PARAM_PREFIX = "stereo="
+private const val SPROP_STEREO_FMTP_PARAM = "sprop-stereo=1"
+private const val MID_ATTRIBUTE = "mid"
+
+/**
+ * Adds `stereo=1` to the Opus fmtp line of the answer for every audio media
+ * section where [offer] advertised `sprop-stereo=1`.
+ *
+ * The native Opus decoder downmixes incoming stereo packets to mono unless the
+ * local answer negotiates `stereo=1`, so without this munging a stereo track
+ * published by another participant is received as mono.
+ *
+ * Mirrors the behavior of client-sdk-js, which extracts `remoteStereoMids` from
+ * the server offer and rewrites the matching fmtp lines when creating the answer.
+ *
+ * @suppress
+ */
+@VisibleForTesting
+internal fun SessionDescription.ensureStereoOpus(offer: SessionDescription): SessionDescription {
+    val sdpFactory = SdpFactory.getInstance()
+    val parsedAnswer = parseSessionDescription(sdpFactory, description) ?: return this
+    val parsedOffer = parseSessionDescription(sdpFactory, offer.description) ?: return this
+
+    val stereoMids = findStereoMids(parsedOffer)
+    if (stereoMids.isEmpty()) {
+        return this
+    }
+
+    for (mediaDesc in mediaDescriptionsOf(parsedAnswer)) {
+        val mid = midOf(mediaDesc) ?: continue
+        if (mid !in stereoMids) continue
+
+        val payloadType = findOpusPayloadType(mediaDesc) ?: continue
+        ensureStereoFmtpParam(mediaDesc, payloadType)
+    }
+
+    return try {
+        SessionDescription(type, parsedAnswer.toString())
+    } catch (_: SdpException) {
+        this
+    }
+}
+
+private fun parseSessionDescription(
+    sdpFactory: SdpFactory,
+    description: String,
+): android.javax.sdp.SessionDescription? = try {
+    sdpFactory.createSessionDescription(description)
+} catch (_: SdpParseException) {
+    LKLog.w { "stereo munging: could not parse sdp" }
+    null
+}
+
+private fun mediaDescriptionsOf(parsed: android.javax.sdp.SessionDescription): List<MediaDescription> {
+    val raw = try {
+        parsed.getMediaDescriptions(true)
+    } catch (_: SdpException) {
+        return emptyList()
+    }
+    return raw.filterIsInstance<MediaDescription>()
+}
+
+private fun findStereoMids(offer: android.javax.sdp.SessionDescription): List<String> {
+    val mids = mutableListOf<String>()
+    for (mediaDesc in mediaDescriptionsOf(offer)) {
+        if (isPublisherStereo(mediaDesc)) {
+            midOf(mediaDesc)?.let { mids.add(it) }
+        }
+    }
+    return mids
+}
+
+private fun midOf(mediaDesc: MediaDescription): String? = try {
+    mediaDesc.getAttribute(MID_ATTRIBUTE)
+} catch (_: SdpParseException) {
+    null
+}
+
+private fun isPublisherStereo(mediaDesc: MediaDescription): Boolean {
+    val payloadType = findOpusPayloadType(mediaDesc) ?: return false
+    for ((_, fmtp) in mediaDesc.getFmtps()) {
+        if (fmtp.payload == payloadType && fmtp.config.split(";").any { it.trim() == SPROP_STEREO_FMTP_PARAM }) {
+            return true
+        }
+    }
+    return false
+}
+
+private fun findOpusPayloadType(mediaDesc: MediaDescription): Long? {
+    for ((_, rtp) in mediaDesc.getRtps()) {
+        if (rtp.codec.equals(OPUS_CODEC, ignoreCase = true)) {
+            return rtp.payload
+        }
+    }
+    return null
+}
+
+/* The native Opus decoder requires both sides of the negotiation to carry
+stereo=1. The server only puts sprop-stereo=1 into its offer; the answer must
+add the stereo=1 parameter itself or received packets are decoded as mono. An
+existing conflicting value such as stereo=0 is replaced, since the decoder
+honors the first stereo parameter and would otherwise stay mono.
+*/
+private fun ensureStereoFmtpParam(mediaDesc: MediaDescription, payloadType: Long) {
+    var fmtpFound = false
+    for ((attribute, fmtp) in mediaDesc.getFmtps()) {
+        if (fmtp.payload != payloadType) {
+            continue
+        }
+        fmtpFound = true
+        val params = fmtp.config.split(";").map { it.trim() }
+        val hasStereo = params.any { it.equals(STEREO_FMTP_PARAM, ignoreCase = true) }
+        val hasConflictingStereo = params.any {
+            it.startsWith(STEREO_PARAM_PREFIX, ignoreCase = true) &&
+                !it.equals(STEREO_FMTP_PARAM, ignoreCase = true)
+        }
+        if (!hasStereo || hasConflictingStereo) {
+            try {
+                val updated = params
+                    .filterNot { it.startsWith(STEREO_PARAM_PREFIX, ignoreCase = true) }
+                    .plus(STEREO_FMTP_PARAM)
+                attribute.setValue("${fmtp.payload} ${updated.joinToString(";")}")
+            } catch (_: SdpException) {
+                LKLog.w { "stereo munging: failed to update opus fmtp line" }
+            }
+        }
+        break
+    }
+
+    // Not found, add manually
+    if (!fmtpFound) {
+        mediaDesc.addAttribute(
+            SdpFmtp(payloadType, STEREO_FMTP_PARAM).toAttributeField(),
+        )
+    }
+}