PPMTOMPEG(1)                General Commands Manual               PPMTOMPEG(1)

       ppmtompeg - encodes MPEG-1 bitstreams

       ppmtompeg [ options ] parameter-file

       ppmtompeg  produces  an MPEG-1 video stream.  param_file is a parameter
       file which includes a list of input files and  other  parameters.   The
       file  is  described in detail below.  The -gop, -combine_gops, -frames,
       and -combine_frames options are all exclusive.  This man page is proba-
       bly incomplete.  For complete usage, see the User's Guide.

       -stat  stat_file  :  causes the encoder to append the statistics to the
              file stat_file.  In any case, the statistics are output to  std-
              out.   The statistics use the following abbreviations:  bits per
              block (bpb), bits per frame (bpf), seconds per frame (spf),  and
              bits per second (bps).

       -quiet  num_seconds  :  causes the program to not report remaining time
              for at least num_seconds seconds.  A negative values  tells  the
              program  not  to  report at all.  0 is the default (reports once
              after each frame).  Note that the time remaining is an  estimate
              and does not take into account time to read in frames.

       -realquiet  :  causes the encoder to run silently, with the only screen
              output being errors.  Particularly  useful  when  reading  input
              from stdin.

       -no_frame_summary  :  prevents the program from printing a summary line
              for each frame

       -float_dct : forces the encoder to use a more accurate, yet more compu-
              tationally expensive version of the DCT.

       -gop  gop_num  :  causes  the  encoder  to only encode the numbered GOP
              (first GOP is 0).  The parameter file is the same as for  normal
              usage.   The output file will be the normal output file with the
              suffix ".gop.<gop_num>"  No sequence info is output.

       -combine_gops : causes the encoder to simply  combine  some  GOP  files
              into   a  single  MPEG  stream.   A  sequence  header/ender  are
              inserted.  In this case, the parameter file  need  only  contain
              the  YUV_SIZE value, an output file, and perhaps a list of input
              GOP files (see below).

       -frames first_frame last_frame : causes the encoder to only encode  the
              frames from first_frame to last_frame, inclusive.  The parameter
              file is the same as for normal usage.  The output will be placed
              in  separate files, one per frame, with the file names being the
              normal output file with the suffix ".frame.<frame num>"  No  GOP
              header  information  is  output.  (Thus, the parameter file need
              not include the GOP_SIZE value)

       -combine_frames : causes the encoder to simply combine some frames into
              a  single  MPEG  stream.   Sequence and GOP headers are inserted
              appropriately.  In this case, the parameter file need only  con-
              tain the YUV_SIZE value, the GOP_SIZE value, an output file, and
              perhaps a list of frame files (see below).

       -nice : causes the program to run any remote processes 'nicely.'   This
              is  only  relevant  if  the  program is using parallel encoding.
              (see 'man nice.')

       -max_machines num_machines : causes the program to  use  no  more  than
              num_machines machines as slaves for use in parallel encoding.

       -snr  :  print  the signal-to-noise ratio.  Prints SNR (Y U V) and peak
              SNR (Y U V) for each frame.   In  summary,  prints  averages  of
              luminance only (Y).  SNR is defined as 10*log(variance of origi-
              nal/variance   of   error).    Peak   SNR    is    defined    as
              20*log(255/RMSE).   Note  that  the  encoder  will  run a little
              slower if you want it to print the SNR.

       -mse : computes the mean squared error per block.   Also  automatically
              computes the quality of the images when set, so there is no need
              to specify -snr then.

       -bit_rate_info rate_file : prints bit rate information  into  the  file
              rate_file.   Bit  rate info is bits per frame, and also bits per

       -mv-histogram : prints histogram of motion vectors as part  of  statis-
              tics.   There  are three histograms -- one for P, forward B, and
              backward B vectors.  Each histogram is  a  2-dimensional  array,
              and there is one entry for each vector in the search window.

       The  parameter file MUST contain the following lines (except when using
       the -combine_gops or -combine_frames options):

              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

                     This line must be followed by a list of the  input  files
                     (in display order) and then the line
                     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,     ...,     foot-
                     ball.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,  foot-
                     ball.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  simplic-
                     ity.   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

                     GOP_SIZE <n>
                            n is roughly the number of frames in  a  Group  of
                            Pictures (roughly because a GOP must begin with an

                     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 num-
                            ber of rows is divisible by SLICES_PER_FRAME.

                     PIXEL <FULL or HALF>
                            use half-pixel motion vectors, or only  full-pixel

                     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  loga-
                            rithmic  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,  EXHAUS-
                            TIVE}.  Tells what kind of search procedure should
                            be used for B-frames.  Simple means find best for-
                            ward   and  backward  vectors,  then  interpolate.
                            Cross2 means find those two vectors, then see what
                            backward vector best matches the best forward vec-
                            tor, 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
                     The following lines are optional:

                                   This  option  is only relevant for parallel
                                   execution (see below).  It forces each pro-
                                   cessor 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.

       If the BASE_FILE_FORMAT is YUV, then the parameter file must contain:
              YUV_SIZE <w>x<h>
       where w = width, h = height (in pixels) of image, and
              YUV_FORMAT <ABEKAS or PHILLIPS or UCB or EYUV or pattern>.
       See the file doc/INPUT.FORMAT for more information.

       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

       The encoder is case-sensitive so, except for file  names  and  directo-
       ries, 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.

       The encoder may be run on multiple machines at once.  To do so,  add  a
       line  "PARALLEL"  in  the  parameter  file,  followed by a listing, one
       machine per line, then "END_PARALLEL".  Each of the lines should be  in
       one  of  two forms.  If the machine has access to the file server, then
       the line should be:

            <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  appro-
       priate 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  computa-

       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.

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

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

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

              If this line is present, then scheduling is done on the  assump-
              tion  that  work  distribution will be perfectly even -- meaning
              that each machine is about the same speed.  The frames will sim-
              ply  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.

       This is version 1.5 it contins new features and bug fixes from  version

       Not  really  a  bug, but at least a limitation: If writing to an output
       file, ppmtompeg sometimes uses <filename>.* as temporary files.

       No  known  bugs,  but  if  you  find  any,   report   them   to   mpeg-

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

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

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

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

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

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

                                1 February 1995                   PPMTOMPEG(1)
Man Pages Copyright Respective Owners. Site Copyright (C) 1994 - 2022 Hurricane Electric. All Rights Reserved.