Skip to main content

Crate y4m_codec

Crate y4m_codec 

Source
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_frame returns a FrameRef borrowing one reusable internal buffer, so the decode and encode hot paths reuse the same storage for every frame. The counting-allocator test tests/zero_alloc.rs pins both loops at zero heap allocations.
  • Defined endianness. Samples deeper than 8 bits are little-endian on the wire on every host. FrameRef::plane_u16 yields host-order samples, and Encoder::write_frame_u16 converts 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 Error variant, 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.
EncoderBuilder
Builds a stream header and produces an Encoder.
FrameRef
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) and A (pixel aspect) header tags. 0:0 is the unknown-aspect sentinel.

Enums§

ChromaSiting
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 I tag.
Subsampling
Chroma subsampling family of a colorspace tag.