1
//! Bandwidth estimation.
2
 
3
use crate::{Rtc, rtp_::Mid};
4
 
5
pub use crate::rtp_::Bitrate;
6
 
7
#[derive(Debug, PartialEq)]
8
#[non_exhaustive]
9
/// Bandwidth estimation kind.
10
pub enum BweKind {
11
    /// Transport wide congestion control.
12
    Twcc(Bitrate),
13
    /// REMB (Receiver Estimated Maximum Bitrate)
14
    Remb(Mid, Bitrate),
15
}
16
 
17
/// Access to the Bandwidth Estimate subsystem.
18
pub struct Bwe<'a>(pub(crate) &'a mut Rtc);
19
 
20
impl<'a> Bwe<'a> {
21
    /// Configure the desired bitrate.
22
    ///
23
    /// Configure the bandwidth estimation system with the desired bitrate.
24
    /// **Note:** This only has an effect if BWE has been enabled via
25
    /// [`RtcConfig::enable_bwe`][crate::RtcConfig::enable_bwe].
26
    ///
27
    /// * `desired_bitrate` The bitrate you would like to eventually send at. The BWE system will try
28
    ///   to reach this bitrate by probing with padding packets. You should allocate your media bitrate
29
    ///   based on the estimated the BWE system produces via
30
    ///   [`Event::EgressBitrateEstimate`][crate::Event::EgressBitrateEstimate]. This rate might not
31
    ///   be reached if the network link cannot sustain the desired bitrate.
32
    ///
33
    /// ## Example
34
    ///
35
    /// Say you have three simulcast video tracks each with a high layer configured at 1.5Mbit/s.
36
    /// You should then set the desired bitrate to 4.5Mbit/s (or slightly higher). If the network
37
    /// link can sustain 4.5Mbit/s there will eventually be an
38
    /// [`Event::EgressBitrateEstimate`][crate::Event::EgressBitrateEstimate] with this estimate.
39
    pub fn set_desired_bitrate(&mut self, desired_bitrate: Bitrate) {
40
        self.0.session.set_bwe_desired_bitrate(desired_bitrate);
41
    }
42
 
43
    /// Reset the BWE with a new init_bitrate
44
    ///
45
    /// # Example
46
    ///
47
    /// This method is useful when you initially start with only an audio stream. In this case,
48
    /// the BWE will report a very low estimated bitrate.
49
    /// Later, when you start a video stream, the estimated bitrate will be affected by the previous
50
    /// low bitrate, resulting in a very low estimated bitrate, which can cause poor video quality.
51
    /// To avoid this, you need to warm up the video stream for a while then calling reset with a
52
    /// provided init_bitrate.
53
    ///
54
    pub fn reset(&mut self, init_bitrate: Bitrate) {
55
        self.0.session.reset_bwe(init_bitrate);
56
    }
57
}