rtc_rtcp/
lib.rs

1#![warn(rust_2018_idioms)]
2#![warn(missing_docs)]
3#![allow(dead_code)]
4
5//! Package rtcp implements encoding and decoding of RTCP packets according to RFCs 3550 and 5506.
6//!
7//! RTCP is a sister protocol of the Real-time Transport Protocol (RTP). Its basic functionality
8//! and packet structure is defined in RFC 3550. RTCP provides out-of-band statistics and control
9//! information for an RTP session. It partners with RTP in the delivery and packaging of multimedia data,
10//! but does not transport any media data itself.
11//!
12//! The primary function of RTCP is to provide feedback on the quality of service (QoS)
13//! in media distribution by periodically sending statistics information such as transmitted octet
14//! and packet counts, packet loss, packet delay variation, and round-trip delay time to participants
15//! in a streaming multimedia session. An application may use this information to control quality of
16//! service parameters, perhaps by limiting flow, or using a different codec.
17//!
18//! # Decoding RTCP packets
19//!
20//! One datagram may hold several packets — RTCP is compound — so [`packet::unmarshal`]
21//! consumes the buffer and returns them all. Recover each concrete type by downcasting:
22//!
23//! ```
24//! use bytes::Bytes;
25//! use rtc_rtcp::goodbye::Goodbye;
26//! use rtc_rtcp::packet::unmarshal;
27//! use rtc_rtcp::payload_feedbacks::picture_loss_indication::PictureLossIndication;
28//!
29//! # fn example(rtcp_data: Bytes) -> Result<(), Box<dyn std::error::Error>> {
30//! let mut buf = rtcp_data;
31//! for packet in unmarshal(&mut buf)? {
32//!     if let Some(pli) = packet.as_any().downcast_ref::<PictureLossIndication>() {
33//!         println!("keyframe requested for ssrc {}", pli.media_ssrc);
34//!     } else if let Some(bye) = packet.as_any().downcast_ref::<Goodbye>() {
35//!         println!("{:?} left the session", bye.sources);
36//!     }
37//! }
38//! # Ok(())
39//! # }
40//! ```
41//!
42//! # Encoding RTCP packets
43//!
44//! Every packet type implements [`Marshal`](shared::marshal::Marshal), so that trait must be
45//! in scope:
46//!
47//! ```
48//! use rtc_rtcp::payload_feedbacks::picture_loss_indication::PictureLossIndication;
49//! use shared::marshal::Marshal;
50//!
51//! # fn example(sender_ssrc: u32, media_ssrc: u32) -> Result<(), Box<dyn std::error::Error>> {
52//! let pli = PictureLossIndication {
53//!     sender_ssrc,
54//!     media_ssrc,
55//! };
56//! let pli_data = pli.marshal()?;
57//! # Ok(())
58//! # }
59//! ```
60
61/// Compound RTCP packets — the several reports that share one datagram.
62pub mod compound_packet;
63/// Extended reports (XR, [RFC 3611]): loss/discard run lengths, receipt times and per-block
64/// statistics.
65///
66/// [RFC 3611]: https://datatracker.ietf.org/doc/html/rfc3611
67pub mod extended_report;
68/// The BYE packet, by which a source announces it is leaving.
69pub mod goodbye;
70/// The four-byte header common to every RTCP packet.
71pub mod header;
72/// The [`Packet`] trait every RTCP packet type implements.
73pub mod packet;
74/// Payload-specific feedback (PT 206): PLI, FIR, SLI and REMB.
75pub mod payload_feedbacks;
76/// An unparsed packet, used for types this crate does not model.
77pub mod raw_packet;
78/// The Receiver Report (RR), which reports reception quality back to a sender.
79pub mod receiver_report;
80/// The reception report block carried inside SR and RR packets.
81pub mod reception_report;
82/// The Sender Report (SR), which carries a sender's timing and packet counts.
83pub mod sender_report;
84/// The SDES packet, which carries CNAME and other source metadata.
85pub mod source_description;
86/// Transport-specific feedback (PT 205): NACK and transport-wide congestion control.
87pub mod transport_feedbacks;
88mod util;
89
90pub use header::Header;
91pub use packet::Packet;
rtc_rtcp/lib.rs

rtc_rtcp/
lib.rs
