snatch/README-MJPEG

   1 Snatch 20020225
   2
   3 Converting Snatch capture files to MPEG audio/video with mjpeg-tools
   4
   5 ****************************** ABOUT ******************************
   6
   7 mjpeg-tools is a nice little collection of MPEG audio and video
   8 utilities that work out of the box.  The output quality is very nice,
   9 and the tool set is intelligently arranged.
  10
  11 The various tools in the mjpeg-tools trade video in YUV4MPEG[2] format
  12 and audio as WAV.  Snatch support for mjpeg-tools consists of three
  13 conversion utilities, snatch2wav, snatch2yuv and snatch2yuv2
  14 (Naturally, these utilities will work with any application accepting
  15 these formats).
  16
  17 The conversion utilities are tested to work with
  18 mjpeg-tools-1.4 through 1.6.0-beta2.  Note that newer versions of
  19 mjpeg-tools use YUV4MPEG2 format (produced by snatch2yuv2) while 1.4
  20 uses the original YUV4MEG (produced by snatch2yuv).  1.6.0 compiled
  21 cleanly here for Debian/x86 and Debian/PPC.  1.4.1 requires some
  22 hacking to correct a few [very minor] problems.  If you don't have
  23 either yet, go for 1.6.0.
  24
  25 Converting a snatch capture file to MPEG video using mjpeg is done in
  26 three steps: encode audio to MPEG-1 layer 2 audio using snatch2wav and
  27 mp2enc or toolame (.mp2), encode the video to MPEG-1/2 video using
  28 snatch2yuv[2] and mpeg2enc and then multiplexing the audio/video into
  29 a complete MPEG video stream with mplex.  All of these tools [except
  30 toolame] are included in the mjpeg-tools and Snatch packages.
  31
  32 ***************************** INSTALL *****************************
  33
  34 The official home of mjpeg-tools is http://mjpeg.sourceforge.net/
  35 Note that the older, official mjpegtools-1.4.1 has a few annoying
  36 build and option parsing bugs.  I've patched the bugs I've found, as
  37 well as added the Snatch conversion utility source to my own
  38 distribution of the mjpeg-tools source:
  39
  40 A patch against stock mjpegtools-1.4.1 can be found at:
  41 http://www.mit.edu/afs/athena/user/x/i/xiphmont/Public/Snatch/mjpegtools-1.4.1-snatchpatch.diff
  42
  43 The complete source with patch already applied is at:
  44 http://www.mit.edu/afs/athena/user/x/i/xiphmont/Public/Snatch/mjpegtools-1.4.1-snatch.tgz
  45
  46 Unless there's a reason to use the older 1.4 release, 1.6 is
  47 recommended.  1.6 requires no patch, and the Makefile included with
  48 Snatch builds and installs the Snatch conversion utilities (as they're
  49 not included with the official 1.6 source).
  50
  51 When building mjpeg-tools, pay attention to the INSTALL document in
  52 the mjpeg-tools tarball.  Things will probably go wrong if you don't
  53 read it.
  54
  55 One trick wrt Debian and installing quicktime4linux through dpkg/apt;
  56 the mjpeg tools build system is confused by it being installed, but
  57 not where 'INSTALL' suggests putting it.  When running configure, do
  58 like:
  59
  60 ./configure --with-quicktime=/usr/include/quicktime
  61
  62 ****************************** USAGE ******************************
  63
  64 Once installed, snatch2wav and snatch2yuv[2] work just like the other
  65 mjpeg 'xxxx2wav' and 'xxx2yuv' tools.  The command line options are
  66 different, but snatch2wav -h and snatch2yuv[2] -h will give a clear
  67 summary.
  68
  69 The basic idea:
  70
  71 Encode an .mp2 audio file from the Snatch capture file using
  72 snatch2wav < capture.snatch | mp2enc -o temp.mp2
  73
  74 Encode an .m1v video file from the Snatch capture file using
  75 snatch2yuv < capture.snatch | mpeg2enc -o temp.m1v
  76
  77 Multiplex them into one movie file:
  78 mplex temp.mp2 temp.m1v -o output.mpeg
  79
  80 (the standalone .mp2 and .m1v files are valid MPEG audio and video
  81 files respectively; you don't *have* to multiplex if you only want the
  82 sound or only want the video).
  83
  84 Some notes before we get onto examples:
  85
  86 1) snatch2yuv doesn't currently do any scaling.  The size options
  87    merely letterbox/crop.  That's OK, mpeg2enc will encode practically
  88    any frame size.
  89
  90    However, many MPEG _players_ require that video width be a multiple
  91    of 8 and RealPlayer, for God Knows What Reason, often decodes, for
  92    example, 240x180 video into a screen resolution of, say, 238x180
  93    for no good reason.  You may need to use -s with snatch2yuv[2] to
  94    force a multiple of eight size for maximum compatibility with
  95    various MPEG players.
  96
  97 2) snatch2yuv does not autosense frame rate.  RealVideo frame rates
  98    are going to be weird, non-MPEG ones for the most part...  but the
  99    oddest thing about RealPlayer8 is that it doesn't display at the
 100    encoded frame rate!  RP8 seems to blast frames to the screen at
 101    ~30fps regardless of what the encoded video actually wants.
 102    snatch2yuv[2] defaults to 30fps, so you shouldn't need to frob frame
 103    rate (but you can if you want to).
 104
 105 3) audio/video sync is Just Not A Concern.  Snatch records timing data
 106    in the capture file; snatch2wav pays attention to the video timing
 107    when extracting audio and snatch2yuv[2] watches the audio when
 108    extracting video.  The separated audio and video will always be in
 109    sync unless explicitly requested otherwise.
 110
 111    However, A/V sync can be a problem in the resulting MPEG file if
 112    you use VBR encoding and an Easily Confused Player.  For example,
 113    the only *NIX player I've seen that pays any attention to sync with
 114    VBR MPEG video is MPlayer (and MPlayer does an excellent job).
 115    Others (like the ubiquitous Xine) have serious trouble even playing
 116    VBR, let alone keeping sync solid.  This, obviously, is not a bug
 117    in Snatch.  The sync is perfect in the .snatch file, and
 118    snatch2yuv/snatch2wav will produce synchronized output.
 119
 120 4) It's possible a capture file will contain different sampling rates
 121    or mixed frame sizes/rates; this can happen if the window is
 122    resized, congestion causes a change in stream rate, etc.
 123
 124    snatch2wav will resample the capture data into a uniform output
 125    automatically; by default it forces all output audio to the
 126    rate/channels it sees in the file first.  The user can override
 127    these settings.  mp2enc is also capable of resampling, but it want
 128    to see a file all in one format.
 129
 130    snatch2yuv, similarly, forces all output to the same frame rate and
 131    frame size.
 132
 133 5) If a capture is momentarily interrupted (congestion, or an old
 134    Linux machine using a 2.2 kernel that only allows 2GB files)
 135    resulting in the capture going into multiple .snatch files, the
 136    files can be strung back together in sequence with cat and piped
 137    into the conversion utilities.  Catting and processing in one batch
 138    eliminates any additional audio/video dropout or padding at the
 139    boundaries that would be caused by the conversion utilities having
 140    to invent or discard frames to keep the beginning and ending output
 141    in sync (an odd but necessary thing about players... although the
 142    audio and video are _played_ in sync, they're not produced that
 143    way.  Audio usually runs several seconds ahead of video because of
 144    hardware buffering.  This would show up if you independently
 145    processed multiple .snatch files comprising one program.  The output
 146    would sill be in sync, but the beginning of each file would begin
 147    with video for several seconds before audio started and end with
 148    audio for several seconds after video stopped).
 149
 150    If a gap within or between two files is greater than two
 151    seconds, the conversion utils will snip most of the gap out
 152    (intentionally leaving a bit), else the splice will be seamless.
 153
 154    Note that the conversion utilities are counting absolute seconds
 155    when using the -b and -n options; gaps and interruptions are
 156    counted time.  That is, if splicing back together, say, a one hour
 157    segment of a live program that lost five minutes in the middle due
 158    to a momentary network outage, "snatch2yuv2 -n 3600" will produce
 159    video for the one hour program, without the five minute gap in the
 160    middle, for a total of 55 minutes of actual video.  Naturally,
 161    snatch2wav will still produce audio exactly matching the video.
 162
 163 Now for a real example.  I've captured a 240x180 (which RP8 actually
 164 displays at 238x180), mono 22050Hz file using Snatch.  Because
 165 RealPlayer actually displays at 30fps, the .snatch file is already at
 166 30fps, which is both the default rate assumed by snatch2yuv and a
 167 legal MPEG1/2 video frame rate (even had it been captured at 10 or
 168 15fps, which is a more likely native RealVideo frame rate, it would
 169 need to be upsampled to 30fps for MPEG encoding).  I, personally,
 170 would use (assuming mjpeg-tools-1.6.0):
 171
 172 snatch2wav < 20011115_22:00:10_mono22050Hz_238x180_AV.snatch | \
 173            mp2enc -m -b 64 -o temp.mp2
 174
 175 snatch2yuv2 -s 240x180 < 20011115_22:00:10_mono22050Hz_238x180_AV.snatch | \
 176            mpeg2enc -q 8 -b 576 -f 3 -B 64 -o temp.m1v
 177
 178 mplex temp.mp2 temp.m1v -r 640 -f 3 -V -o out.mpeg
 179
 180 The first line instructs snatch2wav to convert the audio from the
 181 .snatch file into standard RIFF WAV (but without the length tag set.
 182 That won't be an issue here).  mp2enc then turns that WAV into a 64
 183 kbps mono mpeg layer 2 file.  These options can vary (and are not
 184 actually necessary at all).  I'll note that toolame produces
 185 considerably higher quality output than mp2enc.  It's worth getting.
 186
 187 The second line instructs snatch2yuv to convert the video from the
 188 capture file into YUV 4:2:0 (also called YV12), the format preferred
 189 by mpeg2enc.  The -s argument to snatch2yuv2 forces an output frame
 190 width that's a multiple of eight for maximum MPEG player
 191 compatibility.  mpeg2enc then produces an output video in MPEG format
 192 consisting of square pixels (no option necessary, this is forced by
 193 snatch2yuv2) 30fps (also set in the YUV4MPEG2 header produced by
 194 snatch2yuv2), at a variable bitrate quality level 8 (-q 8) not to
 195 exceed 576kbps for the video (-b 576).  -f 3 requests a generic MPEG 2
 196 output file, and -B 64 lets the encoder know ahead of time that a
 197 64kbps audio stream will also be multiplexed in later on.  The -B is
 198 not strictly necessary.
 199
 200 The third line mixes the audio and video files into the final stream.
 201 -r sets the peak output bitrate of the output stream (add the peak -b
 202 bitrates for audio and video), -f 3 selects MPEG 2, and -V is
 203 required when muxing VBR streams.
 204
 205 ****************************** MORE *******************************
 206
 207 The MJPEG webpages have much much more on using the tool suite.
 208 Specific pages:
 209
 210 homepage:
 211 http://mjpeg.sourceforge.net/
 212
 213 Mjpeg-HOWTO:
 214 https://sourceforge.net/docman/display_doc.php?docid=3456&group_id=5776