diff options
Diffstat (limited to 'upstream/mageia-cauldron/man1/ppmtompeg.1')
| -rw-r--r-- | upstream/mageia-cauldron/man1/ppmtompeg.1 | 1213 |
1 files changed, 1213 insertions, 0 deletions
diff --git a/upstream/mageia-cauldron/man1/ppmtompeg.1 b/upstream/mageia-cauldron/man1/ppmtompeg.1 new file mode 100644 index 00000000..6f4bfc57 --- /dev/null +++ b/upstream/mageia-cauldron/man1/ppmtompeg.1 @@ -0,0 +1,1213 @@ +\ +.\" This man page was generated by the Netpbm tool 'makeman' from HTML source. +.\" Do not hand-hack it! If you have bug fixes or improvements, please find +.\" the corresponding HTML page on the Netpbm website, generate a patch +.\" against that, and send it to the Netpbm maintainer. +.TH "Ppmtompeg User Manual" 0 "23 July 2006" "netpbm documentation" + +.SH NAME +ppmtompeg - encode an MPEG-1 bitstream + +.UN synopsis +.SH SYNOPSIS + +\fBppmtompeg\fP +[\fIoptions\fP] +\fIparameter-file\fP + +.UN description +.SH DESCRIPTION +.PP +This program is part of +.BR "Netpbm" (1)\c +\&. +.PP +\fBppmtompeg\fP produces an MPEG-1 video stream. MPEG-1 is the +first great video compression method, and is what is used in Video CDs +(VCD). \fBppmtompeg\fP 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. +.PP +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 +\fBppmtompeg\fP produces is MPEG-1. +.PP +Mencoder from the +.UR http://www.mplayerhq.hu +Mplayer package +.UE +\& is probably superior for most video format generation +needs, if for no other reason than that it is more popular. +.PP +The programming library +.UR http://pm2v.free.fr +\fBPM2V\fP +.UE +\& +generates MPEG-2 streams. +.PP +Use +.UR http://www.mplayerhq.hu +Mplayer +.UE +\& (not part of Netpbm) +to do the reverse conversion: to create a series of PNM files from an MPEG +stream. +.PP +\fIparam_file\fP is a parameter file which includes a list of +input files and other parameters. The file is described in detail +below. +.PP +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 +.UR http://www.faqs.org/faqs/compression-faq/ +Compression FAQ +.UE +\&. + +.UN options +.SH OPTIONS +.PP +The \fB-gop\fP, \fB-combine_gops\fP, \fB-frames\fP, and +\fB-combine_frames\fP options are all mutually exclusive. + + +.TP +\fB-stat stat_file\fP +This option causes \fBppmtompeg\fP to append the statistics that +it write to Standard Output to the file \fIstat_file\fP 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). +.sp +These statistics include how many I, P, and B frames there were, +and information about compression and quality. + + +.TP +\fB-quiet\fP \fInum_seconds\fP + causes \fBppmtompeg\fP not to report remaining time more often +than every \fInum_seconds\fP seconds (unless the time estimate rises, +which will happen near the beginning of the run). A negative value +tells \fBppmtompeg\fP 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. + +.TP +\fB-realquiet\fP + causes \fBppmtompeg\fP to run silently, +with the only screen output being errors. Particularly useful when +reading input from stdin. The equivalent of the \fB-quiet\fP +common option of most other Netpbm programs. + +.TP + +\fB-no_frame_summary\fP + This option prevents \fBppmtompeg\fP from printing a summary +line for each frame + +.TP +\fB-float_dct\fP + forces \fBppmtompeg\fP to use a more accurate, yet more +computationally expensive version of the DCT. + +.TP +\fB-gop\fP \fIgop_num\fP +causes \fBppmtompeg\fP 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 \fB.gop.\fP\fIgop_num\fP. +\fBppmtompeg\fP does not output any sequence information. + +.TP +\fB-combine_gops\fP + causes \fBppmtompeg\fP simply to combine some GOP files into a +single MPEG output stream. \fBppmtompeg\fP 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 +\fBppmtompeg\fP assumes you're using the same parameter file you used +when you created the input (with the \fB-gop\fP 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 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 \fB.gop.\fP\fIgop_num\fP, with \fIgop_num\fP +starting from 0, as the input files. +.sp +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 (\fB-gop\fP) and for later turning them into an MPEG stream +(\fB-combine_gops\fP). + + +.TP +\fB-frames \fIfirst_frame\fP \fIlast_frame\fP\fP +This option causes \fBppmtompeg\fP to encode only the frames numbered +\fIfirst_frame\fP to \fIlast_frame\fP, 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 name with the suffix \fB.frame.\fP\fIframe_num\fP. No +GOP header information is output. (Thus, the parameter file need not +include the GOP_SIZE value) +.sp +Use \fBppmtompeg -combine_frames\fP to combine these frames later into +an MPEG stream. + + +.TP +\fB-combine_frames\fP + This option causes \fBppmtompeg\fP simply to combine some +individual MPEG frames (such as you might have created with an earlier +run of \fBppmtompeg -frames\fP) into a single MPEG stream. Sequence +and GOP headers are inserted appropriately. In this case, the +parameter file needs to contain only the SIZE value, the GOP_SIZE +value, an output file, and perhaps a list of frame files (see below). +.sp +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 \fB.frame.\fP\fIframe_num\fP, with +\fIframe_num\fP starting from 0, as the input files. + + + +.TP +\fB-nice\fP +This option causes \fBppmtompeg\fP to run any remote processes +"nicely," i.e. at low priority. (This is relevant only if you are +running \fBppmtompeg\fP in parallel mode. Otherwise, there are no +remote processes). See 'man nice.' + +.TP +\fB-max_machines \fInum_machines\fP\fP +This option causes \fBppmtompeg\fP to use no more than +\fInum_machines\fP machines as slaves for use in parallel encoding. + +.TP +\fB-snr\fP +This option causes \fBppmtompeg\fP to include the signal-to-noise +ratio in the reported statistics. 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 original/variance of +error). Peak SNR is defined as 20*log(255/RMSE). Note that +\fBppmtompeg\fP runs a little slower when you use this option. + +.TP +\fB-mse\fP +This option causes \fBppmtompeg\fP to report the mean squared +error per block. It also automatically reports the quality of the +images, so there is no need to specify \fB-snr\fP then. + +.TP +\fB-bit_rate_info\fP \fIrate_file\fP + This option makes \fBppmtompeg\fP write bit rate information +into the file \fIrate_file\fP. Bit rate information is bits per frame, and +also bits per I-frame-to-I-frame. + +.TP +\fB-mv_histogram\fP + This option causes \fBppmtompeg\fP 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. +.sp +The output is in the form of a matrix, each entry corresponding to one +motion vector in the search window. The center of the matrix +represents (0,0) motion vectors. + +.TP +\fB-debug_sockets\fP +This option causes \fBppmtompeg\fP to print to Standard Output +messages that narrate the communication between the machines when you run +\fBppmtompeg\fP in +.UR #parallel +parallel mode +.UE +\&. + +.TP +\fB-debug_machines\fP +This option causes \fBppmtompeg\fP to print to Standard Output +messages that narrate the progress of the conversion on the various +machines when you run \fBppmtompeg\fP in +.UR #parallel +parallel mode +.UE +\&. + + + +.UN parmfile +.SH PARAMETER FILE +.PP +The parameter file \fBmust\fP contain the following +lines (except when using the \fB-combine_gops\fP or \fB-combine_frames\fP +options): + + + +.TP +\fBPATTERN\fP \fIpattern\fP +This statement specifies the pattern (sequence) of I frames, P frames, +and B frames. \fIpattern\fP is just a sequence of the letters I, P, and +B with nothing between. Example: + +.nf + PATTERN IBBPBBPBBPBBPBB +</pre> +.sp +See +.UR #ipb +I Frames, P Frames, B Frames +.UE +\&. + +.TP +\fBOUTPUT\fP \fIoutput file\fP +This names the file where the output MPEG stream goes. + +.TP +\fBINPUT_DIR\fP \fIdirectory\fP +This statement tells where the input images (frames) come from. +If each frame is in a separate file, \fIdirectory\fP is the directory +where they all are. You may use \fB.\fP to refer to the current +directory. A null \fIdirectory\fP refers to the root directory of the +system file tree. +.sp +To have \fBppmtompeg\fP read all the frames serially from Standard +Input, specify +.nf + INPUT_DIR stdin + +.fi + +.TP +\fBINPUT\fP +This line must be followed by a list of the input files (in display order) +and then the line \fBEND_INPUT\fP. +.sp +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 \fIsingle_star_expr\fP +\fB[\fP\fIx\fP\fB-\fP\fIy\fP\fB]\fP. +\fIsingle_star_expr\fP can have a single \fB*\fP in it. It is +replaced by all the numbers between x and y inclusive. So, for +example, the line \fBtennis*.ppm [12-15]\fP refers to the files +tennis12.ppm, tennis13.ppm, tennis14.ppm, tennis15.ppm. +.sp +Uniform zero-padding occurs, as well. For example, the line +\fBfootball.*.ppm [001-130]\fP refers to the files football.001.ppm, +football.002.ppm, ..., football.009.ppm, football.010.ppm, ..., +football.130.ppm. +.sp +The third type of line is: \fIsingle_star_expr\fP +\fB[\fP\fIx\fP\fB-\fP\fIy\fP\fB+\fP\fIs\fP\fB]\fP, where the +line is treated exactly as above, except that we skip by \fIs\fP. Thus, the +line \fBfootball.*.ppm [001-130+4]\fP refers to the files +football.001.ppm, football.005.ppm, football.009.ppm, +football.013.ppm, etc. +.sp +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: + +.nf + `cat myfilelist` + +.fi +.sp +If input is from Standard Input (per the \fBINPUT_DIR\fP statement), +\fBppmtompeg\fP ignores the \fBINPUT\fP/\fBEND_INPUT\fP block, but +it still must be present. + +.TP +\fBBASE_FILE_FORMAT\fP {\fBPPM\fP | \fBPNM\fP | \fBYUV\fP | + \fBJPEG\fP | \fBJMOVIE\fP} +\fBppmtompeg\fP 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 backward compatibility. Use PNM instead +of PPM in new applications. + +.TP +\fBINPUT_CONVERT\fP \fIconversion_command\fP +You must specify how to convert a file to the base file format. +If no conversion is necessary, then you would just say: + +.nf + INPUT_CONVERT * + +.fi +.sp +Otherwise, \fIconversion_command\fP is a shell command that causes +an image in the format your specified with \fBBASE_FILE_FORMAT\fP to +be written to Standard Output. \fBppmtompeg\fP executes the command +once for each line between \fBINPUT\fP and \fBEND_INPUT\fP (which is +normally, but not necessarily, a file name). In the conversion +command, \fBppmtompeg\fP replaces each '*' with the contents of that +line. + + If you had a bunch of gif files, you might say: +.nf + INPUT_CONVERT giftopnm * + +.fi + + 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: + +.nf + INPUT_CONVERT cat *.Y *.U *.V + +.fi +.sp +Input conversion is not allowed with input from stdin, so use + +.nf + INPUT_CONVERT * + +.fi + +as described above. + +.TP +\fBSIZE\fP \fIwidth\fP\fBx\fP\fIheight\fP +.sp +\fIwidth\fP and \fIheight\fP are the width and height of each +frame in pixels. +.sp +When \fBppmtompeg\fP can get this information from the input image +files, it ignores the \fBSIZE\fP parameter and you may omit it. +.sp +When the image files are in YUV format, the files don't contain +dimension information, so \fBSIZE\fP is required. +.sp +When \fBppmtompeg\fP is running in parallel mode, not all of the +processes in the network have access to the image files, so +\fBSIZE\fP is required and must give the same dimensions as the +input image files. + +.TP +\fBYUV_SIZE\fP \fIwidth\fP\fBx\fP\fIheight\fP +This is an obsolete synonym of \fBSIZE\fP. + +.TP +\fBYUV_FORMAT\fP {\fBABEKAS\fP | \fBPHILLIPS\fP | \fBUCB\fP | + \fBEYUV\fP | \fIpattern\fP} +This is meaningful only when \fBBASE_FILE_FORMAT\fP specifies +YUV format, and then it is required. It specifies the sub-format of +the YUV class. + + +.TP +\fBGOP_SIZE\fP \fIn\fP +\fIn\fP is the number of frames in a Group of Pictures. Except that +because a GOP must start with an I frame, \fBppmtompeg\fP makes a GOP as +much longer than \fIn\fP as it has to to make the next GOP start with an +I frame. +.sp +Normally, it makes sense to make your GOP size a multiple of your +pattern length (the latter is determined by the PATTERN parameter file +statement). +.sp +See +.UR #gop +Group Of Pictures +.UE +\&. + +.TP +\fBSLICES_PER_FRAME\fP \fIn\fP +\fIn\fP is roughly the number of slices per frame. Note, at +least one MPEG player may complain if slices do not start at the left +side of an image. To ensure this does not happen, make sure the +number of rows is divisible by SLICES_PER_FRAME. + +.TP +\fBPIXEL\fP {\fBFULL\fP | \fBHALF\fP} +use half-pixel motion vectors, or just full-pixel ones It is +usually important that you use half-pixel motion vectors, because it +results in both better quality and better compression. + + +.TP +\fBRANGE\fP \fIn\fP +Use a search range of \fIn\fP pixels in each of the four directions +from a subject pixel. (So the search window is a square \fIn\fP*2 pixels +on a side). + +.TP +\fBPSEARCH_ALG\fP {\fBEXHAUSTIVE\fP | \fBTWOLEVEL\fP | + \fBSUBSAMPLE\fP | \fBLOGARITHMIC\fP} +This statement tells \fBppmtompeg\fP what kind of search + technique (algorithm) to use for P frames. You select the desired + combination of speed and compression. \fBEXHAUSTIVE\fP gives the + best compression, but \fBLOGARITHMIC\fP is the fastest. + \fBTWOLEVEL\fP 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). + +.TP +\fBBSEARCH_ALG\fP {\fBSIMPLE\fP | \fBCROSS2\fP | \fBEXHAUSTIVE\fP} +This statement tells \fBppmtompeg\fP what kind of search + technique (algorithm) to use for B frames. \fBSIMPLE\fP means + find best forward and backward vectors, then interpolate. + \fBCROSS2\fP means find those two vectors, then see what backward + vector best matches the best forward vector, and vice versa. + \fBEXHAUSTIVE\fP does an n-squared search and is + \fIextremely\fP slow in relation to the others (\fBCROSS2\fP + is about half as fast as \fBSIMPLE\fP). + +.TP +\fBIQSCALE\fP \fIn\fP +Use \fIn\fP as the qscale for I frames. + See +.UR #qscale +Qscale +.UE +\&. + +.TP +\fBPQSCALE\fP \fIn\fP +Use \fIn\fP as the qscale for P frames. + See +.UR #qscale +Qscale +.UE +\&. + +.TP +\fBBQSCALE\fP \fIn\fP +Use \fIn\fP as the qscale for B frames. + See +.UR #qscale +Qscale +.UE +\&. + +.TP +\fBREFERENCE_FRAME\fP {\fBORIGINAL\fP | \fBDECODED\fP} +This +statement determines whether \fBppmtompeg\fP uses the original images +or the decoded images when computing motion vectors. Using 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 parallel encoding). One thing you can +do as a trade-off is select \fBORIGINAL\fP here, and lower the +qscale (see \fBQSCALE\fP if the quality is not good enough. + +.B Original or Decoded? (Normalized) +.TS +r c c c c c. +_ +Reference Compression Speed Quality I Quality P Quality B +Decoded 1000 1000 1000 969 919 +Original 885 1373 1000 912 884 +.TE + + + + + +.PP +The following lines are optional: + + + +.TP +\fBFORCE_ENCODE_LAST_FRAME\fP +This statement is obsolete. It does nothing. +.sp +Before Netpbm 10.26 (January 2005), \fBppmtompeg\fP would drop +trailing B frames from your movie, since a movie can't end with a B +frame. (See +.UR #ipb +I Frames, P Frames, B Frames +.UE +\&.) +You would have to specify \fBFORCE_ENCODE_LAST_FRAME\fP to stop +that from happening and get the same function that \fBppmtompeg\fP +has today. + + +.TP +\fBNIQTABLE\fP +This statement specifies a custom non-intra quantization table. +If you don't specify this statement, \fBppmtompeg\fP uses a default +non-intra quantization table. +.sp +The 8 lines immediately following \fBNIQTABLE\fP specify the quantization +table. Each line defines a table row and consists of 8 integers, +whitespace-delimited, which define the table columns. + +.TP +\fBIQTABLE\fP +This is analogous to NIQTABLE, but for the intra quantization table. + +.TP +\fBASPECT_RATIO\fP \fIratio\fP +This statement specifies the aspect ratio for \fBppmtompeg\fP to +specify in the MPEG output. I'm not sure what this is used for. +.sp +\fIratio\fP 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. + +.TP +\fBFRAME_RATE\fP \fIrate\fP +This specifies the frame rate for \fBppmtompeg\fP to specify in the +MPEG output. Some players use this value to determine the playback rate. +.sp +\fIrate\fP must be 23.976, 24, 25, 29.97, 30, 50, 59.94, or 60. + +.TP +\fBBIT_RATE\fP \fIrate\fP +This specifies the bit rate for Constant Bit Rate (CBR) encoding. +.sp +\fIrate\fP must be an integer. + +.TP +\fBBUFFER_SIZE\fP \fIsize\fP +This specifies the value +\fBppmtompeg\fP is to specify in the MPEG output for the Video +Buffering Verifier (VBV) buffer size needed to decode the sequence. +.sp +A Video Verifying Buffer is a buffer in which a decoder keeps the +decoded bits in order to match the uneven speed of the decoding with +the required constant playback speed. +.sp +As \fBppmtompeg\fP 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. +.sp +If you specify the \fBWARN_VBV_UNDERFLOW\fP statement, +\fBppmtompeg\fP issues 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. +.sp +If you specify the \fBWARN_VBV_OVERFLOW\fP statement, +\fBppmtompeg\fP issues a warning each time the simulation overflows +the buffer, which suggests that an overflow would occur on playback, +which suggests the buffer is too small. + +.TP +\fBWARN_VBV_UNDERFLOW\fP +.TP +\fBWARN_VBV_OVERFLOW\fP +See \fBBUFFER_SIZE\fP. +.sp +These options were new in Netpbm 10.26 (January 2005). Before that, +\fBppmtompeg\fP issued the warnings always. + + + + +The following statements apply only to parallel operation: + + + +.TP +\fBPARALLEL\fP +This statement, paired with \fBEND PARALLEL\fP, is what causes +\fBppmtompeg\fP to operate in parallel mode. See +.UR #parallel +Parallel Operation +.UE +\&. + +.TP +\fBEND PARALLEL\fP +This goes with \fBPARALLEL\fP. + +.TP +\fBPARALLEL_TEST_FRAMES\fP \fIn\fP +The master starts off by measuring each slave's speed. It does +this by giving each slave \fIn\fP 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. +\fBppmtompeg\fP is old and measures time in undivided seconds, so +to get useful timings, specify enough frames that it will take at +least 5 seconds to process them. The default is 10. +.sp +If you specify \fBFORCE_I_ALIGN\fP, \fBppmtompeg\fP will increase +the test frames value enough to maintain the alignment. +.sp +If there aren't enough frames for every slave to have the indicated +number of test frames, \fBppmtompeg\fP will give some slaves fewer. + + +.TP +\fBPARALLEL_TIME_CHUNKS\fP \fIt\fP +When you specify this statement, the master attempts to feed work +to the slaves in chunks that take \fIt\fP seconds to process. It uses +the speed measurement it made when it started up (see PARALLEL_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. +.sp +Smaller values of \fIt\fP increase communication, but improve load +balancing. The default is 30 seconds. +.sp +You may specify only one of PARALLEL_TIME_CHUNKS, PARALLEL_CHUNK_TAPER, +and PARALLEL_PERFECT. PARALLEL_CHUNK_TAPER is usually best. + +.TP +\fBPARALLEL_CHUNK_TAPER\fP +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. +.sp +You may specify only one of PARALLEL_TIME_CHUNKS, PARALLEL_CHUNK_TAPER, +and PARALLEL_PERFECT. PARALLEL_CHUNK_TAPER is usually best. + + +.TP +\fBPARALLEL_PERFECT\fP +If this statement is present, \fBppmtompeg\fP schedules on the +assumption 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. +.sp +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 increase the total elapsed time. +.sp +You may specify only one of PARALLEL_TIME_CHUNKS, PARALLEL_CHUNK_TAPER, +and PARALLEL_PERFECT. PARALLEL_CHUNK_TAPER is usually best. + +.TP +\fBRSH\fP \fIremote_shell_command\fP +\fBppmtompeg\fP executes the shell command +\fIremote_shell_command\fP to start a process on another machine. +The default command is \fBrsh\fP, and whatever command you specify +must have compatible semantics. \fBssh\fP is usually compatible. +The command \fBppmtompeg\fP uses is one like this: +\fBssh remote.host.com -l username shellcommand\fP. +.sp +Be sure to set up \fB.rhosts\fP files or SSH key authorizations +where needed. Otherwise, you'll have to type in passwords. +.sp +On some HP machines, \fBrsh\fP is the restricted shell, and you want +to specify \fBremsh\fP. + +.TP +\fBFORCE_I_ALIGN\fP +This statement forces each slave to encode a chunk of frames which +is a multiple of the pattern length (see \fBPATTERN\fP). 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. +.sp +This document used to say there was an argument to +\fBFORCE_I_ALIGN\fP which was the number of frames \fBppmtompeg\fP +would use (and was required to be a multiple of the pattern length). +But \fBppmtompeg\fP has apparently always ignored that argument, and +it does now. + +.TP +\fBKEEP_TEMP_FILES\fP +This statement causes \fBppmtompeg\fP 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 \fB-frames\fP option. +.sp +This is mostly useful for debugging. +.sp +This works only if you're using a shared filesystem to communicate +between the servers. +.sp +This option was new in Netpbm 10.26 (January 2005). + + + + +.UN parameterfile +.SS Parameter File Notes +.PP + If you use the \fB-combine_gops\fP option, then you need to specify +only the SIZE and OUTPUT values 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 you specify no input GOP files, then \fBppmtompeg\fP uses by default the +output file name with suffix \fB.gop.\fP\fIgop_num\fP, with \fIgop_num\fP +starting from 0, as the input files. +.PP +If you use the \fB-combine_frames\fP option, then you need to +specify only the SIZE, GOP_SIZE, and OUTPUT values 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 +\fB.frame.\fP\fIframe_num\fP, with \fIframe_num\fP starting from 0, +as the input files. +.PP +Any number of spaces and tabs may come between each option and value. Lines +beginning with \fB#\fP 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 \fB-combine_gops\fP and +\fB-combine_frames\fP. +.PP +The file format is case-sensitive so all keywords should be in +upper case. +.PP +The statements may appear in any order, except that the order within +a block statement (such as INPUT ... END INPUT) is significant. +.PP +\fBppmtompeg\fP is prepared to handle up to 16 B frames between +reference frames when encoding with input from stdin. (To build a +modified \fBppmtompeg\fP with a higher limit, change the constant +B_FRAME_RUN in frame.c and recompile). + +.UN general +.SH GENERAL USAGE INFORMATION + +.UN qscale +.SS Qscale +.PP +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. +.PP +You select the qscale values with the \fBIQSCALE\fP, +\fBPQSCALE\fP, and \fBBSCALE\fP parameter file statements. +.PP +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: +.B signal-to-noise formula +.IMG -C ppmtompeg-snr.gif +where MSE is the mean squared error. + +.PP +Flower garden tests: + +.B Qscale vs Quality +.TS +r r r r. +_ +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 +.TE + +.B Qscale vs Compression +.TS +r r r r. +_ +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 +.TE + + +.UN searchtech +.SS Search Techniques + +.PP +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. + +.PP +There are 4 types of P frame search: Exhaustive, TwoLevel, +SubSample, and Logarithmic. + +.PP +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: + +.B P frame Motion Vector Search (Normalized) +.TS +r c c c. +_ +Technique T{ +Compression +.UR #smallbetter +\u1\d +.UE +T} T{ +Speed +.UR #largefaster +\u2\d +.UE +T} T{ +Quality +.UR #largebetter +\u3\d +.UE +T} +Exhaustive 1000 1000 1000 +SubSample 1008 2456 1000 +TwoLevel 1009 3237 1000 +Logarithmic 1085 8229 998 +.TE + +.B B frame Motion Vector Search (Normalized) +.TS +r c c c. +_ +Technique T{ +Compression +.UR #smallbetter +\u1\d +.UE +T} T{ +Speed +.UR #largefaster +\u2\d +.UE +T} T{ +Quality +.UR #largebetter +\u3\d +.UE +T} +Exhaustive 1000 1000 1000 +Cross2 975 1000 996 +Simple 938 1765 991 +.TE + +.UN smallbetter +\u1\dSmaller numbers are better +compression. + +.UN largefaster +\u2\dLarger numbers mean faster +execution. + +.UN largebetter +\u3\dLarger numbers mean better quality. +.PP +For some reason, Simple seems to give better compression, but it +depends on the image sequence. +.PP +Select the search techniques with the \fBPSEARCH_ALG\fP and +\fBBSEARCH_ALG\fP parameter file statements. + + +.UN gop +.SS Group Of Pictures (GOP) +.PP +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 +\fBGOP_SIZE\fP parameter file statement. A GOP always starts with an +I frame. +.PP +Instead of encoding an entire sequence, you can encode a single +GOP. To do this, use the \fB-gop\fP command option. You can later +join the resulting GOP files at any time by running \fBppmtompeg\fP +with the \fB-combine_gops\fP command option. + + +.UN slices +.SS Slices +.PP +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. +Barring 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. + +.PP +Control the slice size with the \fBSLICES_PER_FRAME\fP parameter +file statement. +.PP +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. + +.PP +Note: these MPEG playback systems are really wrong, since the MPEG +standard says this doesn't have to be so. + + + +.UN searchwindow +.SS Search Window + +.PP +The search window is the window in which \fBppmtompeg\fP 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 \fBRANGE\fP and \fBPIXEL\fP parameter file statements. + +.UN ipb +.SS I Frames, P Frames, B Frames +.PP +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 actual 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). +.PP +An I frame ("intra" frame) describes a movie frame in isolation -- +without respect to any other frame in the movie. A P frame +("predictive" 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 \fIand\fP after it. +.PP +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). +.PP +Beyond that, you can choose which frames are represented by which +types. You specify a pattern, such as IBPBP and \fBppmtompeg\fP +simply repeats 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: + +.B Comparison of I/P/B Frames (Normalized) +.TS +r c c c. +_ +Frame Type Size Speed Quality +I frames 1000 1000 1000 +P frames 409 609 969 +B frames 72 260 919 +.TE + +(this is with constant qscale) + +.PP +A standard sequence is IBBPBBPBBPBBPBB. + +.PP +Select the sequence with the \fBPATTERN\fP parameter file statement. +.PP +Since the last MPEG frame cannot be a B frame (see above), if the +pattern you specify indicates a B frame for the last movie frame of +the movie, \fBppmtompeg\fP makes it an I frame instead. +.PP +Before Netpbm 10.26 (January 2005), \fBppmtompeg\fP instead drops +the trailing B frames by default, and you need the +\fBFORCE_ENCODE_LAST_FRAME\fP parameter file statement to make it do +this. +.PP +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. + + +.UN iofiles +.SS Specifying Input and Output Files +.PP +Specify the input frame images with the \fBINPUT_DIR\fP, +\fBINPUT\fP, \fBEND_INPUT\fP, \fBBASE_FILE_FORMAT\fP, +\fBSIZE\fP, \fBYUV_FORMAT\fP and \fBINPUT_CONVERT\fP parameter +file statements. +.PP +Specify the output file with the \fBOUTPUT\fP parameter file statement. + + +.UN statistics +.SS Statistics +.PP +\fBppmtompeg\fP can generate a variety of statistics about the +encoding. See the \fB-stat\fP, \fB-snr\fP, \fB-mv_histogram\fP, +\fB-quiet\fP, \fB-no_frame_summary\fP, and \fB-bit_rate_info\fP +options. + + +.UN parallel +.SH PARALLEL OPERATION +.PP +You can run \fBppmtompeg\fP on multiple machines at once, encoding +the same MPEG stream. When you do, the machines are used as shown in +the following diagram. We call this "parallel mode." +.PP +.B ppmtompeg-par.gif +.IMG -C ppmtompeg-par.gif +.PP +To do parallel processing, put the statement + +.nf + PARALLEL + +.fi + +in the parameter file, followed by a listing of the machines, one +machine per line, then + +.nf + END_PARALLEL + +.fi + +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: +.PP +\fImachine\fP \fIuser\fP \fIexecutable\fP +.PP +The executable is normally \fBppmtompeg\fP (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: +.PP +\fBREMOTE\fP \fImachine\fP \fIuser\fP \fIexecutable\fP +\fIparameter file\fP +.PP +The \fB-max_machines\fP command option limits the number of +machines \fBppmtompeg\fP will use. If you specify more machines in +the parameter file than \fB-max_machines\fP allows, \fBppmtompeg\fP +uses only the machines listed first. This is handy if you want to +experiment with different amounts of parallelism. +.PP +In general, you should use full path file names when describing +executables and parameter files. This \fIincludes\fP the parameter +file argument on the original invocation of \fBppmtompeg\fP. +.PP +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 +mountpoint on all systems). +.PP +Because not all of the processes involved in parallel operation +have easy access to the input files, you must specify the \fBSIZE\fP +parameter file statement when you do parallel operation. +.PP +The machine on which you originally invoke \fBppmtompeg\fP is the +master machine. 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. +.PP +The master uses a remote shell command to start a process on a +slave machine. By default, it uses an \fBrsh\fP shell command to do +this. But use the \fBRSH\fP parameter file statement to control +this. The shell command the master executes remotely is +\fBppmtompeg\fP, but with options to indicate that it is to perform +slave functions. +.PP +The various machines talk to each other over TCP connections. Each +machine finds and binds to a free TCP port number and tells its +partners the port number. These port numbers are at least 2048. +.PP +Use the PARALLEL_TEST_FRAMES, PARALLEL_TIME_CHUNKS, and +PARALLEL_PERFECT parameter file statements to control the way the +master divides up work among the slaves. +.PP +Use the \fB-nice\fP 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. + +.UN speed +.SH SPEED +.PP +Here is a look at \fBppmtompeg\fP speed, in single-node (not parallel) +operation: + +.B Compression Speed +.TS +r c. +_ +Machine Type Macroblocks per second\u1\d +HP 9000/755 280 +DEC 3000/400 247 +HP 9000/750 191 +Sparc 10 104 +DEC 5000 68 +.TE +\u1\dA macroblock is a 16x16 pixel square +.PP +The measurements in the table are with inputs and outputs via a +conventional 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. +.PP +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. +.PP +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. +.PP +When you're first trying to get parallel mode working, be sure to +use the \fB-debug_machines\fP option so you can see what's going on. +Also, \fB-debug_sockets\fP can help you diagnose communication +problems. + + +.UN authors +.SH AUTHORS + + + +.IP \(bu +Kevin Gong - University of California, Berkeley, \fIkeving@cs.berkeley.edu\fP + +.IP \(bu +Ketan Patel - University of California, Berkeley, \fIkpatel@cs.berkeley.edu\fP + +.IP \(bu +Dan Wallach - University of California, Berkeley, \fIdwallach@cs.berkeley.edu\fP + +.IP \(bu +Darryl Brown - University of California, Berkeley, \fIdarryl@cs.berkeley.edu\fP + +.IP \(bu +Eugene Hung - University of California, Berkeley, \fIeyhung@cs.berkeley.edu\fP + +.IP \(bu +Steve Smoot - University of California, Berkeley, \fIsmoot@cs.berkeley.edu\fP +.SH DOCUMENT SOURCE +This manual page was generated by the Netpbm tool 'makeman' from HTML +source. The master documentation is at +.IP +.B http://netpbm.sourceforge.net/doc/ppmtompeg.html +.PP
\ No newline at end of file |