| 1 |
\ |
| 2 |
.\" This man page was generated by the Netpbm tool 'makeman' from HTML source. |
| 3 |
.\" Do not hand-hack it! If you have bug fixes or improvements, please find |
| 4 |
.\" the corresponding HTML page on the Netpbm website, generate a patch |
| 5 |
.\" against that, and send it to the Netpbm maintainer. |
| 6 |
.TH "Ppmtompeg User Manual" 1 "23 July 2006" "netpbm documentation" |
| 7 |
|
| 8 |
.SH NAME |
| 9 |
ppmtompeg - encode an MPEG-1 bitstream |
| 10 |
|
| 11 |
.UN synopsis |
| 12 |
.SH SYNOPSIS |
| 13 |
|
| 14 |
\fBppmtompeg\fP |
| 15 |
[\fIoptions\fP] |
| 16 |
\fIparameter-file\fP |
| 17 |
|
| 18 |
.UN description |
| 19 |
.SH DESCRIPTION |
| 20 |
.PP |
| 21 |
This program is part of |
| 22 |
.BR "Netpbm" (1)\c |
| 23 |
\&. |
| 24 |
.PP |
| 25 |
\fBppmtompeg\fP produces an MPEG-1 video stream. MPEG-1 is the |
| 26 |
first great video compression method, and is what is used in Video CDs |
| 27 |
(VCD). \fBppmtompeg\fP originated in the year 1995. DVD uses a more |
| 28 |
advanced method, MPEG-2. There is an even newer method called MPEG-4 |
| 29 |
which is also called Divx. I don't know where one finds that used. |
| 30 |
.PP |
| 31 |
There's technically a difference between a compression method for |
| 32 |
video and an actual file (stream) format for a movie, and I don't know |
| 33 |
if it can be validly said that the format of the stream |
| 34 |
\fBppmtompeg\fP produces is MPEG-1. |
| 35 |
.PP |
| 36 |
Mencoder from the |
| 37 |
.UR http://www.mplayerhq.hu |
| 38 |
Mplayer package |
| 39 |
.UE |
| 40 |
\& is probably superior for most video format generation |
| 41 |
needs, if for no other reason than that it is more popular. |
| 42 |
.PP |
| 43 |
The programming library |
| 44 |
.UR http://pm2v.free.fr |
| 45 |
\fBPM2V\fP |
| 46 |
.UE |
| 47 |
\& |
| 48 |
generates MPEG-2 streams. |
| 49 |
.PP |
| 50 |
Use |
| 51 |
.UR http://www.mplayerhq.hu |
| 52 |
Mplayer |
| 53 |
.UE |
| 54 |
\& (not part of Netpbm) |
| 55 |
to do the reverse conversion: to create a series of PNM files from an MPEG |
| 56 |
stream. |
| 57 |
.PP |
| 58 |
\fIparam_file\fP is a parameter file which includes a list of |
| 59 |
input files and other parameters. The file is described in detail |
| 60 |
below. |
| 61 |
.PP |
| 62 |
To understand this program, you need to understand something about |
| 63 |
the complex MPEG-1 format. One source of information about this |
| 64 |
standard format is the section Introduction to MPEG in the |
| 65 |
.UR http://www.faqs.org/faqs/compression-faq/ |
| 66 |
Compression FAQ |
| 67 |
.UE |
| 68 |
\&. |
| 69 |
|
| 70 |
.UN options |
| 71 |
.SH OPTIONS |
| 72 |
.PP |
| 73 |
The \fB-gop\fP, \fB-combine_gops\fP, \fB-frames\fP, and |
| 74 |
\fB-combine_frames\fP options are all mutually exclusive. |
| 75 |
|
| 76 |
|
| 77 |
.TP |
| 78 |
\fB-stat stat_file\fP |
| 79 |
This option causes \fBppmtompeg\fP to append the statistics that |
| 80 |
it write to Standard Output to the file \fIstat_file\fP as well. The |
| 81 |
statistics use the following abbreviations: bits per block (bpb), bits |
| 82 |
per frame (bpf), seconds per frame (spf), and bits per second (bps). |
| 83 |
.sp |
| 84 |
These statistics include how many I, P, and B frames there were, |
| 85 |
and information about compression and quality. |
| 86 |
|
| 87 |
|
| 88 |
.TP |
| 89 |
\fB-quiet\fP \fInum_seconds\fP |
| 90 |
causes \fBppmtompeg\fP not to report remaining time more often |
| 91 |
than every \fInum_seconds\fP seconds (unless the time estimate rises, |
| 92 |
which will happen near the beginning of the run). A negative value |
| 93 |
tells \fBppmtompeg\fP not to report at all. 0 is the default |
| 94 |
(reports once after each frame). Note that the time remaining is an |
| 95 |
estimate and does not take into account time to read in frames. |
| 96 |
|
| 97 |
.TP |
| 98 |
\fB-realquiet\fP |
| 99 |
causes \fBppmtompeg\fP to run silently, |
| 100 |
with the only screen output being errors. Particularly useful when |
| 101 |
reading input from stdin. The equivalent of the \fB-quiet\fP |
| 102 |
common option of most other Netpbm programs. |
| 103 |
|
| 104 |
.TP |
| 105 |
|
| 106 |
\fB-no_frame_summary\fP |
| 107 |
This option prevents \fBppmtompeg\fP from printing a summary |
| 108 |
line for each frame |
| 109 |
|
| 110 |
.TP |
| 111 |
\fB-float_dct\fP |
| 112 |
forces \fBppmtompeg\fP to use a more accurate, yet more |
| 113 |
computationally expensive version of the DCT. |
| 114 |
|
| 115 |
.TP |
| 116 |
\fB-gop\fP \fIgop_num\fP |
| 117 |
causes \fBppmtompeg\fP to encode only the numbered GOP (first GOP is 0). The |
| 118 |
parameter file is the same as for normal usage. The output file will be |
| 119 |
the normal output file with the suffix \fB.gop.\fP\fIgop_num\fP. |
| 120 |
\fBppmtompeg\fP does not output any sequence information. |
| 121 |
|
| 122 |
.TP |
| 123 |
\fB-combine_gops\fP |
| 124 |
causes \fBppmtompeg\fP simply to combine some GOP files into a |
| 125 |
single MPEG output stream. \fBppmtompeg\fP inserts a sequence header |
| 126 |
and trailer. In this case, the parameter file needs only to contain |
| 127 |
the SIZE value, an output file, and perhaps a list of input GOP |
| 128 |
files (see below). |
| 129 |
|
| 130 |
If you don't supply a list of input GOP files is used, then |
| 131 |
\fBppmtompeg\fP assumes you're using the same parameter file you used |
| 132 |
when you created the input (with the \fB-gop\fP option) and |
| 133 |
calculates the corresponding gop filenames itself. If this is not the |
| 134 |
case, you can specify input GOP files in the same manner as normal |
| 135 |
input files -- except instead of using INPUT_DIR, INPUT, and |
| 136 |
END_INPUT, use GOP_INPUT_DIR, GOP_INPUT, and GOP_END_INPUT. If no |
| 137 |
input GOP files are specified, then the default is to use the output |
| 138 |
file name with suffix \fB.gop.\fP\fIgop_num\fP, with \fIgop_num\fP |
| 139 |
starting from 0, as the input files. |
| 140 |
.sp |
| 141 |
Thus, unless you're mixing and matching GOP files from different |
| 142 |
sources, you can simply use the same parameter file for creating the |
| 143 |
GOP files (\fB-gop\fP) and for later turning them into an MPEG stream |
| 144 |
(\fB-combine_gops\fP). |
| 145 |
|
| 146 |
|
| 147 |
.TP |
| 148 |
\fB-frames \fIfirst_frame\fP \fIlast_frame\fP\fP |
| 149 |
This option causes \fBppmtompeg\fP to encode only the frames numbered |
| 150 |
\fIfirst_frame\fP to \fIlast_frame\fP, inclusive. The parameter |
| 151 |
file is the same as for normal usage. The output will be placed in |
| 152 |
separate files, one per frame, with the file names being the normal |
| 153 |
output file name with the suffix \fB.frame.\fP\fIframe_num\fP. No |
| 154 |
GOP header information is output. (Thus, the parameter file need not |
| 155 |
include the GOP_SIZE value) |
| 156 |
.sp |
| 157 |
Use \fBppmtompeg -combine_frames\fP to combine these frames later into |
| 158 |
an MPEG stream. |
| 159 |
|
| 160 |
|
| 161 |
.TP |
| 162 |
\fB-combine_frames\fP |
| 163 |
This option causes \fBppmtompeg\fP simply to combine some |
| 164 |
individual MPEG frames (such as you might have created with an earlier |
| 165 |
run of \fBppmtompeg -frames\fP) into a single MPEG stream. Sequence |
| 166 |
and GOP headers are inserted appropriately. In this case, the |
| 167 |
parameter file needs to contain only the SIZE value, the GOP_SIZE |
| 168 |
value, an output file, and perhaps a list of frame files (see below). |
| 169 |
.sp |
| 170 |
The parameter file may specify input frame files in the same manner |
| 171 |
as normal input files -- except instead of using INPUT_DIR, INPUT, and |
| 172 |
END_INPUT, use FRAME_INPUT_DIR, FRAME_INPUT, and FRAME_END_INPUT. If |
| 173 |
no input frame files are specified, then the default is to use the |
| 174 |
output file name with suffix \fB.frame.\fP\fIframe_num\fP, with |
| 175 |
\fIframe_num\fP starting from 0, as the input files. |
| 176 |
|
| 177 |
|
| 178 |
|
| 179 |
.TP |
| 180 |
\fB-nice\fP |
| 181 |
This option causes \fBppmtompeg\fP to run any remote processes |
| 182 |
"nicely," i.e. at low priority. (This is relevant only if you are |
| 183 |
running \fBppmtompeg\fP in parallel mode. Otherwise, there are no |
| 184 |
remote processes). See 'man nice.' |
| 185 |
|
| 186 |
.TP |
| 187 |
\fB-max_machines \fInum_machines\fP\fP |
| 188 |
This option causes \fBppmtompeg\fP to use no more than |
| 189 |
\fInum_machines\fP machines as slaves for use in parallel encoding. |
| 190 |
|
| 191 |
.TP |
| 192 |
\fB-snr\fP |
| 193 |
This option causes \fBppmtompeg\fP to include the signal-to-noise |
| 194 |
ratio in the reported statistics. Prints SNR (Y U V) and peak SNR (Y |
| 195 |
U V) for each frame. In summary, prints averages of luminance only |
| 196 |
(Y). SNR is defined as 10*log(variance of original/variance of |
| 197 |
error). Peak SNR is defined as 20*log(255/RMSE). Note that |
| 198 |
\fBppmtompeg\fP runs a little slower when you use this option. |
| 199 |
|
| 200 |
.TP |
| 201 |
\fB-mse\fP |
| 202 |
This option causes \fBppmtompeg\fP to report the mean squared |
| 203 |
error per block. It also automatically reports the quality of the |
| 204 |
images, so there is no need to specify \fB-snr\fP then. |
| 205 |
|
| 206 |
.TP |
| 207 |
\fB-bit_rate_info\fP \fIrate_file\fP |
| 208 |
This option makes \fBppmtompeg\fP write bit rate information |
| 209 |
into the file \fIrate_file\fP. Bit rate information is bits per frame, and |
| 210 |
also bits per I-frame-to-I-frame. |
| 211 |
|
| 212 |
.TP |
| 213 |
\fB-mv_histogram\fP |
| 214 |
This option causes \fBppmtompeg\fP to print a histogram of the |
| 215 |
motion vectors as part of statistics. There are three histograms -- |
| 216 |
one for P frame, one for forward B frame, and one for backward B frame |
| 217 |
motion vectors. |
| 218 |
.sp |
| 219 |
The output is in the form of a matrix, each entry corresponding to one |
| 220 |
motion vector in the search window. The center of the matrix |
| 221 |
represents (0,0) motion vectors. |
| 222 |
|
| 223 |
.TP |
| 224 |
\fB-debug_sockets\fP |
| 225 |
This option causes \fBppmtompeg\fP to print to Standard Output |
| 226 |
messages that narrate the communication between the machines when you run |
| 227 |
\fBppmtompeg\fP in |
| 228 |
.UR #parallel |
| 229 |
parallel mode |
| 230 |
.UE |
| 231 |
\&. |
| 232 |
|
| 233 |
.TP |
| 234 |
\fB-debug_machines\fP |
| 235 |
This option causes \fBppmtompeg\fP to print to Standard Output |
| 236 |
messages that narrate the progress of the conversion on the various |
| 237 |
machines when you run \fBppmtompeg\fP in |
| 238 |
.UR #parallel |
| 239 |
parallel mode |
| 240 |
.UE |
| 241 |
\&. |
| 242 |
|
| 243 |
|
| 244 |
|
| 245 |
.UN parmfile |
| 246 |
.SH PARAMETER FILE |
| 247 |
.PP |
| 248 |
The parameter file \fBmust\fP contain the following |
| 249 |
lines (except when using the \fB-combine_gops\fP or \fB-combine_frames\fP |
| 250 |
options): |
| 251 |
|
| 252 |
|
| 253 |
|
| 254 |
.TP |
| 255 |
\fBPATTERN\fP \fIpattern\fP |
| 256 |
This statement specifies the pattern (sequence) of I frames, P frames, |
| 257 |
and B frames. \fIpattern\fP is just a sequence of the letters I, P, and |
| 258 |
B with nothing between. Example: |
| 259 |
|
| 260 |
.nf |
| 261 |
PATTERN IBBPBBPBBPBBPBB |
| 262 |
</pre> |
| 263 |
.sp |
| 264 |
See |
| 265 |
.UR #ipb |
| 266 |
I Frames, P Frames, B Frames |
| 267 |
.UE |
| 268 |
\&. |
| 269 |
|
| 270 |
.TP |
| 271 |
\fBOUTPUT\fP \fIoutput file\fP |
| 272 |
This names the file where the output MPEG stream goes. |
| 273 |
|
| 274 |
.TP |
| 275 |
\fBINPUT_DIR\fP \fIdirectory\fP |
| 276 |
This statement tells where the input images (frames) come from. |
| 277 |
If each frame is in a separate file, \fIdirectory\fP is the directory |
| 278 |
where they all are. You may use \fB.\fP to refer to the current |
| 279 |
directory. A null \fIdirectory\fP refers to the root directory of the |
| 280 |
system file tree. |
| 281 |
.sp |
| 282 |
To have \fBppmtompeg\fP read all the frames serially from Standard |
| 283 |
Input, specify |
| 284 |
.nf |
| 285 |
INPUT_DIR stdin |
| 286 |
|
| 287 |
.fi |
| 288 |
|
| 289 |
.TP |
| 290 |
\fBINPUT\fP |
| 291 |
This line must be followed by a list of the input files (in display order) |
| 292 |
and then the line \fBEND_INPUT\fP. |
| 293 |
.sp |
| 294 |
There are three types of lines between INPUT and END_INPUT. First, |
| 295 |
a line may simply be the name of an input file. Second, the line |
| 296 |
may be of the form \fIsingle_star_expr\fP |
| 297 |
\fB[\fP\fIx\fP\fB-\fP\fIy\fP\fB]\fP. |
| 298 |
\fIsingle_star_expr\fP can have a single \fB*\fP in it. It is |
| 299 |
replaced by all the numbers between x and y inclusive. So, for |
| 300 |
example, the line \fBtennis*.ppm [12-15]\fP refers to the files |
| 301 |
tennis12.ppm, tennis13.ppm, tennis14.ppm, tennis15.ppm. |
| 302 |
.sp |
| 303 |
Uniform zero-padding occurs, as well. For example, the line |
| 304 |
\fBfootball.*.ppm [001-130]\fP refers to the files football.001.ppm, |
| 305 |
football.002.ppm, ..., football.009.ppm, football.010.ppm, ..., |
| 306 |
football.130.ppm. |
| 307 |
.sp |
| 308 |
The third type of line is: \fIsingle_star_expr\fP |
| 309 |
\fB[\fP\fIx\fP\fB-\fP\fIy\fP\fB+\fP\fIs\fP\fB]\fP, where the |
| 310 |
line is treated exactly as above, except that we skip by \fIs\fP. Thus, the |
| 311 |
line \fBfootball.*.ppm [001-130+4]\fP refers to the files |
| 312 |
football.001.ppm, football.005.ppm, football.009.ppm, |
| 313 |
football.013.ppm, etc. |
| 314 |
.sp |
| 315 |
Furthermore, a line may specify a shell command to execute to |
| 316 |
generate lines to be interpreted as described above, as if those lines |
| 317 |
were in the parameter file instead. Use back ticks, like in the |
| 318 |
Bourne Shell, like this: |
| 319 |
|
| 320 |
.nf |
| 321 |
`cat myfilelist` |
| 322 |
|
| 323 |
.fi |
| 324 |
.sp |
| 325 |
If input is from Standard Input (per the \fBINPUT_DIR\fP statement), |
| 326 |
\fBppmtompeg\fP ignores the \fBINPUT\fP/\fBEND_INPUT\fP block, but |
| 327 |
it still must be present. |
| 328 |
|
| 329 |
.TP |
| 330 |
\fBBASE_FILE_FORMAT\fP {\fBPPM\fP | \fBPNM\fP | \fBYUV\fP | |
| 331 |
\fBJPEG\fP | \fBJMOVIE\fP} |
| 332 |
\fBppmtompeg\fP must convert all input files to one of the |
| 333 |
following formats as a first step of processing: PNM, YUV, JPEG(v4), |
| 334 |
or JMOVIE. (The conversion may be trivial if your input files are |
| 335 |
already in one of these formats). This line specifies which of the |
| 336 |
four formats. PPM is actually a subset of PNM. The separate |
| 337 |
specification is allowed for backward compatibility. Use PNM instead |
| 338 |
of PPM in new applications. |
| 339 |
|
| 340 |
.TP |
| 341 |
\fBINPUT_CONVERT\fP \fIconversion_command\fP |
| 342 |
You must specify how to convert a file to the base file format. |
| 343 |
If no conversion is necessary, then you would just say: |
| 344 |
|
| 345 |
.nf |
| 346 |
INPUT_CONVERT * |
| 347 |
|
| 348 |
.fi |
| 349 |
.sp |
| 350 |
Otherwise, \fIconversion_command\fP is a shell command that causes |
| 351 |
an image in the format your specified with \fBBASE_FILE_FORMAT\fP to |
| 352 |
be written to Standard Output. \fBppmtompeg\fP executes the command |
| 353 |
once for each line between \fBINPUT\fP and \fBEND_INPUT\fP (which is |
| 354 |
normally, but not necessarily, a file name). In the conversion |
| 355 |
command, \fBppmtompeg\fP replaces each '*' with the contents of that |
| 356 |
line. |
| 357 |
|
| 358 |
If you had a bunch of gif files, you might say: |
| 359 |
.nf |
| 360 |
INPUT_CONVERT giftopnm * |
| 361 |
|
| 362 |
.fi |
| 363 |
|
| 364 |
If you have a bunch of separate a.Y, a.U, and a.V files (where |
| 365 |
the U and V have already been subsampled), then you might say: |
| 366 |
|
| 367 |
.nf |
| 368 |
INPUT_CONVERT cat *.Y *.U *.V |
| 369 |
|
| 370 |
.fi |
| 371 |
.sp |
| 372 |
Input conversion is not allowed with input from stdin, so use |
| 373 |
|
| 374 |
.nf |
| 375 |
INPUT_CONVERT * |
| 376 |
|
| 377 |
.fi |
| 378 |
|
| 379 |
as described above. |
| 380 |
|
| 381 |
.TP |
| 382 |
\fBSIZE\fP \fIwidth\fP\fBx\fP\fIheight\fP |
| 383 |
.sp |
| 384 |
\fIwidth\fP and \fIheight\fP are the width and height of each |
| 385 |
frame in pixels. |
| 386 |
.sp |
| 387 |
When \fBppmtompeg\fP can get this information from the input image |
| 388 |
files, it ignores the \fBSIZE\fP parameter and you may omit it. |
| 389 |
.sp |
| 390 |
When the image files are in YUV format, the files don't contain |
| 391 |
dimension information, so \fBSIZE\fP is required. |
| 392 |
.sp |
| 393 |
When \fBppmtompeg\fP is running in parallel mode, not all of the |
| 394 |
processes in the network have access to the image files, so |
| 395 |
\fBSIZE\fP is required and must give the same dimensions as the |
| 396 |
input image files. |
| 397 |
|
| 398 |
.TP |
| 399 |
\fBYUV_SIZE\fP \fIwidth\fP\fBx\fP\fIheight\fP |
| 400 |
This is an obsolete synonym of \fBSIZE\fP. |
| 401 |
|
| 402 |
.TP |
| 403 |
\fBYUV_FORMAT\fP {\fBABEKAS\fP | \fBPHILLIPS\fP | \fBUCB\fP | |
| 404 |
\fBEYUV\fP | \fIpattern\fP} |
| 405 |
This is meaningful only when \fBBASE_FILE_FORMAT\fP specifies |
| 406 |
YUV format, and then it is required. It specifies the sub-format of |
| 407 |
the YUV class. |
| 408 |
|
| 409 |
|
| 410 |
.TP |
| 411 |
\fBGOP_SIZE\fP \fIn\fP |
| 412 |
\fIn\fP is the number of frames in a Group of Pictures. Except that |
| 413 |
because a GOP must start with an I frame, \fBppmtompeg\fP makes a GOP as |
| 414 |
much longer than \fIn\fP as it has to to make the next GOP start with an |
| 415 |
I frame. |
| 416 |
.sp |
| 417 |
Normally, it makes sense to make your GOP size a multiple of your |
| 418 |
pattern length (the latter is determined by the PATTERN parameter file |
| 419 |
statement). |
| 420 |
.sp |
| 421 |
See |
| 422 |
.UR #gop |
| 423 |
Group Of Pictures |
| 424 |
.UE |
| 425 |
\&. |
| 426 |
|
| 427 |
.TP |
| 428 |
\fBSLICES_PER_FRAME\fP \fIn\fP |
| 429 |
\fIn\fP is roughly the number of slices per frame. Note, at |
| 430 |
least one MPEG player may complain if slices do not start at the left |
| 431 |
side of an image. To ensure this does not happen, make sure the |
| 432 |
number of rows is divisible by SLICES_PER_FRAME. |
| 433 |
|
| 434 |
.TP |
| 435 |
\fBPIXEL\fP {\fBFULL\fP | \fBHALF\fP} |
| 436 |
use half-pixel motion vectors, or just full-pixel ones It is |
| 437 |
usually important that you use half-pixel motion vectors, because it |
| 438 |
results in both better quality and better compression. |
| 439 |
|
| 440 |
|
| 441 |
.TP |
| 442 |
\fBRANGE\fP \fIn\fP |
| 443 |
Use a search range of \fIn\fP pixels in each of the four directions |
| 444 |
from a subject pixel. (So the search window is a square \fIn\fP*2 pixels |
| 445 |
on a side). |
| 446 |
|
| 447 |
.TP |
| 448 |
\fBPSEARCH_ALG\fP {\fBEXHAUSTIVE\fP | \fBTWOLEVEL\fP | |
| 449 |
\fBSUBSAMPLE\fP | \fBLOGARITHMIC\fP} |
| 450 |
This statement tells \fBppmtompeg\fP what kind of search |
| 451 |
technique (algorithm) to use for P frames. You select the desired |
| 452 |
combination of speed and compression. \fBEXHAUSTIVE\fP gives the |
| 453 |
best compression, but \fBLOGARITHMIC\fP is the fastest. |
| 454 |
\fBTWOLEVEL\fP is an exhaustive full-pixel search, followed by a |
| 455 |
local half- pixel search around the best full-pixel vector (the |
| 456 |
PIXEL option is ignored for this search technique). |
| 457 |
|
| 458 |
.TP |
| 459 |
\fBBSEARCH_ALG\fP {\fBSIMPLE\fP | \fBCROSS2\fP | \fBEXHAUSTIVE\fP} |
| 460 |
This statement tells \fBppmtompeg\fP what kind of search |
| 461 |
technique (algorithm) to use for B frames. \fBSIMPLE\fP means |
| 462 |
find best forward and backward vectors, then interpolate. |
| 463 |
\fBCROSS2\fP means find those two vectors, then see what backward |
| 464 |
vector best matches the best forward vector, and vice versa. |
| 465 |
\fBEXHAUSTIVE\fP does an n-squared search and is |
| 466 |
\fIextremely\fP slow in relation to the others (\fBCROSS2\fP |
| 467 |
is about half as fast as \fBSIMPLE\fP). |
| 468 |
|
| 469 |
.TP |
| 470 |
\fBIQSCALE\fP \fIn\fP |
| 471 |
Use \fIn\fP as the qscale for I frames. |
| 472 |
See |
| 473 |
.UR #qscale |
| 474 |
Qscale |
| 475 |
.UE |
| 476 |
\&. |
| 477 |
|
| 478 |
.TP |
| 479 |
\fBPQSCALE\fP \fIn\fP |
| 480 |
Use \fIn\fP as the qscale for P frames. |
| 481 |
See |
| 482 |
.UR #qscale |
| 483 |
Qscale |
| 484 |
.UE |
| 485 |
\&. |
| 486 |
|
| 487 |
.TP |
| 488 |
\fBBQSCALE\fP \fIn\fP |
| 489 |
Use \fIn\fP as the qscale for B frames. |
| 490 |
See |
| 491 |
.UR #qscale |
| 492 |
Qscale |
| 493 |
.UE |
| 494 |
\&. |
| 495 |
|
| 496 |
.TP |
| 497 |
\fBREFERENCE_FRAME\fP {\fBORIGINAL\fP | \fBDECODED\fP} |
| 498 |
This |
| 499 |
statement determines whether \fBppmtompeg\fP uses the original images |
| 500 |
or the decoded images when computing motion vectors. Using decoded |
| 501 |
images is more accurate and should increase the playback quality of |
| 502 |
the output, but it makes the encoding take longer and seems to give |
| 503 |
worse compression. It also causes some complications with parallel |
| 504 |
encoding. (see the section on parallel encoding). One thing you can |
| 505 |
do as a trade-off is select \fBORIGINAL\fP here, and lower the |
| 506 |
qscale (see \fBQSCALE\fP if the quality is not good enough. |
| 507 |
|
| 508 |
.B Original or Decoded? (Normalized) |
| 509 |
.TS |
| 510 |
r c c c c c. |
| 511 |
_ |
| 512 |
Reference Compression Speed Quality I Quality P Quality B |
| 513 |
Decoded 1000 1000 1000 969 919 |
| 514 |
Original 885 1373 1000 912 884 |
| 515 |
.TE |
| 516 |
|
| 517 |
|
| 518 |
|
| 519 |
|
| 520 |
|
| 521 |
.PP |
| 522 |
The following lines are optional: |
| 523 |
|
| 524 |
|
| 525 |
|
| 526 |
.TP |
| 527 |
\fBFORCE_ENCODE_LAST_FRAME\fP |
| 528 |
This statement is obsolete. It does nothing. |
| 529 |
.sp |
| 530 |
Before Netpbm 10.26 (January 2005), \fBppmtompeg\fP would drop |
| 531 |
trailing B frames from your movie, since a movie can't end with a B |
| 532 |
frame. (See |
| 533 |
.UR #ipb |
| 534 |
I Frames, P Frames, B Frames |
| 535 |
.UE |
| 536 |
\&.) |
| 537 |
You would have to specify \fBFORCE_ENCODE_LAST_FRAME\fP to stop |
| 538 |
that from happening and get the same function that \fBppmtompeg\fP |
| 539 |
has today. |
| 540 |
|
| 541 |
|
| 542 |
.TP |
| 543 |
\fBNIQTABLE\fP |
| 544 |
This statement specifies a custom non-intra quantization table. |
| 545 |
If you don't specify this statement, \fBppmtompeg\fP uses a default |
| 546 |
non-intra quantization table. |
| 547 |
.sp |
| 548 |
The 8 lines immediately following \fBNIQTABLE\fP specify the quantization |
| 549 |
table. Each line defines a table row and consists of 8 integers, |
| 550 |
whitespace-delimited, which define the table columns. |
| 551 |
|
| 552 |
.TP |
| 553 |
\fBIQTABLE\fP |
| 554 |
This is analogous to NIQTABLE, but for the intra quantization table. |
| 555 |
|
| 556 |
.TP |
| 557 |
\fBASPECT_RATIO\fP \fIratio\fP |
| 558 |
This statement specifies the aspect ratio for \fBppmtompeg\fP to |
| 559 |
specify in the MPEG output. I'm not sure what this is used for. |
| 560 |
.sp |
| 561 |
\fIratio\fP must be 1.0, 0.6735, 0.7031, 0.7615, 0.8055, 0.8437, |
| 562 |
0.8935, 0.9157, 0.9815, 1.0255, 1.0695, 1.0950, 1.1575, or 1.2015. |
| 563 |
|
| 564 |
.TP |
| 565 |
\fBFRAME_RATE\fP \fIrate\fP |
| 566 |
This specifies the frame rate for \fBppmtompeg\fP to specify in the |
| 567 |
MPEG output. Some players use this value to determine the playback rate. |
| 568 |
.sp |
| 569 |
\fIrate\fP must be 23.976, 24, 25, 29.97, 30, 50, 59.94, or 60. |
| 570 |
|
| 571 |
.TP |
| 572 |
\fBBIT_RATE\fP \fIrate\fP |
| 573 |
This specifies the bit rate for Constant Bit Rate (CBR) encoding. |
| 574 |
.sp |
| 575 |
\fIrate\fP must be an integer. |
| 576 |
|
| 577 |
.TP |
| 578 |
\fBBUFFER_SIZE\fP \fIsize\fP |
| 579 |
This specifies the value |
| 580 |
\fBppmtompeg\fP is to specify in the MPEG output for the Video |
| 581 |
Buffering Verifier (VBV) buffer size needed to decode the sequence. |
| 582 |
.sp |
| 583 |
A Video Verifying Buffer is a buffer in which a decoder keeps the |
| 584 |
decoded bits in order to match the uneven speed of the decoding with |
| 585 |
the required constant playback speed. |
| 586 |
.sp |
| 587 |
As \fBppmtompeg\fP encodes the image, it simulates the decoding |
| 588 |
process in terms of how many bits would be in the VBV as each frame gets |
| 589 |
decoded, assuming a VBV of the size you indicate. |
| 590 |
.sp |
| 591 |
If you specify the \fBWARN_VBV_UNDERFLOW\fP statement, |
| 592 |
\fBppmtompeg\fP issues a warning each time the simulation underflows |
| 593 |
the buffer, which suggests that an underflow would occur on playback, |
| 594 |
which suggests the buffer is too small. |
| 595 |
.sp |
| 596 |
If you specify the \fBWARN_VBV_OVERFLOW\fP statement, |
| 597 |
\fBppmtompeg\fP issues a warning each time the simulation overflows |
| 598 |
the buffer, which suggests that an overflow would occur on playback, |
| 599 |
which suggests the buffer is too small. |
| 600 |
|
| 601 |
.TP |
| 602 |
\fBWARN_VBV_UNDERFLOW\fP |
| 603 |
.TP |
| 604 |
\fBWARN_VBV_OVERFLOW\fP |
| 605 |
See \fBBUFFER_SIZE\fP. |
| 606 |
.sp |
| 607 |
These options were new in Netpbm 10.26 (January 2005). Before that, |
| 608 |
\fBppmtompeg\fP issued the warnings always. |
| 609 |
|
| 610 |
|
| 611 |
|
| 612 |
|
| 613 |
The following statements apply only to parallel operation: |
| 614 |
|
| 615 |
|
| 616 |
|
| 617 |
.TP |
| 618 |
\fBPARALLEL\fP |
| 619 |
This statement, paired with \fBEND PARALLEL\fP, is what causes |
| 620 |
\fBppmtompeg\fP to operate in parallel mode. See |
| 621 |
.UR #parallel |
| 622 |
Parallel Operation |
| 623 |
.UE |
| 624 |
\&. |
| 625 |
|
| 626 |
.TP |
| 627 |
\fBEND PARALLEL\fP |
| 628 |
This goes with \fBPARALLEL\fP. |
| 629 |
|
| 630 |
.TP |
| 631 |
\fBPARALLEL_TEST_FRAMES\fP \fIn\fP |
| 632 |
The master starts off by measuring each slave's speed. It does |
| 633 |
this by giving each slave \fIn\fP frames to encode and noting how |
| 634 |
long the slave takes to finish. These are not just test frames, |
| 635 |
though -- they're real frames and the results become part of the |
| 636 |
output. |
| 637 |
\fBppmtompeg\fP is old and measures time in undivided seconds, so |
| 638 |
to get useful timings, specify enough frames that it will take at |
| 639 |
least 5 seconds to process them. The default is 10. |
| 640 |
.sp |
| 641 |
If you specify \fBFORCE_I_ALIGN\fP, \fBppmtompeg\fP will increase |
| 642 |
the test frames value enough to maintain the alignment. |
| 643 |
.sp |
| 644 |
If there aren't enough frames for every slave to have the indicated |
| 645 |
number of test frames, \fBppmtompeg\fP will give some slaves fewer. |
| 646 |
|
| 647 |
|
| 648 |
.TP |
| 649 |
\fBPARALLEL_TIME_CHUNKS\fP \fIt\fP |
| 650 |
When you specify this statement, the master attempts to feed work |
| 651 |
to the slaves in chunks that take \fIt\fP seconds to process. It uses |
| 652 |
the speed measurement it made when it started up (see PARALLEL_TEST_FRAMES) |
| 653 |
to decide how many frames to put in the chunk. This statement obviously |
| 654 |
doesn't affect the first batch of work sent to each slave, which is the |
| 655 |
one used to measure the slave's speed. |
| 656 |
.sp |
| 657 |
Smaller values of \fIt\fP increase communication, but improve load |
| 658 |
balancing. The default is 30 seconds. |
| 659 |
.sp |
| 660 |
You may specify only one of PARALLEL_TIME_CHUNKS, PARALLEL_CHUNK_TAPER, |
| 661 |
and PARALLEL_PERFECT. PARALLEL_CHUNK_TAPER is usually best. |
| 662 |
|
| 663 |
.TP |
| 664 |
\fBPARALLEL_CHUNK_TAPER\fP |
| 665 |
When you specify this statement, the master distributes work like |
| 666 |
with PARALLEL_TIME_CHUNKS, except that the master chooses the number |
| 667 |
of seconds for the chunks. It starts with a large number and, as it |
| 668 |
gets closer to finishing the job, reduces it. That way, it reduces |
| 669 |
scheduling overhead when precise scheduling isn't helpful, but still |
| 670 |
prevents a slave from finishing early after all the work has already |
| 671 |
been handed out to the other slaves, and then sitting idle while |
| 672 |
there's still work to do. |
| 673 |
.sp |
| 674 |
You may specify only one of PARALLEL_TIME_CHUNKS, PARALLEL_CHUNK_TAPER, |
| 675 |
and PARALLEL_PERFECT. PARALLEL_CHUNK_TAPER is usually best. |
| 676 |
|
| 677 |
|
| 678 |
.TP |
| 679 |
\fBPARALLEL_PERFECT\fP |
| 680 |
If this statement is present, \fBppmtompeg\fP schedules on the |
| 681 |
assumption that each machine is about the same speed. The master will |
| 682 |
simply divide up the frames evenly between the slaves -- each |
| 683 |
slave gets the same number of frames. If some slaves are faster than |
| 684 |
others, they will finish first and remain idle while the slower slaves |
| 685 |
continue. |
| 686 |
.sp |
| 687 |
This has the advantage of minimal scheduling overhead. Where slaves |
| 688 |
have different speeds, though, it makes inefficient use of the fast |
| 689 |
ones. Where slaves are the same speed, it also has the disadvantage |
| 690 |
that they all finish at the same time and feed their output to the |
| 691 |
single Combine Server in a burst, which makes less efficient use of |
| 692 |
the Combine Server and thus can increase the total elapsed time. |
| 693 |
.sp |
| 694 |
You may specify only one of PARALLEL_TIME_CHUNKS, PARALLEL_CHUNK_TAPER, |
| 695 |
and PARALLEL_PERFECT. PARALLEL_CHUNK_TAPER is usually best. |
| 696 |
|
| 697 |
.TP |
| 698 |
\fBRSH\fP \fIremote_shell_command\fP |
| 699 |
\fBppmtompeg\fP executes the shell command |
| 700 |
\fIremote_shell_command\fP to start a process on another machine. |
| 701 |
The default command is \fBrsh\fP, and whatever command you specify |
| 702 |
must have compatible semantics. \fBssh\fP is usually compatible. |
| 703 |
The command \fBppmtompeg\fP uses is one like this: |
| 704 |
\fBssh remote.host.com -l username shellcommand\fP. |
| 705 |
.sp |
| 706 |
Be sure to set up \fB.rhosts\fP files or SSH key authorizations |
| 707 |
where needed. Otherwise, you'll have to type in passwords. |
| 708 |
.sp |
| 709 |
On some HP machines, \fBrsh\fP is the restricted shell, and you want |
| 710 |
to specify \fBremsh\fP. |
| 711 |
|
| 712 |
.TP |
| 713 |
\fBFORCE_I_ALIGN\fP |
| 714 |
This statement forces each slave to encode a chunk of frames which |
| 715 |
is a multiple of the pattern length (see \fBPATTERN\fP). Since the |
| 716 |
first frame in any pattern is an I frame, this forces each chunk |
| 717 |
encoded by a slave to begin with an I frame. |
| 718 |
.sp |
| 719 |
This document used to say there was an argument to |
| 720 |
\fBFORCE_I_ALIGN\fP which was the number of frames \fBppmtompeg\fP |
| 721 |
would use (and was required to be a multiple of the pattern length). |
| 722 |
But \fBppmtompeg\fP has apparently always ignored that argument, and |
| 723 |
it does now. |
| 724 |
|
| 725 |
.TP |
| 726 |
\fBKEEP_TEMP_FILES\fP |
| 727 |
This statement causes \fBppmtompeg\fP not to delete the temporary |
| 728 |
files it uses to transmit encoded frames to the combine server. This |
| 729 |
means you will be left with a file for each frame, the same as you |
| 730 |
would get with the \fB-frames\fP option. |
| 731 |
.sp |
| 732 |
This is mostly useful for debugging. |
| 733 |
.sp |
| 734 |
This works only if you're using a shared filesystem to communicate |
| 735 |
between the servers. |
| 736 |
.sp |
| 737 |
This option was new in Netpbm 10.26 (January 2005). |
| 738 |
|
| 739 |
|
| 740 |
|
| 741 |
|
| 742 |
.UN parameterfile |
| 743 |
.SS Parameter File Notes |
| 744 |
.PP |
| 745 |
If you use the \fB-combine_gops\fP option, then you need to specify |
| 746 |
only the SIZE and OUTPUT values in the parameter file. In |
| 747 |
addition, the parameter file may specify input GOP files in the same |
| 748 |
manner as normal input files -- except instead of using INPUT_DIR, |
| 749 |
INPUT, and END_INPUT, use GOP_INPUT_DIR, GOP_INPUT, and GOP_END_INPUT. |
| 750 |
If you specify no input GOP files, then \fBppmtompeg\fP uses by default the |
| 751 |
output file name with suffix \fB.gop.\fP\fIgop_num\fP, with \fIgop_num\fP |
| 752 |
starting from 0, as the input files. |
| 753 |
.PP |
| 754 |
If you use the \fB-combine_frames\fP option, then you need to |
| 755 |
specify only the SIZE, GOP_SIZE, and OUTPUT values in the |
| 756 |
parameter file. In addition, the parameter file may specify input |
| 757 |
frame files in the same manner as normal input files -- except instead |
| 758 |
of using INPUT_DIR, INPUT, and END_INPUT, use FRAME_INPUT_DIR, |
| 759 |
FRAME_INPUT, and FRAME_END_INPUT. If no input frame files are |
| 760 |
specified, then the default is to use the output file name with suffix |
| 761 |
\fB.frame.\fP\fIframe_num\fP, with \fIframe_num\fP starting from 0, |
| 762 |
as the input files. |
| 763 |
.PP |
| 764 |
Any number of spaces and tabs may come between each option and value. Lines |
| 765 |
beginning with \fB#\fP are ignored. Any other lines are ignored except for |
| 766 |
those between INPUT and END_INPUT. This allows you to use the same |
| 767 |
parameter file for normal usage and for \fB-combine_gops\fP and |
| 768 |
\fB-combine_frames\fP. |
| 769 |
.PP |
| 770 |
The file format is case-sensitive so all keywords should be in |
| 771 |
upper case. |
| 772 |
.PP |
| 773 |
The statements may appear in any order, except that the order within |
| 774 |
a block statement (such as INPUT ... END INPUT) is significant. |
| 775 |
.PP |
| 776 |
\fBppmtompeg\fP is prepared to handle up to 16 B frames between |
| 777 |
reference frames when encoding with input from stdin. (To build a |
| 778 |
modified \fBppmtompeg\fP with a higher limit, change the constant |
| 779 |
B_FRAME_RUN in frame.c and recompile). |
| 780 |
|
| 781 |
.UN general |
| 782 |
.SH GENERAL USAGE INFORMATION |
| 783 |
|
| 784 |
.UN qscale |
| 785 |
.SS Qscale |
| 786 |
.PP |
| 787 |
The quantization scale values (qscale) give a trade-off between |
| 788 |
quality and compression. Using different Qscale values has very little |
| 789 |
effect on speed. The qscale values can be set separately for I, P, and |
| 790 |
B frames. |
| 791 |
.PP |
| 792 |
You select the qscale values with the \fBIQSCALE\fP, |
| 793 |
\fBPQSCALE\fP, and \fBBSCALE\fP parameter file statements. |
| 794 |
.PP |
| 795 |
A qscale value is an integer from 1 to 31. Larger numbers give |
| 796 |
better compression, but worse quality. In the following, the quality |
| 797 |
numbers are peak signal-to-noise ratio, defined as: |
| 798 |
.B signal-to-noise formula |
| 799 |
.IMG -C ppmtompeg-snr.gif |
| 800 |
where MSE is the mean squared error. |
| 801 |
|
| 802 |
.PP |
| 803 |
Flower garden tests: |
| 804 |
|
| 805 |
.B Qscale vs Quality |
| 806 |
.TS |
| 807 |
r r r r. |
| 808 |
_ |
| 809 |
Qscale I Frames P Frames B Frames |
| 810 |
1 43.2 46.3 46.5 |
| 811 |
6 32.6 34.6 34.3 |
| 812 |
11 28.6 29.5 30.0 |
| 813 |
16 26.3 26.8 28.6 |
| 814 |
21 24.7 25.0 27.9 |
| 815 |
26 23.5 23.9 27.5 |
| 816 |
31 22.6 23.0 27.3 |
| 817 |
.TE |
| 818 |
|
| 819 |
.B Qscale vs Compression |
| 820 |
.TS |
| 821 |
r r r r. |
| 822 |
_ |
| 823 |
Qscale I Frames P Frames B Frames |
| 824 |
1 2 2 2 |
| 825 |
6 7 10 15 |
| 826 |
11 11 18 43 |
| 827 |
16 15 29 97 |
| 828 |
21 19 41 173 |
| 829 |
26 24 56 256 |
| 830 |
31 28 73 330 |
| 831 |
.TE |
| 832 |
|
| 833 |
|
| 834 |
.UN searchtech |
| 835 |
.SS Search Techniques |
| 836 |
|
| 837 |
.PP |
| 838 |
There are several different motion vector search techniques |
| 839 |
available. There are different techniques available for P frame |
| 840 |
search and B frame search. Using different search techniques present |
| 841 |
little difference in quality, but a large difference in compression |
| 842 |
and speed. |
| 843 |
|
| 844 |
.PP |
| 845 |
There are 4 types of P frame search: Exhaustive, TwoLevel, |
| 846 |
SubSample, and Logarithmic. |
| 847 |
|
| 848 |
.PP |
| 849 |
There are 3 types of B frame search: Exhaustive, Cross2, and |
| 850 |
Simple. |
| 851 |
|
| 852 |
The recommended search techniques are TwoLevel and Logarithmic for |
| 853 |
P frame search, and Cross2 and Simple for B frame search. Here are |
| 854 |
some numbers comparing the different search methods: |
| 855 |
|
| 856 |
.B P frame Motion Vector Search (Normalized) |
| 857 |
.TS |
| 858 |
r c c c. |
| 859 |
_ |
| 860 |
Technique T{ |
| 861 |
Compression |
| 862 |
.UR #smallbetter |
| 863 |
\u1\d |
| 864 |
.UE |
| 865 |
T} T{ |
| 866 |
Speed |
| 867 |
.UR #largefaster |
| 868 |
\u2\d |
| 869 |
.UE |
| 870 |
T} T{ |
| 871 |
Quality |
| 872 |
.UR #largebetter |
| 873 |
\u3\d |
| 874 |
.UE |
| 875 |
T} |
| 876 |
Exhaustive 1000 1000 1000 |
| 877 |
SubSample 1008 2456 1000 |
| 878 |
TwoLevel 1009 3237 1000 |
| 879 |
Logarithmic 1085 8229 998 |
| 880 |
.TE |
| 881 |
|
| 882 |
.B B frame Motion Vector Search (Normalized) |
| 883 |
.TS |
| 884 |
r c c c. |
| 885 |
_ |
| 886 |
Technique T{ |
| 887 |
Compression |
| 888 |
.UR #smallbetter |
| 889 |
\u1\d |
| 890 |
.UE |
| 891 |
T} T{ |
| 892 |
Speed |
| 893 |
.UR #largefaster |
| 894 |
\u2\d |
| 895 |
.UE |
| 896 |
T} T{ |
| 897 |
Quality |
| 898 |
.UR #largebetter |
| 899 |
\u3\d |
| 900 |
.UE |
| 901 |
T} |
| 902 |
Exhaustive 1000 1000 1000 |
| 903 |
Cross2 975 1000 996 |
| 904 |
Simple 938 1765 991 |
| 905 |
.TE |
| 906 |
|
| 907 |
.UN smallbetter |
| 908 |
\u1\dSmaller numbers are better |
| 909 |
compression. |
| 910 |
|
| 911 |
.UN largefaster |
| 912 |
\u2\dLarger numbers mean faster |
| 913 |
execution. |
| 914 |
|
| 915 |
.UN largebetter |
| 916 |
\u3\dLarger numbers mean better quality. |
| 917 |
.PP |
| 918 |
For some reason, Simple seems to give better compression, but it |
| 919 |
depends on the image sequence. |
| 920 |
.PP |
| 921 |
Select the search techniques with the \fBPSEARCH_ALG\fP and |
| 922 |
\fBBSEARCH_ALG\fP parameter file statements. |
| 923 |
|
| 924 |
|
| 925 |
.UN gop |
| 926 |
.SS Group Of Pictures (GOP) |
| 927 |
.PP |
| 928 |
A Group of Pictures (GOP) is a roughly independently decodable |
| 929 |
sequence of frames. An MPEG video stream is made of one or more |
| 930 |
GOP's. You may specify how many frames should be in each GOP with the |
| 931 |
\fBGOP_SIZE\fP parameter file statement. A GOP always starts with an |
| 932 |
I frame. |
| 933 |
.PP |
| 934 |
Instead of encoding an entire sequence, you can encode a single |
| 935 |
GOP. To do this, use the \fB-gop\fP command option. You can later |
| 936 |
join the resulting GOP files at any time by running \fBppmtompeg\fP |
| 937 |
with the \fB-combine_gops\fP command option. |
| 938 |
|
| 939 |
|
| 940 |
.UN slices |
| 941 |
.SS Slices |
| 942 |
.PP |
| 943 |
A slice is an independently decodable unit in a frame. It can be |
| 944 |
as small as one macroblock, or it can be as big as the entire frame. |
| 945 |
Barring transmission error, adding slices does not change quality or |
| 946 |
speed; the only effect is slightly worse compression. More slices are |
| 947 |
used for noisy transmission so that errors are more recoverable. Since |
| 948 |
usually errors are not such a problem, we usually just use one slice |
| 949 |
per frame. |
| 950 |
|
| 951 |
.PP |
| 952 |
Control the slice size with the \fBSLICES_PER_FRAME\fP parameter |
| 953 |
file statement. |
| 954 |
.PP |
| 955 |
Some MPEG playback systems require that each slice consist of whole |
| 956 |
rows of macroblocks. If you are encoding for this kind of player, if |
| 957 |
the height of the image is H pixels, then you should set the |
| 958 |
SLICES_PER_FRAME to some number which divides H/16. For example, if |
| 959 |
the image is 240 pixels (15 macroblocks) high, then you should use |
| 960 |
only 15, 5, 3, or 1 slices per frame. |
| 961 |
|
| 962 |
.PP |
| 963 |
Note: these MPEG playback systems are really wrong, since the MPEG |
| 964 |
standard says this doesn't have to be so. |
| 965 |
|
| 966 |
|
| 967 |
|
| 968 |
.UN searchwindow |
| 969 |
.SS Search Window |
| 970 |
|
| 971 |
.PP |
| 972 |
The search window is the window in which \fBppmtompeg\fP searches |
| 973 |
for motion vectors. The window is a square. You can specify the size |
| 974 |
of the square, and whether to allow half-pixel motion vectors or not, |
| 975 |
with the \fBRANGE\fP and \fBPIXEL\fP parameter file statements. |
| 976 |
|
| 977 |
.UN ipb |
| 978 |
.SS I Frames, P Frames, B Frames |
| 979 |
.PP |
| 980 |
In MPEG-1, a movie is represented as a sequence of MPEG frames, |
| 981 |
each of which is an I Frame, a P Frame, or a B Frame. Each represents |
| 982 |
an actual frame of the movie (don't get confused by the dual use of |
| 983 |
the word "frame." A movie frame is a graphical image. An MPEG frame |
| 984 |
is a set of data that describes a movie frame). |
| 985 |
.PP |
| 986 |
An I frame ("intra" frame) describes a movie frame in isolation -- |
| 987 |
without respect to any other frame in the movie. A P frame |
| 988 |
("predictive" frame) describes a movie frame by describing how it |
| 989 |
differs from the movie frame described by the latest preceding I or |
| 990 |
P frame. A B frame ("bidirectional" frame) describes a movie frame by |
| 991 |
describing how it differs from the movie frames described by the |
| 992 |
nearest I or P frame before \fIand\fP after it. |
| 993 |
.PP |
| 994 |
Note that the first frame of a movie must be described by an I |
| 995 |
frame (because there is no previous movie frame) and the last movie |
| 996 |
frame must be described by an I or P frame (because there is no |
| 997 |
subsequent movie frame). |
| 998 |
.PP |
| 999 |
Beyond that, you can choose which frames are represented by which |
| 1000 |
types. You specify a pattern, such as IBPBP and \fBppmtompeg\fP |
| 1001 |
simply repeats it over and over throughout the movie. The pattern |
| 1002 |
affects speed, quality, and stream size. Here is a chart which shows |
| 1003 |
some of the trade-offs: |
| 1004 |
|
| 1005 |
.B Comparison of I/P/B Frames (Normalized) |
| 1006 |
.TS |
| 1007 |
r c c c. |
| 1008 |
_ |
| 1009 |
Frame Type Size Speed Quality |
| 1010 |
I frames 1000 1000 1000 |
| 1011 |
P frames 409 609 969 |
| 1012 |
B frames 72 260 919 |
| 1013 |
.TE |
| 1014 |
|
| 1015 |
(this is with constant qscale) |
| 1016 |
|
| 1017 |
.PP |
| 1018 |
A standard sequence is IBBPBBPBBPBBPBB. |
| 1019 |
|
| 1020 |
.PP |
| 1021 |
Select the sequence with the \fBPATTERN\fP parameter file statement. |
| 1022 |
.PP |
| 1023 |
Since the last MPEG frame cannot be a B frame (see above), if the |
| 1024 |
pattern you specify indicates a B frame for the last movie frame of |
| 1025 |
the movie, \fBppmtompeg\fP makes it an I frame instead. |
| 1026 |
.PP |
| 1027 |
Before Netpbm 10.26 (January 2005), \fBppmtompeg\fP instead drops |
| 1028 |
the trailing B frames by default, and you need the |
| 1029 |
\fBFORCE_ENCODE_LAST_FRAME\fP parameter file statement to make it do |
| 1030 |
this. |
| 1031 |
.PP |
| 1032 |
The MPEG frames don't appear in the MPEG-1 stream in the same order that |
| 1033 |
the corresponding movie frames appear in the movie -- the B frames come after |
| 1034 |
the I and P frames on which they are based. For example, if the movie is |
| 1035 |
4 frames that you will represent with the pattern IBBP, the MPEG-1 stream |
| 1036 |
will start with an I frame describing movie frame 0. The next frame in |
| 1037 |
the MPEG-1 stream is a P frame describing movie frame 3. The last two |
| 1038 |
frames in the MPEG-1 stream are B frames describing movie frames 1 and 2, |
| 1039 |
respectively. |
| 1040 |
|
| 1041 |
|
| 1042 |
.UN iofiles |
| 1043 |
.SS Specifying Input and Output Files |
| 1044 |
.PP |
| 1045 |
Specify the input frame images with the \fBINPUT_DIR\fP, |
| 1046 |
\fBINPUT\fP, \fBEND_INPUT\fP, \fBBASE_FILE_FORMAT\fP, |
| 1047 |
\fBSIZE\fP, \fBYUV_FORMAT\fP and \fBINPUT_CONVERT\fP parameter |
| 1048 |
file statements. |
| 1049 |
.PP |
| 1050 |
Specify the output file with the \fBOUTPUT\fP parameter file statement. |
| 1051 |
|
| 1052 |
|
| 1053 |
.UN statistics |
| 1054 |
.SS Statistics |
| 1055 |
.PP |
| 1056 |
\fBppmtompeg\fP can generate a variety of statistics about the |
| 1057 |
encoding. See the \fB-stat\fP, \fB-snr\fP, \fB-mv_histogram\fP, |
| 1058 |
\fB-quiet\fP, \fB-no_frame_summary\fP, and \fB-bit_rate_info\fP |
| 1059 |
options. |
| 1060 |
|
| 1061 |
|
| 1062 |
.UN parallel |
| 1063 |
.SH PARALLEL OPERATION |
| 1064 |
.PP |
| 1065 |
You can run \fBppmtompeg\fP on multiple machines at once, encoding |
| 1066 |
the same MPEG stream. When you do, the machines are used as shown in |
| 1067 |
the following diagram. We call this "parallel mode." |
| 1068 |
.PP |
| 1069 |
.B ppmtompeg-par.gif |
| 1070 |
.IMG -C ppmtompeg-par.gif |
| 1071 |
.PP |
| 1072 |
To do parallel processing, put the statement |
| 1073 |
|
| 1074 |
.nf |
| 1075 |
PARALLEL |
| 1076 |
|
| 1077 |
.fi |
| 1078 |
|
| 1079 |
in the parameter file, followed by a listing of the machines, one |
| 1080 |
machine per line, then |
| 1081 |
|
| 1082 |
.nf |
| 1083 |
END_PARALLEL |
| 1084 |
|
| 1085 |
.fi |
| 1086 |
|
| 1087 |
Each of the machine lines must be in one of two forms. If the machine |
| 1088 |
has filesystem access to the input files, then the line is: |
| 1089 |
.PP |
| 1090 |
\fImachine\fP \fIuser\fP \fIexecutable\fP |
| 1091 |
.PP |
| 1092 |
The executable is normally \fBppmtompeg\fP (you may need to give |
| 1093 |
the complete path if you've built for different architectures). If |
| 1094 |
the machine does not have filesystem access to the input files, the line |
| 1095 |
is: |
| 1096 |
.PP |
| 1097 |
\fBREMOTE\fP \fImachine\fP \fIuser\fP \fIexecutable\fP |
| 1098 |
\fIparameter file\fP |
| 1099 |
.PP |
| 1100 |
The \fB-max_machines\fP command option limits the number of |
| 1101 |
machines \fBppmtompeg\fP will use. If you specify more machines in |
| 1102 |
the parameter file than \fB-max_machines\fP allows, \fBppmtompeg\fP |
| 1103 |
uses only the machines listed first. This is handy if you want to |
| 1104 |
experiment with different amounts of parallelism. |
| 1105 |
.PP |
| 1106 |
In general, you should use full path file names when describing |
| 1107 |
executables and parameter files. This \fIincludes\fP the parameter |
| 1108 |
file argument on the original invocation of \fBppmtompeg\fP. |
| 1109 |
.PP |
| 1110 |
All file names must be the same on all systems (so if e.g. you're |
| 1111 |
using an NFS filesystem, you must make sure it is mounted at the same |
| 1112 |
mountpoint on all systems). |
| 1113 |
.PP |
| 1114 |
Because not all of the processes involved in parallel operation |
| 1115 |
have easy access to the input files, you must specify the \fBSIZE\fP |
| 1116 |
parameter file statement when you do parallel operation. |
| 1117 |
.PP |
| 1118 |
The machine on which you originally invoke \fBppmtompeg\fP is the |
| 1119 |
master machine. It hosts a "combine server,", a |
| 1120 |
"decode server," and a number of "i/o servers," |
| 1121 |
all as separate processes. The other machines in the network (listed |
| 1122 |
in the parameter file) are slave machines. Each hosts a single |
| 1123 |
process that continuously requests work from the master and does it. |
| 1124 |
The slave process does the computation to encode MPEG frames. It |
| 1125 |
processes frames in batches identified by the master. |
| 1126 |
.PP |
| 1127 |
The master uses a remote shell command to start a process on a |
| 1128 |
slave machine. By default, it uses an \fBrsh\fP shell command to do |
| 1129 |
this. But use the \fBRSH\fP parameter file statement to control |
| 1130 |
this. The shell command the master executes remotely is |
| 1131 |
\fBppmtompeg\fP, but with options to indicate that it is to perform |
| 1132 |
slave functions. |
| 1133 |
.PP |
| 1134 |
The various machines talk to each other over TCP connections. Each |
| 1135 |
machine finds and binds to a free TCP port number and tells its |
| 1136 |
partners the port number. These port numbers are at least 2048. |
| 1137 |
.PP |
| 1138 |
Use the PARALLEL_TEST_FRAMES, PARALLEL_TIME_CHUNKS, and |
| 1139 |
PARALLEL_PERFECT parameter file statements to control the way the |
| 1140 |
master divides up work among the slaves. |
| 1141 |
.PP |
| 1142 |
Use the \fB-nice\fP command option to cause all slave processes to run |
| 1143 |
"nicely," i.e. as low priority processes. That way, this substantial and |
| 1144 |
long-running CPU load will have minimal impact on other, possibly |
| 1145 |
interactive, users of the systems. |
| 1146 |
|
| 1147 |
.UN speed |
| 1148 |
.SH SPEED |
| 1149 |
.PP |
| 1150 |
Here is a look at \fBppmtompeg\fP speed, in single-node (not parallel) |
| 1151 |
operation: |
| 1152 |
|
| 1153 |
.B Compression Speed |
| 1154 |
.TS |
| 1155 |
r c. |
| 1156 |
_ |
| 1157 |
Machine Type Macroblocks per second\u1\d |
| 1158 |
HP 9000/755 280 |
| 1159 |
DEC 3000/400 247 |
| 1160 |
HP 9000/750 191 |
| 1161 |
Sparc 10 104 |
| 1162 |
DEC 5000 68 |
| 1163 |
.TE |
| 1164 |
\u1\dA macroblock is a 16x16 pixel square |
| 1165 |
.PP |
| 1166 |
The measurements in the table are with inputs and outputs via a |
| 1167 |
conventional locally attached filesystem. If you are using a network |
| 1168 |
filesystem over a single 10 MB/s Ethernet, that constrains your speed more |
| 1169 |
than your CPU speed. In that case, don't expect to get better than 4 |
| 1170 |
or 5 frames per second no matter how fast your CPUs are. |
| 1171 |
.PP |
| 1172 |
Network speed is even more of a bottleneck when the slaves do not |
| 1173 |
have filesystem access to the input files -- i.e. you declare them |
| 1174 |
REMOTE. |
| 1175 |
.PP |
| 1176 |
Where I/O is the bottleneck, size of the input frames can make a big |
| 1177 |
difference. So YUV input is better than PPM, and JPEG is better than |
| 1178 |
both. |
| 1179 |
.PP |
| 1180 |
When you're first trying to get parallel mode working, be sure to |
| 1181 |
use the \fB-debug_machines\fP option so you can see what's going on. |
| 1182 |
Also, \fB-debug_sockets\fP can help you diagnose communication |
| 1183 |
problems. |
| 1184 |
|
| 1185 |
|
| 1186 |
.UN authors |
| 1187 |
.SH AUTHORS |
| 1188 |
|
| 1189 |
|
| 1190 |
|
| 1191 |
.IP \(bu |
| 1192 |
Kevin Gong - University of California, Berkeley, \[email protected]\fP |
| 1193 |
|
| 1194 |
.IP \(bu |
| 1195 |
Ketan Patel - University of California, Berkeley, \[email protected]\fP |
| 1196 |
|
| 1197 |
.IP \(bu |
| 1198 |
Dan Wallach - University of California, Berkeley, \[email protected]\fP |
| 1199 |
|
| 1200 |
.IP \(bu |
| 1201 |
Darryl Brown - University of California, Berkeley, \[email protected]\fP |
| 1202 |
|
| 1203 |
.IP \(bu |
| 1204 |
Eugene Hung - University of California, Berkeley, \[email protected]\fP |
| 1205 |
|
| 1206 |
.IP \(bu |
| 1207 |
Steve Smoot - University of California, Berkeley, \[email protected]\fP |
| 1208 |
.SH DOCUMENT SOURCE |
| 1209 |
This manual page was generated by the Netpbm tool 'makeman' from HTML |
| 1210 |
source. The master documentation is at |
| 1211 |
.IP |
| 1212 |
.B http://netpbm.sourceforge.net/doc/ppmtompeg.html |
| 1213 |
.PP |