home *** CD-ROM | disk | FTP | other *** search
/ The Best of Select: Multimedia 5 / MMCD5.ISO / mpg / mpeg_enc.doc < prev    next >
Encoding:
Text File  |  1994-05-27  |  14.0 KB  |  397 lines
  1.  
  2.  
  3.  
  4.  MPEG_ENCODE(1)             March              MPEG_ENCODE(1)
  5.                       9
  6.  
  7.  
  8.  
  9.  NAME
  10.       mpeg_encode - mpeg-1 video stream encoder
  11.  
  12.  SYNOPSIS
  13.       mpeg_encode [ -stat stat_file ] [ -quiet num_seconds ] [ -
  14.       no_frame_summary ] [ -gop gop_num ] [ -combine_gops ] [ -frames
  15.       first_frame last_frame ] [ -combine_frames ] [ -nice ] [ -max_machines
  16.       num_machines ] [ -snr ] [ -bit_rate_info rate_file ] [ -mv_histogram ]
  17.       param_file
  18.  
  19.  DESCRIPTION
  20.       mpeg_encode produces an MPEG-1 video stream.  param_file is a
  21.       parameter file which includes a list of input files and other
  22.       parameters.  The file is described in detail below.  The -gop,
  23.       -combine_gops, -frames, and -combine_frames options are all exclusive.
  24.       This man page is probably incomplete.  For complete usage, see the
  25.       User's Guide.
  26.  
  27.  OPTIONS
  28.       -stat stat_file : causes the encoder to append the statistics to the
  29.        file stat_file.  In any case, the statistics are output to
  30.        stdout.  The statistics use the following abbreviations:  bits
  31.        per block (bpb), bits per frame (bpf), seconds per frame (spf),
  32.        and bits per second (bps).
  33.  
  34.       -quiet num_seconds : causes the program to not report remaining time
  35.        for at least num_seconds seconds.  A negative values tells the
  36.        program not to report at all.  0 is the default (reports once
  37.        after each frame).  Note that the time remaining is an estimate
  38.        and does not take into account time to read in frames.
  39.  
  40.       -no_frame_summary : prevents the program from printing a summary line
  41.        for each frame
  42.  
  43.       -gop gop_num : causes the encoder to only encode the numbered GOP
  44.        (first GOP is 0).  The parameter file is the same as for normal
  45.        usage.  The output file will be the normal output file with the
  46.        suffix ".gop.<gop_num>"  No sequence info is output.
  47.  
  48.       -combine_gops : causes the encoder to simply combine some GOP files
  49.        into a single MPEG stream.  A sequence header/ender are inserted.
  50.        In this case, the parameter file need only contain the YUV_SIZE
  51.        value, an output file, and perhaps a list of input GOP files (see
  52.        below).
  53.  
  54.       -frames first_frame last_frame : causes the encoder to only encode the
  55.        frames from first_frame to last_frame, inclusive.  The parameter
  56.        file is the same as for normal usage.  The output will be placed
  57.        in separate files, one per frame, with the file names being the
  58.        normal output file with the suffix ".frame.<frame num>"  No GOP
  59.        header information is output.  (Thus, the parameter file need not
  60.  
  61.  
  62.  
  63.                     - 1 -      Formatted:  March 28, 1994
  64.  
  65.  
  66.  
  67.  
  68.  
  69.  
  70.  MPEG_ENCODE(1)             March              MPEG_ENCODE(1)
  71.                       9
  72.  
  73.  
  74.  
  75.        include the GOP_SIZE value)
  76.  
  77.       -combine_frames : causes the encoder to simply combine some frames
  78.        into a single MPEG stream.  Sequence and GOP headers are inserted
  79.        appropriately.  In this case, the parameter file need only
  80.        contain the YUV_SIZE value, the GOP_SIZE value, an output file,
  81.        and perhaps a list of frame files (see below).
  82.  
  83.       -nice : causes the program to run any remote processes 'nicely.'    This
  84.        is only relevant if the program is using parallel encoding.    (see
  85.        'man nice.')
  86.  
  87.       -max_machines num_machines : causes the program to use no more than
  88.        num_machines machines as slaves for use in parallel encoding.
  89.  
  90.       -snr : print the signal-to-noise ratio.  Prints SNR (Y U V) and peak
  91.        SNR (Y U V) for each frame.    In summary, prints averages of
  92.        luminance only (Y).    SNR is defined as 10*log(variance of
  93.        original/variance of error).  Peak SNR is defined as
  94.        20*log(255/RMSE).  Note that the encoder will run a little slower
  95.        if you want it to print the SNR.
  96.  
  97.       -bit_rate_info rate_file : prints bit rate information into the file
  98.        rate_file.  Bit rate info is bits per frame, and also bits per
  99.        I-frame-to-I-frame.
  100.  
  101.       -mv-histogram : prints histogram of motion vectors as part of
  102.        statistics.    There are three histograms -- one for P, forward B,
  103.        and backward B vectors.  Each histogram is a 2-dimensional array,
  104.        and there is one entry for each vector in the search window.
  105.  
  106.  
  107.  PARAMETER FILE
  108.       The parameter file MUST contain the following lines (except when using
  109.       the -combine_gops or -combine_frames options):
  110.  
  111.        PATTERN <pattern>
  112.  
  113.        OUTPUT <output file>
  114.  
  115.        INPUT_DIR <directory>
  116.         all input files must reside in this directory.    If you want
  117.         to refer to the current directory, use '.' (an empty
  118.         INPUT_DIR value would refer to the root directory).
  119.  
  120.        INPUT
  121.         This line must be followed by a list of the input files (in
  122.         display order) and then the line
  123.              END_INPUT
  124.         There are three types of lines between INPUT and END_INPUT.
  125.         First, a line may simply be the name of an input file.
  126.  
  127.  
  128.  
  129.                     - 2 -      Formatted:  March 28, 1994
  130.  
  131.  
  132.  
  133.  
  134.  
  135.  
  136.  MPEG_ENCODE(1)             March              MPEG_ENCODE(1)
  137.                       9
  138.  
  139.  
  140.  
  141.         Secondly, the line may be of the form
  142.              <single_star_expr> [x-y]
  143.         single_star_expr can have a single '*' in it.  It is
  144.         replaced by all the numbers between x and y inclusive.    So,
  145.         for example, the line
  146.              tennis*.ppm [12-15]
  147.         is replaced by tennis12.ppm, tennis13.ppm, tennis14.ppm,
  148.         tennis15.ppm.  Uniform zero-padding occurs, as well.  For
  149.         example, the line
  150.              football.*.ppm [001-130]
  151.         is replaced by football.001.ppm, football.002.ppm, ...,
  152.         football.009.ppm, football.010.ppm, ..., football.130.ppm.
  153.         The third type of line is:
  154.              <single_star_expr> [x-y+s]
  155.         Where the line is treated exactly as above, except that we
  156.         skip by s.  Thus, the line
  157.              football.*.ppm [001-130+4]
  158.         is replaced by football.001.ppm, football.005.ppm,
  159.         football.009.ppm, football.013.ppm, etc.
  160.  
  161.        BASE_FILE_FORMAT <YUV or PPM or PNM>
  162.         All the input files must be converted to YUV, PNM, or PPM
  163.         format.  This line specifies which of the three formats
  164.         (actually PPM is a subset of PNM).  In the YUV format, the U
  165.         and V components are subsampled 4:1.  The reason for having
  166.         a separate PPM option is for simplicity.  If your files are
  167.         RAWBITS ppm files, then use the PPM option rather than the
  168.         PNM.  Also, depending on the system, file reads will go much
  169.         faster with the PPM option (as opposed to PNM).
  170.  
  171.        INPUT_CONVERT <conversion command>
  172.         You must specify how to convert a file to the base file
  173.         format.  In the conversion command, each '*' is replaced by
  174.         the filename (the items listed between INPUT and END_INPUT).
  175.         If no conversion is necessary, then you would just say:
  176.              INPUT_CONVERT *
  177.         If you had a bunch of gif files, you might say:
  178.              INPUT_CONVERT giftoppm *
  179.         If you have a bunch of separate a.Y, a.U, and a.V files,
  180.         then you might say:
  181.              INPUT_CONVERT cat *.Y *.U *.V
  182.  
  183.        GOP_SIZE <n>
  184.         n is roughly the number of frames in a Group of Pictures
  185.         (roughly because a GOP must begin with an I-frame)
  186.  
  187.        SLICES_PER_FRAME <n>
  188.         n is roughly the number of slices per frame.  Note, at least
  189.         one MPEG player may complain if slices do not start at the
  190.         left side of an image.    To ensure this does not happen, make
  191.         sure the number of rows is divisible by SLICES_PER_FRAME.
  192.  
  193.  
  194.  
  195.                     - 3 -      Formatted:  March 28, 1994
  196.  
  197.  
  198.  
  199.  
  200.  
  201.  
  202.  MPEG_ENCODE(1)             March              MPEG_ENCODE(1)
  203.                       9
  204.  
  205.  
  206.  
  207.        PIXEL <FULL or HALF>
  208.         use half-pixel motion vectors, or only full-pixel ones
  209.  
  210.        RANGE <n>
  211.         use a search range of +/- n pixels
  212.  
  213.        PSEARCH_ALG <algorithm>
  214.         algorithm must be one of {EXHAUSTIVE, TWOLEVEL, SUBSAMPLE,
  215.         LOGARITHMIC}.  Tells what kind of search procedure should be
  216.         used for P-frames.  Exhaustive gives the best compression,
  217.         but logarithmic is the fastest.  You select the desired
  218.         combination of speed and compression.  TWOLEVEL is an
  219.         exhaustive full-pixel search, followed by a local half-
  220.         pixel search around the best full-pixel vector (the PIXEL
  221.         option is ignored for this search algorithm).
  222.  
  223.        BSEARCH_ALG <algorithm>
  224.         algorithm must be one of {SIMPLE, CROSS2, EXHAUSTIVE}.
  225.         Tells what kind of search procedure should be used for B-
  226.         frames.  Simple means find best forward and backward
  227.         vectors, then interpolate.  Cross2 means find those two
  228.         vectors, then see what backward vector best matches the best
  229.         forward vector, and vice versa.  Exhaustive does an n-
  230.         squared search and is EXTREMELY slow in relation to the
  231.         others (Cross2 is about twice as slow as Simple).
  232.  
  233.        IQSCALE <n>
  234.         use n as the qscale for I-frames
  235.  
  236.        PQSCALE <n>
  237.         use n as the qscale for P-frames
  238.  
  239.        BQSCALE <n>
  240.         use n as the qscale for B-frames
  241.  
  242.        REFERENCE_FRAME <ORIGINAL or DECODED>
  243.         If ORIGINAL is specified, then the original images are used
  244.         when computing motion vectors.    To be more accurate, use
  245.         DECODED, in which the decoded images are used.    This should
  246.         increase the quality of the image, but will take a bit
  247.         longer to encode.
  248.        The following lines are optional:
  249.  
  250.         FORCE_I_ALIGN
  251.              This option is only relevant for parallel execution
  252.              (see below).  It forces each processor to encode a
  253.              block of N frames, where N must be a multiple of the
  254.              pattern length.  Since the first frame in any pattern
  255.              is an I-frame, this forces each block encoded by a
  256.              processor to begin with an I-frame.
  257.         foo
  258.  
  259.  
  260.  
  261.                     - 4 -      Formatted:  March 28, 1994
  262.  
  263.  
  264.  
  265.  
  266.  
  267.  
  268.  MPEG_ENCODE(1)             March              MPEG_ENCODE(1)
  269.                       9
  270.  
  271.  
  272.  
  273.  NOTES
  274.       If the BASE_FILE_FORMAT is YUV, then the parameter file must contain:
  275.        YUV_SIZE <w>x<h>
  276.       where w = width, h = height (in pixels) of image If the -combine-gops
  277.       option is used, then only the YUV_SIZE and OUTPUT values need be
  278.       specified in the parameter file.    In addition, the parameter file may
  279.       specify input GOP files in the same manner as normal input files --
  280.       except instead of using INPUT_DIR, INPUT, and END_INPUT, use
  281.       GOP_INPUT_DIR, GOP_INPUT, and GOP_END_INPUT.  If no input GOP files
  282.       are specified, then the default is to use the output file name with
  283.       suffix ".gop.<gop_num>" starting from 0 as the input files.  If the
  284.       -combine-frames option is used, then only the YUV_SIZE, GOP_SIZE, and
  285.       OUTPUT values need be specified in the parameter file.  In addition,
  286.       the parameter file may specify input frame files in the same manner as
  287.       normal input files -- except instead of using INPUT_DIR, INPUT, and
  288.       END_INPUT, use FRAME_INPUT_DIR, FRAME_INPUT, and FRAME_END_INPUT.  If
  289.       no input frame files are specified, then the default is to use the
  290.       output file name with suffix ".frame.<frame_num>" starting from 0 as
  291.       the input files.    Any number of spaces and tabs may come between each
  292.       option and value.  Lines beginning with '#' are ignored.    Any other
  293.       lines are ignored except for those between INPUT and END_INPUT.  This
  294.       allows you to use the same parameter file for normal usage and for
  295.       -combine_gops and -combine_frames.  The encoder is case-sensitive so,
  296.       except for file names and directories, everything should be in upper
  297.       case.  The lines may appear in any order, except the following
  298.       exceptions.  INPUT must appear before END_INPUT  (also, GOP_INPUT
  299.       before GOP_END_INPUT and FRAME_INPUT before FRAME_END_INPUT).  All
  300.       lines between INPUT and END_INPUT must be the frames in play order.
  301.  
  302.  
  303.  PARALLEL OPERATION
  304.       The encoder may be run on multiple machines at once.  To do so, add a
  305.       line "PARALLEL" in the parameter file, followed by a listing, one
  306.       machine per line, then "END_PARALLEL".  Each of the lines should be in
  307.       one of two forms.  If the machine has access to the file server, then
  308.       the line should be:      <machine> <user> <executable> The executable
  309.       is normally mpeg_encode (you may need to give the complete path if
  310.       you've built for different architectures).  If the machine is a remote
  311.       machine, then the line should be:      REMOTE <machine> <user>
  312.       <executable> <parameter file> Full paths should generally be used when
  313.       describing executables and parameter files.  This INCLUDES the
  314.       parameter file given as an argument to the original call to
  315.       mpeg_encode.  Also, .rhosts files on the appropriate machines should
  316.       have the appropriate information.  The encoder will use the original
  317.       machine for the master and I/O server processes, and uses the listed
  318.       machines as slaves to do the computation.  Optional lines are
  319.  
  320.       RSH <remote shell command>
  321.        The encoder uses the remote shell command to start processes on
  322.        other machines.  The default command is 'rsh.'  If your machine
  323.        supports a different command, specify it here.
  324.  
  325.  
  326.  
  327.                     - 5 -      Formatted:  March 28, 1994
  328.  
  329.  
  330.  
  331.  
  332.  
  333.  
  334.  MPEG_ENCODE(1)             March              MPEG_ENCODE(1)
  335.                       9
  336.  
  337.  
  338.  
  339.       PARALLEL_TEST_FRAMES <n>
  340.        n is the number of frames to encode initially on each processor
  341.  
  342.       PARALLEL_TIME_CHUNKS <t>
  343.        subsequently, each slave processor will be asked to encode for
  344.        approximately t seconds.  Smaller values of <t> increase
  345.        communication, but improve load balancing.
  346.  
  347.        The default values for these two options are n = 3 frames and t =
  348.         30 seconds.
  349.  
  350.       PARALLEL_PERFECT
  351.        If this line is present, then scheduling is done on the
  352.        assumption that work distribution will be perfectly even --
  353.        meaning that each machine is about the same speed.  The frames
  354.        will simply be divided up evenly between the processors.  This
  355.        has the advantage of very minimal scheduling overhead, but is
  356.        obviously wrong if machines have varying speeds, or if the
  357.        network load makes performance uneven.
  358.  
  359.  
  360.  AUTHORS
  361.       Kevin Gong - University of California, Berkeley,
  362.        keving@cs.berkeley.edu
  363.  
  364.       Ketan Patel - University of California, Berkeley,
  365.        kpatel@cs.berkeley.edu
  366.  
  367.       Dan Wallach - University of California, Berkeley,
  368.        dwallach@cs.berkeley.edu
  369.  
  370.  BUGS
  371.       No known bugs.
  372.  
  373.  
  374.  
  375.  
  376.  
  377.  
  378.  
  379.  
  380.  
  381.  
  382.  
  383.  
  384.  
  385.  
  386.  
  387.  
  388.  
  389.  
  390.  
  391.  
  392.  
  393.                     - 6 -      Formatted:  March 28, 1994
  394.  
  395.  
  396.  
  397.