Debian Codegraph @

upstream/debian-unstable/man1/ppmtompeg.1

raw
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