1 |
|
+--------------------------------------------------------------------+ |
2 |
|
| XviD core lib examples | |
3 |
|
+--------------------------------------------------------------------+ |
4 |
|
|
5 |
In this directory can find some examples how to use XviD MPEG4 codec |
In this directory can find some examples how to use XviD MPEG4 codec |
6 |
in your own programs. |
in your own programs. |
7 |
|
|
8 |
Christoph (gruel@web.de) |
** cactus.pgm.bz2 |
9 |
|
---------------------------------------------------------------------- |
10 |
|
|
11 |
|
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 |
|
|
17 |
|
* xvid_encraw.c |
18 |
|
---------------------------------------------------------------------- |
19 |
|
|
20 |
|
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 |
|
|
27 |
|
Type "xvid_encraw -help" to have all options' description. |
28 |
|
|
29 |
|
Examples : |
30 |
|
|
31 |
|
1) bzip2 -dc cactus.pgm.bz2 | ./xvid_encraw -t 1 |
32 |
|
|
33 |
|
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 |
|
|
37 |
|
2) ./xvid_encraw -t 1 -i cactus.pgm -m 1 |
38 |
|
|
39 |
|
Compress cactus.pgm frames into mpeg4 stream, and then writes a m4v |
40 |
|
file per encoded frame. |
41 |
|
|
42 |
|
3) ./xvid_encraw -t 1 -i cactus.pgm -m 1 -o my_xvid_example.m4v |
43 |
|
|
44 |
|
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 |
* xvid_enc_dec.c |
** MP4U Format |
186 |
|
---------------------------------------------------------------------- |
187 |
|
|
188 |
This is a complete example of the XviD-API for encoding and decoding: |
- Header : |
|
The program reads a file of YUV 4:2:0 images (as greyscale picture in |
|
|
PGM-format) and encodes this sequence to a MPEG4 bytestream. Then it |
|
|
decodes right away. |
|
189 |
|
|
190 |
* odivx_enc_dec.c |
+-----+-----+-----+-----+ |
191 |
|
| M | P | 4 | U | |
192 |
|
+-----+-----+-----+-----+ |
193 |
|
|1byte|1byte|1byte|1byte| |
194 |
|
+-----+-----+-----+-----+ |
195 |
|
|
196 |
Same program, but using the OpenDivX/DivX4 compatibility API. Wit this |
- Encoded frame |
|
you can use source written for DivX4 and simply relink with XviD-corelibrary. |
|
197 |
|
|
198 |
|
+------+----------------------- ... --+ |
199 |
|
| size | ... Frame data ... | |
200 |
|
+------+----------------------- ... --+ |
201 |
|
|4bytes| 'size' bytes | |
202 |
|
+------+----------------------- ... --+ |
203 |
|
|
204 |
* cactus.pgm.bz2 |
+ size is written in big endian format |
205 |
|
+ frame data is m4v raw data generated by XviD core. |
206 |
|
|
207 |
Example input file for multi_dec_enc.c. A sequence of 3 images, a szene |
- File format |
|
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... |
|
208 |
|
|
209 |
|
Header + x*Encoded frame |