Add bitrate priority control

.changes/priority-control

@@ -0,0 +1 @@
+patch type="added" "Bitrate priority control APIs"

lib/livekit_client.dart

@@ -59,9 +59,11 @@ export 'src/track/remote/video.dart';
 export 'src/track/track.dart';
 export 'src/json/agent_attributes.dart';
 export 'src/types/data_stream.dart';
+export 'src/types/audio_encoding.dart';
 export 'src/types/other.dart';
 export 'src/types/participant_permissions.dart';
 export 'src/types/participant_state.dart';
+export 'src/types/priority.dart';
 export 'src/types/rpc.dart';
 export 'src/types/transcription_segment.dart';
 export 'src/types/video_dimensions.dart';

lib/src/options.dart

@@ -17,6 +17,7 @@ import 'e2ee/options.dart';
 import 'track/local/audio.dart';
 import 'track/local/video.dart';
 import 'track/options.dart';
+import 'types/audio_encoding.dart';
 import 'types/other.dart';
 import 'types/video_encoding.dart';
 import 'types/video_parameters.dart';
@@ -301,19 +302,14 @@ class VideoPublishOptions extends PublishOptions {
   String toString() => '${runtimeType}(videoEncoding: ${videoEncoding}, simulcast: ${simulcast})';
 }
 
-class AudioPreset {
-  static const telephone = 12000;
-  static const speech = 24000;
-  static const music = 48000;
-  static const musicStereo = 64000;
-  static const musicHighQuality = 96000;
-  static const musicHighQualityStereo = 128000;
-}
-
 /// Options used when publishing audio.
 class AudioPublishOptions extends PublishOptions {
   static const defaultMicrophoneName = 'microphone';
 
+  /// Preferred encoding parameters.
+  /// Defaults to [AudioEncoding.presetMusic] when not set.
+  final AudioEncoding? encoding;
+
   /// Whether to enable DTX (Discontinuous Transmission) or not.
   /// https://en.wikipedia.org/wiki/Discontinuous_transmission
   /// Defaults to true.
@@ -322,33 +318,30 @@ class AudioPublishOptions extends PublishOptions {
   /// red (Redundant Audio Data)
   final bool? red;
 
-  /// max audio bitrate
-  final int audioBitrate;
-
   /// Mark this audio as originating from a pre-connect buffer.
   /// Used to populate protobuf audioFeatures (TF_PRECONNECT_BUFFER).
   final bool preConnect;
 
   const AudioPublishOptions({
     super.name,
     super.stream,
+    this.encoding,
     this.dtx = true,
     this.red = true,
-    this.audioBitrate = AudioPreset.music,
     this.preConnect = false,
   });
 
   AudioPublishOptions copyWith({
+    AudioEncoding? encoding,
     bool? dtx,
-    int? audioBitrate,
     String? name,
     String? stream,
     bool? red,
     bool? preConnect,
   }) =>
       AudioPublishOptions(
+        encoding: encoding ?? this.encoding,
         dtx: dtx ?? this.dtx,
-        audioBitrate: audioBitrate ?? this.audioBitrate,
         name: name ?? this.name,
         stream: stream ?? this.stream,
         red: red ?? this.red,
@@ -357,7 +350,7 @@ class AudioPublishOptions extends PublishOptions {
 
   @override
   String toString() =>
-      '${runtimeType}(dtx: ${dtx}, audioBitrate: ${audioBitrate}, red: ${red}, preConnect: ${preConnect})';
+      '${runtimeType}(encoding: ${encoding}, dtx: ${dtx}, red: ${red}, preConnect: ${preConnect})';
 }
 
 final backupCodecs = ['vp8', 'h264'];

lib/src/participant/local.dart

@@ -48,9 +48,11 @@ import '../track/local/audio.dart';
 import '../track/local/local.dart';
 import '../track/local/video.dart';
 import '../track/options.dart';
+import '../types/audio_encoding.dart';
 import '../types/data_stream.dart';
 import '../types/other.dart';
 import '../types/participant_permissions.dart';
+import '../types/priority.dart';
 import '../types/rpc.dart';
 import '../types/video_dimensions.dart';
 import '../utils.dart' show buildStreamId, mimeTypeToVideoCodecString, Utils, compareVersions, isSVCCodec;
@@ -123,9 +125,12 @@ class LocalParticipant extends Participant<LocalTrackPublication> {
     // Use defaultPublishOptions if options is null
     publishOptions ??= track.lastPublishOptions ?? room.roomOptions.defaultAudioPublishOptions;
 
+    final audioEncoding = publishOptions.encoding ?? AudioEncoding.presetMusic;
     final List<rtc.RTCRtpEncoding> encodings = [
       rtc.RTCRtpEncoding(
-        maxBitrate: publishOptions.audioBitrate,
+        maxBitrate: audioEncoding.maxBitrate,
+        priority: (audioEncoding.bitratePriority ?? Priority.low).toRtcpPriorityType(),
+        networkPriority: audioEncoding.networkPriority?.toRtcpPriorityType(),
       )
     ];
 
@@ -163,7 +168,12 @@ class LocalParticipant extends Participant<LocalTrackPublication> {
       final transceiverInit = rtc.RTCRtpTransceiverInit(
         direction: rtc.TransceiverDirection.SendOnly,
         sendEncodings: [
-          if (publishOptions.audioBitrate > 0) rtc.RTCRtpEncoding(maxBitrate: publishOptions.audioBitrate),
+          if (audioEncoding.maxBitrate > 0)
+            rtc.RTCRtpEncoding(
+              maxBitrate: audioEncoding.maxBitrate,
+              priority: (audioEncoding.bitratePriority ?? Priority.low).toRtcpPriorityType(),
+              networkPriority: audioEncoding.networkPriority?.toRtcpPriorityType(),
+            ),
         ],
       );
       // addTransceiver cannot pass in a kind parameter due to a bug in flutter-webrtc (web)

lib/src/track/web/_audio_analyser.dart

@@ -2,8 +2,7 @@ import 'dart:js_interop';
 import 'dart:js_interop_unsafe';
 import 'dart:math' as math;
 
-import 'package:dart_webrtc/dart_webrtc.dart' show MediaStreamTrackWeb;
-import 'package:dart_webrtc/dart_webrtc.dart' show MediaStreamWeb;
+import 'package:dart_webrtc/dart_webrtc.dart' show MediaStreamTrackWeb, MediaStreamWeb;
 import 'package:web/web.dart' as web;
 
 import '../../track/local/local.dart' show AudioTrack;

lib/src/types/audio_encoding.dart

@@ -0,0 +1,88 @@
+// Copyright 2024 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_webrtc/flutter_webrtc.dart' as rtc;
+import 'package:meta/meta.dart';
+
+import 'priority.dart';
+
+/// A type that represents audio encoding information.
+@immutable
+class AudioEncoding {
+  /// Maximum bitrate for the audio track.
+  final int maxBitrate;
+
+  /// Priority for bandwidth allocation.
+  final Priority? bitratePriority;
+
+  /// Priority for DSCP marking. Requires `RTCConfiguration.enableDscp` to be true.
+  final Priority? networkPriority;
+
+  const AudioEncoding({
+    required this.maxBitrate,
+    this.bitratePriority,
+    this.networkPriority,
+  });
+
+  AudioEncoding copyWith({
+    int? maxBitrate,
+    Priority? bitratePriority,
+    Priority? networkPriority,
+  }) =>
+      AudioEncoding(
+        maxBitrate: maxBitrate ?? this.maxBitrate,
+        bitratePriority: bitratePriority ?? this.bitratePriority,
+        networkPriority: networkPriority ?? this.networkPriority,
+      );
+
+  @override
+  String toString() =>
+      '${runtimeType}(maxBitrate: ${maxBitrate}, bitratePriority: ${bitratePriority}, networkPriority: ${networkPriority})';
+
+  @override
+  bool operator ==(Object other) =>
+      identical(this, other) ||
+      other is AudioEncoding &&
+          maxBitrate == other.maxBitrate &&
+          bitratePriority == other.bitratePriority &&
+          networkPriority == other.networkPriority;
+
+  @override
+  int get hashCode => Object.hash(maxBitrate, bitratePriority, networkPriority);
+
+  static const presetTelephone = AudioEncoding(maxBitrate: 12000);
+  static const presetSpeech = AudioEncoding(maxBitrate: 24000);
+  static const presetMusic = AudioEncoding(maxBitrate: 48000);
+  static const presetMusicStereo = AudioEncoding(maxBitrate: 64000);
+  static const presetMusicHighQuality = AudioEncoding(maxBitrate: 96000);
+  static const presetMusicHighQualityStereo = AudioEncoding(maxBitrate: 128000);
+
+  static const presets = [
+    presetTelephone,
+    presetSpeech,
+    presetMusic,
+    presetMusicStereo,
+    presetMusicHighQuality,
+    presetMusicHighQualityStereo,
+  ];
+}
+
+/// Convenience extension for [AudioEncoding].
+extension AudioEncodingExt on AudioEncoding {
+  rtc.RTCRtpEncoding toRTCRtpEncoding() => rtc.RTCRtpEncoding(
+        maxBitrate: maxBitrate,
+        priority: (bitratePriority ?? Priority.low).toRtcpPriorityType(),
+        networkPriority: networkPriority?.toRtcpPriorityType(),
+      );
+}

lib/src/types/other.dart

@@ -141,11 +141,16 @@ class RTCConfiguration {
   final RTCIceTransportPolicy? iceTransportPolicy;
   final bool? encodedInsertableStreams;
 
+  /// Allows DSCP codes to be set on outgoing packets.
+  /// No effect on web platforms.
+  final bool? enableDscp;
+
   const RTCConfiguration({
     this.iceCandidatePoolSize,
     this.iceServers,
     this.iceTransportPolicy,
     this.encodedInsertableStreams,
+    this.enableDscp,
   });
 
   Map<String, dynamic> toMap() {
@@ -158,6 +163,7 @@ class RTCConfiguration {
       // only supports unified plan
       'sdpSemantics': 'unified-plan',
       if (encodedInsertableStreams != null) 'encodedInsertableStreams': encodedInsertableStreams,
+      if (enableDscp != null) 'enableDscp': enableDscp,
       if (iceServersMap.isNotEmpty) 'iceServers': iceServersMap,
       if (iceCandidatePoolSize != null) 'iceCandidatePoolSize': iceCandidatePoolSize,
       if (iceTransportPolicy != null) 'iceTransportPolicy': iceTransportPolicy!.toStringValue(),
@@ -170,12 +176,14 @@ class RTCConfiguration {
     List<RTCIceServer>? iceServers,
     RTCIceTransportPolicy? iceTransportPolicy,
     bool? encodedInsertableStreams,
+    bool? enableDscp,
   }) =>
       RTCConfiguration(
         iceCandidatePoolSize: iceCandidatePoolSize ?? this.iceCandidatePoolSize,
         iceServers: iceServers ?? this.iceServers,
         iceTransportPolicy: iceTransportPolicy ?? this.iceTransportPolicy,
         encodedInsertableStreams: encodedInsertableStreams ?? this.encodedInsertableStreams,
+        enableDscp: enableDscp ?? this.enableDscp,
       );
 }
 

lib/src/types/priority.dart

@@ -0,0 +1,41 @@
+// Copyright 2024 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_webrtc/flutter_webrtc.dart' as rtc;
+
+/// Priority levels for RTP encoding parameters.
+///
+/// `bitratePriority` controls WebRTC internal bandwidth allocation between streams.
+/// `networkPriority` controls DSCP marking for network-level QoS.
+enum Priority {
+  veryLow,
+  low,
+  medium,
+  high,
+}
+
+extension PriorityExt on Priority {
+  rtc.RTCPriorityType toRtcpPriorityType() {
+    switch (this) {
+      case Priority.veryLow:
+        return rtc.RTCPriorityType.veryLow;
+      case Priority.low:
+        return rtc.RTCPriorityType.low;
+      case Priority.medium:
+        return rtc.RTCPriorityType.medium;
+      case Priority.high:
+        return rtc.RTCPriorityType.high;
+    }
+  }
+}

lib/src/types/video_encoding.dart

@@ -15,39 +15,61 @@
 import 'package:flutter_webrtc/flutter_webrtc.dart' as rtc;
 import 'package:meta/meta.dart';
 
+import 'priority.dart';
+
 /// A type that represents video encoding information.
 @immutable
 class VideoEncoding implements Comparable<VideoEncoding> {
+  /// Maximum framerate for the video track.
   final int maxFramerate;
+
+  /// Maximum bitrate for the video track.
   final int maxBitrate;
 
+  /// Priority for bandwidth allocation.
+  final Priority? bitratePriority;
+
+  /// Priority for DSCP marking. Requires `RTCConfiguration.enableDscp` to be true.
+  final Priority? networkPriority;
+
   const VideoEncoding({
     required this.maxFramerate,
     required this.maxBitrate,
+    this.bitratePriority,
+    this.networkPriority,
   });
 
   VideoEncoding copyWith({
     int? maxFramerate,
     int? maxBitrate,
+    Priority? bitratePriority,
+    Priority? networkPriority,
   }) =>
       VideoEncoding(
         maxFramerate: maxFramerate ?? this.maxFramerate,
         maxBitrate: maxBitrate ?? this.maxBitrate,
+        bitratePriority: bitratePriority ?? this.bitratePriority,
+        networkPriority: networkPriority ?? this.networkPriority,
       );
 
   @override
-  String toString() => '${runtimeType}(maxFramerate: ${maxFramerate}, maxBitrate: ${maxBitrate})';
+  String toString() =>
+      '${runtimeType}(maxFramerate: ${maxFramerate}, maxBitrate: ${maxBitrate}, bitratePriority: ${bitratePriority}, networkPriority: ${networkPriority})';
 
   // ----------------------------------------------------------------------
   // equality
 
   @override
   bool operator ==(Object other) =>
       identical(this, other) ||
-      other is VideoEncoding && maxFramerate == other.maxFramerate && maxBitrate == other.maxBitrate;
+      other is VideoEncoding &&
+          maxFramerate == other.maxFramerate &&
+          maxBitrate == other.maxBitrate &&
+          bitratePriority == other.bitratePriority &&
+          networkPriority == other.networkPriority;
 
   @override
-  int get hashCode => Object.hash(maxFramerate, maxBitrate);
+  int get hashCode => Object.hash(maxFramerate, maxBitrate, bitratePriority, networkPriority);
 
   // ----------------------------------------------------------------------
   // Comparable
@@ -78,5 +100,7 @@ extension VideoEncodingExt on VideoEncoding {
         maxFramerate: maxFramerate,
         maxBitrate: maxBitrate,
         numTemporalLayers: numTemporalLayers,
+        priority: (bitratePriority ?? Priority.low).toRtcpPriorityType(),
+        networkPriority: networkPriority?.toRtcpPriorityType(),
       );
 }