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}