Expand description
Streaming reader and writer for the YUV4MPEG2 (.y4m) uncompressed
planar video format.
The decoder works over any std::io::Read and the encoder over any
std::io::Write. Design points:
- Borrowed frames.
Decoder::read_framereturns aFrameRefborrowing one reusable internal buffer, so the decode and encode hot paths reuse the same storage for every frame. The counting-allocator testtests/zero_alloc.rspins both loops at zero heap allocations. - Defined endianness. Samples deeper than 8 bits are little-endian on
the wire on every host.
FrameRef::plane_u16yields host-order samples, andEncoder::write_frame_u16converts host-order samples to little-endian wire bytes. - Byte-exact round-trips. Raw header and frame parameter bytes are preserved verbatim, so decode followed by re-encode reproduces the input byte-for-byte.
- Typed errors. Malformed, truncated, or over-budget input yields a
matching
Errorvariant, and all size arithmetic is checked.
§Reading
use y4m_codec::{Decoder, Error};
let data: &[u8] = b"YUV4MPEG2 W2 H2 F25:1 C420\nFRAME\n\x00\x01\x02\x03\x80\x80";
let mut decoder = Decoder::new(data)?;
assert_eq!((decoder.width(), decoder.height()), (2, 2));
let frame = decoder.read_frame()?;
assert_eq!(frame.y(), &[0x00, 0x01, 0x02, 0x03]);
assert!(matches!(decoder.read_frame(), Err(Error::EndOfStream)));§Writing
use y4m_codec::{EncoderBuilder, Ratio};
let mut out = Vec::new();
let mut encoder = EncoderBuilder::new(2, 2, Ratio::new(25, 1)).write_header(&mut out)?;
encoder.write_frame([&[0, 1, 2, 3], &[0x80], &[0x80]])?;
assert!(out.starts_with(b"YUV4MPEG2 W2 H2 F25:1 C420\nFRAME\n"));Structs§
- Colorspace
- A recognized colorspace: subsampling family, chroma siting, and bit depth.
- Decoder
- A streaming YUV4MPEG2 decoder.
- Encoder
- Writes frames for one stream. Produced by
EncoderBuilder::write_header. - Encoder
Builder - Builds a stream header and produces an
Encoder. - Frame
Ref - A borrowed view of one decoded frame.
- Limits
- Resource budgets enforced by the decoder before allocating.
- Ratio
- An exact rational value, used for the
F(framerate) andA(pixel aspect) header tags.0:0is the unknown-aspect sentinel.
Enums§
- Chroma
Siting - Chroma sample siting carried by the 8-bit 4:2:0 tag variants.
- Error
- Errors reported by the decoder and encoder.
- Interlace
- Interlacing mode from the stream header
Itag. - Subsampling
- Chroma subsampling family of a colorspace tag.