--- trunk/xvidcore/examples/README 2005/09/18 01:34:13 1636 +++ trunk/xvidcore/examples/README 2005/09/20 11:19:34 1637 @@ -28,25 +28,22 @@ Examples : - 1) bzip2 -dc cactus.pgm.bz2 | ./xvid_encraw -t 1 + 1) bzip2 -dc cactus.pgm.bz2 | ./xvid_encraw -type 1 - This command decompress cactus.pgm.bz2 and pipe the pgm file to - xvid_encraw that will compress it to mpeg4 format. No mp4 stream - output is written to disc. + This command decompress cactus.pgm.bz2 and pipe the pgm file to + xvid_encraw that will compress it to mpeg4 format. No mp4 stream + output is written to disk. - 2) ./xvid_encraw -t 1 -i cactus.pgm -m 1 + 2) ./xvid_encraw -type 1 -i cactus.pgm -save - Compress cactus.pgm frames into mpeg4 stream, and then writes a m4v - file per encoded frame. + Compress cactus.pgm frames into mpeg4 stream, and then writes a + m4v file per encoded frame. - 3) ./xvid_encraw -t 1 -i cactus.pgm -m 1 -o my_xvid_example.m4v + 3) ./xvid_encraw -type 1 -i cactus.pgm -o my_xvid_example.m4v -stats - Same thing as above but saves all raw m4v data to a unique file. + Same thing as above but saves all raw m4v data to a singlefile, + and displays yuv-plane psnr statistics to stdout. - 4) ./xvid_encraw -t 1 -i cactus.pgm -m 1 -mt 1 -o my_xvid_example.mp4u - - Same as above but encapsulates the m4v stream into the mp4u file - format. ** xvid_decraw.c ---------------------------------------------------------------------- @@ -58,152 +55,20 @@ Examples : - 1) ./xvid_decraw -w 352 -h 240 -t 1 -i stream.mp4u -d 1 - - This command decodes a mp4u file (-t 1 option) from stream.mp4u and - writes all decoded frames to single PGM files (framexxxxx.pgm). + 1) ./xvid_decraw -i stream.m4v -d - 2) cat stream.m4v | ./xvid_decraw -w 352 -h 240 + This command decodes a m4v file from stream.m4v and saves all + decoder output frames to individual PGM files (framexxxxx.pgm). - This one reads a m4v file from standard input and outputs just - decoding statistics. + 2) cat stream.m4v | ./xvid_decraw - NB :-w and -h parameters are mandatory as XviD lacks a "discover - width and height" from m4v stream. This feature will be added at - a later time, so for now we must use these options. + This examples decodes a m4v stream from standard input, but does + save any decoded frames. -* xvid_stat.c +** xvid_bench.c ---------------------------------------------------------------------- -This last example is a kind of xvid_dec/encraw merged program, it -encodes PGM or YUV files and decode the resulting mp4 stream to -measure both encoding and decoded times as well as PSNR. - -Type "xvid_stat -help" to have all options' description. - -Examples: - - 1) ./xvid_stat < cactus.pgm - - This calls xvid_stat with standard parameters for the 3 frames from - the cactus file from examples directory. - - Output should look similar to this: - - Frame 0: intra 1, enctime = 4.7 ms length= 12470 bytes dectime = 4.2 ms PSNR 39.93 - Frame 1: intra 0, enctime = 6.9 ms length= 1369 bytes dectime = 1.8 ms PSNR 40.40 - Frame 2: intra 0, enctime = 6.6 ms length= 3354 bytes dectime = 2.3 ms PSNR 42.03 - Avg. Q6 br 0900 (0.43 bpp) size 5731 (1146 kbps / 0.54 bpp) enc: 164.7 fps, dec: 362.0 fps - PSNR P(2): 41.22 ( 40.40 , 42.03 ; 0.4698 ) I(1): 39.93 ( 39.93 , 39.93 ; 0.0000 ) - - - The lines in detail: - - For every input frame one line is printed containing the data: - - Frame the frame number, starting with 0 - - intra if the frame was encoded as I-frame (1) or P-frame (0), when - B-frames are supported, they will get a value of 2 - here. enctime time for encoding this frame, in milliseconds - (1/1000th of a second) - - length length of the MPEG-4 bitstream generated from this frame (in - bytes) - - dectime time for decoding - - PSNR picture signal to noice ratio (a measurement of quality, - higher is better) - - Then in the end, two status lines are printed, these can be used, - e.g. for automatic quality tests: - - Avg. indicated that we are now talking about average values - - Q6 quality parameter that was used (so here it was quality - level 6) - - br 0900 bitrate mode was used with a bitrate of 900kbps the other - possibility is "q" instead of "br", see another example. - - size 5731 average size of an encoded frame - - 1146 kbps "real" bitrate that was achieved, it may differ from the - bitrate given to the codec as a parameter, because this is - real life - - 0.54 bpp number of bit per pixel for the encoding, useful when - comparing videos of different size - - enc: 164.7 fps speed of encoding in frames per second - - dec: 362.0 fps speed of decoding in frames per second - - 2) ./xvid_stat -q 6 -b 900 -f 25 -i cactus.pgm - - This does exactly the same as above, but parameters are provided - instead of using default value. Output should be the same as in last - example. Note that first and second parameter are 0, indicating - that a PGM file should be read (which has a header that includes X - and Y dimensions). - - - 3) ./xvid_stat -t 1 -q 1 -quant 8 -i cactus.pgm - - Output: - - Frame 0: intra 1, enctime = 4.1 ms length= 8420 bytes dectime = 3.4 ms PSNR 36.36 - Frame 1: intra 0, enctime = 3.0 ms length= 659 bytes dectime = 1.5 ms PSNR 36.36 - Frame 2: intra 0, enctime = 2.7 ms length= 595 bytes dectime = 1.5 ms PSNR 36.43 - Avg. Q1 q 0008 (0.00 bpp) size 3224 ( 644 kbps / 0.31 bpp)enc: 304.3 fps, dec: 467.1 fps - PSNR P(2): 36.40 ( 36.36 , 36.43 ; 0.0210 ) I(1): 36.36 ( 36.36 , 36.36 ; 0.0000 ) - - This time, quality 1 is used, so output values are a little - different. Since the fourth parameter (here 8) is smaller than 32, - it is not considered as a bitrate value, but as a fixed quantizer. - So in the "Avg." line there is a : - - q 0008 meaning "fixed quantizer mode" with quantizer 8. - - 4) ./xvid_stat -w 176 -h 144 -q 5 -b 112 -i foreman.qcif - - This switches xvid_stat to RAW instead of PGM mode. The input is - expected to be images of dimensions 176*144 in raw YUV 4:2:0 - format. (So every image is exactly 38016 = 176*144 + 88*72 + 88*72 - bytes in size). Some reference streams are in this format. Note - that you MUST give correct dimensions, because they cannot be - detected from the YUV material. Apart from this, the example uses - quality 5 and a bitrate of 112 kbps with video speed of 30 frames - per second (this is not encoding or decoding speed, but the speed at - which the video would be played. This value is only important for - ratecontrol...) - - - -** MP4U Format ----------------------------------------------------------------------- - - - Header : - - +-----+-----+-----+-----+ - | M | P | 4 | U | - +-----+-----+-----+-----+ - |1byte|1byte|1byte|1byte| - +-----+-----+-----+-----+ - - - Encoded frame - - +------+----------------------- ... --+ - | size | ... Frame data ... | - +------+----------------------- ... --+ - |4bytes| 'size' bytes | - +------+----------------------- ... --+ - - + size is written in big endian format - + frame data is m4v raw data generated by XviD core. - - - File format +This is a tool to conduct unit testing and profiling of the signal +processing functions used internally within libxvidcore. - Header + x*Encoded frame