Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
Ppmtompeg User Manual(0)			      Ppmtompeg	User Manual(0)

NAME
       ppmtompeg - encode an MPEG-1 bitstream

SYNOPSIS
       ppmtompeg [options] parameter-file

DESCRIPTION
       This program is part of Netpbm(1).

       ppmtompeg  produces  an MPEG-1 video stream.  MPEG-1 is the first great
       video compression method, and is	what is	used in	Video CDs (VCD).  ppm-
       tompeg  originated  in the year 1995.  DVD uses a more advanced method,
       MPEG-2.	There is an even newer method  called  MPEG-4  which  is  also
       called Divx.  I don't know where	one finds that used.

       There's technically a difference	between	a compression method for video
       and an actual file (stream) format for a	movie, and I don't know	if  it
       can be validly said that	the format of the stream ppmtompeg produces is
       MPEG-1.

       Mencoder	from the Mplayer package <http://www.mplayerhq.hu>  is	proba-
       bly  superior  for  most	video format generation	needs, if for no other
       reason than that	it is more popular.

       The programming library PM2V <http://pm2v.free.fr>    generates	MPEG-2
       streams.

       Use  Mplayer  <http://www.mplayerhq.hu>	(not part of Netpbm) to	do the
       reverse conversion: to create a	series	of  PNM	 files	from  an  MPEG
       stream.

       param_file is a parameter file which includes a list of input files and
       other parameters.  The file is described	in detail below.

       To understand this program, you need to understand something about  the
       complex	MPEG-1	format.	 One source of information about this standard
       format is the section Introduction  to  MPEG  in	 the  Compression  FAQ
       <http://www.faqs.org/faqs/compression-faq> .

OPTIONS
       The  -gop,  -combine_gops, -frames, and -combine_frames options are all
       mutually	exclusive.

       -stat stat_file
	      This option causes ppmtompeg to append the  statistics  that  it
	      write  to	 Standard  Output  to the file stat_file as well.  The
	      statistics use  the  following  abbreviations:  bits  per	 block
	      (bpb),  bits  per	frame (bpf), seconds per frame (spf), and bits
	      per second (bps).

	      These statistics include how many	I, P, and B frames there were,
	      and information about compression	and quality.

       -quiet num_seconds
	       causes  ppmtompeg  not to report	remaining time more often than
	      every num_seconds	seconds	(unless	the time estimate rises, which
	      will  happen  near  the beginning	of the run).  A	negative value
	      tells ppmtompeg not to report at all.  0 is the default (reports
	      once  after each frame).	Note that the time remaining is	an es-
	      timate and does not take into account time to read in frames.

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

       -no_frame_summary
	       This option prevents ppmtompeg from printing a summary line for
	      each frame

       -float_dct
	       forces  ppmtompeg to use	a more accurate, yet more computation-
	      ally expensive version of	the DCT.

       -gop gop_num
	      causes ppmtompeg to encode only 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.   ppmtompeg	 does not output any sequence informa-
	      tion.

       -combine_gops
	       causes ppmtompeg	simply to combine some GOP files into a	single
	      MPEG  output  stream.   ppmtompeg	 inserts a sequence header and
	      trailer.	In this	case, the parameter file needs only to contain
	      the  SIZE	value, an output file, and perhaps a list of input GOP
	      files (see below).

	      If you don't supply a list of input GOP files is used, then ppm-
	      tompeg  assumes  you're  using  the same parameter file you used
	      when you created the input (with the -gop	option)	and calculates
	      the  corresponding  gop  filenames  itself.   If this is not the
	      case, you	can specify input GOP files in the same	manner as nor-
	      mal 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, with gop_num starting
	      from 0, as the input files.

	      Thus, unless you're mixing and matching GOP files	from different
	      sources, you can simply use the same parameter file for creating
	      the  GOP	files  (-gop)  and for later turning them into an MPEG
	      stream (-combine_gops).

       -frames first_frame last_frame
	      This option causes ppmtompeg to encode only the frames  numbered
	      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 out-
	      put file name with the suffix .frame.frame_num.  No  GOP	header
	      information  is  output.	(Thus, the parameter file need not in-
	      clude the	GOP_SIZE value)

	      Use ppmtompeg -combine_frames to combine these frames later into
	      an MPEG stream.

       -combine_frames
	       This  option causes ppmtompeg simply to combine some individual
	      MPEG frames (such	as you might have created with an earlier  run
	      of  ppmtompeg  -frames) into a single MPEG stream.  Sequence and
	      GOP headers are inserted appropriately.  In this case,  the  pa-
	      rameter  file needs to contain only the SIZE value, the GOP_SIZE
	      value, an	output file, and perhaps a list	of  frame  files  (see
	      below).

	      The  parameter  file  may	 specify input frame files in the same
	      manner as	normal input files --  except  instead	of  using  IN-
	      PUT_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,	with frame_num starting	from 0,	as  the	 input
	      files.

       -nice  This  option  causes  ppmtompeg  to  run	any  remote  processes
	      "nicely,"	i.e.  at low priority.	(This is relevant only if  you
	      are running ppmtompeg in parallel	mode.  Otherwise, there	are no
	      remote processes).  See 'man nice.'

       -max_machines num_machines
	      This option causes ppmtompeg to use no  more  than  num_machines
	      machines as slaves for use in parallel encoding.

       -snr   This  option causes ppmtompeg to include the signal-to-noise ra-
	      tio in the reported statistics.  Prints SNR (Y U V) and peak SNR
	      (Y  U  V)	 for each frame.  In summary, prints averages of lumi-
	      nance 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 ppmtompeg runs a little slower when
	      you use this option.

       -mse   This  option  causes  ppmtompeg to report	the mean squared error
	      per block.  It also automatically	reports	the quality of the im-
	      ages, so there is	no need	to specify -snr	then.

       -bit_rate_info rate_file
	       This option makes ppmtompeg write bit rate information into the
	      file rate_file.  Bit rate	information is	bits  per  frame,  and
	      also bits	per I-frame-to-I-frame.

       -mv_histogram
	       This option causes ppmtompeg to print a histogram of the	motion
	      vectors as part of statistics.  There are	 three	histograms  --
	      one for P	frame, one for forward B frame,	and one	for backward B
	      frame motion vectors.

	      The output is in the form	of a matrix, each entry	 corresponding
	      to one motion vector in the search window. The center of the ma-
	      trix represents (0,0) motion vectors.

       -debug_sockets
	      This option causes ppmtompeg to print to	Standard  Output  mes-
	      sages  that  narrate the communication between the machines when
	      you run ppmtompeg	in parallel mode <#parallel> .

       -debug_machines
	      This option causes ppmtompeg to print to	Standard  Output  mes-
	      sages that narrate the progress of the conversion	on the various
	      machines when you	run ppmtompeg in parallel mode <#parallel> .

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

       PATTERN pattern
	      This  statement  specifies the pattern (sequence)	of I frames, P
	      frames, and B frames.  pattern is	just a sequence	of the letters
	      I, P, and	B with nothing between.	 Example:

		  PATTERN IBBPBBPBBPBBPBB

	      See I Frames, P Frames, B	Frames <#ipb> .

       OUTPUT output file
	      This names the file where	the output MPEG	stream goes.

       INPUT_DIR directory
	      This  statement tells where the input images (frames) come from.
	      If each frame is in a separate file, directory is	the  directory
	      where  they  all are.  You may use . to refer to the current di-
	      rectory.	A null directory refers	to the root directory  of  the
	      system file tree.

	      To have ppmtompeg	read all the frames serially from Standard In-
	      put, specify
		  INPUT_DIR stdin

       INPUT  This line	must be	followed by a list of the input	files (in dis-
	      play 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.   Second,
	      the  line	 may  be  of  the  form	 single_star_expr [x-y].  sin-
	      gle_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] refers to the files tennis12.ppm,  ten-
	      nis13.ppm, tennis14.ppm, tennis15.ppm.

	      Uniform  zero-padding  occurs,  as  well.	 For example, the line
	      football.*.ppm [001-130] refers to the  files  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]	refers	to  the	 files
	      football.001.ppm,	  football.005.ppm,   football.009.ppm,	 foot-
	      ball.013.ppm, etc.

	      Furthermore, a line may specify a	shell command  to  execute  to
	      generate lines to	be interpreted as described above, as if those
	      lines were in the	parameter file instead.	 Use back ticks,  like
	      in the Bourne Shell, like	this:

		  `cat myfilelist`

	      If  input	 is from Standard Input	(per the INPUT_DIR statement),
	      ppmtompeg	ignores	the INPUT/END_INPUT block, but it  still  must
	      be present.

       BASE_FILE_FORMAT	{PPM | PNM | YUV |
		   JPEG	 |  JMOVIE}  ppmtompeg must convert all	input files to
	      one of the following formats as a	first step of processing: PNM,
	      YUV,  JPEG(v4),  or  JMOVIE.   (The conversion may be trivial if
	      your input files are already in one  of  these  formats).	  This
	      line  specifies  which  of  the four formats.  PPM is actually a
	      subset of	PNM.  The separate specification is allowed for	 back-
	      ward compatibility.  Use PNM instead of PPM in new applications.

       INPUT_CONVERT conversion_command
	      You  must	specify	how to convert a file to the base file format.
	      If no conversion is necessary, then you would just say:

		   INPUT_CONVERT *

	      Otherwise, conversion_command is a shell command that causes  an
	      image  in	 the format your specified with	BASE_FILE_FORMAT to be
	      written to Standard Output.  ppmtompeg executes the command once
	      for  each	 line  between INPUT and END_INPUT (which is normally,
	      but not necessarily, a file name).  In the  conversion  command,
	      ppmtompeg	replaces each '*' with the contents of that line.

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

		   If  you  have  a  bunch of separate a.Y, a.U, and a.V files
	      (where
		   the U and V have already been subsampled), then  you	 might
	      say:

		   INPUT_CONVERT cat *.Y *.U *.V

	      Input conversion is not allowed with input from stdin, so	use

		   INPUT_CONVERT *

	      as described above.

       SIZE widthxheight

	      width  and height	are the	width and height of each frame in pix-
	      els.

	      When ppmtompeg can get this information  from  the  input	 image
	      files, it	ignores	the SIZE parameter and you may omit it.

	      When  the	image files are	in YUV format, the files don't contain
	      dimension	information, so	SIZE is	required.

	      When ppmtompeg is	running	in parallel mode, not all of the  pro-
	      cesses in	the network have access	to the image files, so SIZE is
	      required and must	give the same dimensions as  the  input	 image
	      files.

       YUV_SIZE	widthxheight
	      This is an obsolete synonym of SIZE.

       YUV_FORMAT {ABEKAS | PHILLIPS | UCB |
				    EYUV  |  pattern}  This is meaningful only
	      when BASE_FILE_FORMAT specifies YUV format, and then it  is  re-
	      quired.  It specifies the	sub-format of the YUV class.

       GOP_SIZE	n
	      n	 is  the number	of frames in a Group of	Pictures.  Except that
	      because a	GOP must start with an I frame,	ppmtompeg makes	a  GOP
	      as  much	longer	than n as it has to to make the	next GOP start
	      with an I	frame.

	      Normally,	it makes sense to make your GOP	 size  a  multiple  of
	      your pattern length (the latter is determined by the PATTERN pa-
	      rameter file statement).

	      See Group	Of Pictures <#gop> .

       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 | HALF}
	      use  half-pixel  motion  vectors,	 or just full-pixel ones It is
	      usually important	that you use half-pixel	 motion	 vectors,  be-
	      cause it results in both better quality and better compression.

       RANGE n
	      Use  a  search  range of n pixels	in each	of the four directions
	      from a subject pixel.  (So the search window  is	a  square  n*2
	      pixels on	a side).

       PSEARCH_ALG {EXHAUSTIVE | TWOLEVEL |
		   SUBSAMPLE  |	 LOGARITHMIC}  This  statement tells ppmtompeg
	      what kind	of search
		  technique (algorithm)	to use for P frames.  You  select  the
	      desired
		  combination of speed and compression.	 EXHAUSTIVE gives the
		  best compression, but	LOGARITHMIC is the fastest.
		  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 technique).

       BSEARCH_ALG {SIMPLE | CROSS2 | EXHAUSTIVE}
	      This statement tells ppmtompeg what kind of search
		  technique (algorithm)	to use 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 half	as fast	as SIMPLE).

       IQSCALE n
	      Use n as the qscale for I	frames.
		   See Qscale <#qscale>	.

       PQSCALE n
	      Use n as the qscale for P	frames.
		   See Qscale <#qscale>	.

       BQSCALE n
	      Use n as the qscale for B	frames.
		   See Qscale <#qscale>	.

       REFERENCE_FRAME {ORIGINAL | DECODED}
	      This statement determines	whether	ppmtompeg  uses	 the  original
	      images or	the decoded images when	computing motion vectors.  Us-
	      ing decoded images is more  accurate  and	 should	 increase  the
	      playback	quality	 of the	output,	but it makes the encoding take
	      longer and seems to give worse compression.  It also causes some
	      complications with parallel encoding. (see the section on	paral-
	      lel encoding).  One thing	you can	do as a	 trade-off  is	select
	      ORIGINAL	here,  and lower the qscale (see QSCALE	if the quality
	      is not good enough.

	      Original or Decoded? (Normalized)

	      --------------------------------------------------------------------
	      Reference	  Compression	Speed	Quality	I   Quality P	Quality	B
		Decoded	     1000	1000	  1000	       969	   919
	       Original	      885	1373	  1000	       912	   884

       The following lines are optional:

       FORCE_ENCODE_LAST_FRAME
	      This statement is	obsolete.  It does nothing.

	      Before Netpbm 10.26 (January 2005), ppmtompeg would drop	trail-
	      ing  B  frames from your movie, since a movie can't end with a B
	      frame.  (See I Frames, P Frames, B Frames	<#ipb>	.   You	 would
	      have  to	specify	FORCE_ENCODE_LAST_FRAME	to stop	that from hap-
	      pening and get the same function that ppmtompeg has today.

       NIQTABLE
	      This statement specifies a custom	non-intra quantization	table.
	      If  you  don't  specify this statement, ppmtompeg	uses a default
	      non-intra	quantization table.

	      The 8 lines immediately following	NIQTABLE specify the quantiza-
	      tion table.  Each	line defines a table row and consists of 8 in-
	      tegers, whitespace-delimited, which define the table columns.

       IQTABLE
	      This is analogous	to NIQTABLE, but for  the  intra  quantization
	      table.

       ASPECT_RATIO ratio
	      This statement specifies the aspect ratio	for ppmtompeg to spec-
	      ify in the MPEG output.  I'm not sure what this is used for.

	      ratio must be  1.0,  0.6735,  0.7031,  0.7615,  0.8055,  0.8437,
	      0.8935,  0.9157,	0.9815,	 1.0255,  1.0695,  1.0950,  1.1575, or
	      1.2015.

       FRAME_RATE rate
	      This specifies the frame rate for	ppmtompeg to  specify  in  the
	      MPEG output.  Some players use this value	to determine the play-
	      back rate.

	      rate must	be 23.976, 24, 25, 29.97, 30, 50, 59.94, or 60.

       BIT_RATE	rate
	      This specifies the bit rate for Constant Bit Rate	 (CBR)	encod-
	      ing.

	      rate must	be an integer.

       BUFFER_SIZE size
	      This  specifies  the  value  ppmtompeg is	to specify in the MPEG
	      output for the Video Buffering Verifier (VBV) buffer size	needed
	      to decode	the sequence.

	      A	 Video	Verifying  Buffer is a buffer in which a decoder keeps
	      the decoded bits in order	to match the uneven speed of  the  de-
	      coding with the required constant	playback speed.

	      As  ppmtompeg  encodes  the  image,  it  simulates  the decoding
	      process in terms of how many bits	would be in the	 VBV  as  each
	      frame gets decoded, assuming a VBV of the	size you indicate.

	      If  you  specify the WARN_VBV_UNDERFLOW statement, ppmtompeg is-
	      sues a warning each time the simulation underflows  the  buffer,
	      which  suggests that an underflow	would occur on playback, which
	      suggests the buffer is too small.

	      If you specify the WARN_VBV_OVERFLOW statement, ppmtompeg	issues
	      a	 warning  each time the	simulation overflows the buffer, which
	      suggests that an overflow	would occur on	playback,  which  sug-
	      gests the	buffer is too small.

       WARN_VBV_UNDERFLOW

       WARN_VBV_OVERFLOW
	      See BUFFER_SIZE.

	      These  options  were new in Netpbm 10.26 (January	2005).	Before
	      that, ppmtompeg issued the warnings always.

	      The following statements apply only to parallel operation:

       PARALLEL
	      This statement, paired with END PARALLEL,	is what	causes ppmtom-
	      peg  to  operate	in  parallel  mode.   See  Parallel  Operation
	      <#parallel> .

       END PARALLEL
	      This goes	with PARALLEL.

       PARALLEL_TEST_FRAMES n
	      The master starts	off by measuring each slave's speed.  It  does
	      this by giving each slave	n frames to encode and noting how long
	      the slave	takes to finish.  These	 are  not  just	 test  frames,
	      though --	they're	real frames and	the results become part	of the
	      output.  ppmtompeg is old	and measures time  in  undivided  sec-
	      onds,  so	 to  get useful	timings, specify enough	frames that it
	      will take	at least 5 seconds to process them.   The  default  is
	      10.

	      If  you  specify FORCE_I_ALIGN, ppmtompeg	will increase the test
	      frames value enough to maintain the alignment.

	      If there aren't enough frames for	every slave to have the	 indi-
	      cated  number  of	 test  frames, ppmtompeg will give some	slaves
	      fewer.

       PARALLEL_TIME_CHUNKS t
	      When you specify this statement, the  master  attempts  to  feed
	      work to the slaves in chunks that	take t seconds to process.  It
	      uses the speed measurement it made when it started up (see  PAR-
	      ALLEL_TEST_FRAMES)  to  decide  how  many	 frames	 to put	in the
	      chunk.  This statement obviously doesn't affect the first	 batch
	      of work sent to each slave, which	is the one used	to measure the
	      slave's speed.

	      Smaller values of	t increase  communication,  but	 improve  load
	      balancing.  The default is 30 seconds.

	      You   may	 specify  only	one  of	 PARALLEL_TIME_CHUNKS,	PARAL-
	      LEL_CHUNK_TAPER, and PARALLEL_PERFECT.  PARALLEL_CHUNK_TAPER  is
	      usually best.

       PARALLEL_CHUNK_TAPER
	      When  you	 specify  this	statement, the master distributes work
	      like with	PARALLEL_TIME_CHUNKS, except that the  master  chooses
	      the  number  of  seconds for the chunks.	It starts with a large
	      number and, as it	gets closer to finishing the job, reduces  it.
	      That way,	it reduces scheduling overhead when precise scheduling
	      isn't helpful, but still prevents	a slave	from  finishing	 early
	      after  all  the  work  has  already been handed out to the other
	      slaves, and then sitting idle while there's still	work to	do.

	      You  may	specify	 only  one  of	PARALLEL_TIME_CHUNKS,	PARAL-
	      LEL_CHUNK_TAPER,	and PARALLEL_PERFECT.  PARALLEL_CHUNK_TAPER is
	      usually best.

       PARALLEL_PERFECT
	      If this statement	is present, ppmtompeg schedules	on the assump-
	      tion that	each machine is	about the same speed.  The master will
	      simply divide up the frames evenly between the  slaves  --  each
	      slave gets the same number of frames.  If	some slaves are	faster
	      than others, they	will finish first and remain  idle  while  the
	      slower slaves continue.

	      This  has	 the  advantage	of minimal scheduling overhead.	 Where
	      slaves have different speeds, though, it makes  inefficient  use
	      of  the fast ones.  Where	slaves are the same speed, it also has
	      the disadvantage that they all finish at the same	time and  feed
	      their  output  to	 the  single  Combine Server in	a burst, which
	      makes less efficient use of the Combine Server and thus can  in-
	      crease the total elapsed time.

	      You   may	 specify  only	one  of	 PARALLEL_TIME_CHUNKS,	PARAL-
	      LEL_CHUNK_TAPER, and PARALLEL_PERFECT.  PARALLEL_CHUNK_TAPER  is
	      usually best.

       RSH remote_shell_command
	      ppmtompeg	 executes  the	shell  command remote_shell_command to
	      start a process on another machine.  The default command is rsh,
	      and whatever command you specify must have compatible semantics.
	      ssh is usually compatible.  The command ppmtompeg	 uses  is  one
	      like this: ssh remote.host.com -l	username shellcommand.

	      Be  sure to set up .rhosts files or SSH key authorizations where
	      needed.  Otherwise, you'll have to type in passwords.

	      On some HP machines, rsh is the restricted shell,	and  you  want
	      to specify remsh.

       FORCE_I_ALIGN
	      This  statement  forces  each  slave to encode a chunk of	frames
	      which is a multiple of the pattern length	(see PATTERN).	 Since
	      the  first  frame	in any pattern is an I frame, this forces each
	      chunk encoded by a slave to begin	with an	I frame.

	      This document used to say	there was an argument to FORCE_I_ALIGN
	      which  was the number of frames ppmtompeg	would use (and was re-
	      quired to	be a multiple of the pattern length).	But  ppmtompeg
	      has apparently always ignored that argument, and it does now.

       KEEP_TEMP_FILES
	      This  statement  causes  ppmtompeg  not  to delete the temporary
	      files it uses to transmit	encoded	frames to the combine  server.
	      This means you will be left with a file for each frame, the same
	      as you would get with the	-frames	option.

	      This is mostly useful for	debugging.

	      This works only if you're	using a	shared filesystem to  communi-
	      cate between the servers.

	      This option was new in Netpbm 10.26 (January 2005).

   Parameter File Notes
	If you use the -combine_gops option, then you need to specify only the
       SIZE and	OUTPUT values in the parameter file.  In addition, the parame-
       ter 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 you specify no input
       GOP files, then ppmtompeg uses by default the  output  file  name  with
       suffix .gop.gop_num, with gop_num starting from 0, as the input files.

       If  you	use  the -combine_frames option, then you need to specify only
       the SIZE, GOP_SIZE, and OUTPUT values in	the parameter file.  In	 addi-
       tion, the parameter file	may specify input frame	files in the same man-
       ner 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, with 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 -com-
       bine_frames.

       The file	format is case-sensitive so all	keywords should	 be  in	 upper
       case.

       The  statements may appear in any order,	except that the	order within a
       block statement (such as	INPUT ... END INPUT) is	significant.

       ppmtompeg is prepared to	handle up to 16	 B  frames  between  reference
       frames  when encoding with input	from stdin.  (To build a modified ppm-
       tompeg with a higher limit, change the constant B_FRAME_RUN in  frame.c
       and recompile).

GENERAL	USAGE INFORMATION
   Qscale
       The quantization	scale values (qscale) give a trade-off between quality
       and compression.	 Using different Qscale	values has very	little	effect
       on  speed.   The	 qscale	 values	 can be	set separately for I, P, and B
       frames.

       You select the qscale values with the IQSCALE, PQSCALE, and BSCALE  pa-
       rameter file statements.

       A  qscale value is an integer from 1 to 31.  Larger numbers give	better
       compression, but	worse quality.	In the following, the quality  numbers
       are  peak  signal-to-noise  ratio,  defined as: signal-to-noise formula
       where MSE is the	mean squared error.

       Flower garden tests:

       Qscale vs Quality

       ----------------------------------------
       Qscale	I Frames   P Frames   B	Frames
	    1	    43.2       46.3	  46.5
	    6	    32.6       34.6	  34.3
	   11	    28.6       29.5	  30.0
	   16	    26.3       26.8	  28.6
	   21	    24.7       25.0	  27.9
	   26	    23.5       23.9	  27.5
	   31	    22.6       23.0	  27.3

       Qscale vs Compression

       ----------------------------------------
       Qscale	I Frames   P Frames   B	Frames
	    1	       2	  2	     2
	    6	       7	 10	    15
	   11	      11	 18	    43
	   16	      15	 29	    97
	   21	      19	 41	   173
	   26	      24	 56	   256
	   31	      28	 73	   330

   Search Techniques
       There are several different motion vector search	techniques  available.
       There are different techniques available	for P frame search and B frame
       search. Using different search techniques present little	difference  in
       quality,	but a large difference in compression and speed.

       There  are  4 types of P	frame search: Exhaustive, TwoLevel, SubSample,
       and Logarithmic.

       There are 3 types of B frame search: Exhaustive,	Cross2,	and Simple.

       The recommended search techniques are TwoLevel and  Logarithmic	for  P
       frame  search,  and Cross2 and Simple for B frame search. Here are some
       numbers comparing the different search methods:

       P frame Motion Vector Search (Normalized)

       ---------------------------------------------------------------------
	 Technique   Compression    1	Speed	       2   Quality	  3
		     <#smallbetter>	<#largefaster>	   <#largebetter>
	Exhaustive	   1000		      1000		 1000
	 SubSample	   1008		      2456		 1000
	  TwoLevel	   1009		      3237		 1000

       Logarithmic	   1085		      8229		 998

       B frame Motion Vector Search (Normalized)

       --------------------------------------------------------------------
	Technique   Compression	   1   Speed	      2	  Quality	 3
		    <#smallbetter>     <#largefaster>	  <#largebetter>
       Exhaustive	  1000		     1000		1000
	   Cross2	  975		     1000		996
	   Simple	  938		     1765		991

       1Smaller	numbers	are better compression.

       2Larger numbers mean faster execution.

       3Larger numbers mean better quality.

       For some	reason,	Simple seems to	give better compression,  but  it  de-
       pends on	the image sequence.

       Select  the  search techniques with the PSEARCH_ALG and BSEARCH_ALG pa-
       rameter file statements.

   Group Of Pictures (GOP)
       A Group of Pictures (GOP) is a roughly independently decodable sequence
       of frames.  An MPEG video stream	is made	of one or more GOP's.  You may
       specify how many	frames should be in each GOP with the GOP_SIZE parame-
       ter file	statement.  A GOP always starts	with an	I frame.

       Instead	of  encoding  an entire	sequence, you can encode a single GOP.
       To do this, use the -gop	command	option.	 You can later	join  the  re-
       sulting	GOP  files  at	any  time  by running ppmtompeg	with the -com-
       bine_gops command option.

   Slices
       A slice is an independently decodable unit in a frame.  It  can	be  as
       small as	one macroblock,	or it can be as	big as the entire frame.  Bar-
       ring transmission error,	adding	slices	does  not  change  quality  or
       speed;  the only	effect is slightly worse compression.  More slices are
       used for	noisy transmission so that errors are more recoverable.	 Since
       usually	errors	are  not such a	problem, we usually just use one slice
       per frame.

       Control the slice size with the SLICES_PER_FRAME	parameter file	state-
       ment.

       Some  MPEG  playback  systems  require that each	slice consist of whole
       rows of macroblocks.  If	you are	encoding for this kind of  player,  if
       the  height  of	the  image  is	H  pixels,  then  you  should  set the
       SLICES_PER_FRAME	to some	number which divides H/16.   For  example,  if
       the image is 240	pixels (15 macroblocks)	high, then you should use only
       15, 5, 3, or 1 slices per frame.

       Note: these MPEG	playback systems are  really  wrong,  since  the  MPEG
       standard	says this doesn't have to be so.

   Search Window
       The  search window is the window	in which ppmtompeg searches for	motion
       vectors.	 The window is a square.  You can  specify  the	 size  of  the
       square, and whether to allow half-pixel motion vectors or not, with the
       RANGE and PIXEL parameter file statements.

   I Frames, P Frames, B Frames
       In MPEG-1, a movie is represented as a sequence of MPEG frames, each of
       which  is  an I Frame, a	P Frame, or a B	Frame.	Each represents	an ac-
       tual frame of the movie (don't get confused by the dual use of the word
       "frame."	  A  movie frame is a graphical	image.	An MPEG	frame is a set
       of data that describes a	movie frame).

       An I frame ("intra" frame) describes a  movie  frame  in	 isolation  --
       without	respect	 to any	other frame in the movie.  A P frame ("predic-
       tive" frame) describes a	movie frame by describing how it differs  from
       the  movie  frame described by the latest preceding I  or P frame.  A B
       frame ("bidirectional" frame) describes a movie frame by	describing how
       it  differs from	the movie frames described by the nearest I or P frame
       before and after	it.

       Note that the first frame of a movie must be described by  an  I	 frame
       (because	 there	is  no	previous movie frame) and the last movie frame
       must be described by an I or P frame (because there  is	no  subsequent
       movie frame).

       Beyond  that,  you  can	choose	which  frames are represented by which
       types.  You specify a pattern, such as IBPBP and	ppmtompeg  simply  re-
       peats  it  over	and  over  throughout  the movie.  The pattern affects
       speed, quality, and stream size.	 Here is a chart which shows  some  of
       the trade-offs:

       Comparison of I/P/B Frames (Normalized)

       ------------------------------------
       Frame Type   Size   Speed   Quality
	 I frames   1000   1000	    1000
	 P frames   409	    609	     969
	 B frames    72	    260	     919

       (this is	with constant qscale)

       A standard sequence is IBBPBBPBBPBBPBB.

       Select the sequence with	the PATTERN parameter file statement.

       Since  the last MPEG frame cannot be a B	frame (see above), if the pat-
       tern you	specify	indicates a B frame for	the last movie	frame  of  the
       movie, ppmtompeg	makes it an I frame instead.

       Before  Netpbm 10.26 (January 2005), ppmtompeg instead drops the	trail-
       ing B frames by default,	and you	need the  FORCE_ENCODE_LAST_FRAME  pa-
       rameter file statement to make it do this.

       The  MPEG  frames  don't	 appear	in the MPEG-1 stream in	the same order
       that the	corresponding movie frames appear in the movie -- the B	frames
       come after the I	and P frames on	which they are based.  For example, if
       the movie is 4 frames that you will represent with  the	pattern	 IBBP,
       the  MPEG-1 stream will start with an I frame describing	movie frame 0.
       The next	frame in the MPEG-1 stream is a	P frame	describing movie frame
       3.   The	 last  two frames in the MPEG-1	stream are B frames describing
       movie frames 1 and 2, respectively.

   Specifying Input and	Output Files
       Specify the input frame images with the	INPUT_DIR,  INPUT,  END_INPUT,
       BASE_FILE_FORMAT,  SIZE,	 YUV_FORMAT  and  INPUT_CONVERT	parameter file
       statements.

       Specify the output file with the	OUTPUT parameter file statement.

   Statistics
       ppmtompeg can generate a	variety	of statistics about the	encoding.  See
       the   -stat,   -snr,   -mv_histogram,  -quiet,  -no_frame_summary,  and
       -bit_rate_info options.

PARALLEL OPERATION
       You can run ppmtompeg on	multiple machines at once, encoding  the  same
       MPEG  stream.   When you	do, the	machines are used as shown in the fol-
       lowing diagram.	We call	this "parallel mode."

       ppmtompeg-par.gif

       To do parallel processing, put the statement

	   PARALLEL

       in the parameter	file, followed by a listing of the machines,  one  ma-
       chine per line, then

	   END_PARALLEL

       Each  of	the machine lines must be in one of two	forms.	If the machine
       has filesystem access to	the input files, then the line is:

       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 does
       not have	filesystem access to the input files, the line is:

       REMOTE machine user executable parameter	file

       The -max_machines command option	limits the number of machines  ppmtom-
       peg  will use.  If you specify more machines in the parameter file than
       -max_machines allows, ppmtompeg uses only the  machines	listed	first.
       This  is	handy if you want to experiment	with different amounts of par-
       allelism.

       In general, you should use full path file names	when  describing  exe-
       cutables	 and  parameter	files.	This includes the parameter file argu-
       ment on the original invocation of ppmtompeg.

       All file	names must be the same on all systems (so if e.g. you're using
       an  NFS filesystem, you must make sure it is mounted at the same	mount-
       point on	all systems).

       Because not all of the processes	involved in  parallel  operation  have
       easy  access  to	 the  input files, you must specify the	SIZE parameter
       file statement when you do parallel operation.

       The machine on which you	originally invoke ppmtompeg is the master  ma-
       chine.	It  hosts a "combine server,", a "decode server," and a	number
       of "i/o servers," all as	separate processes.  The other machines	in the
       network	(listed	in the parameter file) are slave machines.  Each hosts
       a single	process	that continuously requests work	from  the  master  and
       does it.	 The slave process does	the computation	to encode MPEG frames.
       It processes frames in batches identified by the	master.

       The master uses a remote	shell command to start a process  on  a	 slave
       machine.	 By default, it	uses an	rsh shell command to do	this.  But use
       the RSH parameter file statement	to control this.   The	shell  command
       the master executes remotely is ppmtompeg, but with options to indicate
       that it is to perform slave functions.

       The various machines talk to each other over TCP	connections.  Each ma-
       chine  finds and	binds to a free	TCP port number	and tells its partners
       the port	number.	 These port numbers are	at least 2048.

       Use the PARALLEL_TEST_FRAMES, PARALLEL_TIME_CHUNKS,  and	 PARALLEL_PER-
       FECT parameter file statements to control the way the master divides up
       work among the slaves.

       Use the -nice command option  to	 cause	all  slave  processes  to  run
       "nicely,"  i.e.	as low priority	processes.  That way, this substantial
       and long-running	CPU load will have minimal impact on  other,  possibly
       interactive, users of the systems.

SPEED
       Here is a look at ppmtompeg speed, in single-node (not parallel)	opera-
       tion:

       Compression Speed

       ---------------------------------------
       Machine Type   Macroblocks per second1
	HP 9000/755		280
       DEC 3000/400		247
	HP 9000/750		191
	   Sparc 10		104
	   DEC 5000		68
       1A macroblock is	a 16x16	pixel square

       The measurements	in the table are with inputs and outputs via a conven-
       tional  locally	attached  filesystem.	If  you	 are  using  a network
       filesystem over a single	10 MB/s	Ethernet, that constrains  your	 speed
       more  than  your	 CPU  speed.  In that case, don't expect to get	better
       than 4 or 5 frames per second no	matter how fast	your CPUs are.

       Network speed is	even more of a bottleneck when the slaves do not  have
       filesystem access to the	input files -- i.e. you	declare	them REMOTE.

       Where  I/O  is  the bottleneck, size of the input frames	can make a big
       difference.  So YUV input is better than	PPM, and JPEG is  better  than
       both.

       When  you're  first trying to get parallel mode working,	be sure	to use
       the -debug_machines option so you can see what's	going on.  Also,  -de-
       bug_sockets can help you	diagnose communication problems.

AUTHORS
       o      Kevin   Gong   -	 University   of  California,  Berkeley,  kev-
	      ing@cs.berkeley.edu

       o      Ketan  Patel  -  University  of	California,   Berkeley,	  kpa-
	      tel@cs.berkeley.edu

       o      Dan   Wallach   -	 University  of	 California,  Berkeley,	 dwal-
	      lach@cs.berkeley.edu

       o      Darryl  Brown  -	University  of	California,   Berkeley,	  dar-
	      ryl@cs.berkeley.edu

       o      Eugene   Hung   -	  University   of  California,	Berkeley,  ey-
	      hung@cs.berkeley.edu

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

DOCUMENT SOURCE
       This  manual  page was generated	by the Netpbm tool 'makeman' from HTML
       source.	The master documentation is at

	      http://netpbm.sourceforge.net/doc/ppmtompeg.html

netpbm documentation		 23 July 2006	      Ppmtompeg	User Manual(0)

NAME | SYNOPSIS | DESCRIPTION | OPTIONS | PARAMETER FILE | GENERAL USAGE INFORMATION | PARALLEL OPERATION | SPEED | AUTHORS | DOCUMENT SOURCE

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=ppmtompeg&sektion=1&manpath=FreeBSD+12.2-RELEASE+and+Ports>

home | help