moq_mux/container/
mod.rs

1//! Container formats.
2//!
3//! A container decides how a media frame is laid out inside a moq-lite
4//! frame: framing overhead, whether multiple samples can share one moq
5//! frame, and whether the same encoding doubles as a file format on disk.
6//!
7//! Each submodule implements one format. The wire-level ones implement
8//! the [`Container`] trait, so [`Producer<C>`] and [`Consumer<C>`] can
9//! be generic over the choice. The catalog announces a container per
10//! track; [`catalog::hang::Container`](crate::catalog::hang::Container)
11//! dispatches the right implementation at runtime.
12
13use std::task::Poll;
14
15use bytes::Bytes;
16
17mod consumer;
18mod producer;
19mod source;
20#[cfg(test)]
21pub(crate) mod test_util;
22
23pub mod flv;
24pub mod fmp4;
25pub mod legacy;
26pub mod loc;
27pub mod mkv;
28pub mod ts;
29
30pub use consumer::Consumer;
31pub use producer::Producer;
32pub(crate) use source::ExportSource;
33
34/// A decoded media frame: timestamp, payload bytes, keyframe flag.
35///
36/// `payload` is the raw codec bitstream that gets handed to the decoder.
37/// The exact shape depends on the codec (Annex B for H.264/H.265, OBU for
38/// AV1, and so on).
39#[derive(Clone, Debug)]
40pub struct Frame {
41	/// Presentation timestamp.
42	///
43	/// Each container picks its own native scale: fmp4 uses the source
44	/// `mdhd.timescale`, mkv uses nanoseconds, legacy is fixed at microseconds.
45	/// LOC defaults to microseconds but a decoded frame keeps whatever per-frame
46	/// timescale the wire carried, so an exporter can re-emit without forcing
47	/// micros. Frames within a track must be in *decode* order, not display
48	/// order. B-frames may have non-monotonic presentation timestamps.
49	pub timestamp: moq_net::Timestamp,
50
51	/// Sample duration in the frame's own scale, when the container reports it.
52	///
53	/// CMAF carries a per-sample duration (trun sample-duration); containers
54	/// that don't (Legacy, LOC) leave this `None`. The [`Consumer`] adds it to
55	/// `timestamp` to learn how far a group has presented, so it can advance to
56	/// a newer group as soon as the gap is covered instead of waiting out the
57	/// latency budget.
58	pub duration: Option<moq_net::Timestamp>,
59
60	/// Encoded codec payload.
61	pub payload: Bytes,
62
63	/// Whether this frame is a keyframe.
64	///
65	/// Containers that carry the bit on the wire (CMAF reads it from
66	/// trun sample-flags) should set it; containers that don't (Legacy,
67	/// LOC) leave it `false`. The wrapping [`Consumer`] still asserts
68	/// "first frame in a group is a keyframe" as a fallback, so the
69	/// Legacy/LOC case lands correctly without anyone having to know.
70	pub keyframe: bool,
71}
72
73/// A non-keyframe frame arrived with no open group.
74///
75/// A track must open with a keyframe (and so must the frame after
76/// [`cut`](Producer::cut) / [`seek`](Producer::seek)).
77/// [`Producer::write`] returns this so a caller joining mid-stream can skip
78/// frames until the first keyframe instead of treating it as fatal.
79#[derive(Debug, Clone, Copy, PartialEq, Eq, thiserror::Error)]
80#[error("missing keyframe: a group must open on a keyframe")]
81pub struct MissingKeyframe;
82
83/// Encode and decode media frames over a moq-lite group.
84///
85/// Implementors decide how many [`Frame`]s map onto one moq-lite frame:
86/// Legacy and LOC write one media frame per moq-lite frame; CMAF can
87/// pack many samples into a single moof+mdat fragment.
88pub trait Container {
89	/// Container-specific error. Must be convertible from [`moq_net::Error`]
90	/// (so IO errors propagate) and [`MissingKeyframe`] (so the producer can
91	/// reject a group that doesn't open on a keyframe).
92	type Error: std::error::Error + Send + Sync + Unpin + From<moq_net::Error> + From<MissingKeyframe>;
93
94	/// Encode one or more frames into a single moq-lite frame appended to `group`.
95	fn write(&self, group: &mut moq_net::group::Producer, frames: &[Frame]) -> Result<(), Self::Error>;
96
97	/// Poll the next moq-lite frame from `group` and decode it into media
98	/// frames. A single call may produce multiple media frames (e.g. all samples
99	/// in a CMAF fragment).
100	///
101	/// Only `Ok(None)` signals the end of the group. `Ok(Some(batch))` may carry
102	/// an empty `batch`: a wire frame was consumed but decoded to no media frames
103	/// (e.g. a CMAF fragment with zero samples). That is not end-of-group; poll
104	/// again for the next batch. Callers accumulating frames must not treat an
105	/// empty batch as completion.
106	fn poll_read(
107		&self,
108		group: &mut moq_net::group::Consumer,
109		waiter: &kio::Waiter,
110	) -> Poll<Result<Option<Vec<Frame>>, Self::Error>>;
111
112	/// Async wrapper around [`Self::poll_read`]. Carries the same contract: only
113	/// `Ok(None)` ends the group, and `Ok(Some(batch))` may hand back an empty
114	/// `batch` (poll again for more), so a caller loop must key completion off
115	/// `None`, not an empty batch.
116	fn read(
117		&self,
118		group: &mut moq_net::group::Consumer,
119	) -> impl std::future::Future<Output = Result<Option<Vec<Frame>>, Self::Error>>
120	where
121		Self: Sync,
122	{
123		async { kio::wait(|waiter| self.poll_read(group, waiter)).await }
124	}
125}
moq_mux/container/mod.rs

moq_mux/container/
mod.rs
