Add RFC 2198 RED (redundant audio) support for Opus

A default-off `RtcConfig::enable_red` negotiates RFC 2198 RED for Opus,
modeled on RTX: a `Codec::Red` marker and a `PayloadParams.red` linkage
folded onto the primary codec in SDP (`red/48000/2` and `fmtp <opus>/<opus>`),
kept only when both peers offer it.

In frame mode RED is transparent. Outgoing Opus is wrapped with one level of
redundancy (the previous frame); incoming RED is unwrapped back to Opus and a
single lost packet is recovered from the next packet's redundancy. In rtp mode
the RED packets pass through unchanged, and `RedEncoder`/`RedDecoder` are
exposed for callers that want to build or parse RED themselves.

A self-contained `packet::red` codec does the byte-level RFC 2198 work and is
fuzzed; recovered packets reuse the existing depayload path and the jitter
buffer's de-duplication.

Author: farit2000

CHANGELOG.md

@@ -1,5 +1,7 @@
 # Unreleased
 
+  * Add RFC 2198 RED (redundant audio) for Opus via `RtcConfig::enable_red`: transparent send/recv
+    with single-loss recovery in frame mode, pass-through in rtp mode, and public `RedEncoder`/`RedDecoder` #982
   * Add H266/VVC RTP packetizer and depacketizer #971
   * Negotiate SCTP max message size for data channels #852
   * Expose the negotiated DTLS protocol version #979

crates/fuzz/Cargo.toml

@@ -62,3 +62,9 @@ name = "receive_register"
 path = "fuzz_targets/receive_register.rs"
 test = false
 doc = false
+
+[[bin]]
+name = "red_decode"
+path = "fuzz_targets/red_decode.rs"
+test = false
+doc = false

crates/fuzz/fuzz_targets/red_decode.rs

@@ -0,0 +1,9 @@
+#![no_main]
+
+use libfuzzer_sys::fuzz_target;
+use str0m::rtp::RedDecoder;
+
+fuzz_target!(|data: &[u8]| {
+    // RFC 2198 RED payloads come from untrusted peers; decoding must never panic.
+    let _ = RedDecoder::decode(data);
+});

src/change/sdp.rs

@@ -1521,6 +1521,9 @@ impl AsSdpMediaLine for Media {
             if let Some(rtx) = p.resend() {
                 pts.push(rtx);
             }
+            if let Some(red) = p.red() {
+                pts.push(red);
+            }
         }
 
         if let Some(s) = self.simulcast() {

src/config.rs

@@ -229,6 +229,19 @@ impl RtcConfig {
         self
     }
 
+    /// Enable RFC 2198 RED (redundant Opus audio). Off by default. Requires Opus.
+    ///
+    /// RED carries a redundant copy of the previous Opus frame in each packet so the
+    /// receiver can recover single packet losses without retransmission, at the cost of
+    /// roughly doubling audio payload size.
+    ///
+    /// Call this after [`Self::enable_opus`]: RED folds onto the enabled Opus payload, so
+    /// enabling it while no Opus codec is configured is a no-op (and is logged).
+    pub fn enable_red(mut self, enabled: bool) -> Self {
+        self.codec_config.enable_red(enabled);
+        self
+    }
+
     /// Enable PCM μ-law audio codec.
     ///
     /// This is 14-bit audio compressed to 8-bit as specified by G.711

src/format/codec.rs

@@ -46,6 +46,10 @@ pub enum Codec {
     /// in `a=rtpmap` lines.
     #[doc(hidden)]
     Rtx,
+    /// RFC 2198 redundant encoding (RED). Like `Rtx`, technically not a codec;
+    /// it appears in `a=rtpmap` lines and wraps a primary audio codec.
+    #[doc(hidden)]
+    Red,
     /// For RTP mode. No codec.
     #[doc(hidden)]
     Null,
@@ -93,6 +97,7 @@ impl<'a> From<&'a str> for Codec {
             "vp9" => Codec::Vp9,
             "av1" => Codec::Av1,
             "rtx" => Codec::Rtx, // resends
+            "red" => Codec::Red, // RFC 2198 redundancy
             _ => Codec::Unknown,
         }
     }
@@ -111,8 +116,22 @@ impl fmt::Display for Codec {
             Codec::Vp9 => write!(f, "VP9"),
             Codec::Av1 => write!(f, "AV1"),
             Codec::Rtx => write!(f, "rtx"),
+            Codec::Red => write!(f, "red"),
             Codec::Null => write!(f, "null"),
             Codec::Unknown => write!(f, "unknown"),
         }
     }
 }
+
+#[cfg(test)]
+mod test {
+    use super::*;
+
+    #[test]
+    fn red_codec_string_roundtrip() {
+        assert_eq!(Codec::from("red"), Codec::Red);
+        assert_eq!(Codec::Red.to_string(), "red");
+        assert!(!Codec::Red.is_audio());
+        assert!(!Codec::Red.is_video());
+    }
+}

src/format/codec_config.rs

@@ -49,6 +49,9 @@ pub(crate) const PT_H266_RTX: Pt = Pt::new_with_value(105);
 /// Default payload type for Opus.
 pub(crate) const PT_OPUS: Pt = Pt::new_with_value(111);
 
+/// Default payload type for RFC 2198 RED (redundant Opus).
+pub(crate) const PT_RED: Pt = Pt::new_with_value(63);
+
 /// Session config for all codecs.
 #[derive(Debug, Clone, Default)]
 pub struct CodecConfig {
@@ -119,6 +122,7 @@ impl CodecConfig {
                 format,
             },
             resend,
+            red: None,
             fb_transport_cc,
             fb_fir,
             fb_nack,
@@ -232,6 +236,21 @@ impl CodecConfig {
         )
     }
 
+    /// Enable RFC 2198 RED (redundant Opus) for the audio m-line. Off by default.
+    ///
+    /// RED roughly doubles audio payload size, so it is opt-in. This is a no-op when
+    /// Opus is not enabled.
+    pub fn enable_red(&mut self, enabled: bool) {
+        if enabled && !self.params.iter().any(|p| p.spec.codec == Codec::Opus) {
+            warn!("enable_red(true) ignored: Opus is not enabled");
+        }
+        for p in &mut self.params {
+            if p.spec.codec == Codec::Opus {
+                p.red = if enabled { Some(PT_RED) } else { None };
+            }
+        }
+    }
+
     /// Add a default VP8 payload type.
     pub fn enable_vp8(&mut self, enabled: bool) {
         self.params.retain(|c| c.spec.codec != Codec::Vp8);
@@ -444,14 +463,18 @@ impl CodecConfig {
             if let Some(rtx) = p.resend {
                 claimed.assert_claim_once(rtx);
             }
+
+            if let Some(red) = p.red {
+                claimed.assert_claim_once(red);
+            }
         }
 
         // Collect all currently unlocked PTs since we will need to avoid them when reassigning.
         let mut unlocked = self
             .params
             .iter()
             .filter(|p| !p.locked)
-            .flat_map(|p| [Some(p.pt()), p.resend()])
+            .flat_map(|p| [Some(p.pt()), p.resend(), p.red()])
             .flatten()
             .collect::<HashSet<_>>();
 
@@ -491,6 +514,25 @@ impl CodecConfig {
                 unlocked.remove(&pt);
             }
 
+            // RED rides its own PT (like RTX); reassign it if it now collides.
+            if let Some(red) = p.red {
+                if claimed.is_claimed(red) {
+                    match claimed.find_unclaimed(PREFERED_RANGES, &unlocked) {
+                        Some(new_red) => {
+                            debug!("Reassigned RED PT {:?} => {:?}", p.red, new_red);
+                            p.red = Some(new_red);
+                            claimed.assert_claim_once(new_red);
+                            unlocked.remove(&new_red);
+                        }
+                        // RED is opt-in; drop it rather than panic if no PT is free.
+                        None => {
+                            debug!("No free PT for RED; dropping it");
+                            p.red = None;
+                        }
+                    }
+                }
+            }
+
             let Some(rtx) = p.resend else {
                 continue;
             };
@@ -554,6 +596,62 @@ mod test {
     use super::*;
     use crate::format::{CodecSpec, FormatParams};
 
+    #[test]
+    fn enable_red_links_opus() {
+        let mut c = CodecConfig::empty();
+        c.enable_opus(true);
+        c.enable_red(true);
+        let opus = c
+            .params()
+            .iter()
+            .find(|p| p.spec().codec == Codec::Opus)
+            .unwrap();
+        assert_eq!(opus.red(), Some(PT_RED));
+    }
+
+    #[test]
+    fn red_kept_when_both_sides_enable() {
+        let mut local = CodecConfig::empty();
+        local.enable_opus(true);
+        local.enable_red(true);
+
+        let mut remote = CodecConfig::empty();
+        remote.enable_opus(true);
+        remote.enable_red(true);
+
+        local.update_params(remote.params(), Direction::SendRecv);
+
+        let opus = local
+            .params()
+            .iter()
+            .find(|p| p.spec().codec == Codec::Opus)
+            .unwrap();
+        assert_eq!(opus.red(), Some(PT_RED));
+    }
+
+    #[test]
+    fn red_dropped_when_remote_lacks_red() {
+        let mut local = CodecConfig::empty();
+        local.enable_opus(true);
+        local.enable_red(true);
+
+        let mut remote = CodecConfig::empty();
+        remote.enable_opus(true); // remote does not offer RED
+
+        local.update_params(remote.params(), Direction::SendRecv);
+
+        let opus = local
+            .params()
+            .iter()
+            .find(|p| p.spec().codec == Codec::Opus)
+            .unwrap();
+        assert_eq!(
+            opus.red(),
+            None,
+            "RED must be dropped when remote doesn't offer it"
+        );
+    }
+
     #[test]
     fn test_pt_conflict_different_directions() {
         // Simulates:

src/format/format_params.rs

@@ -157,6 +157,7 @@ impl FormatParams {
             H266ProfileTierLevel(v) => self.h266_profile_tier_level = Some(*v),
             SpropMaxDonDiff(v) => self.sprop_max_don_diff = Some(*v),
             Apt(_) => {}
+            Red(_) => {}
             Unknown => {}
         }
     }