Skip to main content

y4m_codec/
decode.rs

1//! Streaming decoder over any [`Read`].
2
3use std::io::{BufReader, Read};
4
5use crate::colorspace::Colorspace;
6use crate::{Error, Interlace, Ratio};
7
8/// Whole header line budget in bytes, including magic and the terminating LF.
9/// Applies to the stream header and to every frame header.
10pub(crate) const MAX_HEADER_LINE: usize = 4096;
11
12const STREAM_MAGIC: &[u8; 10] = b"YUV4MPEG2 ";
13const FRAME_MAGIC: &[u8; 5] = b"FRAME";
14
15/// Resource budgets enforced by the decoder before allocating.
16#[derive(Debug, Clone, Copy, PartialEq, Eq)]
17pub struct Limits {
18    /// Upper bound on the decoder's total peak frame-buffer memory in
19    /// bytes: the wire-byte buffer holding one frame's plane data plus,
20    /// for streams deeper than 8 bits, the equally sized host-order `u16`
21    /// sample buffer. Exceeding it is [`Error::Limits`], checked before
22    /// either buffer is allocated. Default: 1 GiB.
23    pub max_frame_bytes: usize,
24}
25
26impl Default for Limits {
27    fn default() -> Self {
28        Limits {
29            max_frame_bytes: 1 << 30,
30        }
31    }
32}
33
34/// Stream header fields parsed from raw parameter bytes.
35pub(crate) struct StreamParams {
36    pub width: usize,
37    pub height: usize,
38    /// `None` when the `F` tag is absent. Readers default to 25:1 without
39    /// re-emitting the tag.
40    pub framerate: Option<Ratio>,
41    /// `Ratio { num: 0, den: 0 }` means unknown.
42    pub pixel_aspect: Ratio,
43    pub interlace: Interlace,
44    pub colorspace: Colorspace,
45}
46
47/// Parses a decimal unsigned integer: ASCII digits only, no sign, leading
48/// zeros tolerated. A value that does not fit `u64` is a parse error.
49fn parse_uint(bytes: &[u8]) -> Result<u64, Error> {
50    if bytes.is_empty() {
51        return Err(Error::Parse("empty integer value"));
52    }
53    let mut value: u64 = 0;
54    for &b in bytes {
55        if !b.is_ascii_digit() {
56            return Err(Error::Parse("non-digit in integer value"));
57        }
58        value = value
59            .checked_mul(10)
60            .and_then(|v| v.checked_add(u64::from(b - b'0')))
61            .ok_or(Error::Parse("integer value too large"))?;
62    }
63    Ok(value)
64}
65
66/// Parses `num:den` into a [`Ratio`]. `zero_den_ok` admits the `A0:0`
67/// unknown-aspect sentinel. Otherwise `den` must be positive.
68fn parse_ratio(bytes: &[u8], zero_den_ok: bool) -> Result<Ratio, Error> {
69    let colon = bytes
70        .iter()
71        .position(|&b| b == b':')
72        .ok_or(Error::Parse("ratio value missing ':'"))?;
73    let num = parse_uint(&bytes[..colon])?;
74    let den = parse_uint(&bytes[colon + 1..])?;
75    let num = u32::try_from(num).map_err(|_| Error::Parse("ratio numerator too large"))?;
76    let den = u32::try_from(den).map_err(|_| Error::Parse("ratio denominator too large"))?;
77    if den == 0 && !(zero_den_ok && num == 0) {
78        return Err(Error::Parse("ratio denominator is zero"));
79    }
80    Ok(Ratio { num, den })
81}
82
83/// Bytes that can never appear inside a header parameter: the line
84/// terminator, CR (an illegal byte per the format contract), and NUL.
85/// SP is excluded separately since it is the parameter separator.
86pub(crate) fn is_forbidden_param_byte(b: u8) -> bool {
87    matches!(b, b'\n' | b'\r' | 0)
88}
89
90/// Checks a SP-separated parameter list (stream header bytes after the
91/// magic, or frame header bytes after `"FRAME "`) against the grammar
92/// `parameter := tag-char value`, SP-separated, with at least one parameter:
93///
94/// - no empty parameter (no leading, trailing, or doubled SP)
95/// - the tag is a single ASCII letter
96/// - the value is at least one byte, so a parameter is two bytes or more
97/// - no LF, CR, or NUL byte anywhere.
98///
99/// Both the decoder and the writer apply this grammar, so every accepted
100/// input is re-encodable and every writer-supplied parameter list is a
101/// well-formed single line.
102pub(crate) fn validate_param_list(raw: &[u8]) -> Result<(), Error> {
103    if raw.is_empty() {
104        return Err(Error::Parse("empty header parameter"));
105    }
106    for param in raw.split(|&b| b == b' ') {
107        let (tag, value) = match param.split_first() {
108            Some(pair) => pair,
109            None => return Err(Error::Parse("empty header parameter")),
110        };
111        if !tag.is_ascii_alphabetic() {
112            return Err(Error::Parse("parameter tag is not an ASCII letter"));
113        }
114        if value.is_empty() {
115            return Err(Error::Parse("parameter has no value"));
116        }
117        if value.iter().copied().any(is_forbidden_param_byte) {
118            return Err(Error::Parse("LF, CR, or NUL byte inside a parameter"));
119        }
120    }
121    Ok(())
122}
123
124/// Parses the stream header parameter bytes (everything after `"YUV4MPEG2 "`,
125/// LF excluded). Duplicate tags: last one wins. Unknown tag letters are
126/// tolerated and survive round-trips through the raw parameter bytes.
127pub(crate) fn parse_stream_params(raw: &[u8]) -> Result<StreamParams, Error> {
128    validate_param_list(raw)?;
129
130    let mut width: Option<usize> = None;
131    let mut height: Option<usize> = None;
132    let mut framerate: Option<Ratio> = None;
133    let mut pixel_aspect = Ratio { num: 0, den: 0 };
134    let mut interlace = Interlace::Unknown;
135    let mut colorspace: Option<Colorspace> = None;
136
137    for param in raw.split(|&b| b == b' ') {
138        let (tag, value) = match param.split_first() {
139            Some(pair) => pair,
140            None => return Err(Error::Parse("empty header parameter")),
141        };
142        match tag {
143            b'W' => {
144                let w = parse_uint(value)?;
145                if w == 0 {
146                    return Err(Error::Parse("width must be positive"));
147                }
148                width = Some(usize::try_from(w).map_err(|_| Error::Limits)?);
149            }
150            b'H' => {
151                let h = parse_uint(value)?;
152                if h == 0 {
153                    return Err(Error::Parse("height must be positive"));
154                }
155                height = Some(usize::try_from(h).map_err(|_| Error::Limits)?);
156            }
157            b'F' => framerate = Some(parse_ratio(value, false)?),
158            b'A' => pixel_aspect = parse_ratio(value, true)?,
159            b'I' => {
160                interlace = match value {
161                    b"p" => Interlace::Progressive,
162                    b"t" => Interlace::TopFirst,
163                    b"b" => Interlace::BottomFirst,
164                    b"m" => Interlace::Mixed,
165                    b"?" => Interlace::Unknown,
166                    _ => return Err(Error::Parse("invalid interlace value")),
167                };
168            }
169            b'C' => colorspace = Some(Colorspace::from_tag_bytes(value)?),
170            _ => {
171                // `X` vendor extensions are carried, not interpreted. Unknown
172                // tag letters are tolerated for forward compatibility. Both
173                // survive verbatim in the raw parameter bytes.
174            }
175        }
176    }
177
178    Ok(StreamParams {
179        width: width.ok_or(Error::Parse("missing W tag"))?,
180        height: height.ok_or(Error::Parse("missing H tag"))?,
181        framerate,
182        pixel_aspect,
183        interlace,
184        colorspace: colorspace.unwrap_or(Colorspace::C420),
185    })
186}
187
188fn read_byte<R: Read>(r: &mut R) -> Result<Option<u8>, Error> {
189    let mut byte = [0u8; 1];
190    loop {
191        match r.read(&mut byte) {
192            Ok(0) => return Ok(None),
193            Ok(_) => return Ok(Some(byte[0])),
194            Err(e) if e.kind() == std::io::ErrorKind::Interrupted => continue,
195            Err(e) => return Err(Error::Io(e)),
196        }
197    }
198}
199
200/// A streaming YUV4MPEG2 decoder.
201///
202/// Owns one reusable frame buffer sized at header parse time.
203/// [`Decoder::read_frame`] fills it and returns borrowed plane slices.
204pub struct Decoder<R: Read> {
205    inner: BufReader<R>,
206    params: StreamParams,
207    raw_params: Vec<u8>,
208    plane_sizes: [usize; 3],
209    frame_total: usize,
210    /// Wire bytes of the current frame's planes.
211    buf: Vec<u8>,
212    /// Host-order samples of the current frame, empty for 8-bit streams.
213    samples: Vec<u16>,
214    /// Current frame header bytes after `FRAME`, LF excluded, leading SP
215    /// included. Capacity is reserved once and bounded by the line budget.
216    frame_params: Vec<u8>,
217}
218
219impl<R: Read> Decoder<R> {
220    /// Reads and parses the stream header with the default [`Limits`].
221    pub fn new(reader: R) -> Result<Self, Error> {
222        Decoder::with_limits(reader, Limits::default())
223    }
224
225    /// Reads and parses the stream header, enforcing `limits` before the
226    /// frame buffer is allocated.
227    ///
228    /// EOF while reading the stream header is [`Error::EndOfStream`]. A
229    /// wrong magic or malformed parameter is [`Error::Parse`].
230    pub fn with_limits(reader: R, limits: Limits) -> Result<Self, Error> {
231        let mut inner = BufReader::new(reader);
232
233        let mut magic = [0u8; 10];
234        let mut filled = 0;
235        while filled < magic.len() {
236            match read_byte(&mut inner)? {
237                Some(b) => {
238                    magic[filled] = b;
239                    filled += 1;
240                }
241                None => return Err(Error::EndOfStream),
242            }
243        }
244        if &magic != STREAM_MAGIC {
245            return Err(Error::Parse("bad stream magic"));
246        }
247
248        let mut raw_params = Vec::with_capacity(64);
249        loop {
250            match read_byte(&mut inner)? {
251                Some(b'\n') => break,
252                Some(b) => {
253                    // magic (10) + params + LF (1) must fit the line budget.
254                    if STREAM_MAGIC.len() + raw_params.len() + 1 >= MAX_HEADER_LINE {
255                        return Err(Error::Limits);
256                    }
257                    raw_params.push(b);
258                }
259                None => return Err(Error::EndOfStream),
260            }
261        }
262
263        let params = parse_stream_params(&raw_params)?;
264        let plane_sizes = params.colorspace.plane_sizes(params.width, params.height)?;
265        let frame_total = plane_sizes
266            .iter()
267            .try_fold(0usize, |acc, &s| acc.checked_add(s))
268            .ok_or(Error::Limits)?;
269        // Peak frame memory: the wire-byte buffer plus, for >8-bit
270        // streams, the u16 sample buffer of the same byte size. The
271        // budget bounds that total, checked before either allocation.
272        let peak_bytes = if params.colorspace.bytes_per_sample() == 2 {
273            frame_total.checked_mul(2).ok_or(Error::Limits)?
274        } else {
275            frame_total
276        };
277        if peak_bytes > limits.max_frame_bytes {
278            return Err(Error::Limits);
279        }
280
281        let samples = if params.colorspace.bytes_per_sample() == 2 {
282            vec![0u16; frame_total / 2]
283        } else {
284            Vec::new()
285        };
286
287        Ok(Decoder {
288            inner,
289            params,
290            raw_params,
291            plane_sizes,
292            frame_total,
293            buf: vec![0u8; frame_total],
294            samples,
295            frame_params: Vec::with_capacity(MAX_HEADER_LINE),
296        })
297    }
298
299    /// Frame width in luma samples.
300    pub fn width(&self) -> usize {
301        self.params.width
302    }
303
304    /// Frame height in luma samples.
305    pub fn height(&self) -> usize {
306        self.params.height
307    }
308
309    /// Frame rate. Defaults to 25:1 when the `F` tag is absent. The default
310    /// stays out of [`Decoder::raw_params`].
311    pub fn framerate(&self) -> Ratio {
312        self.params.framerate.unwrap_or(Ratio { num: 25, den: 1 })
313    }
314
315    /// Pixel (sample) aspect ratio, where `0:0` means unknown.
316    pub fn pixel_aspect(&self) -> Ratio {
317        self.params.pixel_aspect
318    }
319
320    /// Interlacing mode, [`Interlace::Unknown`] when the `I` tag is absent.
321    pub fn interlace(&self) -> Interlace {
322        self.params.interlace
323    }
324
325    /// The stream colorspace, plain 4:2:0 8-bit when the `C` tag is absent.
326    pub fn colorspace(&self) -> Colorspace {
327        self.params.colorspace
328    }
329
330    /// Stream header parameter bytes after the `"YUV4MPEG2 "` prefix,
331    /// verbatim, LF excluded. Feed to
332    /// [`EncoderBuilder::raw_params`](crate::EncoderBuilder::raw_params) for
333    /// a byte-exact re-encode.
334    pub fn raw_params(&self) -> &[u8] {
335        &self.raw_params
336    }
337
338    /// Per-plane byte sizes `[Y, U, V]`. Chroma entries are 0 for mono.
339    pub fn plane_sizes(&self) -> [usize; 3] {
340        self.plane_sizes
341    }
342
343    /// Borrows the next frame. Planes point into the decoder's reusable
344    /// internal buffer, so each call reuses the same storage. The
345    /// counting-allocator test `tests/zero_alloc.rs` pins the decode loop
346    /// at zero heap allocations.
347    ///
348    /// Returns [`Error::EndOfStream`] at a clean end (EOF exactly where the
349    /// next `FRAME` magic would start) and [`Error::Truncated`] when EOF
350    /// falls inside a frame header or payload.
351    pub fn read_frame(&mut self) -> Result<FrameRef<'_>, Error> {
352        // Frame magic, detecting clean EOF on the first byte only.
353        match read_byte(&mut self.inner)? {
354            None => return Err(Error::EndOfStream),
355            Some(b) if b == FRAME_MAGIC[0] => {}
356            Some(_) => return Err(Error::Parse("bad frame magic")),
357        }
358        for &expected in &FRAME_MAGIC[1..] {
359            match read_byte(&mut self.inner)? {
360                None => return Err(Error::Truncated),
361                Some(b) if b == expected => {}
362                Some(_) => return Err(Error::Parse("bad frame magic")),
363            }
364        }
365
366        self.frame_params.clear();
367        loop {
368            match read_byte(&mut self.inner)? {
369                Some(b'\n') => break,
370                Some(b) => {
371                    if FRAME_MAGIC.len() + self.frame_params.len() + 1 >= MAX_HEADER_LINE {
372                        return Err(Error::Limits);
373                    }
374                    self.frame_params.push(b);
375                }
376                None => return Err(Error::Truncated),
377            }
378        }
379        // Grammar: "FRAME" *( SP parameter ) LF. A SP must be followed by a
380        // parameter, so "FRAME \n" is malformed rather than a bare header.
381        if !self.frame_params.is_empty() {
382            if self.frame_params[0] != b' ' {
383                return Err(Error::Parse("frame parameters must follow a space"));
384            }
385            validate_param_list(&self.frame_params[1..])?;
386        }
387
388        // Payload: `From<io::Error>` maps UnexpectedEof to Truncated.
389        self.inner.read_exact(&mut self.buf)?;
390
391        if !self.samples.is_empty() {
392            for (sample, wire) in self.samples.iter_mut().zip(self.buf.chunks_exact(2)) {
393                *sample = u16::from_le_bytes([wire[0], wire[1]]);
394            }
395        }
396
397        let (y, rest) = self.buf.split_at(self.plane_sizes[0]);
398        let (u, v) = rest.split_at(self.plane_sizes[1]);
399        let (planes16, hi_depth) = if self.samples.is_empty() {
400            ([&[] as &[u16]; 3], false)
401        } else {
402            let (y16, rest16) = self.samples.split_at(self.plane_sizes[0] / 2);
403            let (u16p, v16) = rest16.split_at(self.plane_sizes[1] / 2);
404            ([y16, u16p, v16], true)
405        };
406        let raw_params = if self.frame_params.is_empty() {
407            &[]
408        } else {
409            &self.frame_params[1..]
410        };
411
412        Ok(FrameRef {
413            planes: [y, u, v],
414            planes16,
415            hi_depth,
416            raw_params,
417        })
418    }
419
420    /// The frame byte count implied by the header (sum of plane sizes).
421    pub fn frame_bytes(&self) -> usize {
422        self.frame_total
423    }
424}
425
426impl<R: Read> std::fmt::Debug for Decoder<R> {
427    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
428        f.debug_struct("Decoder")
429            .field("width", &self.params.width)
430            .field("height", &self.params.height)
431            .field("colorspace", &self.params.colorspace)
432            .finish_non_exhaustive()
433    }
434}
435
436/// A borrowed view of one decoded frame.
437///
438/// Lives as long as the borrow of the decoder that produced it, so one
439/// frame is live at a time. Copy explicitly to retain a frame.
440#[derive(Debug, Clone, Copy)]
441pub struct FrameRef<'a> {
442    planes: [&'a [u8]; 3],
443    planes16: [&'a [u16]; 3],
444    hi_depth: bool,
445    raw_params: &'a [u8],
446}
447
448impl<'a> FrameRef<'a> {
449    /// Plane `i` as wire-format bytes (Y=0, U=1, V=2, empty chroma for
450    /// mono). For >8-bit streams these are the little-endian wire bytes.
451    ///
452    /// # Panics
453    ///
454    /// Panics if `i > 2`.
455    pub fn plane(&self, i: usize) -> &'a [u8] {
456        self.planes[i]
457    }
458
459    /// The Y (luma) plane.
460    pub fn y(&self) -> &'a [u8] {
461        self.planes[0]
462    }
463
464    /// The U (Cb) plane, empty for mono streams.
465    pub fn u(&self) -> &'a [u8] {
466        self.planes[1]
467    }
468
469    /// The V (Cr) plane, empty for mono streams.
470    pub fn v(&self) -> &'a [u8] {
471        self.planes[2]
472    }
473
474    /// Plane `i` as host-order `u16` samples for >8-bit streams, or `None`
475    /// when the bit depth is 8 or less.
476    ///
477    /// # Panics
478    ///
479    /// Panics if `i > 2`.
480    pub fn plane_u16(&self, i: usize) -> Option<&'a [u16]> {
481        if self.hi_depth {
482            Some(self.planes16[i])
483        } else {
484            None
485        }
486    }
487
488    /// Frame header parameter bytes verbatim (the bytes after `"FRAME "`,
489    /// LF excluded), empty when the frame header was bare. Feed to
490    /// [`Encoder::write_frame_with_params`](crate::Encoder::write_frame_with_params)
491    /// for a byte-exact re-encode.
492    pub fn raw_params(&self) -> &'a [u8] {
493        self.raw_params
494    }
495}