[svn] / trunk / xvidcore / examples / README Repository:
ViewVC logotype

Diff of /trunk/xvidcore/examples/README

Parent Directory Parent Directory | Revision Log Revision Log | View Patch Patch

revision 561, Sat Sep 28 14:53:40 2002 UTC revision 562, Sat Sep 28 15:41:27 2002 UTC
# Line 1  Line 1 
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

Legend:
Removed from v.561  
changed lines
  Added in v.562

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