home *** CD-ROM | disk | FTP | other *** search
/ DP Tool Club 9 / CD_ASCQ_09_1193.iso / news / 4441 / mpegcode / doc / mpeg_enc.man < prev    next >
Text File  |  1993-09-27  |  17KB  |  463 lines

  1.  
  2.  
  3.  
  4. MPEG_ENCODE(1)                                     MPEG_ENCODE(1)
  5.  
  6.  
  7. NNAAMMEE
  8.        mpeg_encode - mpeg-1 video stream encoder
  9.  
  10. SSYYNNOOPPSSIISS
  11.        mmppeegg__eennccooddee  [  --ssttaatt ssttaatt__ffiillee ] [ --qquuiieett nnuumm__sseeccoonnddss ] [
  12.        --nnoo__ffrraammee__ssuummmmaarryy ] [ --ggoopp ggoopp__nnuumm ] [ --ccoommbbiinnee__ggooppss  ]  [
  13.        --ffrraammeess  ffiirrsstt__ffrraammee  llaasstt__ffrraammee  ]  [ --ccoommbbiinnee__ffrraammeess ] [
  14.        --nniiccee ] [ --mmaaxx__mmaacchhiinneess nnuumm__mmaacchhiinneess ] [ --ssnnrr ] ppaarraamm__ffiillee
  15.  
  16. DDEESSCCRRIIPPTTIIOONN
  17.        mmppeegg__eennccooddee  produces  an MPEG-1 video stream.  param_file
  18.        is a parameter file which includes a list of  input  files
  19.        and  other  parameters.   The  file is described in detail
  20.        below.   The  -gop,  -combine_gops,  -frames,  and   -com-
  21.        bine_frames options are all exclusive.
  22.  
  23. OOPPTTIIOONNSS
  24.        --ssttaatt ssttaatt__ffiillee : causes the encoder to append the statis-
  25.               tics to the  file  _s_t_a_t___f_i_l_e.   In  any  case,  the
  26.               statistics  are  output  to stdout.  The statistics
  27.               use the following abbreviations:   bits  per  block
  28.               (bpb),  bits  per  frame  (bpf),  seconds per frame
  29.               (spf), and bits per second (bps).
  30.  
  31.        --qquuiieett nnuumm__sseeccoonnddss : causes  the  program  to  not  report
  32.               remaining time for at least num_seconds seconds.  A
  33.               negative values tells the program not to report  at
  34.               all.   0  is  the  default (reports once after each
  35.               frame).  Note that the time remaining is  an  esti-
  36.               mate and does not take into account time to read in
  37.               frames.
  38.  
  39.        --nnoo__ffrraammee__ssuummmmaarryy : prevents the program from  printing  a
  40.               summary line for each frame
  41.  
  42.        --ggoopp  ggoopp__nnuumm : causes the encoder to only encode the num-
  43.               bered GOP (first GOP is 0).  The parameter file  is
  44.               the same as for normal usage.  The output file will
  45.               be  the  normal  output  file   with   the   suffix
  46.               ".gop.<gop_num>"  No sequence info is output.
  47.  
  48.        --ccoommbbiinnee__ggooppss  : causes the encoder to simply combine some
  49.               GOP files into a single MPEG  stream.   A  sequence
  50.               header/ender  are  inserted.   In  this  case,  the
  51.               parameter  file  need  only  contain  the  YUV_SIZE
  52.               value,  an output file, and perhaps a list of input
  53.               GOP files (see below).
  54.  
  55.        --ffrraammeess ffiirrsstt__ffrraammee llaasstt__ffrraammee :  causes  the  encoder  to
  56.               only   encode   the   frames  from  first_frame  to
  57.               last_frame, inclusive.  The parameter file  is  the
  58.               same  as  for  normal  usage.   The  output will be
  59.               placed in separate files, one per frame,  with  the
  60.               file  names  being  the normal output file with the
  61.  
  62.  
  63.  
  64.                           9 August 1993                         1
  65.  
  66.  
  67.  
  68.  
  69.  
  70. MPEG_ENCODE(1)                                     MPEG_ENCODE(1)
  71.  
  72.  
  73.               suffix ".frame.<frame num>"  No GOP header informa-
  74.               tion is output.  (Thus, the parameter file need not
  75.               include the GOP_SIZE value)
  76.  
  77.        --ccoommbbiinnee__ffrraammeess : causes the  encoder  to  simply  combine
  78.               some  frames  into  a single MPEG stream.  Sequence
  79.               and GOP headers  are  inserted  appropriately.   In
  80.               this case, the parameter file need only contain the
  81.               YUV_SIZE value, the GOP_SIZE value, an output file,
  82.               and perhaps a list of frame files (see below).
  83.  
  84.        --nniiccee  :  causes  the  program to run any remote processes
  85.               'nicely.'  This is only relevant if the program  is
  86.               using parallel encoding.  (see 'man nice.')
  87.  
  88.        --mmaaxx__mmaacchhiinneess  nnuumm__mmaacchhiinneess : causes the program to use no
  89.               more than num_machines machines as slaves  for  use
  90.               in parallel encoding.
  91.  
  92.        --ssnnrr  :  print the signal-to-noise ratio.  Prints SNR (Y U
  93.               V) and peak SNR (Y U V) for each  frame.   In  sum-
  94.               mary,  prints  averages of luminance only (Y).  SNR
  95.               is defined as 10*log(variance of  original/variance
  96.               of    error).     Peak    SNR    is    defined   as
  97.               20*log(255/RMSE).  Note that the encoder will run a
  98.               little slower if you want it to print the SNR.
  99.  
  100.  
  101. PPAARRAAMMEETTEERR FFIILLEE
  102.        The  parameter  file  MUST  contain  the  following  lines
  103.        (except when using the  -combine_gops  or  -combine_frames
  104.        options):
  105.  
  106.               PATTERN <pattern>
  107.  
  108.               OUTPUT <output file>
  109.  
  110.               INPUT_DIR <directory>
  111.                      all  input  files must reside in this direc-
  112.                      tory.  If you want to refer to  the  current
  113.                      directory, use '.' (an empty INPUT_DIR value
  114.                      would refer to the root directory).
  115.  
  116.               INPUT
  117.                      This line must be followed by a list of  the
  118.                      input  files (in display order) and then the
  119.                      line
  120.                              END_INPUT
  121.                      There are three types of lines between INPUT
  122.                      and  END_INPUT.  First, a line may simply be
  123.                      the name of an input  file.   Secondly,  the
  124.                      line may be of the form
  125.                              <single_star_expr> [x-y]
  126.                      single_star_expr  can  have  a single '*' in
  127.  
  128.  
  129.  
  130.                           9 August 1993                         2
  131.  
  132.  
  133.  
  134.  
  135.  
  136. MPEG_ENCODE(1)                                     MPEG_ENCODE(1)
  137.  
  138.  
  139.                      it.  It  is  replaced  by  all  the  numbers
  140.                      between x and y inclusive.  So, for example,
  141.                      the line
  142.                              tennis*.ppm [12-15]
  143.                      is replaced by  tennis12.ppm,  tennis13.ppm,
  144.                      tennis14.ppm,  tennis15.ppm.   Uniform zero-
  145.                      padding occurs, as well.  For  example,  the
  146.                      line
  147.                              football.*.ppm [001-130]
  148.                      is   replaced   by  football.001.ppm,  foot-
  149.                      ball.002.ppm, ...,  football.009.ppm,  foot-
  150.                      ball.010.ppm,  ...,  football.130.ppm.   The
  151.                      third type of line is:
  152.                              <single_star_expr> [x-y+s]
  153.                      Where the line is treated exactly as  above,
  154.                      except that we skip by s.  Thus, the line
  155.                              football.*.ppm [001-130+4]
  156.                      is   replaced   by  football.001.ppm,  foot-
  157.                      ball.005.ppm,    football.009.ppm,     foot-
  158.                      ball.013.ppm, etc.
  159.  
  160.               BASE_FILE_FORMAT <YUV or PPM or PNM>
  161.                      All  the  input  files  must be converted to
  162.                      YUV, PNM or PPM format.  This line specifies
  163.                      which  of the three formats (actually PPM is
  164.                      a subset of PNM).  In the YUV format, the  U
  165.                      and  V  components  are subsampled 4:1.  The
  166.                      reason for having a separate PPM  option  is
  167.                      for  simplicity.   If your files are RAWBITS
  168.                      ppm files, then use the  PPM  option  rather
  169.                      than  the  PNM.  Also, depending on the sys-
  170.                      tem, file reads will go much faster with the
  171.                      PPM option (as opposed to PNM).
  172.  
  173.               INPUT_CONVERT <conversion command>
  174.                      You  must  specify  how to convert a file to
  175.                      the base file  format.   In  the  conversion
  176.                      command,  each  '*' is replaced by the file-
  177.                      name (the items  listed  between  INPUT  and
  178.                      END_INPUT).   If no conversion is necessary,
  179.                      then you would just say:
  180.                              INPUT_CONVERT *
  181.                      If you had a bunch of gif files,  you  might
  182.                      say:
  183.                              INPUT_CONVERT giftoppm *
  184.                      If  you  have  a bunch of separate a.Y, a.U,
  185.                      and a.V files, then you might say:
  186.                              INPUT_CONVERT cat *.Y *.U *.V
  187.  
  188.               GOP_SIZE <n>
  189.                      n is roughly the number of frames in a Group
  190.                      of  Pictures  (roughly  because  a  GOP must
  191.                      begin with an I-frame)
  192.  
  193.  
  194.  
  195.  
  196.                           9 August 1993                         3
  197.  
  198.  
  199.  
  200.  
  201.  
  202. MPEG_ENCODE(1)                                     MPEG_ENCODE(1)
  203.  
  204.  
  205.               SLICES_PER_FRAME <n>
  206.                      n is roughly the number of slices per frame.
  207.                      Note,  at least one MPEG player may complain
  208.                      if slices do not start at the left  side  of
  209.                      an  image.   To ensure this does not happen,
  210.                      make sure the number of rows is divisible by
  211.                      SLICES_PER_FRAME.
  212.  
  213.               PIXEL <FULL or HALF>
  214.                      use half-pixel motion vectors, or only full-
  215.                      pixel ones
  216.  
  217.               RANGE <n>
  218.                      use a search range of +/- n pixels
  219.  
  220.               PSEARCH_ALG <algorithm>
  221.                      algorithm  must  be  one   of   {EXHAUSTIVE,
  222.                      TWOLEVEL,  SUBSAMPLE,  LOGARITHMIC}.   Tells
  223.                      what kind of search procedure should be used
  224.                      for  P-frames.   Exhaustive  gives  the best
  225.                      compression, but logarithmic is the fastest.
  226.                      You  select the desired combination of speed
  227.                      and compression.  TWOLEVEL is an  exhaustive
  228.                      full-pixel search, followed by a local half-
  229.                      pixel search around the best full-pixel vec-
  230.                      tor  (the  PIXEL  option is ignored for this
  231.                      search algorithm).
  232.  
  233.               BSEARCH_ALG <algorithm>
  234.                      algorithm must be one  of  {SIMPLE,  CROSS2,
  235.                      EXHAUSTIVE}.  Tells what kind of search pro-
  236.                      cedure should be used for B-frames.   Simple
  237.                      means  find  best  forward and backward vec-
  238.                      tors, then interpolate.  Cross2  means  find
  239.                      those  two  vectors,  then see what backward
  240.                      vector best matches the best forward vector,
  241.                      and  vice  versa.   Exhaustive  does  an  n-
  242.                      squared search  and  is  EXTREMELY  slow  in
  243.                      relation  to  the  others  (Cross2  is about
  244.                      twice as slow as Simple).
  245.  
  246.               IQSCALE <n>
  247.                      use n as the qscale for I-frames
  248.  
  249.               PQSCALE <n>
  250.                      use n as the qscale for P-frames
  251.  
  252.               BQSCALE <n>
  253.                      use n as the qscale for B-frames
  254.  
  255.               REFERENCE_FRAME <ORIGINAL or DECODED>
  256.                      If ORIGINAL is specified, then the  original
  257.                      images  are  used when computing motion vec-
  258.                      tors.  To be more accurate, use DECODED,  in
  259.  
  260.  
  261.  
  262.                           9 August 1993                         4
  263.  
  264.  
  265.  
  266.  
  267.  
  268. MPEG_ENCODE(1)                                     MPEG_ENCODE(1)
  269.  
  270.  
  271.                      which  the  decoded  images  are used.  This
  272.                      should increase the quality  of  the  image,
  273.                      but will take a bit longer to encode.
  274.  
  275. NNOOTTEESS
  276.        If  the  BASE_FILE_FORMAT  is YUV, then the parameter file
  277.        must contain:
  278.               YUV_SIZE <w>x<h>
  279.        where w = width, h = height (in pixels) of image
  280.  
  281.        If  the  -combine-gops  option  is  used,  then  only  the
  282.        YUV_SIZE and OUTPUT values need be specified in the param-
  283.        eter file.  In addition, the parameter  file  may  specify
  284.        input  GOP  files in the same manner as normal input files
  285.        --  except  instead  of  using   INPUT_DIR,   INPUT,   and
  286.        END_INPUT,     use     GOP_INPUT_DIR,    GOP_INPUT,    and
  287.        GOP_END_INPUT.  If no input GOP files are specified,  then
  288.        the  default  is  to  use the output file name with suffix
  289.        ".gop.<gop_num>" starting from 0 as the input files.
  290.  
  291.        If the -combine-frames  option  is  used,  then  only  the
  292.        YUV_SIZE, GOP_SIZE, and OUTPUT values need be specified in
  293.        the parameter file.  In addition, the parameter  file  may
  294.        specify  input  frame  files  in the same manner as normal
  295.        input files -- except instead of using  INPUT_DIR,  INPUT,
  296.        and   END_INPUT,  use  FRAME_INPUT_DIR,  FRAME_INPUT,  and
  297.        FRAME_END_INPUT.  If no input frame files  are  specified,
  298.        then  the default is to use the output file name with suf-
  299.        fix ".frame.<frame_num>" starting  from  0  as  the  input
  300.        files.
  301.  
  302.        Any number of spaces and tabs may come between each option
  303.        and value.  Lines beginning with  '#'  are  ignored.   Any
  304.        other lines are ignored except for those between INPUT and
  305.        END_INPUT.  This allows you to use the same parameter file
  306.        for   normal   usage   and  for  -combine_gops  and  -com-
  307.        bine_frames.
  308.  
  309.        The encoder is case-sensitive so, except  for  file  names
  310.        and directories, everything should be in upper case.
  311.  
  312.        The  lines  may  appear in any order, except the following
  313.        exceptions.  INPUT must appear  before  END_INPUT   (also,
  314.        GOP_INPUT  before  GOP_END_INPUT  and  FRAME_INPUT  before
  315.        FRAME_END_INPUT).  All lines between INPUT  and  END_INPUT
  316.        must be the frames in play order.
  317.  
  318.  
  319. PPAARRAALLLLEELL OOPPEERRAATTIIOONN
  320.        The  encoder  may be run on multiple machines at once.  To
  321.        do so, add a line "PARALLEL" in the parameter  file,  fol-
  322.        lowed   by   a   listing,   one  machine  per  line,  then
  323.        "END_PARALLEL".  Each of the lines should be in one of two
  324.        forms.  If the machine has access to the file server, then
  325.  
  326.  
  327.  
  328.                           9 August 1993                         5
  329.  
  330.  
  331.  
  332.  
  333.  
  334. MPEG_ENCODE(1)                                     MPEG_ENCODE(1)
  335.  
  336.  
  337.        the line should be:
  338.  
  339.             <machine> <user> <executable>
  340.  
  341.        The executable is normally mpeg_encode (you  may  need  to
  342.        give  the  complete  path  if  you've  built for different
  343.        architectures).  If the machine is a remote machine,  then
  344.        the line should be:
  345.  
  346.             REMOTE <machine> <user> <executable> <parameter file>
  347.  
  348.        Full paths should generally be used when  describing  exe-
  349.        cutables and parameter files.  This INCLUDES the parameter
  350.        file  given  as  an  argument  to  the  original  call  to
  351.        mpeg_encode.   Also,  .rhosts  files  on  the  appropriate
  352.        machines should have the appropriate information.
  353.  
  354.        The encoder will use the original machine for  the  master
  355.        and  I/O server processes, and uses the listed machines as
  356.        slaves to do the computation.
  357.  
  358.        Optional lines are
  359.  
  360.        RSH <remote shell command>
  361.               The encoder uses the remote shell command to  start
  362.               processes  on  other machines.  The default command
  363.               is 'rsh.'  If your  machine  supports  a  different
  364.               command, specify it here.
  365.  
  366.        PARALLEL_TEST_FRAMES <n>
  367.               n  is  the  number of frames to encode initially on
  368.               each processor
  369.  
  370.        PARALLEL_TIME_CHUNKS <t>
  371.               subsequently, each slave processor will be asked to
  372.               encode for approximately t seconds.  Smaller values
  373.               of <t> increase  communication,  but  improve  load
  374.               balancing.
  375.  
  376.               The  default values for these two options are n = 3
  377.                      frames and t = 30 seconds.
  378.  
  379.        Please note that the parallel  code  has  not  been  well-
  380.        tested  and is not very fault-tolerant (if a slave process
  381.        goes down, nothing works).  Future versions of the encoder
  382.        will support parallel execution better.
  383.  
  384.  
  385. AAUUTTHHOORRSS
  386.        Kevin  Gong  -  University  of  California, Berkeley, kev-
  387.               ing@cs.berkeley.edu
  388.  
  389.        Ketan Patel - University  of  California,  Berkeley,  kpa-
  390.               tel@cs.berkeley.edu
  391.  
  392.  
  393.  
  394.                           9 August 1993                         6
  395.  
  396.  
  397.  
  398.  
  399.  
  400. MPEG_ENCODE(1)                                     MPEG_ENCODE(1)
  401.  
  402.  
  403.        Dan  Wallach  -  University of California, Berkeley, dwal-
  404.               lach@cs.berkeley.edu
  405.  
  406. BBUUGGSS
  407.        No known bugs.
  408.  
  409.  
  410.  
  411.  
  412.  
  413.  
  414.  
  415.  
  416.  
  417.  
  418.  
  419.  
  420.  
  421.  
  422.  
  423.  
  424.  
  425.  
  426.  
  427.  
  428.  
  429.  
  430.  
  431.  
  432.  
  433.  
  434.  
  435.  
  436.  
  437.  
  438.  
  439.  
  440.  
  441.  
  442.  
  443.  
  444.  
  445.  
  446.  
  447.  
  448.  
  449.  
  450.  
  451.  
  452.  
  453.  
  454.  
  455.  
  456.  
  457.  
  458.  
  459.  
  460.                           9 August 1993                         7
  461.  
  462.  
  463.