Default video degradation preference by track source, including the backup codec (#1155)

Aligns Flutter with the behavior landed in client-sdk-android
(livekit/client-sdk-android#991). Two related changes.

## Source-based defaults

Previously every video track fell back to `maintainResolution`, and the
preference was only applied to camera and screen share tracks at all:

```dart
if ([TrackSource.camera, TrackSource.screenShareVideo].contains(track.source)) {
  final degradationPreference = options.degradationPreference ?? DegradationPreference.maintainResolution;
  await track.setDegradationPreference(degradationPreference);
}
```

Now `getDefaultDegradationPreference(source)` resolves camera →
`maintainFramerate` (smoother video for real-time communication), screen
share → `maintainResolution` (clarity matters for text/UI), other →
`balanced`, and it is applied to every video sender. Custom sources
previously got whatever WebRTC derived implicitly from the native
source; `balanced` is the preference the WebRTC spec mandates as the
default and is the honest choice when the application declined to
declare a motion-vs-detail intent.

An explicitly set `degradationPreference` still wins in all cases — the
default only fills a null.

## Backup codec sender

Degradation preference is a property of the **sender**, not of the track
— a top-level field on `RtpParameters`, not per-encoding.
`publishAdditionalCodecForPublication` adds a second transceiver and
therefore a second sender, which was never configured, so the backup
encoder resolved a preference implicitly and could adapt along a
different axis than the primary.

Both senders sink from the same video source, so a diverging backup does
not just degrade itself — its restriction is merged onto the shared
source and affects the primary too.

`setDegradationPreference` now stores the resolved preference and fans
out to every sender, and `publishAdditionalCodecForPublication` applies
it to the backup sender once created. Using the track's stored resolved
value means the two encoders cannot disagree.

Note simulcast is unaffected — all simulcast encodings live under one
sender and already share its preference. Only the backup codec is a
separate sender.

## Tests

`test/options/degradation_preference_test.dart` covers the three source
mappings. Full suite passes (379 tests), `flutter analyze lib/ test/`
clean, `dart format` clean at the repo's 120-column width.

## Cross-SDK

client-sdk-js gets the backup-sender half in livekit/client-sdk-js#2040
(its source-based defaults already matched). The Rust SDK already
resolves the same defaults and has no backup-codec publish path. Swift
follows separately.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

---------

Co-authored-by: Claude Opus 5 (1M context) <noreply@anthropic.com>
Co-authored-by: Hiroshi Horie <548776+hiroshihorie@users.noreply.github.com>

Author: 3 people

.changes/default-degradation-preference-by-source

@@ -0,0 +1 @@
+patch type="changed" "Default video degradation preference is now based on the track source (camera maintains framerate, screen share maintains resolution, others balanced) and is applied to the backup codec's sender as well"

lib/src/options.dart

@@ -348,6 +348,29 @@ enum DegradationPreference {
   maintainFramerateAndResolution,
 }
 
+/// Returns the degradation preference to use for a video track published under
+/// [source], when the application did not set one explicitly.
+///
+/// - Camera: [DegradationPreference.maintainFramerate] (smoother video for
+///   real-time communication)
+/// - Screen share: [DegradationPreference.maintainResolution] (clarity is
+///   critical for reading text/UI)
+/// - Other/unknown: [DegradationPreference.balanced]
+///
+/// Any other source means the application declined to declare a
+/// motion-vs-detail intent, so this falls back to balanced, the preference the
+/// WebRTC spec mandates as the default.
+DegradationPreference getDefaultDegradationPreference(TrackSource source) {
+  switch (source) {
+    case TrackSource.camera:
+      return DegradationPreference.maintainFramerate;
+    case TrackSource.screenShareVideo:
+      return DegradationPreference.maintainResolution;
+    default:
+      return DegradationPreference.balanced;
+  }
+}
+
 class BackupVideoCodec {
   const BackupVideoCodec({
     this.enabled = true,
@@ -415,6 +438,13 @@ class VideoPublishOptions extends PublishOptions {
   /// Defaults to true.
   final bool simulcast;
 
+  /// Controls how the encoder trades off between resolution and framerate when
+  /// bandwidth is constrained.
+  ///
+  /// When null, the SDK picks a default based on the track's source, see
+  /// [getDefaultDegradationPreference]. A preference is always applied to video
+  /// senders, so leaving this null selects that default rather than deferring to
+  /// WebRTC's own implicit choice.
   final DegradationPreference? degradationPreference;
 
   final List<VideoParameters> videoSimulcastLayers;

lib/src/participant/local.dart

@@ -390,10 +390,9 @@ class LocalParticipant extends Participant<LocalTrackPublication> {
         );
       }
 
-      if ([TrackSource.camera, TrackSource.screenShareVideo].contains(track.source)) {
-        final degradationPreference = options.degradationPreference ?? DegradationPreference.maintainResolution;
-        await track.setDegradationPreference(degradationPreference);
-      }
+      await track.setDegradationPreference(
+        options.degradationPreference ?? getDefaultDegradationPreference(track.source),
+      );
 
       if (kIsWeb && lkBrowser() == BrowserType.firefox && track.kind == TrackType.AUDIO) {
         //TOOD:
@@ -489,10 +488,9 @@ class LocalParticipant extends Participant<LocalTrackPublication> {
         );
       }
 
-      if ([TrackSource.camera, TrackSource.screenShareVideo].contains(track.source)) {
-        final degradationPreference = publishOptions.degradationPreference ?? DegradationPreference.maintainResolution;
-        await track.setDegradationPreference(degradationPreference);
-      }
+      await track.setDegradationPreference(
+        publishOptions.degradationPreference ?? getDefaultDegradationPreference(track.source),
+      );
 
       if (kIsWeb && lkBrowser() == BrowserType.firefox && track.kind == TrackType.AUDIO) {
         //TOOD:
@@ -944,6 +942,10 @@ class LocalParticipant extends Participant<LocalTrackPublication> {
       backupCodec,
     );
 
+    // the backup codec publishes over its own sender, so it needs the same
+    // degradation preference the primary sender resolved to.
+    await track.applyDegradationPreference(simulcastTrack.sender);
+
     final cid = simulcastTrack.sender!.senderId;
 
     final req = lk_rtc.AddTrackRequest(

lib/src/track/local/video.dart

@@ -68,6 +68,8 @@ class LocalVideoTrack extends LocalTrack with VideoTrack {
   Map<String, SimulcastTrackInfo> simulcastCodecs = {};
   Map<(String, int), rtc.RTCRtpEncoding> encodingBackups = {};
 
+  DegradationPreference? _degradationPreference;
+
   List<lk_rtc.SubscribedCodec> subscribedCodecs = [];
 
   @override
@@ -503,11 +505,31 @@ extension LocalVideoTrackExt on LocalVideoTrack {
   }
 
   Future<void> setDegradationPreference(DegradationPreference preference) async {
-    final params = sender?.parameters;
-    if (params == null) {
+    _degradationPreference = preference;
+    await applyDegradationPreference(sender);
+    for (final simulcastCodec in simulcastCodecs.values.toList()) {
+      await applyDegradationPreference(simulcastCodec.sender);
+    }
+  }
+
+  /// Applies the degradation preference resolved for this track to [sender].
+  ///
+  /// Degradation preference is a property of the sender, not of the track, so
+  /// every sender publishing this track needs it applied separately. A backup
+  /// codec publishes over its own sender, which would otherwise resolve a
+  /// preference implicitly and diverge from the primary encoder.
+  @internal
+  Future<void> applyDegradationPreference(rtc.RTCRtpSender? sender) async {
+    final preference = _degradationPreference;
+    if (sender == null || preference == null) {
       return;
     }
+    final params = sender.parameters;
     params.degradationPreference = preference.toRTCType();
-    await sender?.setParameters(params);
+    try {
+      await sender.setParameters(params);
+    } catch (e) {
+      logger.warning('Failed to set degradation preference on sender $e');
+    }
   }
 }

test/options/degradation_preference_test.dart

@@ -0,0 +1,44 @@
+// 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.
+
+import 'package:flutter_test/flutter_test.dart';
+
+import 'package:livekit_client/src/options.dart';
+import 'package:livekit_client/src/types/other.dart';
+
+void main() {
+  group('getDefaultDegradationPreference', () {
+    test('camera prefers framerate', () {
+      expect(
+        getDefaultDegradationPreference(TrackSource.camera),
+        DegradationPreference.maintainFramerate,
+      );
+    });
+
+    test('screen share prefers resolution', () {
+      expect(
+        getDefaultDegradationPreference(TrackSource.screenShareVideo),
+        DegradationPreference.maintainResolution,
+      );
+    });
+
+    test('other sources fall back to balanced', () {
+      // the application declined to declare a motion-vs-detail intent
+      expect(
+        getDefaultDegradationPreference(TrackSource.unknown),
+        DegradationPreference.balanced,
+      );
+    });
+  });
+}