rtc_interceptor/
stream_info.rs

1//! Stream information types for interceptor binding.
2//!
3//! This module provides types that describe media streams for interceptor binding.
4//! When a stream is bound to an interceptor chain, [`StreamInfo`] provides all the
5//! necessary metadata about the stream's codec, SSRC, and supported features.
6//!
7//! # Stream Binding
8//!
9//! Interceptors need to know about streams before they can process packets:
10//!
11//! - **Local streams** (outgoing): Bind with [`Interceptor::bind_local_stream`]
12//! - **Remote streams** (incoming): Bind with [`Interceptor::bind_remote_stream`]
13//!
14//! # Feature Detection
15//!
16//! Interceptors use [`StreamInfo`] to detect which features are supported:
17//!
18//! - **NACK support**: Check [`rtcp_feedback`](StreamInfo::rtcp_feedback) for `type: "nack"`
19//! - **TWCC support**: Check [`rtp_header_extensions`](StreamInfo::rtp_header_extensions) for the TWCC URI
20//! - **RTX support**: Check if [`ssrc_rtx`](StreamInfo::ssrc_rtx) and [`payload_type_rtx`](StreamInfo::payload_type_rtx) are set
21
22/// RTP header extension as negotiated via SDP (RFC 5285).
23///
24/// Represents a header extension that can be used to add metadata to RTP packets,
25/// such as audio levels, video orientation, or custom application data.
26///
27/// # Common Extension URIs
28///
29/// | URI | Description |
30/// |-----|-------------|
31/// | `urn:ietf:params:rtp-hdrext:ssrc-audio-level` | Audio level indication |
32/// | `urn:ietf:params:rtp-hdrext:toffset` | Transmission time offset |
33/// | `http://www.webrtc.org/experiments/rtp-hdrext/abs-send-time` | Absolute send time |
34/// | `http://www.ietf.org/id/draft-holmer-rmcat-transport-wide-cc-extensions-01` | TWCC sequence number |
35#[derive(Default, Debug, Clone)]
36pub struct RTPHeaderExtension {
37    /// URI identifying the extension type (e.g., "urn:ietf:params:rtp-hdrext:ssrc-audio-level")
38    pub uri: String,
39    /// Local identifier (1-14 for one-byte, 1-255 for two-byte) used in RTP packets to reference this extension
40    pub id: u16,
41}
42
43/// RTCP feedback mechanism negotiated for the stream.
44///
45/// Specifies additional RTCP packet types that can be used for feedback
46/// between peers, such as NACK for retransmissions or PLI for picture loss.
47///
48/// # Common Feedback Types
49///
50/// | Type | Parameter | Description | RFC |
51/// |------|-----------|-------------|-----|
52/// | `nack` | (empty) | Generic NACK for retransmission | RFC 4585 |
53/// | `nack` | `pli` | Picture Loss Indication | RFC 4585 |
54/// | `nack` | `fir` | Full Intra Request | RFC 5104 |
55/// | `ccm` | `fir` | Codec Control Message: FIR | RFC 5104 |
56/// | `goog-remb` | (empty) | Google REMB for bandwidth estimation | - |
57/// | `transport-cc` | (empty) | Transport-wide CC feedback | draft-holmer |
58///
59/// See: <https://draft.ortc.org/#dom-rtcrtcpfeedback>
60#[derive(Default, Debug, Clone)]
61pub struct RTCPFeedback {
62    /// Type of feedback mechanism.
63    ///
64    /// Valid values: "ack", "ccm", "nack", "goog-remb", "transport-cc"
65    ///
66    /// See: <https://draft.ortc.org/#dom-rtcrtcpfeedback>
67    pub typ: String,
68
69    /// Parameter value that depends on the feedback type.
70    ///
71    /// For example, `typ="nack"` with `parameter="pli"` enables Picture Loss Indicator packets.
72    /// An empty string indicates the base feedback type without additional parameters.
73    pub parameter: String,
74}
75
76/// Stream context passed to interceptor bind/unbind callbacks.
77///
78/// Contains all relevant information about a media stream (audio or video)
79/// when it's bound to or unbound from an interceptor. This includes codec
80/// parameters, SSRC, RTP extensions, and RTCP feedback mechanisms.
81///
82/// Used by [`Interceptor::bind_local_stream`](crate::Interceptor::bind_local_stream),
83/// [`Interceptor::unbind_local_stream`](crate::Interceptor::unbind_local_stream),
84/// [`Interceptor::bind_remote_stream`](crate::Interceptor::bind_remote_stream), and
85/// [`Interceptor::unbind_remote_stream`](crate::Interceptor::unbind_remote_stream).
86///
87/// # Example
88///
89/// ```ignore
90/// use rtc_interceptor::{StreamInfo, RTCPFeedback, RTPHeaderExtension};
91///
92/// let info = StreamInfo {
93///     ssrc: 0x12345678,
94///     clock_rate: 90000,
95///     mime_type: "video/VP8".to_string(),
96///     payload_type: 96,
97///     // Enable NACK for retransmission
98///     rtcp_feedback: vec![RTCPFeedback {
99///         typ: "nack".to_string(),
100///         parameter: String::new(),
101///     }],
102///     ..Default::default()
103/// };
104/// ```
105#[derive(Default, Debug, Clone)]
106pub struct StreamInfo {
107    /// Synchronization Source identifier (SSRC) of the stream.
108    ///
109    /// Uniquely identifies the source of an RTP stream within an RTP session.
110    pub ssrc: u32,
111
112    /// RTX (Retransmission) SSRC for RFC 4588 retransmission.
113    ///
114    /// When set, retransmissions will use this separate SSRC instead of the
115    /// original stream's SSRC. This allows the receiver to distinguish between
116    /// original and retransmitted packets.
117    pub ssrc_rtx: Option<u32>,
118
119    /// FEC (Forward Error Correction) SSRC.
120    ///
121    /// SSRC used for FEC packets if separate-stream FEC is configured.
122    pub ssrc_fec: Option<u32>,
123
124    /// RTP payload type (e.g., 96 for VP8, 111 for Opus).
125    ///
126    /// Dynamic payload types (96-127) are typically used for modern codecs.
127    pub payload_type: u8,
128
129    /// RTX payload type for RFC 4588 retransmission.
130    ///
131    /// When set along with `ssrc_rtx`, retransmitted packets will use this
132    /// payload type to distinguish them from original packets.
133    pub payload_type_rtx: Option<u8>,
134
135    /// FEC payload type.
136    ///
137    /// Payload type used for FEC packets if configured.
138    pub payload_type_fec: Option<u8>,
139
140    /// Negotiated RTP header extensions for this stream.
141    ///
142    /// Contains the list of header extensions that can be used with this stream,
143    /// such as TWCC sequence numbers, audio levels, or video orientation.
144    pub rtp_header_extensions: Vec<RTPHeaderExtension>,
145
146    /// MIME type of the codec (e.g., "video/VP8", "audio/opus").
147    pub mime_type: String,
148
149    /// Clock rate in Hz (e.g., 90000 for video, 48000 for Opus audio).
150    ///
151    /// Used to convert between RTP timestamps and wall-clock time.
152    pub clock_rate: u32,
153
154    /// Number of audio channels (0 for video, 1 for mono, 2 for stereo).
155    pub channels: u16,
156
157    /// Format-specific parameters from SDP (fmtp line).
158    ///
159    /// Contains codec-specific parameters like "profile-level-id" for H.264
160    /// or "minptime" for audio codecs.
161    pub sdp_fmtp_line: String,
162
163    /// RTCP feedback mechanisms negotiated for this stream.
164    ///
165    /// Specifies which RTCP feedback types (NACK, PLI, REMB, etc.) are
166    /// supported for this stream.
167    pub rtcp_feedback: Vec<RTCPFeedback>,
168}
rtc_interceptor/stream_info.rs

rtc_interceptor/
stream_info.rs
