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

Add `LiveKit.enableFlexFec` to negotiate FlexFEC, and `RemoteTrackPublication.setFecProtection` to request FlexFEC repair packets from the server for a subscribed video track, with disabled, adaptive, fixed and minimum modes and low, medium and high levels.
21 changes: 21 additions & 0 deletions livekit-android-sdk/src/main/java/io/livekit/android/LiveKit.kt
Original file line number Diff line number Diff line change
Expand Up @@ -64,6 +64,27 @@ object LiveKit {
@JvmStatic
var enableWebRTCLogging: Boolean = false

/**
* Enables FlexFEC forward error correction for video.
*
* When enabled, connections negotiate `flexfec-03`, which lets subscribed video tracks
* receive repair packets from the server, see
* [io.livekit.android.room.track.RemoteTrackPublication.setFecProtection].
* Video tracks published without simulcast also send FlexFEC, at a rate WebRTC adapts to the
* reported loss; WebRTC does not protect simulcast tracks with FlexFEC.
* Disabled by default.
*
* This is a process-wide WebRTC setting, so it must be set before the first [Room] is
* created or [init] is called; later changes have no effect.
*
* ```
* LiveKit.enableFlexFec = true
* val room = LiveKit.create(appContext)
* ```
*/
@JvmStatic
var enableFlexFec: Boolean = false

/**
* Certain WebRTC classes need to be initialized prior to use.
*
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -91,6 +91,10 @@ internal object RTCModule {
* it.
*/
private const val DEFAULT_FIELD_TRIALS = "WebRTC-IceHandshakeDtls/Enabled/"
private const val FLEXFEC_FIELD_TRIALS = "WebRTC-FlexFEC-03-Advertised/Enabled/WebRTC-FlexFEC-03/Enabled/"

private val fieldTrials: String
get() = if (LiveKit.enableFlexFec) DEFAULT_FIELD_TRIALS + FLEXFEC_FIELD_TRIALS else DEFAULT_FIELD_TRIALS

/**
* Certain classes require libwebrtc to be initialized prior to use.
Expand Down Expand Up @@ -122,7 +126,7 @@ internal object RTCModule {
PeerConnectionFactory.InitializationOptions
.builder(appContext)
.setNativeLibraryName("lkjingle_peerconnection_so")
.setFieldTrials(DEFAULT_FIELD_TRIALS)
.setFieldTrials(fieldTrials)
.setInjectableLogger(
{ s, severity, s2 ->
if (!LiveKit.enableWebRTCLogging) {
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -529,12 +529,14 @@ constructor(
sendRequest(request)
}

@Suppress("LongParameterList")
fun sendUpdateTrackSettings(
sid: String,
disabled: Boolean,
videoDimensions: Track.Dimensions?,
videoQuality: LivekitModels.VideoQuality?,
fps: Int?,
fecProtection: LivekitRtc.FECProtection? = null,
) {
val trackSettings = LivekitRtc.UpdateTrackSettings.newBuilder()
.addTrackSids(sid)
Expand All @@ -553,6 +555,10 @@ constructor(
if (fps != null) {
setFps(fps)
}

if (fecProtection != null) {
fec = fecProtection
}
}

val request = LivekitRtc.SignalRequest.newBuilder()
Expand Down
Original file line number Diff line number Diff line change
@@ -0,0 +1,92 @@
/*
* 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.track

import livekit.LivekitRtc

/**
* Proactive FlexFEC protection the server adds to a subscribed video track.
*
* The server sends repair packets alongside the track's media, so the receiver can recover lost
* packets without waiting for a retransmission.
*
* @see RemoteTrackPublication.setFecProtection
*/
sealed class FecProtection {
/** No repair packets. This is the default. */
data object Disabled : FecProtection()

/**
* Protection follows the observed packet loss, using the same algorithm as libwebrtc.
*/
data object Adaptive : FecProtection()

/**
* Constant protection at [level], regardless of packet loss.
*/
data class Fixed(val level: FecProtectionLevel) : FecProtection()

/**
* Protection never drops below [level]. It rises adaptively under higher packet loss, and
* returns to [level] once the loss subsides.
*/
data class Minimum(val level: FecProtectionLevel) : FecProtection()

internal fun toProto(): LivekitRtc.FECProtection {
val builder = LivekitRtc.FECProtection.newBuilder()
when (this) {
Disabled -> builder.mode = LivekitRtc.FECProtectionMode.FEC_MODE_DISABLED
Adaptive -> builder.mode = LivekitRtc.FECProtectionMode.FEC_MODE_ADAPTIVE
is Fixed -> {
builder.mode = LivekitRtc.FECProtectionMode.FEC_MODE_FIXED
builder.level = level.toProto()
}

is Minimum -> {
builder.mode = LivekitRtc.FECProtectionMode.FEC_MODE_MINIMUM
builder.level = level.toProto()
}
}
return builder.build()
}
}

/**
* The share of packets spent on FlexFEC repairs, used by [FecProtection.Fixed] and
* [FecProtection.Minimum].
*
* Frames that span only a few packets get proportionally more repairs.
*/
enum class FecProtectionLevel {
/** Approximately 15% repair packet overhead. */
LOW,

/** Approximately 25% repair packet overhead. */
MEDIUM,

/** Approximately 35% repair packet overhead. */
HIGH,
;

internal fun toProto(): LivekitRtc.FECProtectionLevel {
return when (this) {
LOW -> LivekitRtc.FECProtectionLevel.FEC_LEVEL_LOW
MEDIUM -> LivekitRtc.FECProtectionLevel.FEC_LEVEL_MEDIUM
HIGH -> LivekitRtc.FECProtectionLevel.FEC_LEVEL_HIGH
}
}
}
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 @@ -75,6 +75,15 @@ class RemoteTrackPublication(
private var videoDimensions: Track.Dimensions? = null
private var fps: Int? = null

/**
* The FlexFEC protection requested with [setFecProtection].
*/
val fecProtection: FecProtection
get() = requestedFecProtection ?: FecProtection.Disabled

// null until requested, so updates leave the server's setting unchanged
private var requestedFecProtection: FecProtection? = null

var subscriptionAllowed: Boolean = true
internal set

Expand Down Expand Up @@ -204,6 +213,29 @@ class RemoteTrackPublication(
sendUpdateTrackSettings.invoke()
}

/**
* Requests proactive FlexFEC repair packets from the server for this video track.
*
* Repairs let the receiver recover lost packets without waiting for a retransmission, at the
* cost of extra bandwidth. The protection changes without renegotiation, and is applied even
* when the track's quality is managed by adaptive stream.
*
* Repairs are only sent when the server has downstream FlexFEC enabled and FlexFEC was
* negotiated, which requires [io.livekit.android.LiveKit.enableFlexFec]. Otherwise the request
* has no effect.
*
* ```
* publication.setFecProtection(FecProtection.Minimum(FecProtectionLevel.MEDIUM))
* ```
*/
fun setFecProtection(protection: FecProtection) {
if (!subscribed || track !is VideoTrack || protection == requestedFecProtection) {
return
}
requestedFecProtection = protection
sendUpdateTrackSettings.invoke()
}

private fun handleVisibilityChanged(isVisible: Boolean) {
disabled = !isVisible
sendUpdateTrackSettings.invoke()
Expand Down Expand Up @@ -237,6 +269,7 @@ class RemoteTrackPublication(
videoDimensions,
videoQuality?.toProto(),
fps,
requestedFecProtection?.toProto(),
)
}

Expand Down
6 changes: 6 additions & 0 deletions livekit-android-test/src/androidTest/AndroidManifest.xml
Original file line number Diff line number Diff line change
@@ -0,0 +1,6 @@
<?xml version="1.0" encoding="utf-8"?>
<manifest xmlns:android="http://schemas.android.com/apk/res/android">

<!-- Lets on-device tests reach a local development server over ws:// -->
<application android:usesCleartextTraffic="true" />
</manifest>
Loading
Loading