[svn] / branches / dev-api-4 / xvidcore / examples / README Repository:
ViewVC logotype

Annotation of /branches/dev-api-4/xvidcore/examples/README

Parent Directory Parent Directory | Revision Log Revision Log


Revision 886 - (view) (download)

1 : edgomez 562 +--------------------------------------------------------------------+
2 :     | XviD core lib examples |
3 :     +--------------------------------------------------------------------+
4 :    
5 : Isibaar 3 In this directory can find some examples how to use XviD MPEG4 codec
6 :     in your own programs.
7 :    
8 : edgomez 562 ** cactus.pgm.bz2
9 :     ----------------------------------------------------------------------
10 : Isibaar 3
11 : edgomez 562 This a test sequence of 3 images with a cactus moving from right to
12 :     left. It bzip2-compressed for size reason (half the size of a
13 :     ZIP-file). Binaries of bunzip2 are available for all major OSes at
14 :     http://sources.redhat.com/bzip2/ The original source of the cactus
15 :     image is unknown...
16 : Isibaar 3
17 : edgomez 562 * xvid_encraw.c
18 :     ----------------------------------------------------------------------
19 : Isibaar 3
20 : edgomez 562 This is a small example that allows you to encode YUV streams or PGM
21 :     files into a MPEG4 stream. It can output single files (on per encoded
22 :     frame), or one file for all the enced stream (m4v format or a simple
23 :     container format that we called mp4u, its description can be found at
24 :     the end of this file). This program also outputs some very basic time
25 :     results.
26 : Isibaar 3
27 : edgomez 562 Type "xvid_encraw -help" to have all options' description.
28 : Isibaar 3
29 : edgomez 562 Examples :
30 : Isibaar 3
31 : edgomez 562 1) bzip2 -dc cactus.pgm.bz2 | ./xvid_encraw -t 1
32 : Isibaar 3
33 : edgomez 562 This command decompress cactus.pgm.bz2 and pipe the pgm file to
34 :     xvid_encraw that will compress it to mpeg4 format. No mp4 stream
35 :     output is written to disc.
36 : Isibaar 3
37 : edgomez 562 2) ./xvid_encraw -t 1 -i cactus.pgm -m 1
38 : Isibaar 3
39 : edgomez 562 Compress cactus.pgm frames into mpeg4 stream, and then writes a m4v
40 :     file per encoded frame.
41 : Isibaar 3
42 : edgomez 562 3) ./xvid_encraw -t 1 -i cactus.pgm -m 1 -o my_xvid_example.m4v
43 : Isibaar 3
44 : edgomez 562 Same thing as above but saves all raw m4v data to a unique file.
45 :    
46 :     4) ./xvid_encraw -t 1 -i cactus.pgm -m 1 -mt 1 -o my_xvid_example.mp4u
47 :    
48 :     Same as above but encapsulates the m4v stream into the mp4u file
49 :     format.
50 :    
51 :     ** xvid_decraw.c
52 :     ----------------------------------------------------------------------
53 :    
54 :     This is a decoder example that is able to decode a m4v or mp4u
55 :     stream. You can use it to decode what xvid_encraw encoded.
56 :    
57 :     Type "xvid_decraw -help" to have all options' description.
58 :    
59 :     Examples :
60 :    
61 :     1) ./xvid_decraw -w 352 -h 240 -t 1 -i stream.mp4u -d 1
62 :    
63 :     This command decodes a mp4u file (-t 1 option) from stream.mp4u and
64 :     writes all decoded frames to single PGM files (framexxxxx.pgm).
65 :    
66 :     2) cat stream.m4v | ./xvid_decraw -w 352 -h 240
67 :    
68 :     This one reads a m4v file from standard input and outputs just
69 :     decoding statistics.
70 :    
71 :     NB :-w and -h parameters are mandatory as XviD lacks a "discover
72 :     width and height" from m4v stream. This feature will be added at
73 :     a later time, so for now we must use these options.
74 :    
75 :    
76 :     * xvid_stat.c
77 :     ----------------------------------------------------------------------
78 :    
79 :     This last example is a kind of xvid_dec/encraw merged program, it
80 :     encodes PGM or YUV files and decode the resulting mp4 stream to
81 :     measure both encoding and decoded times as well as PSNR.
82 :    
83 :     Type "xvid_stat -help" to have all options' description.
84 :    
85 :     Examples:
86 :    
87 :     1) ./xvid_stat < cactus.pgm
88 :    
89 :     This calls xvid_stat with standard parameters for the 3 frames from
90 :     the cactus file from examples directory.
91 :    
92 :     Output should look similar to this:
93 :    
94 :     Frame 0: intra 1, enctime = 4.7 ms length= 12470 bytes dectime = 4.2 ms PSNR 39.93
95 :     Frame 1: intra 0, enctime = 6.9 ms length= 1369 bytes dectime = 1.8 ms PSNR 40.40
96 :     Frame 2: intra 0, enctime = 6.6 ms length= 3354 bytes dectime = 2.3 ms PSNR 42.03
97 :     Avg. Q6 br 0900 (0.43 bpp) size 5731 (1146 kbps / 0.54 bpp) enc: 164.7 fps, dec: 362.0 fps
98 :     PSNR P(2): 41.22 ( 40.40 , 42.03 ; 0.4698 ) I(1): 39.93 ( 39.93 , 39.93 ; 0.0000 )
99 :    
100 :    
101 :     The lines in detail:
102 :    
103 :     For every input frame one line is printed containing the data:
104 :    
105 :     Frame the frame number, starting with 0
106 :    
107 :     intra if the frame was encoded as I-frame (1) or P-frame (0), when
108 :     B-frames are supported, they will get a value of 2
109 :     here. enctime time for encoding this frame, in milliseconds
110 :     (1/1000th of a second)
111 :    
112 :     length length of the MPEG-4 bitstream generated from this frame (in
113 :     bytes)
114 :    
115 :     dectime time for decoding
116 :    
117 :     PSNR picture signal to noice ratio (a measurement of quality,
118 :     higher is better)
119 :    
120 :     Then in the end, two status lines are printed, these can be used,
121 :     e.g. for automatic quality tests:
122 :    
123 :     Avg. indicated that we are now talking about average values
124 :    
125 :     Q6 quality parameter that was used (so here it was quality
126 :     level 6)
127 :    
128 :     br 0900 bitrate mode was used with a bitrate of 900kbps the other
129 :     possibility is "q" instead of "br", see another example.
130 :    
131 :     size 5731 average size of an encoded frame
132 :    
133 :     1146 kbps "real" bitrate that was achieved, it may differ from the
134 :     bitrate given to the codec as a parameter, because this is
135 :     real life
136 :    
137 :     0.54 bpp number of bit per pixel for the encoding, useful when
138 :     comparing videos of different size
139 :    
140 :     enc: 164.7 fps speed of encoding in frames per second
141 :    
142 :     dec: 362.0 fps speed of decoding in frames per second
143 :    
144 :     2) ./xvid_stat -q 6 -b 900 -f 25 -i cactus.pgm
145 :    
146 :     This does exactly the same as above, but parameters are provided
147 :     instead of using default value. Output should be the same as in last
148 :     example. Note that first and second parameter are 0, indicating
149 :     that a PGM file should be read (which has a header that includes X
150 :     and Y dimensions).
151 :    
152 :    
153 :     3) ./xvid_stat -t 1 -q 1 -quant 8 -i cactus.pgm
154 :    
155 :     Output:
156 :    
157 :     Frame 0: intra 1, enctime = 4.1 ms length= 8420 bytes dectime = 3.4 ms PSNR 36.36
158 :     Frame 1: intra 0, enctime = 3.0 ms length= 659 bytes dectime = 1.5 ms PSNR 36.36
159 :     Frame 2: intra 0, enctime = 2.7 ms length= 595 bytes dectime = 1.5 ms PSNR 36.43
160 :     Avg. Q1 q 0008 (0.00 bpp) size 3224 ( 644 kbps / 0.31 bpp)enc: 304.3 fps, dec: 467.1 fps
161 :     PSNR P(2): 36.40 ( 36.36 , 36.43 ; 0.0210 ) I(1): 36.36 ( 36.36 , 36.36 ; 0.0000 )
162 :    
163 :     This time, quality 1 is used, so output values are a little
164 :     different. Since the fourth parameter (here 8) is smaller than 32,
165 :     it is not considered as a bitrate value, but as a fixed quantizer.
166 :     So in the "Avg." line there is a :
167 :    
168 :     q 0008 meaning "fixed quantizer mode" with quantizer 8.
169 :    
170 :     4) ./xvid_stat -w 176 -h 144 -q 5 -b 112 -i foreman.qcif
171 :    
172 :     This switches xvid_stat to RAW instead of PGM mode. The input is
173 :     expected to be images of dimensions 176*144 in raw YUV 4:2:0
174 :     format. (So every image is exactly 38016 = 176*144 + 88*72 + 88*72
175 :     bytes in size). Some reference streams are in this format. Note
176 :     that you MUST give correct dimensions, because they cannot be
177 :     detected from the YUV material. Apart from this, the example uses
178 :     quality 5 and a bitrate of 112 kbps with video speed of 30 frames
179 :     per second (this is not encoding or decoding speed, but the speed at
180 :     which the video would be played. This value is only important for
181 :     ratecontrol...)
182 :    
183 :    
184 :    
185 :     ** MP4U Format
186 :     ----------------------------------------------------------------------
187 :    
188 :     - Header :
189 :    
190 :     +-----+-----+-----+-----+
191 :     | M | P | 4 | U |
192 :     +-----+-----+-----+-----+
193 :     |1byte|1byte|1byte|1byte|
194 :     +-----+-----+-----+-----+
195 :    
196 :     - Encoded frame
197 :    
198 :     +------+----------------------- ... --+
199 :     | size | ... Frame data ... |
200 :     +------+----------------------- ... --+
201 :     |4bytes| 'size' bytes |
202 :     +------+----------------------- ... --+
203 :    
204 :     + size is written in big endian format
205 :     + frame data is m4v raw data generated by XviD core.
206 :    
207 :     - File format
208 :    
209 :     Header + x*Encoded frame

No admin address has been configured
ViewVC Help
Powered by ViewVC 1.0.4