MPEG-FAQ 4.0:

Xmg

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. 

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