+--------------------------------------------------------------------+ | XviD core lib examples | +--------------------------------------------------------------------+ In this directory can find some examples how to use XviD MPEG4 codec in your own programs. ** cactus.pgm.bz2 ---------------------------------------------------------------------- This a test sequence of 3 images with a cactus moving from right to left. It bzip2-compressed for size reason (half the size of a ZIP-file). Binaries of bunzip2 are available for all major OSes at http://sources.redhat.com/bzip2/ The original source of the cactus image is unknown... * xvid_encraw.c ---------------------------------------------------------------------- This is a small example that allows you to encode YUV streams or PGM files into a MPEG4 stream. It can output single files (on per encoded frame), or one file for all the enced stream (m4v format or a simple container format that we called mp4u, its description can be found at the end of this file). This program also outputs some very basic time results. Type "xvid_encraw -help" to have all options' description. Examples : 1) bzip2 -dc cactus.pgm.bz2 | ./xvid_encraw -t 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. 2) ./xvid_encraw -t 1 -i cactus.pgm -m 1 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 Same thing as above but saves all raw m4v data to a unique file. 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 ---------------------------------------------------------------------- This is a decoder example that is able to decode a m4v or mp4u stream. You can use it to decode what xvid_encraw encoded. Type "xvid_decraw -help" to have all options' description. 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). 2) cat stream.m4v | ./xvid_decraw -w 352 -h 240 This one reads a m4v file from standard input and outputs just decoding statistics. 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. * xvid_stat.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 Header + x*Encoded frame