[ViewVC] Contents of: svn/branches/release-0_9_1-fixes/xvidcore/examples/README

+--------------------------------------------------------------------+
|                      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
Revision:	847
Committed:	Thu Feb 13 17:31:35 2003 UTC (21 years, 7 months ago)
File size:	7756 byte(s)
Log Message:	This commit was manufactured by cvs2svn to create branch 'release-0_9_1-fixes'.
#	Content
1	+--------------------------------------------------------------------+
2	\| XviD core lib examples \|
3	+--------------------------------------------------------------------+
4
5	In this directory can find some examples how to use XviD MPEG4 codec
6	in your own programs.
7
8	** 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 = 176144 + 8872 + 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