XMG v1.0 - The X MPEG Grabber

DESCRIPTION

XMG is a utility for the X Window System which allows you to create MPEG-1 video streams by repeatedly grabbing a window on the screen and then joining the frames into an MPEG sequence. XMG has several options that modify its behaviour, but it also provides sensible defaults for most of them. The two switches that you'll use most of the time are -fps (or -fpm) and -frames. These specify the number of frames per second (or per minute) and the total number of frames to grab. Here's an example invocation :

 xmg -fps 1 -frames 20
This specifies that we want to grab 20 frames, one per second, and also that we want to see what's going on during the grabbing process. At this point the XMG window will appear :

Click on the "Grab" button and then click with the left mouse button inside the window that you want to grab. Once you've done this, the grabbing process will begin immediately, displaying some progress information as it does it. It is possible to change a few parameters directly from inside the window, instead of specifying them on the command line. When all the frames have been grabbed, the MPEG encoding process begins: go off and make yourself a nice cup of tea and come back later. By default the program creates a file called xmgout.mpg in the current directory. This file can then be viewed with any MPEG player which supports I,P and B frames of any size (Xing for example, doesn't support them). You can specify a different name for the output file with the -output switch. For example, the command :

 xmg -fps 1 -frames 20 -output mympeg.mpg
will create a file called mympeg.mpg. When XMG is grabbing the frames, it stores them in a temporary RLE compressed and archived format called XLA. This file can become quite large very quickly, especially if you're grabbing several frames of a certain size. This file will be created by default in the /tmp directory with the name xmgtmp.$$$. This can be changed with the -tmp option :
 xmg -fps 1 -frames 20 -tmp /empty/xmpeggrab.tmp
which will create it in the /empty directory with the name xmpeggrab.tmp. Make sure you've got plenty of space on the device ! To actually perform the encoding, XMG requires a parameter file. By default this file is called xmg.param and has to be in the current directory. Don't worry if you haven't got one : XMG will create a default one for you and use that. A different parameter file can be specified with the -param switch :
 xmg -fps 1 -frames 20 -param flower.param
This will use the file flower.param. A description of the possible contents of the paramter file is provided later on.

SYNOPSIS

    xmg
        -help
        -display host:dpy
        -frames nframes
        -fps nfps
        -fpm nfpm
        -terse
        -output filename
        -tmp filename
        -param filename

OPTIONS

-fps nfps : specifies the number of frames per second to grab. Even if the machine you're using is slow, XMG will grab the server during the grab, so that no other application can write to the screen at the same time. As soon as the frame has been grabbed, the server is released so that the other applications can redraw their client area.

-fpm nfpm : specifies the number of frames per minute to grab.

-frames nframes : specifies the number of frames to grab in total.

-output filename : specifies a name and location for the generated MPEG stream. By default XMG creates a file in the current directory called xmgout.mpg.

-tmp filename : specifies a name and location for the temporary storage of the grabbed frames. This file is deleted when XMG has completed the encoding process. The default is /tmp/xmgtmp.$$$

-terse : does not display the XMG status window during the grabbing/encoding process. The default is to display the XMG window.

-param : specifies a name and location for the parameter file. By default the file is called xmg.param and has to be in the current directory. If one doesn't exist, a default one will be created for you.

PARAMETER FILE

The parameter file MUST contain the following lines :

PATTERN pattern

pattern is a sequence of I's, P's and B's, that specifies the order of the frames in the MPEG stream.

GOP_SIZE n

n is roughly the number of frames in a Group of Pictures (roughly because a GOP must begin with an I-frame)

SLICES_PER_FRAME n

n is roughly the number of slices per frame. Note, at least one MPEG player may complain if slices do not start at the left side of an image. To ensure this does not happen, make sure the number of rows is divisible by SLICES_PER_FRAME.

PIXEL (FULL or HALF)

use half-pixel motion vectors, or only full-pixel ones

RANGE

use a search range of +/- n pixels

PSEARCH_ALG algorithm

algorithm must be one of {EXHAUSTIVE, TWOLEVEL, SUBSAMPLE, LOGARITHMIC}. Tells what kind of search procedure should be used for P-frames. Exhaustive gives the best compression, but logarithmic is the fastest. You select the desired combination of speed and compression. TWOLEVEL is an exhaustive full-pixel search, followed by a local half- pixel search around the best full-pixel vector (the PIXEL option is ignored for this search algorithm). BSEARCH_ALG algorithm must be one of {SIMPLE, CROSS2, EXHAUSTIVE}. Tells what kind of search procedure should be used for B-frames. Simple means find best forward and backward vectors, then interpolate. Cross2 means find those two vectors, then see what backward vector best matches the best forward vector, and vice versa. Exhaustive does an n-squared search and is EXTREMELY slow in relation to the others (Cross2 is about twice as slow as Simple).

IQSCALE

use n as the qscale for I-frames

PQSCALE

use n as the qscale for P-frames

BQSCALE

use n as the qscale for B-frames

REFERENCE_FRAME (ORIGINAL or DECODED)

If ORIGINAL is specified, then the original images are used when computing motion vectors. To be more accurate, use DECODED, in which the decoded images are used. This should increase the quality of the image, but will take a bit longer to encode.

The lines may appear in any order, except the following exceptions.

SOURCE CODE

To retrieve the source code click here

NOTES

If XMG was compiled with the -DMITSHM switch enabled, then shared memory will be used if available and will increase performance noticeably.

AUTHOR

Tristan Tarrant - University of Sussex, UK, tristant@cogs.susx.ac.uk

CREDITS

MPEG encoding based on mpeg_encode by :

Kevin Gong - University of California, Berkeley, keving@cs.berkeley.edu

Ketan Patel - University of California, Berkeley, kpatel@cs.berkeley.edu

Dan Wallach - University of California, Berkeley, dwallach@cs.berkeley.edu

BUGS AND LIMITATIONS

XMG works only on Pseudo-Color displays. No known bugs.

Tristan Tarrant, tristant@cogs.susx.ac.uk