add downgrade decay and emergency drop

Author: lherman-cs

pulsebeam/src/bitrate.rs

@@ -5,18 +5,12 @@ pub struct BitrateControllerConfig {
     pub min_bitrate: Bitrate,
     pub max_bitrate: Bitrate,
     pub default_bitrate: Bitrate,
-
-    // Safety headroom (e.g. 0.85 of estimate)
     pub headroom_factor: f64,
-
-    // Immediate downgrade if target drops below this % of current (e.g. 0.90)
-    pub downgrade_threshold: f64,
-
-    // Number of ticks to hold a higher target before committing
-    // Since input is already smoothed, 5-8 ticks is usually enough stability.
+    // Max percentage to decrease per tick (e.g. 0.95 = 5% max drop)
+    pub max_decay_factor: f64,
+    // Drop immediately if target is below this % of current (e.g. 0.50)
+    pub emergency_drop_threshold: f64,
     pub required_up_samples: usize,
-
-    // Step size to prevent micro-fluctuations (e.g. 50kbps)
     pub quantization_step: Bitrate,
 }
 
@@ -27,8 +21,9 @@ impl Default for BitrateControllerConfig {
             max_bitrate: Bitrate::mbps(5),
             default_bitrate: Bitrate::kbps(300),
             headroom_factor: 1.0,
-            downgrade_threshold: 0.90,
-            required_up_samples: 1,
+            max_decay_factor: 0.95,
+            emergency_drop_threshold: 0.50,
+            required_up_samples: 5,
             quantization_step: Bitrate::kbps(10),
         }
     }
@@ -44,8 +39,7 @@ pub struct BitrateController {
 
 impl Default for BitrateController {
     fn default() -> Self {
-        let config = BitrateControllerConfig::default();
-        Self::new(config)
+        Self::new(BitrateControllerConfig::default())
     }
 }
 
@@ -60,12 +54,9 @@ impl BitrateController {
     }
 
     pub fn update(&mut self, available_bandwidth: Bitrate) -> Bitrate {
-        // 1. Give headroom
         let raw_bw = available_bandwidth.as_f64();
         let safe_bw = raw_bw * self.config.headroom_factor;
 
-        // 2. Quantize (Floor)
-        // This stabilizes the input "jitter" into steps
         let step = self.config.quantization_step.as_f64();
         let quantized_target = (safe_bw / step).floor() * step;
 
@@ -74,30 +65,23 @@ impl BitrateController {
             self.config.max_bitrate.as_f64(),
         );
 
-        // 3. Logic
-
-        // A: Immediate Downgrade
-        // If external BWE says we dropped significant bandwidth, believe it immediately.
-        if target < self.current_bitrate * self.config.downgrade_threshold {
-            self.current_bitrate = target;
+        if target < self.current_bitrate {
             self.reset_stability();
-            return self.current();
-        }
 
-        // B: Debounced Upgrade
-        // If target is higher, wait for N samples to confirm it's not a temporary spike.
-        if target > self.current_bitrate {
+            if target < self.current_bitrate * self.config.emergency_drop_threshold {
+                self.current_bitrate = target;
+            } else {
+                let decay_limit = self.current_bitrate * self.config.max_decay_factor;
+                self.current_bitrate = target.max(decay_limit);
+            }
+        } else if target > self.current_bitrate {
             match self.pending_target {
                 Some(mut pending) => {
-                    // Track the "Floor" of the new bandwidth during the window.
-                    // If bandwidth dips during the wait, lower our expectations
-                    // to that dip, but keep the counter running.
                     if target < pending {
                         pending = target;
                         self.pending_target = Some(pending);
                     }
 
-                    // If the dip made it drop below current, the upgrade is invalid.
                     if pending <= self.current_bitrate {
                         self.reset_stability();
                     } else {
@@ -117,7 +101,6 @@ impl BitrateController {
                 self.reset_stability();
             }
         } else {
-            // Target is roughly equal or slightly below (within threshold). Stable.
             self.reset_stability();
         }
 
@@ -133,3 +116,97 @@ impl BitrateController {
         Bitrate::from(self.current_bitrate)
     }
 }
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn test_steady_state() {
+        let mut ctrl = BitrateController::default();
+        let bw = Bitrate::kbps(500);
+
+        // Stabilize at 500
+        for _ in 0..10 {
+            ctrl.update(bw);
+        }
+        assert_eq!(ctrl.current().as_f64(), 500_000.0);
+    }
+
+    #[test]
+    fn test_transient_drop_filtering() {
+        let mut ctrl = BitrateController::default();
+        // Start stable at 1000 kbps
+        for _ in 0..10 {
+            ctrl.update(Bitrate::kbps(1000));
+        }
+        assert_eq!(ctrl.current().as_f64(), 1_000_000.0);
+
+        // One tick drop to 300 kbps (simulating bad estimate/jitter)
+        // With decay 0.95, should only drop to ~950k, not 300k
+        let res = ctrl.update(Bitrate::kbps(300));
+        assert!(res.as_f64() > 900_000.0);
+        assert!(res.as_f64() < 1_000_000.0);
+
+        // Input recovers immediately
+        let res = ctrl.update(Bitrate::kbps(1000));
+
+        // Should climb back up (or stay high) rather than waiting for full debounce
+        // because we never actually dropped low.
+        assert!(res.as_f64() > 900_000.0);
+    }
+
+    #[test]
+    fn test_real_congestion_decay() {
+        let mut ctrl = BitrateController::default();
+        for _ in 0..10 {
+            ctrl.update(Bitrate::kbps(1000));
+        }
+
+        // Sustained drop to 500
+        for _ in 0..10 {
+            ctrl.update(Bitrate::kbps(500));
+        }
+
+        // Should be sliding down
+        let current = ctrl.current().as_f64();
+        assert!(current < 1_000_000.0);
+        assert!(current > 500_000.0);
+    }
+
+    #[test]
+    fn test_emergency_drop() {
+        let mut ctrl = BitrateController::default();
+        for _ in 0..10 {
+            ctrl.update(Bitrate::kbps(2000));
+        }
+
+        // Massive drop (e.g. WiFi loss), < 50%
+        let res = ctrl.update(Bitrate::kbps(300));
+
+        // Should snap immediately
+        assert_eq!(res.as_f64(), 300_000.0);
+    }
+
+    #[test]
+    fn test_debounce_up() {
+        let config = BitrateControllerConfig {
+            required_up_samples: 3,
+            ..Default::default()
+        };
+        let mut ctrl = BitrateController::new(config);
+
+        // Start 300
+        ctrl.update(Bitrate::kbps(300));
+
+        // Jump to 500
+        ctrl.update(Bitrate::kbps(500)); // Tick 1 (Pending)
+        assert_eq!(ctrl.current().as_f64(), 300_000.0);
+
+        ctrl.update(Bitrate::kbps(500)); // Tick 2
+        assert_eq!(ctrl.current().as_f64(), 300_000.0);
+
+        ctrl.update(Bitrate::kbps(500)); // Tick 3 (Commit)
+        assert_eq!(ctrl.current().as_f64(), 500_000.0);
+    }
+}

pulsebeam/src/rtp/monitor.rs

@@ -351,9 +351,9 @@ impl BitrateEstimate {
             max_bitrate: Bitrate::mbps(5),
             default_bitrate: Bitrate::kbps(100),
             headroom_factor: 1.0,
-            downgrade_threshold: 0.95,
             required_up_samples: 1,
             quantization_step: Bitrate::kbps(10),
+            ..Default::default()
         };
 
         let controller = BitrateController::new(config);
@@ -1219,7 +1219,7 @@ mod test {
         // The BitrateController should have completely ignored the bump.
         // It might have risen by 1 quantization step (10kbps), but not more.
         assert!(
-            (after_spike - baseline).abs() < 50_000.0,
+            (after_spike - baseline).abs() < 5.0,
             "Estimator flapped due to keyframe!"
         );
     }