PATTERN <pattern>

OUTPUT <output file>

INPUT_DIR <directory>

all input files must reside in this directory. If you want to refer to the current directory, use '.' (an empty INPUT_DIR value would refer to the root directory). If input files will be coming in from standard input, use 'stdin'.

INPUT

This line must be followed by a list of the input files (in display order) and then the line

END_INPUT

There are three types of lines between INPUT and END_INPUT. First, a line may simply be the name of an input file. Secondly, the line may be of the form

<single_star_expr> [x-y]

single_star_expr can have a single '*' in it. It is replaced by all the numbers between x and y inclusive. So, for example, the line

tennis*.ppm [12-15]

is replaced by tennis12.ppm, tennis13.ppm, tennis14.ppm, tennis15.ppm. Uniform zero-padding occurs, as well. For example, the line

football.*.ppm [001-130]

is replaced by football.001.ppm, football.002.ppm, ..., football.009.ppm, football.010.ppm, ..., football.130.ppm. The third type of line is:

<single_star_expr> [x-y+s]

Where the line is treated exactly as above, except that we skip by s. Thus, the line

football.*.ppm [001-130+4]

is replaced by football.001.ppm, football.005.ppm, football.009.ppm, football.013.ppm, etc.

BASE_FILE_FORMAT <YUV or PPM or PNM or JPEG or JMOVIE>

All the input files must be converted to YUV, JPEG(v4), JMOVIE, PNM, or PPM format. This line specifies which of the three formats (actually PPM is a subset of PNM). The reason for having a separate PPM option is for simplicity. If your files are RAWBITS ppm files, then use the PPM option rather than the PNM. Also, depending on the system, file reads will go much faster with the PPM option (as opposed to PNM).

INPUT_CONVERT <conversion command>

You must specify how to convert a file to the base file format. In the conversion command, each '*' is replaced by the filename (the items listed between INPUT and END_INPUT). If no conversion is necessary, then you would just say:

INPUT_CONVERT *

If you had a bunch of gif files, you might say:

INPUT_CONVERT giftoppm *

If you have a bunch of separate a.Y, a.U, and a.V files, then you might say:

INPUT_CONVERT cat *.Y *.U *.V

Input conversion is not allowed with input from stdin.

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 <n>

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>

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 <n>

use n as the qscale for I-frames

PQSCALE <n>

use n as the qscale for P-frames

BQSCALE <n>

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 following lines are optional:

FORCE_I_ALIGN

This option is only relevant for parallel execution (see below). It forces each processor to encode a block of N frames, where N must be a multiple of the pattern length. Since the first frame in any pattern is an I-frame, this forces each block encoded by a processor to begin with an I-frame.

foo

NOTES

YUV_SIZE <w>x<h>

YUV_FORMAT <ABEKAS or PHILLIPS or UCB or EYUV or pattern>.

If the -combine-gops option is used, then only the YUV_SIZE and OUTPUT values need be specified in the parameter file. In addition, the parameter file may specify input GOP files in the same manner as normal input files -- except instead of using INPUT_DIR, INPUT, and END_INPUT, use GOP_INPUT_DIR, GOP_INPUT, and GOP_END_INPUT. If no input GOP files are specified, then the default is to use the output file name with suffix ".gop.<gop_num>" starting from 0 as the input files.

If the -combine-frames option is used, then only the YUV_SIZE, GOP_SIZE, and OUTPUT values need be specified in the parameter file. In addition, the parameter file may specify input frame files in the same manner as normal input files -- except instead of using INPUT_DIR, INPUT, and END_INPUT, use FRAME_INPUT_DIR, FRAME_INPUT, and FRAME_END_INPUT. If no input frame files are specified, then the default is to use the output file name with suffix ".frame.<frame_num>" starting from 0 as the input files.

Any number of spaces and tabs may come between each option and value. Lines beginning with '#' are ignored. Any other lines are ignored except for those between INPUT and END_INPUT. This allows you to use the same parameter file for normal usage and for -combine_gops and -combine_frames.

The encoder is case-sensitive so, except for file names and directories, everything should be in upper case.

The lines may appear in any order, except the following exceptions. INPUT must appear before END_INPUT (also, GOP_INPUT before GOP_END_INPUT and FRAME_INPUT before FRAME_END_INPUT). All lines between INPUT and END_INPUT must be the frames in play order.

The encoder is prepared to handle up to 16 B frames between reference frames when encoding with input from stdin. To increase this amount, change the constant B_FRAME_RUN in frame.c and recompile.

PARALLEL OPERATION

       <machine> <user> <executable>

The executable is normally ppmtompeg (you may need to give the complete path if you've built for different architectures). If the machine is a remote machine, then the line should be:

       REMOTE <machine> <user> <executable> <parameter file>

Full paths should generally be used when describing executables and parameter files. This INCLUDES the parameter file given as an argument to the original call to ppmtompeg. Also, .rhosts files on the appropriate machines should have the appropriate information.

The encoder will use the original machine for the master and I/O server processes, and uses the listed machines as slaves to do the computation.

Optional lines are

RSH <remote shell command>

The encoder uses the remote shell command to start processes on other machines. The default command is 'rsh.' If your machine supports a different command, specify it here.

PARALLEL_TEST_FRAMES <n>

n is the number of frames to encode initially on each processor

PARALLEL_TIME_CHUNKS <t>

subsequently, each slave processor will be asked to encode for approximately t seconds. Smaller values of <t> increase communication, but improve load balancing.

The default values for these two options are n = 3 frames and t = 30 seconds.

PARALLEL_PERFECT

If this line is present, then scheduling is done on the assumption that work distribution will be perfectly even -- meaning that each machine is about the same speed. The frames will simply be divided up evenly between the processors. This has the advantage of very minimal scheduling overhead, but is obviously wrong if machines have varying speeds, or if the network load makes performance uneven.

VERSION

BUGS

No known bugs, but if you find any, report them to mpeg-bugs@plateau.cs.berkeley.edu.

AUTHORS

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

Darryl Brown - University of California, Berkeley, darryl@cs.berkeley.edu

Eugene Hung - University of California, Berkeley, eyhung@cs.berkeley.edu

Steve Smoot - University of California, Berkeley, smoot@cs.berkeley.edu