yuv4mpeg(5)

✨ YUV4MPEG2 — the video stream format bestie 💖

okay so welcome to yuv4mpeg(5), the manual page for YUV4MPEG2, the video stream format that all the pipe-based MJPEGtools use. pull up a chair, grab a strawberry 🍓, we're gonna get into it.

---

🌸 DESCRIPTION 🌸

so like, a whole bunch of the MJPEGtools talk to each other through pipes and act as filters (or sources, or sinks, no judgment). the format of the video data flowing through those pipes is called "YUV4MPEG", or, to be precise about it, "YUV4MPEG2". (the format got extended and codified during v1.5.x of the tools, iykyk.)

the basic structure is literally just a stream header followed by an unlimited number of frames. and each frame is itself a header plus video data. the headers are vaguely human-readable ASCII, but the video data is straight up simple byte-size binary. no cap.

the MJPEGtools distribution ships a C library (libmjpegutils) that has functions for manipulating YUV4MPEG2 streams. we highly recommend you use this library instead of writing your own code if you possibly can. the header file yuv4mpeg.h describes all those functions. 🫶

🎀 Design Goals

• Easy to parse both via C or sh.
• Extensible; easy to add new parameters while maintaining backwards compatibility.
• Simple upgrade from original "YUV4MPEG" format.

💀 Drawbacks

• Frame headers do not have constant size, so streams are not seekable.

yes bestie that last one is a real one. no seeking. the frames are giving "mystery length" energy and that's just how it is.

---

🦋 GRAMMAR 🦋

the precise description of the YUV4MPEG2 stream format is as follows:

STREAM consists of

• one STREAM-HEADER
• unlimited number of FRAMEs

STREAM-HEADER consists of

• magic string "YUV4MPEG2"
• unlimited number of TAGGED-FIELDs, each preceeded by a ' ' (single space) separator
• single '\n' line terminator

FRAME consists of

• one FRAME-HEADER
• "length" octets of planar YCbCr 4:2:0 image data (If the stream is interlaced, then the two fields per frame are interleaved, with proper spatial ordering.)

FRAME-HEADER consists of

• magic string "FRAME"
• unlimited number of TAGGED-FIELDs, each preceeded by a ' ' (single space) separator
• single '\n' line terminator

TAGGED-FIELD consists of

• single ASCII character tag
• VALUE (which does not contain whitespace)

VALUE consists of

• RATIO, or
• integer (base 10 ASCII representation), or
• single ascii character, or
• string (multiple ASCII characters)

RATIO consists of

• numerator (base 10 ASCII integer)
• ':' (a colon)
• denominator (base 10 ASCII integer)

---

header tags fall into three categories: optional, required and has-default. optional tags are completely optional and may be omitted from a header. required tags must be present in a header. has-default tags have a default value which is implied if the tag is not present. and independent of these categories, some tags allow an "unknown" value and some do not. the way that's a whole taxonomy 😭

👑 the supported tags for the STREAM-HEADER

• W[integer] — frame width in pixels, must be > 0 (required)
• H[integer] — frame height in pixels, must be > 0 (required)
• C[string] — chroma subsampling, image data format (has default)
  • 420jpeg — 4:2:0 with JPEG/MPEG-1 siting (default)
  • 420mpeg2 — 4:2:0 with MPEG-2 siting
  • 420paldv — 4:2:0 with PAL-DV siting
  • 411 — 4:1:1, cosited
  • 422 — 4:2:2, cosited
  • 444 — 4:4:4 (no subsampling)
  • 444alpha — 4:4:4 with an alpha channel
  • mono — luma (Y') plane only
• I[char] — interlacing specification: (has default)
  • ? — unknown (default)
  • p — progressive/none
  • t — top-field-first
  • b — bottom-field-first
  • m — mixed-mode: refer to 'I' tag in frame header
• F[ratio] — frame-rate (has default of 0:0 == unknown)
• A[ratio] — sample aspect ratio (has default of 0:0 == unknown)
• X[string] — 'metadata' (optional; unparsed, but passed around)

💅 the currently supported tags for the FRAME-HEADER

• I[string] — framing and sampling (required if-and-only-if Im is present in stream header). Value is a string of three characters "xyz" which have the following meanings:
  • x: frame presentation
    • t — top-field-first
    • T — top-field-first and repeat
    • b — bottom-field-first
    • B — bottom-field-first and repeat
    • 1 — single progressive frame
    • 2 — double progressive frame (repeat)
    • 3 — triple progressive frame (repeat)
  • y: frame temporal sampling
    • p — progressive (fields sampled at same time)
    • i — interlaced (fields sampled at different times)
  • z: frame chroma-subsampling
    • p — progressive (subsampling over whole frame)
    • i — interlaced (each field subsampled independently)
    • ? — unknown (allowed only for non-4:2:0 subsampling)
• X[string] — 'metadata' (optional; unparsed, but passed around)

ok important one bestie: a filter application must faithfully forward all "X" tags from input pipe to output pipe (unless it uses one of those tags, of course). the supplied library will do this automatically if the functions y4m_copy_stream_info() and y4m_copy_frame_info() are used appropriately. don't be the filter that drops the metadata. that's not the vibe. 🚫

---

🧚 NOTES ON IMAGE DATA 🧚

all image data is in the CCIR-601 Y'CbCr colorspace, presented plane-by-plane in row-major order. each sample within each plane is one octet (8-bits) in size. when all planes are present, they are transmitted in the order Y', Cb, Cr, potentially followed by an alpha/transparency mask plane (for the 444alpha chroma format). the alpha channel data is follows the same range as the Y' luma channel: full transparency is at 16 and full opacity is at 235. 🌈

all Y' and alpha planes consist of (height X width) octets. the size of the chroma planes depends on the subsampling mode:

• 4:4:4 — (height X width) octets
• 4:2:2 — (height X width) / 2 octets
• 4:1:1 — (height X width) / 4 octets
• 4:2:0 — (height X width) / 4 octets

---

🌟 NOTES ON FRAMING 🌟

for more details about reading and writing yuv4mpeg files read the sources — there are many utility programs, some simple, some complex that can serve as guides. literally go look, it's giving textbook energy. 📚

---

🔥 SEE ALSO 🔥

mjpegtools(1), yuv4mpeg.h

---

💖 AUTHOR 💖

This manual page Copyright 2004 Matthew J. Marjanovic.

---

and that's the whole page, bestie. this was written by the MJPEG Tools Team, dated 25 November 2002, from the MJPEG Tools Manual. slay, periodt. 💅✨🎀🦋🌸