rtc_media/
lib.rs

1#![warn(rust_2018_idioms)]
2#![warn(missing_docs)]
3#![allow(dead_code)]
4
5//! Media samples and container I/O.
6//!
7//! The bridge between encoded media and RTP: a codec-agnostic [`Sample`] type, and readers
8//! and writers for the container formats the examples and tests use.
9//!
10//! # Structure
11//!
12//! * [`Sample`] — one encoded unit of media (a video frame, an audio frame) with its
13//!   duration, timestamp and packet metadata. Hand these to a sample-based local track and
14//!   the RTP packetizer does the rest.
15//! * [`io`] — the [`Writer`](io::Writer) trait plus concrete readers and writers for IVF
16//!   (VP8/VP9), Ogg (Opus) and H.264/H.265 Annex B — [`IVFReader`](io::ivf_reader::IVFReader),
17//!   [`OggReader`](io::ogg_reader::OggReader) and friends — enough to play media from disk or
18//!   record it to disk. [`SampleBuilder`](io::sample_builder::SampleBuilder) goes the other
19//!   way, reassembling inbound RTP into [`Sample`]s.
20//! * [`audio`], [`video`] — per-codec helpers, including audio buffering and frame
21//!   inspection.
22//!
23//! # Example
24//!
25//! ```
26//! use bytes::Bytes;
27//! use rtc_media::Sample;
28//! use shared::time::SystemInstant;
29//! use std::time::Duration;
30//!
31//! // One encoded frame, ready to hand to a sample-based local track.
32//! let sample = Sample {
33//!     data: Bytes::from_static(&[0u8; 128]),
34//!     timestamp: SystemInstant::now(),
35//!     duration: Duration::from_millis(33), // ~30 fps
36//!     ..Default::default()
37//! };
38//! assert_eq!(sample.data.len(), 128);
39//! ```
40//!
41//! Most applications do not depend on this crate directly — the
42//! [`rtc`](https://docs.rs/rtc) crate re-exports it as `rtc::media`.
43
44/// Audio sample types and multi-channel buffers.
45pub mod audio;
46/// Container readers and writers, plus RTP sample reassembly.
47pub mod io;
48/// Video frame helpers.
49pub mod video;
50
51use bytes::Bytes;
52use shared::time::SystemInstant;
53use std::time::Duration;
54
55/// A Sample contains encoded media and timing information
56#[derive(Debug)]
57pub struct Sample {
58    /// The assembled data in the sample, as a bitstream.
59    ///
60    /// The format is Codec dependant, but is always a bitstream format
61    /// rather than the packetized format used when carried over RTP.
62    ///
63    /// See: [`rtp::packetizer::Depacketizer`] and implementations of it for more details.
64    pub data: Bytes,
65
66    /// The wallclock time when this sample was generated.
67    pub timestamp: SystemInstant,
68
69    /// The duration of this sample
70    pub duration: Duration,
71
72    /// The RTP packet timestamp of this sample.
73    ///
74    /// For all RTP packets that contributed to a single sample the timestamp is the same.
75    pub packet_timestamp: u32,
76
77    /// The number of packets that were dropped prior to building this sample.
78    ///
79    /// Packets being dropped doesn't necessarily indicate something wrong, e.g., packets are sometimes
80    /// dropped because they aren't relevant for sample building.
81    pub prev_dropped_packets: u16,
82
83    /// The number of packets that were identified as padding prior to building this sample.
84    ///
85    /// Some implementations, notably libWebRTC, send padding packets to keep the send rate steady.
86    /// These packets don't carry media and aren't useful for building samples.
87    ///
88    /// This field can be combined with [`Sample::prev_dropped_packets`] to determine if any
89    /// dropped packets are likely to have detrimental impact on the steadiness of the RTP stream.
90    ///
91    /// ## Example adjustment
92    ///
93    /// ```rust
94    /// # use bytes::Bytes;
95    /// # use std::time::{SystemTime, Duration};
96    /// # use rtc_media::Sample;
97    /// use shared::time::SystemInstant;
98    /// # let sample = Sample {
99    /// #   data: Bytes::new(),
100    /// #   timestamp: SystemInstant::now(),
101    /// #   duration: Duration::from_secs(0),
102    /// #   packet_timestamp: 0,
103    /// #   prev_dropped_packets: 10,
104    /// #   prev_padding_packets: 15
105    /// # };
106    /// #
107    /// let adjusted_dropped =
108    /// sample.prev_dropped_packets.saturating_sub(sample.prev_padding_packets);
109    /// ```
110    pub prev_padding_packets: u16,
111}
112
113impl Default for Sample {
114    fn default() -> Self {
115        Sample {
116            data: Bytes::new(),
117            timestamp: SystemInstant::now(),
118            duration: Duration::from_secs(0),
119            packet_timestamp: 0,
120            prev_dropped_packets: 0,
121            prev_padding_packets: 0,
122        }
123    }
124}
125
126impl PartialEq for Sample {
127    fn eq(&self, other: &Self) -> bool {
128        let mut equal: bool = true;
129        if self.data != other.data {
130            equal = false;
131        }
132        if self.timestamp.duration_since_unix_epoch().as_secs()
133            != other.timestamp.duration_since_unix_epoch().as_secs()
134        {
135            equal = false;
136        }
137        if self.duration != other.duration {
138            equal = false;
139        }
140        if self.packet_timestamp != other.packet_timestamp {
141            equal = false;
142        }
143        if self.prev_dropped_packets != other.prev_dropped_packets {
144            equal = false;
145        }
146        if self.prev_padding_packets != other.prev_padding_packets {
147            equal = false;
148        }
149
150        equal
151    }
152}
rtc_media/lib.rs

rtc_media/
lib.rs
