.TH "yuv4mpeg" "5" "25 November 2002" "MJPEG Linux Square" "MJPEG Tools Manual"

.SH "NAME"
yuv4mpeg \- video stream format used by pipe-based MJPEGtools
.hw libmjpegutils yuv4mpeg.h YUV4MPEG YUV4MPEG2 

.SH "DESCRIPTION"
.PP
Many of the MJPEGtools communicate via pipes and act as filters
(or sources or sinks).  The format of video data used in the pipes is
referred to as "YUV4MPEG", or, more precisely, "YUV4MPEG2".  (The format
was extended and codified during v1.5.x of the tools.)
.PP
The basic structure is a stream header followed by an unlimited number of
frames.  Each frame itself consists of a header followed by video data.
The headers are vaguely human-readable ASCII, but the video data is simple
byte-size binary.
.PP
The MJPEGtools distribution has a C library (libmjpegutils) which contains
functions for manipulating YUV4MPEG2 streams.  We recommend that you use
this library rather than writing your own code if possible.  See the header
file "yuv4mpeg.h" for a description of these functions.
.PP
Design Goals:
.IP o
Easy to parse both via C or sh.
.IP o
Extensible; easy to add new parameters while maintaining backwards
compatibility.
.IP o
Simple upgrade from original "YUV4MPEG" format.
.PP
Drawbacks:
.IP o
Frame headers do not have constant size, so streams are not seekable.

.SH "GRAMMAR"
The precise description of the the YUV4MPEG2 stream format is as follows:

.PP
\fISTREAM\fP consists of
.IP - 3 
one \fISTREAM-HEADER\fP
.IP - 3 
unlimited number of \fIFRAME\fPs
.PP
\fISTREAM-HEADER\fP consists of
.IP - 3 
magic string "YUV4MPEG2"
.IP - 3 
unlimited number of \fITAGGED-FIELD\fPs,
each preceeded by a '\ ' (single space) separator
.IP - 3
single '\en' line terminator

.PP
\fIFRAME\fP consists of 
.IP - 3
one \fIFRAME-HEADER\fP
.IP - 3
"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.)
.PP
\fIFRAME-HEADER\fP consists of
.IP - 3
magic string "FRAME"
.IP - 3
unlimited number of \fITAGGED-FIELD\fPs,
each preceeded by a '\ ' (single space) separator
.IP - 3
single '\en' line terminator

.PP
.I \fITAGGED-FIELD\fP 
consists of
.IP - 3
single ASCII character tag
.IP - 3
\fIVALUE\fP (which does not contain whitespace)
.PP
\fIVALUE\fP
consists of
.IP - 3
\fIRATIO\fP,
.B or
.IP - 3
integer (base 10 ASCII representation),
.B or
.IP - 3
single ascii character,
.B or
.IP - 3
string (multiple ASCII characters)

.PP
\fIRATIO\fP 
consists of
.IP - 3
numerator (base 10 ASCII integer)
.IP - 3
\&':' (a colon)
.IP - 3
denominator (base 10 ASCII integer)


.PP
The supported tags for the \fISTREAM-HEADER\fP:
.RS
.HP
W\ \-\ [integer] frame width in pixels, must be > 0 (\fBrequired\fP)
.HP
H\ \-\ [integer] frame height in pixels, must be > 0 (\fBrequired\fP)
.HP
I\ \-\ [char] interlacing specification:  
.RS
 p\ \-\ progressive (none)
 t\ \-\ top-field-first
 b\ \-\ bottom-field-first
 ?\ \-\ unknown
.RE
.HP
F\ \-\ [ratio] frame-rate, 0:0 == unknown
.HP
A\ \-\ [ratio] sample aspect ratio, 0:0 == unknown
.HP
X\ \-\ [string] 'metadata' (unparsed, but passed around)
.RE

.PP
The currently supported tags for the \fIFRAME-HEADER\fP:
.RS
.HP
X\ \-\ [string] 'metadata' (unparsed, but passed around)
.RE

.PP
Except for those specified as "required", all tags are optional,
and the absence of a tag indicates that the parameter is unknown.
.PP
Note that 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.

.SH "NOTES ON IMAGE DATA"
.PP
Currently only planar, 4:2:0-subsampled CCIR-601, Y'CbCr image data is 
supported.
This consists of, one after another:
.IP - 3
(height\ X\ width) octets (8-bit bytes) of Y' samples in row-major order;
.IP - 3
(height\ X\ width\ /\ 4) octets of Cb samples;
.IP - 3
(height\ X\ width\ /\ 4) octets of Cr samples.
.PP
Sample siting (for the subsampling of the chroma planes) is not specified.
(Not yet, at least.)

.SH "SEE ALSO"
.BR mjpegtools (1),
yuv4mpeg.h

.SH "AUTHOR"
This manual page Copyright 2002 Matthew J. Marjanovic.