feat: add stereo to opus format params

Author: lherman-cs

CHANGELOG.md

@@ -1,3 +1,7 @@
+# Unreleased
+
+  * Add stereo to opus format params #955
+
 # 0.19.0
 
   * Expose H265 some already referenced profile structs #948

src/format/format_params.rs

@@ -11,6 +11,18 @@ pub struct FormatParams {
     /// The minimum duration of media represented by a packet.
     pub min_p_time: Option<u8>,
 
+    /// Opus specific parameter.
+    ///
+    /// Decoder-side preference for stereo audio. Default is mono per
+    /// RFC 7587 Section 7.1: <https://datatracker.ietf.org/doc/html/rfc7587#section-7.1>
+    pub stereo: Option<bool>,
+
+    /// Opus specific parameter.
+    ///
+    /// Sender-side stereo hint for Opus. When set, it signals the intent to
+    /// transmit stereo from the sender, matching the symmetric m-line model.
+    pub sprop_stereo: Option<bool>,
+
     /// Opus specific parameter.
     ///
     /// Specifies that the decoder can do Opus in-band FEC
@@ -117,6 +129,8 @@ impl FormatParams {
         use FormatParam::*;
         match param {
             MinPTime(v) => self.min_p_time = Some(*v),
+            Stereo(v) => self.stereo = Some(*v),
+            SpropStereo(v) => self.sprop_stereo = Some(*v),
             UseInbandFec(v) => self.use_inband_fec = Some(*v),
             UseDtx(v) => self.use_dtx = Some(*v),
             LevelAsymmetryAllowed(v) => self.level_asymmetry_allowed = Some(*v),
@@ -140,6 +154,12 @@ impl FormatParams {
         if let Some(v) = self.min_p_time {
             r.push(MinPTime(v));
         }
+        if let Some(v) = self.stereo {
+            r.push(Stereo(v));
+        }
+        if let Some(v) = self.sprop_stereo {
+            r.push(SpropStereo(v));
+        }
         if let Some(v) = self.use_inband_fec {
             r.push(UseInbandFec(v));
         }
@@ -212,6 +232,20 @@ mod test {
         assert_eq!(parsed.sprop_max_don_diff, Some(32));
     }
 
+    #[test]
+    fn sprop_stereo_roundtrip() {
+        let f = FormatParams {
+            sprop_stereo: Some(true),
+            ..Default::default()
+        };
+
+        let fmtp_str = f.to_string();
+        assert_eq!(fmtp_str, "sprop-stereo=1");
+
+        let parsed = FormatParams::parse_line(&fmtp_str);
+        assert_eq!(parsed.sprop_stereo, Some(true));
+    }
+
     #[test]
     fn h265_combined_params_roundtrip() {
         use crate::packet::H265ProfileTierLevel;

src/format/payload_params.rs

@@ -341,6 +341,20 @@ impl PayloadParams {
             score = score.saturating_sub(4);
         }
 
+        // If neither value is specified both sides should assume mono for stereo
+        // and the sprop-stereo hint defaults to false.
+        let c0_stereo = c0.format.stereo.unwrap_or(false);
+        let c1_stereo = c1.format.stereo.unwrap_or(false);
+        if c0_stereo != c1_stereo {
+            score = score.saturating_sub(8);
+        }
+
+        let c0_sprop_stereo = c0.format.sprop_stereo.unwrap_or(false);
+        let c1_sprop_stereo = c1.format.sprop_stereo.unwrap_or(false);
+        if c0_sprop_stereo != c1_sprop_stereo {
+            score = score.saturating_sub(8);
+        }
+
         score
     }
 

src/sdp/data.rs

@@ -907,6 +907,14 @@ pub enum FormatParam {
     /// Default 3. Max 120.
     MinPTime(u8),
 
+    /// Decoder-side preference for stereo audio. Default is mono per
+    /// RFC 7587 Section 7.1: <https://datatracker.ietf.org/doc/html/rfc7587#section-7.1>
+    Stereo(bool),
+
+    /// Sender-side stereo hint for Opus. This is the symmetric m-line companion
+    /// to `stereo` and signals the sender's intention to transmit stereo.
+    SpropStereo(bool),
+
     /// Specifies that the decoder can do Opus in-band FEC
     UseInbandFec(bool),
 
@@ -965,6 +973,8 @@ impl FormatParam {
             "minptime" => v.parse().map(MinPTime).ok(),
             "useinbandfec" => Some(UseInbandFec(v == "1")),
             "usedtx" => Some(UseDtx(v == "1")),
+            "stereo" => Some(Stereo(v == "1")),
+            "sprop-stereo" => Some(SpropStereo(v == "1")),
             "level-asymmetry-allowed" => Some(LevelAsymmetryAllowed(v == "1")),
             "packetization-mode" => v.parse().map(PacketizationMode).ok(),
             "profile-level-id" => u32::from_str_radix(v, 16)
@@ -1031,6 +1041,8 @@ impl fmt::Display for FormatParam {
             MinPTime(v) => write!(f, "minptime={v}"),
             UseInbandFec(v) => write!(f, "useinbandfec={}", i32::from(*v)),
             UseDtx(v) => write!(f, "usedtx={}", i32::from(*v)),
+            Stereo(v) => write!(f, "stereo={}", i32::from(*v)),
+            SpropStereo(v) => write!(f, "sprop-stereo={}", i32::from(*v)),
             LevelAsymmetryAllowed(v) => {
                 write!(f, "level-asymmetry-allowed={}", i32::from(*v))
             }
@@ -1514,10 +1526,11 @@ mod test {
         fn fmtp_param_to_string() {
             let f = FormatParams {
                 min_p_time: Some(10),
+                stereo: Some(true),
                 use_inband_fec: Some(true),
                 ..Default::default()
             };
-            assert_eq!(f.to_string(), "minptime=10;useinbandfec=1");
+            assert_eq!(f.to_string(), "minptime=10;stereo=1;useinbandfec=1");
         }
     }
 
@@ -1845,6 +1858,42 @@ f78dde68-7055-4e20-bb37-433803dd1ed1\r\n\
         }
     }
 
+    /// Opus codec-specific tests.
+    /// These tests are mainly verify SDP format params.
+    mod opus_codec {
+        use super::*;
+
+        #[test]
+        fn opus_fmtp_round_trip() {
+            let f = FormatParams {
+                use_dtx: Some(true),
+                stereo: Some(true),
+                sprop_stereo: Some(true),
+                ..Default::default()
+            };
+
+            let fmtp_str = f.to_string();
+            assert_eq!(fmtp_str, "stereo=1;sprop-stereo=1;usedtx=1");
+
+            let parsed = FormatParams::parse_line(&fmtp_str);
+            assert_eq!(parsed, f);
+        }
+
+        #[test]
+        fn opus_default_to_mono() {
+            let f = FormatParams {
+                ..Default::default()
+            };
+            let fmtp_str = f.to_string();
+            assert_eq!(fmtp_str, "");
+
+            let parsed = FormatParams::parse_line(&fmtp_str);
+            assert!(parsed.stereo.is_none());
+            assert_eq!(parsed.stereo.unwrap_or(false), false);
+            assert_eq!(parsed.sprop_stereo.unwrap_or(false), false);
+        }
+    }
+
     /// Core H.265 (HEVC) codec-specific tests.
     /// Tests basic H.265 parameter handling including profile-tier-level parsing,
     /// serialization, and format parameter combinations.