	vrecord - video4linux command-line video recording tool

  Copyright (C) 2006 Joe Pfeiffer

  vrecord is free software; you can redistribute it and/or modify
  it under the terms of the GNU General Public License as published by
  the Free Software Foundation; either version 2 of the License, or
  (at your option) any later version.

  This program is distributed in the hope that it will be useful,
  but WITHOUT ANY WARRANTY; without even the implied warranty of
  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  GNU General Public License for more details.

  You should have received a copy of the GNU General Public License
  along with this program; if not, write to the Free Software
  Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA

Quickstart:

This is a little app to just see if I can capture from a
webcam...  it seems like every webcam program I can find has grown
far, far beyond my modest needs, and writing my own will be easier
than figuring them out.

The intent here is to have a simple, command-line program to perform
video captures, with sane defaults.  It's only been tested with my
camera; it ought to work with any camera that supports v4l and 24-bit
JPEG output, but YMMV.  Its use is deliberately very similar to that
of the 'arecord' command-line alsa recording utility.

Just giving the command

% vrecord

will start capturing images as quickly as your camera and PC can do
it, and dumping them to stdout as a series of color PPM files.

A way to use arecord and vrecord to record a short movie would be:

% vrecord -f 24 -d 60 capture.ppm & arecord -r 16000 -D usb -f S16 -c 2 -d 60 capture.wav
    This will record a 60-second video to capture.ppm, and a 60-second
    audio to capture.wav

    The requested framerate of 24 fps (the -f option) is a best-effort
    attempt.  Depending on your hardware, it may not be possible to
	record at the requested rate; after it is finished recording, vrecord
	will report the number of frames and the actual time.  If it's
    markedly different from the requested 24:1, you should replace the
	argument in the next command with the actual framerate (for
    instance, if it actually recorded 738 frames, you'd use -F 738:60
    in the next command.

% ppmtoy4m -v 0 -F 24:1 -S 420jpeg < capture.ppm | mpeg2enc -v 0 -o video.mpeg 
    this will convert the ppm file captured in the first step to a
    video-only mpeg

    If the frame rate was something other than 24 FPS, you'll need to
    convert it to the correct frame rate now with yuvfps in between the
    ppmtoy4m and mpeg2end commands in the above pipe.

% sox capture.wav capture2.wav trim 1.5
    This trims the first 1.5 second of audio, to try to sync audio and
    video.  Playing with the trim parameter tends to be necessary to get
    it just right.  By default, the verbosity level of vrecord will make
    it print the initialization time, giving a good first approximation
    setting for this parameter.

% mp2enc < capture2.wav -o audio.mpeg
    This will convert the trimmed audio capture to an audio-only mpeg.

% mplex -o combined.mpeg video.mpeg audio.mpeg
    This will combine the audio and video streams into a single mpeg.

The arecord, ppmtoy4m, sox, mp2enc, mpeg2enc, mplex, and yuvfps
programs are not part of this distribution.  I run Debian; the
packages they come from in Debian are:

package    programs
alsa-utils arecord
mjpegtools mp2enc mpeg2enc mplex ppmtoy4m yuvfps
sox        sox

I expect the package names will be similar in other distributions.
--------------------------------------------------------------------
The -v (--verbosity) option can take a value of 0 (error text only), 1
(prints time until video captures start, and the number of frames and
time elapsed capturing them), and 2 (prints everything it does in gory
detail).

Unfortunately, this program uses the deprecated v4l API rather than
the current v4l2 API.  But my camera's driver (spca5xx) is
v4l-only, so that's what this program uses.  

At the moment, it looks like it's easier to spit out and manipulate
a series of ppm files rather than a yuv file; also, the y4l-
conversion utilities don't seem to want to deal with the subsampled
color components the webcam wants to produce.  So ppm is what I'll
be producing!  In order to get the pixel color components in the
right order, the driver module must be modprobed with the
force_rgb=1 option.

