Skip to content

Commit 306b65e

Browse files
authored
Add bitrate priority control (#969)
<!-- This is an auto-generated comment: release notes by coderabbit.ai --> ## Summary by CodeRabbit * **New Features** * Bitrate priority controls for audio and video encodings with preset encoding profiles for common audio use cases. * New priority levels (veryLow, low, medium, high) for bitrate and network priority. * Audio publish options now accept encoding presets instead of legacy numeric bitrate fields. * RTC configuration adds an option to enable DSCP for improved QoS. * **Chores** * Updated WebRTC-related package versions for compatibility. <sub>✏️ Tip: You can customize this high-level summary in your review settings.</sub> <!-- end of auto-generated comment: release notes by coderabbit.ai -->
1 parent 2e421d4 commit 306b65e

12 files changed

Lines changed: 208 additions & 44 deletions

File tree

‎.changes/priority-control‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
patch type="added" "Bitrate priority control APIs"

‎lib/livekit_client.dart‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -59,9 +59,11 @@ export 'src/track/remote/video.dart';
5959
export 'src/track/track.dart';
6060
export 'src/json/agent_attributes.dart';
6161
export 'src/types/data_stream.dart';
62+
export 'src/types/audio_encoding.dart';
6263
export 'src/types/other.dart';
6364
export 'src/types/participant_permissions.dart';
6465
export 'src/types/participant_state.dart';
66+
export 'src/types/priority.dart';
6567
export 'src/types/rpc.dart';
6668
export 'src/types/transcription_segment.dart';
6769
export 'src/types/video_dimensions.dart';

‎lib/src/options.dart‎

Lines changed: 9 additions & 17 deletions
Original file line numberDiff line numberDiff line change
@@ -17,6 +17,7 @@ import 'e2ee/options.dart';
1717
import 'track/local/audio.dart';
1818
import 'track/local/video.dart';
1919
import 'track/options.dart';
20+
import 'types/audio_encoding.dart';
2021
import 'types/other.dart';
2122
import 'types/video_encoding.dart';
2223
import 'types/video_parameters.dart';
@@ -301,19 +302,14 @@ class VideoPublishOptions extends PublishOptions {
301302
String toString() => '${runtimeType}(videoEncoding: ${videoEncoding}, simulcast: ${simulcast})';
302303
}
303304

304-
class AudioPreset {
305-
static const telephone = 12000;
306-
static const speech = 24000;
307-
static const music = 48000;
308-
static const musicStereo = 64000;
309-
static const musicHighQuality = 96000;
310-
static const musicHighQualityStereo = 128000;
311-
}
312-
313305
/// Options used when publishing audio.
314306
class AudioPublishOptions extends PublishOptions {
315307
static const defaultMicrophoneName = 'microphone';
316308

309+
/// Preferred encoding parameters.
310+
/// Defaults to [AudioEncoding.presetMusic] when not set.
311+
final AudioEncoding? encoding;
312+
317313
/// Whether to enable DTX (Discontinuous Transmission) or not.
318314
/// https://en.wikipedia.org/wiki/Discontinuous_transmission
319315
/// Defaults to true.
@@ -322,42 +318,38 @@ class AudioPublishOptions extends PublishOptions {
322318
/// red (Redundant Audio Data)
323319
final bool? red;
324320

325-
/// max audio bitrate
326-
final int audioBitrate;
327-
328321
/// Mark this audio as originating from a pre-connect buffer.
329322
/// Used to populate protobuf audioFeatures (TF_PRECONNECT_BUFFER).
330323
final bool preConnect;
331324

332325
const AudioPublishOptions({
333326
super.name,
334327
super.stream,
328+
this.encoding,
335329
this.dtx = true,
336330
this.red = true,
337-
this.audioBitrate = AudioPreset.music,
338331
this.preConnect = false,
339332
});
340333

341334
AudioPublishOptions copyWith({
335+
AudioEncoding? encoding,
342336
bool? dtx,
343-
int? audioBitrate,
344337
String? name,
345338
String? stream,
346339
bool? red,
347340
bool? preConnect,
348341
}) =>
349342
AudioPublishOptions(
343+
encoding: encoding ?? this.encoding,
350344
dtx: dtx ?? this.dtx,
351-
audioBitrate: audioBitrate ?? this.audioBitrate,
352345
name: name ?? this.name,
353346
stream: stream ?? this.stream,
354347
red: red ?? this.red,
355348
preConnect: preConnect ?? this.preConnect,
356349
);
357350

358351
@override
359-
String toString() =>
360-
'${runtimeType}(dtx: ${dtx}, audioBitrate: ${audioBitrate}, red: ${red}, preConnect: ${preConnect})';
352+
String toString() => '${runtimeType}(encoding: ${encoding}, dtx: ${dtx}, red: ${red}, preConnect: ${preConnect})';
361353
}
362354

363355
final backupCodecs = ['vp8', 'h264'];

‎lib/src/participant/local.dart‎

Lines changed: 4 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -48,6 +48,7 @@ import '../track/local/audio.dart';
4848
import '../track/local/local.dart';
4949
import '../track/local/video.dart';
5050
import '../track/options.dart';
51+
import '../types/audio_encoding.dart';
5152
import '../types/data_stream.dart';
5253
import '../types/other.dart';
5354
import '../types/participant_permissions.dart';
@@ -123,11 +124,8 @@ class LocalParticipant extends Participant<LocalTrackPublication> {
123124
// Use defaultPublishOptions if options is null
124125
publishOptions ??= track.lastPublishOptions ?? room.roomOptions.defaultAudioPublishOptions;
125126

126-
final List<rtc.RTCRtpEncoding> encodings = [
127-
rtc.RTCRtpEncoding(
128-
maxBitrate: publishOptions.audioBitrate,
129-
)
130-
];
127+
final audioEncoding = publishOptions.encoding ?? AudioEncoding.presetMusic;
128+
final List<rtc.RTCRtpEncoding> encodings = [audioEncoding.toRTCRtpEncoding()];
131129

132130
final req = lk_rtc.AddTrackRequest(
133131
cid: track.getCid(),
@@ -162,9 +160,7 @@ class LocalParticipant extends Participant<LocalTrackPublication> {
162160

163161
final transceiverInit = rtc.RTCRtpTransceiverInit(
164162
direction: rtc.TransceiverDirection.SendOnly,
165-
sendEncodings: [
166-
if (publishOptions.audioBitrate > 0) rtc.RTCRtpEncoding(maxBitrate: publishOptions.audioBitrate),
167-
],
163+
sendEncodings: encodings,
168164
);
169165
// addTransceiver cannot pass in a kind parameter due to a bug in flutter-webrtc (web)
170166
track.transceiver = await room.engine.publisher?.pc.addTransceiver(

‎lib/src/track/web/_audio_analyser.dart‎

Lines changed: 1 addition & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -2,8 +2,7 @@ import 'dart:js_interop';
22
import 'dart:js_interop_unsafe';
33
import 'dart:math' as math;
44

5-
import 'package:dart_webrtc/dart_webrtc.dart' show MediaStreamTrackWeb;
6-
import 'package:dart_webrtc/dart_webrtc.dart' show MediaStreamWeb;
5+
import 'package:dart_webrtc/dart_webrtc.dart' show MediaStreamTrackWeb, MediaStreamWeb;
76
import 'package:web/web.dart' as web;
87

98
import '../../track/local/local.dart' show AudioTrack;

‎lib/src/types/audio_encoding.dart‎

Lines changed: 88 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,88 @@
1+
// Copyright 2024 LiveKit, Inc.
2+
//
3+
// Licensed under the Apache License, Version 2.0 (the "License");
4+
// you may not use this file except in compliance with the License.
5+
// You may obtain a copy of the License at
6+
//
7+
// http://www.apache.org/licenses/LICENSE-2.0
8+
//
9+
// Unless required by applicable law or agreed to in writing, software
10+
// distributed under the License is distributed on an "AS IS" BASIS,
11+
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
12+
// See the License for the specific language governing permissions and
13+
// limitations under the License.
14+
15+
import 'package:flutter_webrtc/flutter_webrtc.dart' as rtc;
16+
import 'package:meta/meta.dart';
17+
18+
import 'priority.dart';
19+
20+
/// A type that represents audio encoding information.
21+
@immutable
22+
class AudioEncoding {
23+
/// Maximum bitrate for the audio track.
24+
final int maxBitrate;
25+
26+
/// Priority for bandwidth allocation.
27+
final Priority? bitratePriority;
28+
29+
/// Priority for DSCP marking. Requires `RTCConfiguration.isDscpEnabled` to be true.
30+
final Priority? networkPriority;
31+
32+
const AudioEncoding({
33+
required this.maxBitrate,
34+
this.bitratePriority,
35+
this.networkPriority,
36+
});
37+
38+
AudioEncoding copyWith({
39+
int? maxBitrate,
40+
Priority? bitratePriority,
41+
Priority? networkPriority,
42+
}) =>
43+
AudioEncoding(
44+
maxBitrate: maxBitrate ?? this.maxBitrate,
45+
bitratePriority: bitratePriority ?? this.bitratePriority,
46+
networkPriority: networkPriority ?? this.networkPriority,
47+
);
48+
49+
@override
50+
String toString() =>
51+
'${runtimeType}(maxBitrate: ${maxBitrate}, bitratePriority: ${bitratePriority}, networkPriority: ${networkPriority})';
52+
53+
@override
54+
bool operator ==(Object other) =>
55+
identical(this, other) ||
56+
other is AudioEncoding &&
57+
maxBitrate == other.maxBitrate &&
58+
bitratePriority == other.bitratePriority &&
59+
networkPriority == other.networkPriority;
60+
61+
@override
62+
int get hashCode => Object.hash(maxBitrate, bitratePriority, networkPriority);
63+
64+
static const presetTelephone = AudioEncoding(maxBitrate: 12000);
65+
static const presetSpeech = AudioEncoding(maxBitrate: 24000);
66+
static const presetMusic = AudioEncoding(maxBitrate: 48000);
67+
static const presetMusicStereo = AudioEncoding(maxBitrate: 64000);
68+
static const presetMusicHighQuality = AudioEncoding(maxBitrate: 96000);
69+
static const presetMusicHighQualityStereo = AudioEncoding(maxBitrate: 128000);
70+
71+
static const presets = [
72+
presetTelephone,
73+
presetSpeech,
74+
presetMusic,
75+
presetMusicStereo,
76+
presetMusicHighQuality,
77+
presetMusicHighQualityStereo,
78+
];
79+
}
80+
81+
/// Convenience extension for [AudioEncoding].
82+
extension AudioEncodingExt on AudioEncoding {
83+
rtc.RTCRtpEncoding toRTCRtpEncoding() => rtc.RTCRtpEncoding(
84+
maxBitrate: maxBitrate,
85+
priority: bitratePriority?.toRtcpPriorityType() ?? rtc.RTCPriorityType.low,
86+
networkPriority: networkPriority?.toRtcpPriorityType(),
87+
);
88+
}

‎lib/src/types/other.dart‎

Lines changed: 13 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -141,11 +141,21 @@ class RTCConfiguration {
141141
final RTCIceTransportPolicy? iceTransportPolicy;
142142
final bool? encodedInsertableStreams;
143143

144+
/// Allows DSCP (Differentiated Services Code Point) codes to be set on
145+
/// outgoing packets for network level QoS.
146+
///
147+
/// This is a best effort hint and network routers may ignore DSCP markings.
148+
/// Required for `networkPriority` to take effect.
149+
///
150+
/// Ignored on web platforms.
151+
final bool? isDscpEnabled;
152+
144153
const RTCConfiguration({
145154
this.iceCandidatePoolSize,
146155
this.iceServers,
147156
this.iceTransportPolicy,
148157
this.encodedInsertableStreams,
158+
this.isDscpEnabled,
149159
});
150160

151161
Map<String, dynamic> toMap() {
@@ -158,6 +168,7 @@ class RTCConfiguration {
158168
// only supports unified plan
159169
'sdpSemantics': 'unified-plan',
160170
if (encodedInsertableStreams != null) 'encodedInsertableStreams': encodedInsertableStreams,
171+
if (isDscpEnabled != null) 'enableDscp': isDscpEnabled,
161172
if (iceServersMap.isNotEmpty) 'iceServers': iceServersMap,
162173
if (iceCandidatePoolSize != null) 'iceCandidatePoolSize': iceCandidatePoolSize,
163174
if (iceTransportPolicy != null) 'iceTransportPolicy': iceTransportPolicy!.toStringValue(),
@@ -170,12 +181,14 @@ class RTCConfiguration {
170181
List<RTCIceServer>? iceServers,
171182
RTCIceTransportPolicy? iceTransportPolicy,
172183
bool? encodedInsertableStreams,
184+
bool? isDscpEnabled,
173185
}) =>
174186
RTCConfiguration(
175187
iceCandidatePoolSize: iceCandidatePoolSize ?? this.iceCandidatePoolSize,
176188
iceServers: iceServers ?? this.iceServers,
177189
iceTransportPolicy: iceTransportPolicy ?? this.iceTransportPolicy,
178190
encodedInsertableStreams: encodedInsertableStreams ?? this.encodedInsertableStreams,
191+
isDscpEnabled: isDscpEnabled ?? this.isDscpEnabled,
179192
);
180193
}
181194

‎lib/src/types/priority.dart‎

Lines changed: 41 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,41 @@
1+
// Copyright 2024 LiveKit, Inc.
2+
//
3+
// Licensed under the Apache License, Version 2.0 (the "License");
4+
// you may not use this file except in compliance with the License.
5+
// You may obtain a copy of the License at
6+
//
7+
// http://www.apache.org/licenses/LICENSE-2.0
8+
//
9+
// Unless required by applicable law or agreed to in writing, software
10+
// distributed under the License is distributed on an "AS IS" BASIS,
11+
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
12+
// See the License for the specific language governing permissions and
13+
// limitations under the License.
14+
15+
import 'package:flutter_webrtc/flutter_webrtc.dart' as rtc;
16+
17+
/// Priority levels for RTP encoding parameters.
18+
///
19+
/// `bitratePriority` controls WebRTC internal bandwidth allocation between streams.
20+
/// `networkPriority` controls DSCP marking for network-level QoS.
21+
enum Priority {
22+
veryLow,
23+
low,
24+
medium,
25+
high,
26+
}
27+
28+
extension PriorityExt on Priority {
29+
rtc.RTCPriorityType toRtcpPriorityType() {
30+
switch (this) {
31+
case Priority.veryLow:
32+
return rtc.RTCPriorityType.veryLow;
33+
case Priority.low:
34+
return rtc.RTCPriorityType.low;
35+
case Priority.medium:
36+
return rtc.RTCPriorityType.medium;
37+
case Priority.high:
38+
return rtc.RTCPriorityType.high;
39+
}
40+
}
41+
}

0 commit comments

Comments
 (0)