Skip to main content

rff_core/
media.rs

1//! Core media enumerations: media types, codec identifiers, and raw sample
2//! layouts (pixel formats for video, sample formats for audio).
3//!
4//! These deliberately cover only a small, growing subset of what FFmpeg
5//! supports. Add variants as new codecs land — every variant is `#[non_exhaustive]`
6//! friendly so downstream `match`es must keep a wildcard arm.
7
8use std::fmt;
9
10/// The broad category of an elementary stream.
11#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
12pub enum MediaType {
13    Video,
14    Audio,
15    Subtitle,
16    Data,
17    Attachment,
18}
19
20impl fmt::Display for MediaType {
21    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
22        let s = match self {
23            MediaType::Video => "video",
24            MediaType::Audio => "audio",
25            MediaType::Subtitle => "subtitle",
26            MediaType::Data => "data",
27            MediaType::Attachment => "attachment",
28        };
29        f.write_str(s)
30    }
31}
32
33/// Identifier for a specific codec (the *what*, independent of any particular
34/// encoder/decoder *implementation*).
35///
36/// Marked `#[non_exhaustive]`: we add codecs over time, and external matchers
37/// must handle the open-ended set.
38#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, Default)]
39#[non_exhaustive]
40pub enum CodecId {
41    /// Sentinel for "no/unknown codec".
42    #[default]
43    None,
44    /// H.264 / AVC video.
45    H264,
46    /// H.265 / HEVC video. Decode only.
47    Hevc,
48    /// Opus audio.
49    Opus,
50    /// AVIF still image (an AV1 intra frame in a HEIF box).
51    Avif,
52    /// PNG still image (DEFLATE-compressed RGB/RGBA).
53    Png,
54    /// JPEG still image (a.k.a. MJPEG).
55    Jpeg,
56    /// GIF image (first frame; palette-based).
57    Gif,
58    /// WebP image (VP8 / VP8L).
59    Webp,
60    /// Linear PCM audio (uncompressed; layout in the stream's sample format).
61    Pcm,
62    /// Vorbis audio (Ogg Vorbis).
63    Vorbis,
64    /// FLAC lossless audio.
65    Flac,
66    /// JPEG XL image.
67    Jxl,
68    /// AAC audio (Advanced Audio Coding).
69    Aac,
70    /// VP9 video.
71    Vp9,
72    /// AV2 video (AOMedia's successor to AV1). Decode only.
73    Av2,
74    /// MP3 audio (MPEG-1/2 Audio Layer III).
75    Mp3,
76    /// Raw uncompressed video (planar/packed pixels; layout in the stream's
77    /// pixel format). The video analog of [`CodecId::Pcm`].
78    RawVideo,
79    /// SubRip subtitle (`.srt`): plain-text cues with `HH:MM:SS,mmm` timing.
80    Subrip,
81    /// WebVTT subtitle (`.vtt`): plain-text cues with `HH:MM:SS.mmm` timing.
82    WebVtt,
83    /// Apple ProRes video (422 Proxy/LT/standard/HQ, 4444, 4444 XQ). Stream
84    /// copy only; the profile travels as the stream's `codec_tag`.
85    ProRes,
86    /// Avid DNxHD / DNxHR video. Stream copy only.
87    DnxHd,
88    /// APV (Advanced Professional Video). Stream copy only.
89    Apv,
90    /// VP8 video. Stream copy only.
91    Vp8,
92    /// Apple Lossless (ALAC) audio. Stream copy only.
93    Alac,
94    /// Dolby Digital (AC-3) audio. Stream copy only.
95    Ac3,
96    /// Dolby Digital Plus (E-AC-3) audio. Stream copy only.
97    Eac3,
98}
99
100impl CodecId {
101    /// Short canonical name, matching the token used on the `ffmpeg` command
102    /// line (`-c:v h264`, `-c:a opus`, ...).
103    pub fn name(self) -> &'static str {
104        match self {
105            CodecId::None => "none",
106            CodecId::H264 => "h264",
107            CodecId::Hevc => "hevc",
108            CodecId::Opus => "opus",
109            CodecId::Avif => "avif",
110            CodecId::Png => "png",
111            CodecId::Jpeg => "mjpeg",
112            CodecId::Gif => "gif",
113            CodecId::Webp => "webp",
114            CodecId::Pcm => "pcm",
115            CodecId::Vorbis => "vorbis",
116            CodecId::Flac => "flac",
117            CodecId::Jxl => "jpegxl",
118            CodecId::Aac => "aac",
119            CodecId::Vp9 => "vp9",
120            CodecId::Av2 => "av2",
121            CodecId::Mp3 => "mp3",
122            CodecId::RawVideo => "rawvideo",
123            CodecId::Subrip => "subrip",
124            CodecId::WebVtt => "webvtt",
125            CodecId::ProRes => "prores",
126            CodecId::DnxHd => "dnxhd",
127            CodecId::Apv => "apv",
128            CodecId::Vp8 => "vp8",
129            CodecId::Alac => "alac",
130            CodecId::Ac3 => "ac3",
131            CodecId::Eac3 => "eac3",
132        }
133    }
134
135    /// The media category this codec produces.
136    pub fn media_type(self) -> MediaType {
137        match self {
138            CodecId::None => MediaType::Data,
139            CodecId::H264 | CodecId::Hevc => MediaType::Video,
140            CodecId::Opus => MediaType::Audio,
141            // Image codecs carry pixel data; we model them as (single-frame) video.
142            CodecId::Avif => MediaType::Video,
143            CodecId::Png => MediaType::Video,
144            CodecId::Jpeg => MediaType::Video,
145            CodecId::Gif => MediaType::Video,
146            CodecId::Webp => MediaType::Video,
147            CodecId::Pcm => MediaType::Audio,
148            CodecId::Vorbis => MediaType::Audio,
149            CodecId::Flac => MediaType::Audio,
150            CodecId::Jxl => MediaType::Video,
151            CodecId::Aac => MediaType::Audio,
152            CodecId::Vp9 => MediaType::Video,
153            CodecId::Av2 => MediaType::Video,
154            CodecId::Mp3 => MediaType::Audio,
155            CodecId::RawVideo => MediaType::Video,
156            CodecId::Subrip => MediaType::Subtitle,
157            CodecId::WebVtt => MediaType::Subtitle,
158            CodecId::ProRes | CodecId::DnxHd | CodecId::Apv | CodecId::Vp8 => MediaType::Video,
159            CodecId::Alac | CodecId::Ac3 | CodecId::Eac3 => MediaType::Audio,
160        }
161    }
162
163    /// The sample format a codec NAME pins, when the name carries one.
164    ///
165    /// `CodecId` is deliberately format-agnostic — `pcm_s16le` and `pcm_f32le`
166    /// are both [`CodecId::Pcm`] — but for raw PCM the name IS the format, and
167    /// dropping it means `-c:a pcm_s16le` silently writes whatever the decoder
168    /// happened to emit. Compressed codecs return `None`: their sample format is
169    /// an internal detail, not something the CLI name selects.
170    pub fn sample_format_from_name(name: &str) -> Option<SampleFormat> {
171        match name {
172            "pcm_u8" => Some(SampleFormat::U8),
173            "pcm_s16le" => Some(SampleFormat::S16),
174            "pcm_s24le" => Some(SampleFormat::S24),
175            "pcm_s32le" => Some(SampleFormat::S32),
176            "pcm_f32le" => Some(SampleFormat::F32),
177            "pcm_f64le" => Some(SampleFormat::F64),
178            _ => None,
179        }
180    }
181
182    /// Look up a codec id from its canonical CLI name.
183    pub fn from_name(name: &str) -> Option<CodecId> {
184        match name {
185            "h264" | "avc" | "libx264" => Some(CodecId::H264),
186            "hevc" | "h265" | "x265" | "libx265" => Some(CodecId::Hevc),
187            "opus" | "libopus" => Some(CodecId::Opus),
188            "avif" => Some(CodecId::Avif),
189            "png" => Some(CodecId::Png),
190            "mjpeg" | "jpeg" | "jpg" => Some(CodecId::Jpeg),
191            "gif" => Some(CodecId::Gif),
192            "webp" => Some(CodecId::Webp),
193            "pcm" | "pcm_u8" | "pcm_s16le" | "pcm_s24le" | "pcm_s32le" | "pcm_f32le"
194            | "pcm_f64le" => Some(CodecId::Pcm),
195            "vorbis" => Some(CodecId::Vorbis),
196            "flac" => Some(CodecId::Flac),
197            "jpegxl" | "jxl" => Some(CodecId::Jxl),
198            "aac" => Some(CodecId::Aac),
199            "vp9" | "libvpx-vp9" => Some(CodecId::Vp9),
200            "av2" | "libavm" => Some(CodecId::Av2),
201            "mp3" | "mp3float" | "libmp3lame" => Some(CodecId::Mp3),
202            "rawvideo" | "yuv4mpegpipe" => Some(CodecId::RawVideo),
203            "srt" | "subrip" => Some(CodecId::Subrip),
204            "vtt" | "webvtt" => Some(CodecId::WebVtt),
205            "prores" | "prores_ks" => Some(CodecId::ProRes),
206            "dnxhd" | "dnxhr" => Some(CodecId::DnxHd),
207            "apv" => Some(CodecId::Apv),
208            "vp8" | "libvpx" => Some(CodecId::Vp8),
209            "alac" => Some(CodecId::Alac),
210            "ac3" => Some(CodecId::Ac3),
211            "eac3" => Some(CodecId::Eac3),
212            _ => None,
213        }
214    }
215}
216
217impl fmt::Display for CodecId {
218    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
219        f.write_str(self.name())
220    }
221}
222
223/// Luma/chroma value range of a Y'CbCr stream.
224///
225/// This is metadata, not a conversion: it records how the samples in a plane
226/// should be interpreted, so containers can label them and consumers can avoid
227/// re-scaling data that is already in the range they want.
228///
229/// Getting it wrong is expensive and silent. Writing full-range samples into a
230/// y4m without an `XCOLORRANGE=FULL` tag makes every reader treat them as
231/// limited-range; on real content that fabricated **12 dB** of error between two
232/// byte-identical payloads (41.3 dB compared raw, 29.0 dB compared through the
233/// mislabelled container).
234#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, Default)]
235pub enum ColorRange {
236    /// Not known. Consumers apply their own default — for Y'CbCr that is
237    /// conventionally limited range, which is why leaving this unset on
238    /// full-range data is a bug rather than a neutral choice.
239    #[default]
240    Unspecified,
241    /// "TV" / MPEG range: Y 16–235, Cb/Cr 16–240.
242    Limited,
243    /// "PC" / JPEG range: all components 0–255. JPEG and PNG are always this.
244    Full,
245}
246
247impl ColorRange {
248    /// The y4m `XCOLORRANGE` tag value, or `None` when unspecified.
249    pub fn y4m_tag(self) -> Option<&'static str> {
250        match self {
251            ColorRange::Unspecified => None,
252            ColorRange::Limited => Some("LIMITED"),
253            ColorRange::Full => Some("FULL"),
254        }
255    }
256
257    /// Parse a y4m `XCOLORRANGE` value.
258    pub fn from_y4m_tag(tag: &str) -> ColorRange {
259        match tag.trim().to_ascii_uppercase().as_str() {
260            "FULL" => ColorRange::Full,
261            "LIMITED" => ColorRange::Limited,
262            _ => ColorRange::Unspecified,
263        }
264    }
265}
266
267/// Raw pixel layout of a decoded video frame. A small starter subset.
268#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
269#[non_exhaustive]
270pub enum PixelFormat {
271    /// Planar Y'CbCr 4:2:0, 8-bit (the workhorse for H.264).
272    Yuv420p,
273    /// Planar Y'CbCr 4:2:2, 8-bit.
274    Yuv422p,
275    /// Planar Y'CbCr 4:4:4, 8-bit.
276    Yuv444p,
277    /// Planar Y'CbCr 4:2:0, 10-bit (each sample stored as little-endian u16).
278    Yuv420p10,
279    /// Planar Y'CbCr 4:2:2, 10-bit (little-endian u16 samples).
280    Yuv422p10,
281    /// Planar Y'CbCr 4:4:4, 10-bit (little-endian u16 samples).
282    Yuv444p10,
283    /// Planar Y'CbCr 4:2:0, 12-bit (little-endian u16 samples).
284    Yuv420p12,
285    /// Planar Y'CbCr 4:2:2, 12-bit (little-endian u16 samples).
286    Yuv422p12,
287    /// Planar Y'CbCr 4:4:4, 12-bit (little-endian u16 samples).
288    Yuv444p12,
289    /// Packed RGB, 8 bits per channel.
290    Rgb24,
291    /// Packed RGBA, 8 bits per channel.
292    Rgba,
293}
294
295impl PixelFormat {
296    pub fn name(self) -> &'static str {
297        match self {
298            PixelFormat::Yuv420p => "yuv420p",
299            PixelFormat::Yuv422p => "yuv422p",
300            PixelFormat::Yuv444p => "yuv444p",
301            PixelFormat::Yuv420p10 => "yuv420p10le",
302            PixelFormat::Yuv422p10 => "yuv422p10le",
303            PixelFormat::Yuv444p10 => "yuv444p10le",
304            PixelFormat::Yuv420p12 => "yuv420p12le",
305            PixelFormat::Yuv422p12 => "yuv422p12le",
306            PixelFormat::Yuv444p12 => "yuv444p12le",
307            PixelFormat::Rgb24 => "rgb24",
308            PixelFormat::Rgba => "rgba",
309        }
310    }
311
312    /// Bits per component sample (8 for the 8-bit formats, 10 for the 10-bit
313    /// planar ones).
314    pub fn bit_depth(self) -> u32 {
315        match self {
316            PixelFormat::Yuv420p10 | PixelFormat::Yuv422p10 | PixelFormat::Yuv444p10 => 10,
317            PixelFormat::Yuv420p12 | PixelFormat::Yuv422p12 | PixelFormat::Yuv444p12 => 12,
318            _ => 8,
319        }
320    }
321
322    /// Bytes used to store one component sample: 1 for 8-bit, 2 for the 10-bit
323    /// formats (whose samples live in the low bits of a little-endian `u16`).
324    pub fn bytes_per_sample(self) -> usize {
325        if self.bit_depth() > 8 {
326            2
327        } else {
328            1
329        }
330    }
331}
332
333/// Raw audio sample layout. Multi-byte samples are little-endian; containers
334/// that store big-endian PCM (QuickTime `twos`, `in24`, ...) swap on the way
335/// in and out, so a buffer of a given format always means one byte order.
336#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
337#[non_exhaustive]
338pub enum SampleFormat {
339    /// Signed 16-bit, interleaved.
340    S16,
341    /// 32-bit float, interleaved.
342    F32,
343    /// 32-bit float, planar (one buffer per channel).
344    F32Planar,
345    /// Unsigned 8-bit (128 = silence), interleaved.
346    U8,
347    /// Signed 24-bit packed in 3 bytes, interleaved.
348    S24,
349    /// Signed 32-bit, interleaved.
350    S32,
351    /// 64-bit float, interleaved.
352    F64,
353}
354
355impl SampleFormat {
356    pub fn name(self) -> &'static str {
357        match self {
358            SampleFormat::S16 => "s16",
359            SampleFormat::F32 => "flt",
360            SampleFormat::F32Planar => "fltp",
361            SampleFormat::U8 => "u8",
362            SampleFormat::S24 => "s24",
363            SampleFormat::S32 => "s32",
364            SampleFormat::F64 => "dbl",
365        }
366    }
367
368    /// Bytes occupied by one sample of one channel.
369    pub fn bytes_per_sample(self) -> usize {
370        match self {
371            SampleFormat::U8 => 1,
372            SampleFormat::S16 => 2,
373            SampleFormat::S24 => 3,
374            SampleFormat::S32 | SampleFormat::F32 | SampleFormat::F32Planar => 4,
375            SampleFormat::F64 => 8,
376        }
377    }
378}