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 /// G.711 A-law audio (WAV format 0x0006, AIFF-C/CAF `alaw`).
99 PcmAlaw,
100 /// G.711 µ-law audio (WAV format 0x0007, AIFF-C/CAF `ulaw`).
101 PcmMulaw,
102 /// Microsoft ADPCM (WAV format 0x0002). One block per packet.
103 AdpcmMs,
104 /// IMA/DVI ADPCM as WAV stores it (format 0x0011). One block per packet.
105 AdpcmImaWav,
106 /// IMA ADPCM as QuickTime stores it (`ima4`: 34-byte blocks of 64 samples
107 /// per channel), in AIFF-C, CAF and MOV.
108 AdpcmImaQt,
109 /// MPEG-1/2 Audio Layer II (MP2). Decode only.
110 Mp2,
111 /// MPEG-1/2 Audio Layer I (MP1). Decode only.
112 Mp1,
113 /// MPEG-1 video. Identified (Matroska `V_MPEG1`), no codec.
114 Mpeg1Video,
115 /// MPEG-2 video (H.262). Identified (Matroska `V_MPEG2`), no codec.
116 Mpeg2Video,
117 /// DTS / DTS-HD audio. Identified (Matroska `A_DTS`), no codec.
118 Dts,
119 /// Dolby TrueHD audio. Identified (Matroska `A_TRUEHD`), no codec.
120 TrueHd,
121}
122
123impl CodecId {
124 /// Short canonical name, matching the token used on the `ffmpeg` command
125 /// line (`-c:v h264`, `-c:a opus`, ...).
126 pub fn name(self) -> &'static str {
127 match self {
128 CodecId::None => "none",
129 CodecId::H264 => "h264",
130 CodecId::Hevc => "hevc",
131 CodecId::Opus => "opus",
132 CodecId::Avif => "avif",
133 CodecId::Png => "png",
134 CodecId::Jpeg => "mjpeg",
135 CodecId::Gif => "gif",
136 CodecId::Webp => "webp",
137 CodecId::Pcm => "pcm",
138 CodecId::Vorbis => "vorbis",
139 CodecId::Flac => "flac",
140 CodecId::Jxl => "jpegxl",
141 CodecId::Aac => "aac",
142 CodecId::Vp9 => "vp9",
143 CodecId::Av2 => "av2",
144 CodecId::Mp3 => "mp3",
145 CodecId::RawVideo => "rawvideo",
146 CodecId::Subrip => "subrip",
147 CodecId::WebVtt => "webvtt",
148 CodecId::ProRes => "prores",
149 CodecId::DnxHd => "dnxhd",
150 CodecId::Apv => "apv",
151 CodecId::Vp8 => "vp8",
152 CodecId::Alac => "alac",
153 CodecId::Ac3 => "ac3",
154 CodecId::Eac3 => "eac3",
155 CodecId::PcmAlaw => "pcm_alaw",
156 CodecId::PcmMulaw => "pcm_mulaw",
157 CodecId::AdpcmMs => "adpcm_ms",
158 CodecId::AdpcmImaWav => "adpcm_ima_wav",
159 CodecId::AdpcmImaQt => "adpcm_ima_qt",
160 CodecId::Mp2 => "mp2",
161 CodecId::Mp1 => "mp1",
162 CodecId::Mpeg1Video => "mpeg1video",
163 CodecId::Mpeg2Video => "mpeg2video",
164 CodecId::Dts => "dts",
165 CodecId::TrueHd => "truehd",
166 }
167 }
168
169 /// The media category this codec produces.
170 pub fn media_type(self) -> MediaType {
171 match self {
172 CodecId::None => MediaType::Data,
173 CodecId::H264 | CodecId::Hevc => MediaType::Video,
174 CodecId::Opus => MediaType::Audio,
175 // Image codecs carry pixel data; we model them as (single-frame) video.
176 CodecId::Avif => MediaType::Video,
177 CodecId::Png => MediaType::Video,
178 CodecId::Jpeg => MediaType::Video,
179 CodecId::Gif => MediaType::Video,
180 CodecId::Webp => MediaType::Video,
181 CodecId::Pcm => MediaType::Audio,
182 CodecId::Vorbis => MediaType::Audio,
183 CodecId::Flac => MediaType::Audio,
184 CodecId::Jxl => MediaType::Video,
185 CodecId::Aac => MediaType::Audio,
186 CodecId::Vp9 => MediaType::Video,
187 CodecId::Av2 => MediaType::Video,
188 CodecId::Mp3 => MediaType::Audio,
189 CodecId::RawVideo => MediaType::Video,
190 CodecId::Subrip => MediaType::Subtitle,
191 CodecId::WebVtt => MediaType::Subtitle,
192 CodecId::ProRes | CodecId::DnxHd | CodecId::Apv | CodecId::Vp8 => MediaType::Video,
193 CodecId::Alac | CodecId::Ac3 | CodecId::Eac3 => MediaType::Audio,
194 CodecId::PcmAlaw
195 | CodecId::PcmMulaw
196 | CodecId::AdpcmMs
197 | CodecId::AdpcmImaWav
198 | CodecId::AdpcmImaQt => MediaType::Audio,
199 CodecId::Mp2 | CodecId::Mp1 => MediaType::Audio,
200 CodecId::Mpeg1Video | CodecId::Mpeg2Video => MediaType::Video,
201 CodecId::Dts | CodecId::TrueHd => MediaType::Audio,
202 }
203 }
204
205 /// The sample format a codec NAME pins, when the name carries one.
206 ///
207 /// `CodecId` is deliberately format-agnostic — `pcm_s16le` and `pcm_f32le`
208 /// are both [`CodecId::Pcm`] — but for raw PCM the name IS the format, and
209 /// dropping it means `-c:a pcm_s16le` silently writes whatever the decoder
210 /// happened to emit. Compressed codecs return `None`: their sample format is
211 /// an internal detail, not something the CLI name selects.
212 pub fn sample_format_from_name(name: &str) -> Option<SampleFormat> {
213 match name {
214 "pcm_u8" => Some(SampleFormat::U8),
215 "pcm_s16le" => Some(SampleFormat::S16),
216 "pcm_s24le" => Some(SampleFormat::S24),
217 "pcm_s32le" => Some(SampleFormat::S32),
218 "pcm_f32le" => Some(SampleFormat::F32),
219 "pcm_f64le" => Some(SampleFormat::F64),
220 _ => None,
221 }
222 }
223
224 /// Look up a codec id from its canonical CLI name.
225 pub fn from_name(name: &str) -> Option<CodecId> {
226 match name {
227 "h264" | "avc" | "libx264" => Some(CodecId::H264),
228 "hevc" | "h265" | "x265" | "libx265" => Some(CodecId::Hevc),
229 "opus" | "libopus" => Some(CodecId::Opus),
230 "avif" => Some(CodecId::Avif),
231 "png" => Some(CodecId::Png),
232 "mjpeg" | "jpeg" | "jpg" => Some(CodecId::Jpeg),
233 "gif" => Some(CodecId::Gif),
234 "webp" => Some(CodecId::Webp),
235 "pcm" | "pcm_u8" | "pcm_s16le" | "pcm_s24le" | "pcm_s32le" | "pcm_f32le"
236 | "pcm_f64le" => Some(CodecId::Pcm),
237 "vorbis" => Some(CodecId::Vorbis),
238 "flac" => Some(CodecId::Flac),
239 "jpegxl" | "jxl" => Some(CodecId::Jxl),
240 "aac" => Some(CodecId::Aac),
241 "vp9" | "libvpx-vp9" => Some(CodecId::Vp9),
242 "av2" | "libavm" => Some(CodecId::Av2),
243 "mp3" | "mp3float" | "libmp3lame" => Some(CodecId::Mp3),
244 "rawvideo" | "yuv4mpegpipe" => Some(CodecId::RawVideo),
245 "srt" | "subrip" => Some(CodecId::Subrip),
246 "vtt" | "webvtt" => Some(CodecId::WebVtt),
247 "prores" | "prores_ks" => Some(CodecId::ProRes),
248 "dnxhd" | "dnxhr" => Some(CodecId::DnxHd),
249 "apv" => Some(CodecId::Apv),
250 "vp8" | "libvpx" => Some(CodecId::Vp8),
251 "alac" => Some(CodecId::Alac),
252 "ac3" => Some(CodecId::Ac3),
253 "eac3" => Some(CodecId::Eac3),
254 "pcm_alaw" | "alaw" => Some(CodecId::PcmAlaw),
255 "pcm_mulaw" | "mulaw" | "ulaw" => Some(CodecId::PcmMulaw),
256 "adpcm_ms" => Some(CodecId::AdpcmMs),
257 "adpcm_ima_wav" => Some(CodecId::AdpcmImaWav),
258 "adpcm_ima_qt" | "ima4" => Some(CodecId::AdpcmImaQt),
259 "mp2" | "mp2float" => Some(CodecId::Mp2),
260 "mp1" | "mp1float" => Some(CodecId::Mp1),
261 "mpeg1video" => Some(CodecId::Mpeg1Video),
262 "mpeg2video" | "mpeg2" => Some(CodecId::Mpeg2Video),
263 "dts" | "dca" => Some(CodecId::Dts),
264 "truehd" | "mlp" => Some(CodecId::TrueHd),
265 _ => None,
266 }
267 }
268}
269
270impl fmt::Display for CodecId {
271 fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
272 f.write_str(self.name())
273 }
274}
275
276/// Luma/chroma value range of a Y'CbCr stream.
277///
278/// This is metadata, not a conversion: it records how the samples in a plane
279/// should be interpreted, so containers can label them and consumers can avoid
280/// re-scaling data that is already in the range they want.
281///
282/// Getting it wrong is expensive and silent. Writing full-range samples into a
283/// y4m without an `XCOLORRANGE=FULL` tag makes every reader treat them as
284/// limited-range; on real content that fabricated **12 dB** of error between two
285/// byte-identical payloads (41.3 dB compared raw, 29.0 dB compared through the
286/// mislabelled container).
287#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, Default)]
288pub enum ColorRange {
289 /// Not known. Consumers apply their own default — for Y'CbCr that is
290 /// conventionally limited range, which is why leaving this unset on
291 /// full-range data is a bug rather than a neutral choice.
292 #[default]
293 Unspecified,
294 /// "TV" / MPEG range: Y 16–235, Cb/Cr 16–240.
295 Limited,
296 /// "PC" / JPEG range: all components 0–255. JPEG and PNG are always this.
297 Full,
298}
299
300impl ColorRange {
301 /// The y4m `XCOLORRANGE` tag value, or `None` when unspecified.
302 pub fn y4m_tag(self) -> Option<&'static str> {
303 match self {
304 ColorRange::Unspecified => None,
305 ColorRange::Limited => Some("LIMITED"),
306 ColorRange::Full => Some("FULL"),
307 }
308 }
309
310 /// Parse a y4m `XCOLORRANGE` value.
311 pub fn from_y4m_tag(tag: &str) -> ColorRange {
312 match tag.trim().to_ascii_uppercase().as_str() {
313 "FULL" => ColorRange::Full,
314 "LIMITED" => ColorRange::Limited,
315 _ => ColorRange::Unspecified,
316 }
317 }
318}
319
320/// Raw pixel layout of a decoded video frame. A small starter subset.
321#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
322#[non_exhaustive]
323pub enum PixelFormat {
324 /// Planar Y'CbCr 4:2:0, 8-bit (the workhorse for H.264).
325 Yuv420p,
326 /// Planar Y'CbCr 4:2:2, 8-bit.
327 Yuv422p,
328 /// Planar Y'CbCr 4:4:4, 8-bit.
329 Yuv444p,
330 /// Planar Y'CbCr 4:2:0, 10-bit (each sample stored as little-endian u16).
331 Yuv420p10,
332 /// Planar Y'CbCr 4:2:2, 10-bit (little-endian u16 samples).
333 Yuv422p10,
334 /// Planar Y'CbCr 4:4:4, 10-bit (little-endian u16 samples).
335 Yuv444p10,
336 /// Planar Y'CbCr 4:2:0, 12-bit (little-endian u16 samples).
337 Yuv420p12,
338 /// Planar Y'CbCr 4:2:2, 12-bit (little-endian u16 samples).
339 Yuv422p12,
340 /// Planar Y'CbCr 4:4:4, 12-bit (little-endian u16 samples).
341 Yuv444p12,
342 /// Packed RGB, 8 bits per channel.
343 Rgb24,
344 /// Packed RGBA, 8 bits per channel.
345 Rgba,
346}
347
348impl PixelFormat {
349 pub fn name(self) -> &'static str {
350 match self {
351 PixelFormat::Yuv420p => "yuv420p",
352 PixelFormat::Yuv422p => "yuv422p",
353 PixelFormat::Yuv444p => "yuv444p",
354 PixelFormat::Yuv420p10 => "yuv420p10le",
355 PixelFormat::Yuv422p10 => "yuv422p10le",
356 PixelFormat::Yuv444p10 => "yuv444p10le",
357 PixelFormat::Yuv420p12 => "yuv420p12le",
358 PixelFormat::Yuv422p12 => "yuv422p12le",
359 PixelFormat::Yuv444p12 => "yuv444p12le",
360 PixelFormat::Rgb24 => "rgb24",
361 PixelFormat::Rgba => "rgba",
362 }
363 }
364
365 /// Bits per component sample (8 for the 8-bit formats, 10 for the 10-bit
366 /// planar ones).
367 pub fn bit_depth(self) -> u32 {
368 match self {
369 PixelFormat::Yuv420p10 | PixelFormat::Yuv422p10 | PixelFormat::Yuv444p10 => 10,
370 PixelFormat::Yuv420p12 | PixelFormat::Yuv422p12 | PixelFormat::Yuv444p12 => 12,
371 _ => 8,
372 }
373 }
374
375 /// Bytes used to store one component sample: 1 for 8-bit, 2 for the 10-bit
376 /// formats (whose samples live in the low bits of a little-endian `u16`).
377 pub fn bytes_per_sample(self) -> usize {
378 if self.bit_depth() > 8 {
379 2
380 } else {
381 1
382 }
383 }
384}
385
386/// Raw audio sample layout. Multi-byte samples are little-endian; containers
387/// that store big-endian PCM (QuickTime `twos`, `in24`, ...) swap on the way
388/// in and out, so a buffer of a given format always means one byte order.
389#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
390#[non_exhaustive]
391pub enum SampleFormat {
392 /// Signed 16-bit, interleaved.
393 S16,
394 /// 32-bit float, interleaved.
395 F32,
396 /// 32-bit float, planar (one buffer per channel).
397 F32Planar,
398 /// Unsigned 8-bit (128 = silence), interleaved.
399 U8,
400 /// Signed 24-bit packed in 3 bytes, interleaved.
401 S24,
402 /// Signed 32-bit, interleaved.
403 S32,
404 /// 64-bit float, interleaved.
405 F64,
406}
407
408impl SampleFormat {
409 pub fn name(self) -> &'static str {
410 match self {
411 SampleFormat::S16 => "s16",
412 SampleFormat::F32 => "flt",
413 SampleFormat::F32Planar => "fltp",
414 SampleFormat::U8 => "u8",
415 SampleFormat::S24 => "s24",
416 SampleFormat::S32 => "s32",
417 SampleFormat::F64 => "dbl",
418 }
419 }
420
421 /// Bytes occupied by one sample of one channel.
422 pub fn bytes_per_sample(self) -> usize {
423 match self {
424 SampleFormat::U8 => 1,
425 SampleFormat::S16 => 2,
426 SampleFormat::S24 => 3,
427 SampleFormat::S32 | SampleFormat::F32 | SampleFormat::F32Planar => 4,
428 SampleFormat::F64 => 8,
429 }
430 }
431}