Skip to main content

rff_format/
lib.rs

1//! `rff-format` — the container (muxer/demuxer) abstraction layer (FFmpeg's
2//! `libavformat` core, minus the formats themselves).
3//!
4//! A container is the file wrapper (AVI, MP4, Matroska, ...) that interleaves
5//! one or more elementary streams. This crate defines:
6//! * [`Stream`] — the description of one elementary stream inside a container,
7//! * [`Demuxer`] — reads a container, exposing streams and [`Packet`]s,
8//! * [`Muxer`] — writes streams + packets back into a container,
9//! * [`FormatRegistry`] — what individual format crates register into.
10//!
11//! Concrete formats live in their own crates (`rff-format-avi`, ...).
12
13pub mod aac;
14pub mod av1;
15pub mod avc;
16pub mod hvc;
17
18use std::collections::HashMap;
19use std::io::{Read, Seek, Write};
20
21use rff_core::{
22    CleanAperture, CodecId, ColorInfo, ColorRange, ContentLightLevel, Dictionary, Error,
23    MasteringDisplay, MediaType, Packet, PixelFormat, Rational, Result, SampleFormat, Timecode,
24};
25
26/// Description of one elementary stream within a container.
27#[derive(Debug, Clone)]
28pub struct Stream {
29    /// Position of this stream within its container.
30    pub index: usize,
31    pub codec_id: CodecId,
32    pub media_type: MediaType,
33    /// Unit of all timestamps on packets of this stream.
34    pub time_base: Rational,
35    // --- Video parameters (zero/ignored for non-video) ---
36    pub width: u32,
37    pub height: u32,
38    /// Raw pixel layout, when known (raw video). Self-describing codecs leave this `None`.
39    pub pixel_format: Option<PixelFormat>,
40    /// Luma/chroma value range. JPEG and PNG sources are always
41    /// [`ColorRange::Full`]; leaving it [`Unspecified`](ColorRange::Unspecified)
42    /// makes containers label the data limited-range, which silently corrupts it.
43    pub color_range: ColorRange,
44    // --- Audio parameters (zero/ignored for non-audio) ---
45    pub sample_rate: u32,
46    pub channels: u16,
47    /// Raw sample layout, when known (PCM). Self-describing codecs leave this `None`.
48    pub sample_format: Option<SampleFormat>,
49    /// Codec-private initialization data (e.g. H.264 SPS/PPS, OpusHead). Empty
50    /// for codecs whose bitstream is fully self-describing.
51    pub extradata: Vec<u8>,
52    /// Total stream duration in [`time_base`](Stream::time_base) units, when
53    /// the container declares it (MP4 `mdhd`, Matroska `Duration`). `None` when
54    /// unknown (live streams, TS).
55    pub duration: Option<i64>,
56    /// Total packet count (frames for video), when the container's index
57    /// declares it. `None` when unknown — never a guess.
58    pub nb_frames: Option<u64>,
59    /// The container's own code for this codec, when it has one worth
60    /// keeping: the MP4/QuickTime sample-entry fourcc (`apch` vs `apcn` names
61    /// the ProRes profile, `twos` vs `sowt` the PCM byte order on disk). A
62    /// muxer of the same family writes it back when it is valid for the
63    /// codec, so a remux keeps the original entry; `None` lets the muxer pick.
64    pub codec_tag: Option<[u8; 4]>,
65    // --- Video description (containers label; they do not convert) ---
66    /// Colour primaries / transfer / matrix (MP4 `colr`, Matroska `Colour`).
67    pub color: ColorInfo,
68    /// HDR mastering display (MP4 `mdcv`, Matroska `MasteringMetadata`).
69    pub mastering_display: Option<MasteringDisplay>,
70    /// HDR content light level (MP4 `clli`, Matroska `MaxCLL`/`MaxFALL`).
71    pub content_light: Option<ContentLightLevel>,
72    /// Pixel aspect ratio as `(horizontal, vertical)` spacing (MP4 `pasp`).
73    /// `None` when not recorded, which means square.
74    pub pixel_aspect: Option<(u32, u32)>,
75    /// Clean aperture (MP4 `clap`).
76    pub clean_aperture: Option<CleanAperture>,
77    /// Start timecode (a QuickTime `tmcd` track referenced by this video track).
78    pub timecode: Option<Timecode>,
79    /// The frames carry an alpha plane as a block addition (Matroska
80    /// `AlphaMode`; WebM VP8/VP9 alpha).
81    pub alpha_mode: bool,
82    // --- Audio timing the container records beside the packets ---
83    /// Samples the decoder must drop from the start, in nanoseconds
84    /// (Matroska `CodecDelay`; Opus pre-skip). The demuxer has already taken
85    /// it off packet timestamps; it is here so a remux can write it back.
86    pub codec_delay_ns: u64,
87    /// How far before a seek target decoding must start to converge, in
88    /// nanoseconds (Matroska `SeekPreRoll`; 80 ms for Opus).
89    pub seek_preroll_ns: u64,
90}
91
92impl Stream {
93    /// Create a stream with sane defaults for the given codec.
94    pub fn new(index: usize, codec_id: CodecId) -> Stream {
95        Stream {
96            index,
97            codec_id,
98            media_type: codec_id.media_type(),
99            time_base: Rational::new(1, 1000),
100            width: 0,
101            height: 0,
102            pixel_format: None,
103            color_range: ColorRange::Unspecified,
104            sample_rate: 0,
105            channels: 0,
106            sample_format: None,
107            extradata: Vec::new(),
108            duration: None,
109            nb_frames: None,
110            codec_tag: None,
111            color: ColorInfo::UNSPECIFIED,
112            mastering_display: None,
113            content_light: None,
114            pixel_aspect: None,
115            clean_aperture: None,
116            timecode: None,
117            alpha_mode: false,
118            codec_delay_ns: 0,
119            seek_preroll_ns: 0,
120        }
121    }
122}
123
124/// A byte source a demuxer reads from. (`Box<dyn Read + Send>` keeps the trait
125/// object-safe and lets inputs be files, network streams, or in-memory buffers.)
126pub type Input = Box<dyn Read + Send>;
127
128/// A byte source that can also seek — what a local file or an in-memory buffer
129/// offers and a pipe or socket does not. Blanket-implemented for every
130/// `Read + Seek` type.
131pub trait ReadSeek: Read + Seek {}
132impl<T: Read + Seek> ReadSeek for T {}
133
134/// A seekable [`Input`]. Formats whose index can sit anywhere in the file (MP4's
135/// `moov`) use it to read only that index and fetch each payload on demand,
136/// instead of buffering the whole file. It upcasts to [`Input`] for formats
137/// that only stream.
138pub type SeekInput = Box<dyn ReadSeek + Send>;
139/// A byte sink a muxer writes to.
140pub type Output = Box<dyn Write + Send>;
141
142/// A byte sink that can also seek -- a local file, an in-memory buffer; not a
143/// pipe or socket. Blanket-implemented for every `Write + Seek` type.
144pub trait WriteSeek: Write + Seek {}
145impl<T: Write + Seek> WriteSeek for T {}
146
147/// A seekable [`Output`]. Containers whose header records sizes or an index
148/// that is only known at the end (MP4 `mdat`/`moov`, Matroska Segment/Cues,
149/// AVI `movi`/`idx1`, WAV `RIFF`/`data`) use it to stream the payload as it
150/// arrives and patch the header afterwards, instead of holding the whole
151/// output in memory until the trailer (#28). It upcasts to [`Output`] for
152/// muxers that only stream.
153pub type SeekOutput = Box<dyn WriteSeek + Send>;
154
155/// Reads a container format: parses the header into [`Stream`]s, then yields
156/// [`Packet`]s until the input is exhausted.
157pub trait Demuxer: Send {
158    /// Parse the container header and return its streams.
159    fn read_header(&mut self) -> Result<Vec<Stream>>;
160
161    /// Read the next packet. Returns [`Error::Eof`] at end of input.
162    fn read_packet(&mut self) -> Result<Packet>;
163
164    /// Name the streams the caller will drop: `discard[i]` is stream `i`.
165    /// Called after [`read_header`](Demuxer::read_header); a demuxer may then
166    /// skip those streams' packets without reading or converting them. It is
167    /// a hint: a demuxer that ignores it (the default) still returns them and
168    /// the caller drops them, so either way the kept packets are identical.
169    fn set_discard(&mut self, _discard: &[bool]) {}
170}
171
172/// Writes a container format: declare streams, write packets, finalize.
173pub trait Muxer: Send {
174    /// Hand the muxer output metadata (`-metadata title=...`). Called before
175    /// [`write_header`](Muxer::write_header); formats without a metadata slot
176    /// simply ignore it (the default).
177    fn set_metadata(&mut self, _metadata: &Dictionary) {}
178
179    /// Write the container header for the given set of streams.
180    fn write_header(&mut self, streams: &[Stream]) -> Result<()>;
181
182    /// Write one packet (its `stream_index` selects the target stream).
183    fn write_packet(&mut self, packet: &Packet) -> Result<()>;
184
185    /// Finalize the container (indexes, trailers, fixups).
186    fn write_trailer(&mut self) -> Result<()>;
187}
188
189/// Factory opening a demuxer over an input byte source.
190pub type DemuxerFactory = fn(Input) -> Box<dyn Demuxer>;
191/// Factory opening a demuxer over a [`SeekInput`] — registered alongside the
192/// format's [`DemuxerFactory`] by formats that read less when they can seek.
193pub type SeekableDemuxerFactory = fn(SeekInput) -> Box<dyn Demuxer>;
194/// Factory opening a muxer over an output byte sink.
195pub type MuxerFactory = fn(Output) -> Box<dyn Muxer>;
196/// Factory opening a muxer over a [`SeekOutput`] -- registered alongside the
197/// format's [`MuxerFactory`] by formats that can stream when they can seek.
198pub type SeekableMuxerFactory = fn(SeekOutput) -> Box<dyn Muxer>;
199/// Factory opening a muxer that owns its own file set (HLS/DASH write a
200/// playlist/manifest plus many segment files, so a single byte sink cannot
201/// model them). Receives the output path and the format options
202/// (`-hls_time 6` → `{"hls_time": "6"}`).
203pub type PathMuxerFactory = fn(&std::path::Path, &Dictionary) -> Result<Box<dyn Muxer>>;
204/// Content sniffer: scores how strongly a byte prefix looks like this format,
205/// `0` (no match) to `100` (certain) — mirrors FFmpeg's `AVInputFormat::read_probe`.
206pub type ProbeFn = fn(&[u8]) -> i32;
207
208/// What a container's **muxer** will accept: the machine-readable half of the
209/// rules each muxer already enforces when it writes a header.
210///
211/// Muxers validate at run time, and a few historically wrote a zero codec tag
212/// rather than refusing an unmappable codec. Declaring the same rules here lets
213/// a caller answer "what can this file become?" *before* opening an encoder —
214/// which is what `rff-targets` is built on.
215#[derive(Debug, Clone, Copy, PartialEq, Eq)]
216pub struct MuxCaps {
217    /// Every codec this muxer can write. Empty for demux-only formats.
218    pub codecs: &'static [CodecId],
219    /// Most streams the container holds; `None` when there is no fixed limit.
220    pub max_streams: Option<usize>,
221    /// True when the container holds exactly ONE picture, so extra frames are
222    /// refused or dropped (png, jpeg, gif, webp, avif, jxl, av2f).
223    pub still_image: bool,
224}
225
226impl MuxCaps {
227    /// A format that cannot be written at all (demux-only).
228    pub const NONE: MuxCaps = MuxCaps {
229        codecs: &[],
230        max_streams: Some(0),
231        still_image: false,
232    };
233
234    /// A container interleaving any number of streams (mp4, matroska, mpegts).
235    pub const fn container(codecs: &'static [CodecId]) -> MuxCaps {
236        MuxCaps {
237            codecs,
238            max_streams: None,
239            still_image: false,
240        }
241    }
242
243    /// A file holding exactly one elementary stream (wav, mp3, ivf, ogg).
244    pub const fn single(codecs: &'static [CodecId]) -> MuxCaps {
245        MuxCaps {
246            codecs,
247            max_streams: Some(1),
248            still_image: false,
249        }
250    }
251
252    /// Narrow a [`single`](MuxCaps::single) file to one picture (png, jpeg).
253    pub const fn image(self) -> MuxCaps {
254        MuxCaps {
255            codecs: self.codecs,
256            max_streams: self.max_streams,
257            still_image: true,
258        }
259    }
260
261    /// Can this muxer write `id`?
262    pub fn accepts(&self, id: CodecId) -> bool {
263        self.codecs.contains(&id)
264    }
265
266    /// Can this muxer carry any stream of `media` at all?
267    pub fn accepts_media(&self, media: MediaType) -> bool {
268        self.codecs.iter().any(|c| c.media_type() == media)
269    }
270
271    /// The codecs this muxer accepts for one media category.
272    pub fn codecs_for(&self, media: MediaType) -> impl Iterator<Item = CodecId> + '_ {
273        self.codecs
274            .iter()
275            .copied()
276            .filter(move |c| c.media_type() == media)
277    }
278}
279
280/// Static description of a container format and its read/write support.
281pub struct Format {
282    /// Short name (`avi`, `mp4`, ...), as used by `ffmpeg -f <name>`.
283    pub name: &'static str,
284    pub long_name: &'static str,
285    /// File extensions that imply this format (without the dot).
286    pub extensions: &'static [&'static str],
287    /// Present if this format can be demuxed (read).
288    pub demuxer: Option<DemuxerFactory>,
289    /// Present if this format can be muxed (written).
290    pub muxer: Option<MuxerFactory>,
291    /// Present for formats that mux into a *path* (playlist + segment files)
292    /// rather than one byte sink — HLS, DASH. Mutually exclusive with `muxer`.
293    pub muxer_path: Option<PathMuxerFactory>,
294    /// Content sniffer for magic-byte detection (independent of the filename).
295    pub probe: Option<ProbeFn>,
296    /// What this format's muxer accepts. [`MuxCaps::NONE`] for demux-only
297    /// formats. Keep it in step with the muxer — `tests/mux_caps.rs` gates it.
298    pub mux_caps: MuxCaps,
299}
300
301impl Format {
302    pub fn can_demux(&self) -> bool {
303        self.demuxer.is_some()
304    }
305    pub fn can_mux(&self) -> bool {
306        self.muxer.is_some() || self.muxer_path.is_some()
307    }
308}
309
310/// Holds every container format known to a running engine.
311#[derive(Default)]
312pub struct FormatRegistry {
313    by_name: HashMap<&'static str, Format>,
314    /// Seek-aware demuxer factories, keyed by format name (see
315    /// [`register_seekable_demuxer`](Self::register_seekable_demuxer)).
316    seekable: HashMap<&'static str, SeekableDemuxerFactory>,
317    /// Seek-aware muxer factories, keyed by format name (see
318    /// [`register_seekable_muxer`](Self::register_seekable_muxer)).
319    seekable_muxers: HashMap<&'static str, SeekableMuxerFactory>,
320}
321
322impl FormatRegistry {
323    pub fn new() -> FormatRegistry {
324        FormatRegistry::default()
325    }
326
327    pub fn register(&mut self, format: Format) {
328        self.by_name.insert(format.name, format);
329    }
330
331    /// Give the format named `name` a demuxer that takes a [`SeekInput`]. Used
332    /// by [`open_demuxer_seekable`](Self::open_demuxer_seekable) when the caller
333    /// has a seekable source; the plain [`Format::demuxer`] still serves pipes
334    /// and sockets.
335    pub fn register_seekable_demuxer(
336        &mut self,
337        name: &'static str,
338        factory: SeekableDemuxerFactory,
339    ) {
340        self.seekable.insert(name, factory);
341    }
342
343    pub fn by_name(&self, name: &str) -> Option<&Format> {
344        self.by_name.get(name)
345    }
346
347    /// Find a format whose extension list contains `ext` (case-insensitive,
348    /// no leading dot). The cheap "guess by filename" path; [`probe`](Self::probe)
349    /// inspects content instead.
350    pub fn by_extension(&self, ext: &str) -> Option<&Format> {
351        let ext = ext.trim_start_matches('.').to_ascii_lowercase();
352        self.by_name
353            .values()
354            .find(|f| f.extensions.iter().any(|e| e.eq_ignore_ascii_case(&ext)))
355    }
356
357    /// Identify a format by sniffing a byte prefix: the registered format whose
358    /// [`probe`](Format::probe) returns the highest positive score wins. Returns
359    /// `None` if nothing recognizes the data.
360    pub fn probe(&self, data: &[u8]) -> Option<&Format> {
361        self.by_name
362            .values()
363            .filter_map(|f| f.probe.map(|p| (p(data), f)))
364            .filter(|(score, _)| *score > 0)
365            .max_by_key(|(score, _)| *score)
366            .map(|(_, f)| f)
367    }
368
369    /// Open a demuxer for the format named `name`.
370    pub fn open_demuxer(&self, name: &str, input: Input) -> Result<Box<dyn Demuxer>> {
371        self.by_name
372            .get(name)
373            .and_then(|f| f.demuxer)
374            .map(|factory| factory(input))
375            .ok_or_else(|| Error::DemuxerNotFound(name.to_string()))
376    }
377
378    /// Open a demuxer over a seekable input: the format's seek-aware demuxer if
379    /// it registered one, otherwise its plain streaming demuxer (a seekable
380    /// source is still a byte stream). Callers that hold a file should prefer
381    /// this — it is what lets MP4 read only `moov` instead of the whole file.
382    pub fn open_demuxer_seekable(&self, name: &str, input: SeekInput) -> Result<Box<dyn Demuxer>> {
383        if !self.by_name.get(name).is_some_and(Format::can_demux) {
384            return Err(Error::DemuxerNotFound(name.to_string()));
385        }
386        match self.seekable.get(name) {
387            Some(factory) => Ok(factory(input)),
388            None => self.open_demuxer(name, input),
389        }
390    }
391
392    /// Give the format named `name` a muxer that takes a [`SeekOutput`]. Used
393    /// by [`open_muxer_seekable`](Self::open_muxer_seekable) when the caller
394    /// writes to something seekable; the plain [`Format::muxer`] still serves
395    /// pipes and sockets.
396    pub fn register_seekable_muxer(&mut self, name: &'static str, factory: SeekableMuxerFactory) {
397        self.seekable_muxers.insert(name, factory);
398    }
399
400    /// Open a muxer over a seekable output: the format's seek-aware muxer if it
401    /// registered one, otherwise its plain muxer (a seekable sink is still a
402    /// byte sink). Callers writing a file should prefer this -- it is what lets
403    /// MP4/Matroska/AVI/WAV stream instead of buffering the whole output.
404    pub fn open_muxer_seekable(&self, name: &str, output: SeekOutput) -> Result<Box<dyn Muxer>> {
405        if !self.by_name.get(name).is_some_and(|f| f.muxer.is_some()) {
406            return Err(Error::MuxerNotFound(name.to_string()));
407        }
408        match self.seekable_muxers.get(name) {
409            Some(factory) => Ok(factory(output)),
410            None => self.open_muxer(name, output),
411        }
412    }
413
414    /// Open a muxer for the format named `name`.
415    pub fn open_muxer(&self, name: &str, output: Output) -> Result<Box<dyn Muxer>> {
416        self.by_name
417            .get(name)
418            .and_then(|f| f.muxer)
419            .map(|factory| factory(output))
420            .ok_or_else(|| Error::MuxerNotFound(name.to_string()))
421    }
422
423    pub fn iter(&self) -> impl Iterator<Item = &Format> {
424        self.by_name.values()
425    }
426
427    pub fn len(&self) -> usize {
428        self.by_name.len()
429    }
430
431    pub fn is_empty(&self) -> bool {
432        self.by_name.is_empty()
433    }
434}
435
436#[cfg(test)]
437mod tests {
438    use super::*;
439    use std::io::Cursor;
440
441    /// Reports which factory built it via the stream count.
442    struct Tagged(usize);
443    impl Demuxer for Tagged {
444        fn read_header(&mut self) -> Result<Vec<Stream>> {
445            Ok((0..self.0).map(|i| Stream::new(i, CodecId::None)).collect())
446        }
447        fn read_packet(&mut self) -> Result<rff_core::Packet> {
448            Err(Error::Eof)
449        }
450    }
451
452    fn format(name: &'static str) -> Format {
453        Format {
454            name,
455            long_name: name,
456            extensions: &[],
457            demuxer: Some(|_| Box::new(Tagged(1))),
458            muxer: None,
459            muxer_path: None,
460            probe: None,
461            mux_caps: MuxCaps::NONE,
462        }
463    }
464
465    fn streams(mut d: Box<dyn Demuxer>) -> usize {
466        d.read_header().unwrap().len()
467    }
468
469    #[test]
470    fn seekable_open_prefers_the_seekable_factory_and_falls_back() {
471        let mut r = FormatRegistry::new();
472        r.register(format("plain"));
473        r.register(format("seeky"));
474        r.register_seekable_demuxer("seeky", |_| Box::new(Tagged(2)));
475        let input = || -> SeekInput { Box::new(Cursor::new(vec![0u8; 4])) };
476        assert_eq!(
477            streams(r.open_demuxer_seekable("seeky", input()).unwrap()),
478            2
479        );
480        // No seekable factory: the streaming one serves the seekable input.
481        assert_eq!(
482            streams(r.open_demuxer_seekable("plain", input()).unwrap()),
483            1
484        );
485        // A plain stream open never takes the seekable path.
486        assert_eq!(
487            streams(
488                r.open_demuxer("seeky", Box::new(Cursor::new(vec![])))
489                    .unwrap()
490            ),
491            1
492        );
493        assert!(matches!(
494            r.open_demuxer_seekable("missing", input()),
495            Err(Error::DemuxerNotFound(_))
496        ));
497    }
498
499    /// Reports which factory built it through the error `write_trailer` returns.
500    struct TaggedMux(&'static str);
501    impl Muxer for TaggedMux {
502        fn write_header(&mut self, _: &[Stream]) -> Result<()> {
503            Ok(())
504        }
505        fn write_packet(&mut self, _: &rff_core::Packet) -> Result<()> {
506            Ok(())
507        }
508        fn write_trailer(&mut self) -> Result<()> {
509            Err(Error::invalid(self.0))
510        }
511    }
512
513    fn tag(mut m: Box<dyn Muxer>) -> String {
514        m.write_trailer().unwrap_err().to_string()
515    }
516
517    #[test]
518    fn seekable_muxer_open_prefers_the_seekable_factory_and_falls_back() {
519        let mut r = FormatRegistry::new();
520        let with_muxer = |name| Format {
521            muxer: Some(|_| Box::new(TaggedMux("plain"))),
522            ..format(name)
523        };
524        r.register(with_muxer("plain"));
525        r.register(with_muxer("seeky"));
526        r.register(format("demux_only"));
527        r.register_seekable_muxer("seeky", |_| Box::new(TaggedMux("seekable")));
528        let output = || -> SeekOutput { Box::new(Cursor::new(Vec::new())) };
529        assert!(tag(r.open_muxer_seekable("seeky", output()).unwrap()).contains("seekable"));
530        // No seekable factory: the plain one serves the seekable output.
531        assert!(tag(r.open_muxer_seekable("plain", output()).unwrap()).contains("plain"));
532        // A plain open never takes the seekable path.
533        assert!(tag(r.open_muxer("seeky", Box::new(Vec::new())).unwrap()).contains("plain"));
534        assert!(matches!(
535            r.open_muxer_seekable("demux_only", output()),
536            Err(Error::MuxerNotFound(_))
537        ));
538        assert!(matches!(
539            r.open_muxer_seekable("missing", output()),
540            Err(Error::MuxerNotFound(_))
541        ));
542    }
543}