Move capabilities API into submodule in medea-flutter-webrtc-native crate (#214, #210)

Author: turtletongue

crates/native/src/api/capability/mod.rs

@@ -0,0 +1,74 @@
+//! Capabilities of an [RTP] endpoint.
+//!
+//! [RTP]: https://en.wikipedia.org/wiki/Real-time_Transport_Protocol
+
+pub mod rtp_codec;
+pub mod rtp_header_extension_capability;
+
+use libwebrtc_sys as sys;
+
+pub use self::{
+    rtp_codec::{
+        RtcpFeedback, RtcpFeedbackMessageType, RtcpFeedbackType,
+        RtpCodecCapability, ScalabilityMode, set_codec_preferences,
+    },
+    rtp_header_extension_capability::RtpHeaderExtensionCapability,
+};
+#[cfg(doc)]
+use crate::RtpParameters;
+use crate::api::{MediaType, WEBRTC};
+
+/// Representation of the static capabilities of an endpoint.
+///
+/// Applications can use these capabilities to construct [`RtpParameters`].
+#[derive(Debug)]
+pub struct RtpCapabilities {
+    /// Supported codecs.
+    pub codecs: Vec<RtpCodecCapability>,
+
+    /// Supported [RTP] header extensions.
+    ///
+    /// [RTP]: https://en.wikipedia.org/wiki/Real-time_Transport_Protocol
+    pub header_extensions: Vec<RtpHeaderExtensionCapability>,
+}
+
+impl From<sys::RtpCapabilities> for RtpCapabilities {
+    fn from(value: sys::RtpCapabilities) -> Self {
+        Self {
+            codecs: value.codecs().into_iter().map(Into::into).collect(),
+            header_extensions: value
+                .header_extensions()
+                .into_iter()
+                .map(Into::into)
+                .collect(),
+        }
+    }
+}
+
+/// Returns the capabilities of an [RTP] sender of the provided [`MediaType`].
+///
+/// [RTP]: https://en.wikipedia.org/wiki/Real-time_Transport_Protocol
+#[must_use]
+pub fn get_rtp_sender_capabilities(kind: MediaType) -> RtpCapabilities {
+    RtpCapabilities::from(
+        WEBRTC
+            .lock()
+            .unwrap()
+            .peer_connection_factory
+            .get_rtp_sender_capabilities(kind.into()),
+    )
+}
+
+/// Returns the capabilities of an [RTP] receiver of the provided [`MediaType`].
+///
+/// [RTP]: https://en.wikipedia.org/wiki/Real-time_Transport_Protocol
+#[must_use]
+pub fn get_rtp_receiver_capabilities(kind: MediaType) -> RtpCapabilities {
+    RtpCapabilities::from(
+        WEBRTC
+            .lock()
+            .unwrap()
+            .peer_connection_factory
+            .get_rtp_receiver_capabilities(kind.into()),
+    )
+}

crates/native/src/api/capability/rtp_codec/mod.rs

@@ -0,0 +1,100 @@
+//! Static codec capabilities.
+
+pub mod rtcp_feedback;
+pub mod scalability_mode;
+
+use std::sync::Arc;
+
+use libwebrtc_sys as sys;
+
+pub use self::{
+    rtcp_feedback::{RtcpFeedback, RtcpFeedbackMessageType, RtcpFeedbackType},
+    scalability_mode::ScalabilityMode,
+};
+use crate::{RtpTransceiver, api::MediaType, frb_generated::RustOpaque};
+
+/// Representation of static capabilities of an endpoint's implementation of a
+/// codec.
+#[derive(Debug)]
+pub struct RtpCodecCapability {
+    /// Default payload type for the codec.
+    ///
+    /// Mainly needed for codecs that have statically assigned payload types.
+    pub preferred_payload_type: Option<i32>,
+
+    /// List of [`ScalabilityMode`]s supported by the video codec.
+    pub scalability_modes: Vec<ScalabilityMode>,
+
+    /// Built [MIME "type/subtype"][0] string from `name` and `kind`.
+    ///
+    /// [0]: https://en.wikipedia.org/wiki/Media_type
+    pub mime_type: String,
+
+    /// Used to identify the codec. Equivalent to [MIME subtype][0].
+    ///
+    /// [0]: https://en.wikipedia.org/wiki/Media_type#Subtypes
+    pub name: String,
+
+    /// [`MediaType`] of this codec. Equivalent to [MIME] top-level type.
+    ///
+    /// [MIME]: https://en.wikipedia.org/wiki/Media_type
+    pub kind: MediaType,
+
+    /// If [`None`], the implementation default is used.
+    pub clock_rate: Option<i32>,
+
+    /// Number of audio channels used.
+    ///
+    /// [`None`] for video codecs.
+    ///
+    /// If [`None`] for audio, the implementation default is used.
+    pub num_channels: Option<i32>,
+
+    /// Codec-specific parameters that must be signaled to the remote party.
+    ///
+    /// Corresponds to `a=fmtp` parameters in [SDP].
+    ///
+    /// Contrary to ORTC, these parameters are named using all lowercase
+    /// strings. This helps make the mapping to [SDP] simpler, if an application
+    /// is using [SDP]. Boolean values are represented by the string "1".
+    ///
+    /// [SDP]: https://en.wikipedia.org/wiki/Session_Description_Protocol
+    pub parameters: Vec<(String, String)>,
+
+    /// Feedback mechanisms to be used for this codec.
+    pub feedback: Vec<RtcpFeedback>,
+}
+
+impl From<sys::RtpCodecCapability> for RtpCodecCapability {
+    fn from(value: sys::RtpCodecCapability) -> Self {
+        Self {
+            preferred_payload_type: value.preferred_payload_type(),
+            scalability_modes: value
+                .scalability_modes()
+                .into_iter()
+                .map(Into::into)
+                .collect(),
+            mime_type: value.mime_type(),
+            name: value.name(),
+            kind: value.kind().into(),
+            clock_rate: value.clock_rate(),
+            num_channels: value.num_channels(),
+            parameters: value.parameters().into_iter().collect(),
+            feedback: value
+                .rtcp_feedback()
+                .into_iter()
+                .map(Into::into)
+                .collect(),
+        }
+    }
+}
+
+/// Changes the preferred [`RtpTransceiver`] codecs to the provided
+/// [`Vec`]`<`[`RtpCodecCapability`]`>`.
+#[expect(clippy::needless_pass_by_value, reason = "FFI")]
+pub fn set_codec_preferences(
+    transceiver: RustOpaque<Arc<RtpTransceiver>>,
+    codecs: Vec<RtpCodecCapability>,
+) {
+    transceiver.set_codec_preferences(codecs);
+}

crates/native/src/api/capability/rtp_codec/rtcp_feedback.rs

@@ -0,0 +1,87 @@
+//! [RTCP] feedback message.
+//!
+//! [RTCP]: https://en.wikipedia.org/wiki/RTP_Control_Protocol
+
+use libwebrtc_sys as sys;
+
+/// [RTCP] feedback message intended to enable congestion control for
+/// interactive real-time traffic using [RTP].
+///
+/// [RTCP]: https://en.wikipedia.org/wiki/RTP_Control_Protocol
+/// [RTP]: https://en.wikipedia.org/wiki/Real-time_Transport_Protocol
+#[derive(Debug)]
+pub struct RtcpFeedback {
+    /// Message type of this [`RtcpFeedback`].
+    pub message_type: Option<RtcpFeedbackMessageType>,
+
+    /// Kind of this [`RtcpFeedback`].
+    pub kind: RtcpFeedbackType,
+}
+
+impl From<sys::RtcpFeedback> for RtcpFeedback {
+    fn from(value: sys::RtcpFeedback) -> Self {
+        Self {
+            message_type: value.message_type().map(Into::into),
+            kind: value.kind().into(),
+        }
+    }
+}
+
+/// Possible types of an [`RtcpFeedback`].
+#[derive(Debug, Eq, Hash, PartialEq)]
+#[repr(i32)]
+pub enum RtcpFeedbackType {
+    /// Codec control messages.
+    Ccm,
+
+    /// Loss notification feedback.
+    Lntf,
+
+    /// Negative acknowledgemen.
+    Nack,
+
+    /// Receiver estimated maximum bitrate.
+    Remb,
+
+    /// Transport wide congestion control.
+    TransportCC,
+}
+
+impl From<sys::RtcpFeedbackType> for RtcpFeedbackType {
+    fn from(value: sys::RtcpFeedbackType) -> Self {
+        match value {
+            sys::RtcpFeedbackType::CCM => Self::Ccm,
+            sys::RtcpFeedbackType::LNTF => Self::Lntf,
+            sys::RtcpFeedbackType::NACK => Self::Nack,
+            sys::RtcpFeedbackType::REMB => Self::Remb,
+            sys::RtcpFeedbackType::TRANSPORT_CC => Self::TransportCC,
+            _ => unreachable!(),
+        }
+    }
+}
+
+/// Possible message types of an [`RtcpFeedback`], when is type is
+/// [`RtcpFeedbackType::Nack`] or [`RtcpFeedbackType::Ccm`].
+#[derive(Debug, Eq, Hash, PartialEq)]
+#[repr(i32)]
+pub enum RtcpFeedbackMessageType {
+    /// Equivalent to `{ type: "nack", parameter: undefined }` in ORTC.
+    GenericNACK,
+
+    /// Usable with [`RtcpFeedbackType::Nack`].
+    Pli,
+
+    /// Usable with [`RtcpFeedbackType::Ccm`].
+    Fir,
+}
+
+impl From<sys::RtcpFeedbackMessageType> for RtcpFeedbackMessageType {
+    fn from(value: sys::RtcpFeedbackMessageType) -> Self {
+        match value {
+            sys::RtcpFeedbackMessageType::GENERIC_NACK => Self::GenericNACK,
+            sys::RtcpFeedbackMessageType::PLI => Self::Pli,
+            sys::RtcpFeedbackMessageType::FIR => Self::Fir,
+            _ => unreachable!(),
+        }
+    }
+}