mention libavformat API examples
[ffmpeg.git] / doc / ffmpeg-doc.texi
1 \input texinfo @c -*- texinfo -*-
2
3 @settitle FFmpeg Documentation
4 @titlepage
5 @sp 7
6 @center @titlefont{FFmpeg Documentation}
7 @sp 3
8 @end titlepage
9
10
11 @chapter Introduction
12
13 FFmpeg is a very fast video and audio converter. It can also grab from
14 a live audio/video source.
15   
16 The command line interface is designed to be intuitive, in the sense
17 that ffmpeg tries to figure out all the parameters, when
18 possible. You have usually to give only the target bitrate you want.
19
20 FFmpeg can also convert from any sample rate to any other, and resize
21 video on the fly with a high quality polyphase filter.
22
23 @chapter Quick Start
24
25 @section Video and Audio grabbing
26
27  FFmpeg can use a video4linux compatible video source and any Open Sound
28   System audio source:
29 @example
30   ffmpeg /tmp/out.mpg 
31 @end example
32
33   Note that you must activate the right video source and channel before
34   launching ffmpeg. You can use any TV viewer such as xawtv
35   (@url{http://bytesex.org/xawtv/}) by Gerd Knorr which I find very
36   good. You must also set correctly the audio recording levels with a
37   standard mixer.
38
39 @section Video and Audio file format conversion
40
41 * ffmpeg can use any supported file format and protocol as input: 
42
43 Examples:
44
45 * You can input from YUV files:
46
47 @example
48   ffmpeg -i /tmp/test%d.Y /tmp/out.mpg 
49 @end example
50
51   It will use the files: 
52 @example
53        /tmp/test0.Y, /tmp/test0.U, /tmp/test0.V,
54        /tmp/test1.Y, /tmp/test1.U, /tmp/test1.V, etc...
55 @end example
56
57   The Y files use twice the resolution of the U and V files. They are
58   raw files, without header. They can be generated by all decent video
59   decoders. You must specify the size of the image with the '-s' option
60   if ffmpeg cannot guess it.
61
62 * You can input from a RAW YUV420P file:
63
64 @example
65   ffmpeg -i /tmp/test.yuv /tmp/out.avi
66 @end example
67
68   The RAW YUV420P is a file containing RAW YUV planar, for each frame first
69   come the Y plane followed by U and V planes, which are half vertical and
70   horizontal resolution.
71
72 * You can output to a RAW YUV420P file:
73
74 @example
75   ffmpeg -i mydivx.avi -o hugefile.yuv
76 @end example
77
78 * You can set several input files and output files:
79
80 @example
81   ffmpeg -i /tmp/a.wav -s 640x480 -i /tmp/a.yuv /tmp/a.mpg
82 @end example
83
84   Convert the audio file a.wav and the raw yuv video file a.yuv
85   to mpeg file a.mpg
86
87 * You can also do audio and video conversions at the same time:
88
89 @example
90   ffmpeg -i /tmp/a.wav -ar 22050 /tmp/a.mp2
91 @end example
92
93   Convert the sample rate of a.wav to 22050 Hz and encode it to MPEG audio.
94
95 * You can encode to several formats at the same time and define a
96   mapping from input stream to output streams:
97
98 @example
99   ffmpeg -i /tmp/a.wav -ab 64 /tmp/a.mp2 -ab 128 /tmp/b.mp2 -map 0:0 -map 0:0
100 @end example
101
102   Convert a.wav to a.mp2 at 64 kbits and b.mp2 at 128 kbits. '-map
103   file:index' specify which input stream is used for each output
104   stream, in the order of the definition of output streams.
105
106 * You can transcode decrypted VOBs
107
108 @example
109   ffmpeg -i snatch_1.vob -f avi -vcodec mpeg4 -b 800 -g 300 -bf 2 -acodec mp3 -ab 128 snatch.avi
110 @end example
111
112   This is a typical DVD ripper example, input from a VOB file, output
113   to an AVI file with MPEG-4 video and MP3 audio, note that in this
114   command we use B frames so the MPEG-4 stream is DivX5 compatible, GOP
115   size is 300 that means an INTRA frame every 10 seconds for 29.97 fps
116   input video.  Also the audio stream is MP3 encoded so you need LAME
117   support which is enabled using @code{--enable-mp3lame} when
118   configuring.  The mapping is particularly useful for DVD transcoding
119   to get the desired audio language.
120
121   NOTE: to see the supported input formats, use @code{ffmpeg -formats}.
122
123 @chapter Invocation
124
125 @section Syntax
126
127  The generic syntax is:
128
129 @example 
130   ffmpeg [[options][-i input_file]]... {[options] output_file}...
131 @end example
132   If no input file is given, audio/video grabbing is done.
133
134   As a general rule, options are applied to the next specified
135   file. For example, if you give the '-b 64' option, it sets the video
136   bitrate of the next file. Format option may be needed for raw input
137   files.
138
139   By default, ffmpeg tries to convert as losslessly as possible: it
140   uses the same audio and video parameter for the outputs as the one
141   specified for the inputs.
142
143 @section Main options
144
145 @table @samp
146 @item -L
147 show license
148 @item -h
149                   show help
150 @item -formats            
151 show available formats, codecs, protocols, ...
152 @item -f fmt              
153 force format
154 @item -i filename         
155 input file name
156
157 @item -y                  
158 overwrite output files
159
160 @item -t duration         
161 set the recording time in seconds. @code{hh:mm:ss[.xxx]} syntax is also
162 supported.
163
164 @item -title string       
165 set the title
166
167 @item -author string      
168 set the author
169
170 @item -copyright string   
171 set the copyright
172
173 @item -comment string     
174 set the comment
175
176 @item -b bitrate          
177 set video bitrate (in kbit/s)
178 @end table
179
180 @section Video Options
181
182 @table @samp
183 @item -s size             
184 set frame size                       [160x128]
185 @item -r fps           
186 set frame rate                       [25]
187 @item -b bitrate
188 set the video bitrate in kbit/s      [200]
189 @item -vn
190 disable video recording              [no]
191 @item -bt tolerance       
192 set video bitrate tolerance (in kbit/s)
193 @item -sameq              
194 use same video quality as source (implies VBR)
195
196 @item -pass n  
197 select the pass number (1 or 2). It is useful to do two pass encoding. The statistics of the video are recorded in the first pass and the video at the exact requested bit rate is generated in the second pass.
198
199 @item -passlogfile file   
200 select two pass log file name
201
202 @end table
203
204 @section Audio Options
205
206 @table @samp
207 @item -ab bitrate         
208 set audio bitrate (in kbit/s)
209 @item -ar freq    
210  set the audio sampling freq          [44100]
211 @item -ab bitrate 
212  set the audio bitrate in kbit/s      [64]
213 @item -ac channels
214  set the number of audio channels     [1]
215 @item -an     
216  disable audio recording              [no]
217 @end table
218
219 @section Advanced options
220
221 @table @samp
222 @item -map file:stream    
223 set input stream mapping
224 @item -g gop_size         
225 set the group of picture size
226 @item -intra              
227 use only intra frames
228 @item -qscale q           
229 use fixed video quantiser scale (VBR)
230 @item -qmin q             
231 min video quantiser scale (VBR)
232 @item -qmax q             
233 max video quantiser scale (VBR)
234 @item -qdiff q            
235 max difference between the quantiser scale (VBR)
236 @item -qblur blur         
237 video quantiser scale blur (VBR)
238 @item -qcomp compression  
239 video quantiser scale compression (VBR)
240 @item -vd device          
241 set video device
242 @item -vcodec codec       
243 force video codec
244 @item -me method          
245 set motion estimation method
246 @item -bf frames          
247 use 'frames' B frames (only MPEG-4)
248 @item -hq                 
249 activate high quality settings
250 @item -4mv                
251 use four motion vector by macroblock (only MPEG-4)
252 @item -ad device          
253 set audio device
254 @item -acodec codec       
255 force audio codec
256 @item -deinterlace        
257 deinterlace pictures
258 @item -benchmark          
259 add timings for benchmarking
260 @item -hex                
261 dump each input packet
262 @item -psnr               
263 calculate PSNR of compressed frames
264 @item -vstats             
265 dump video coding statistics to file
266 @end table
267
268 @section Protocols
269
270 The filename can be @file{-} to read from the standard input or to write
271 to the standard output.
272
273 ffmpeg handles also many protocols specified with the URL syntax.
274
275  Use 'ffmpeg -formats' to have a list of the supported protocols.
276
277  The protocol @code{http:} is currently used only to communicate with
278  ffserver (see the ffserver documentation). When ffmpeg will be a
279  video player it will also be used for streaming :-)
280
281 @chapter Tips
282
283 @itemize
284 @item For streaming at very low bit rate application, use a low frame rate
285   and a small gop size. This is especially true for real video where
286   the Linux player does not seem to be very fast, so it can miss
287   frames. An example is:
288
289 @example
290   ffmpeg -g 3 -r 3 -t 10 -b 50 -s qcif -f rv10 /tmp/b.rm
291 @end example
292
293 @item  The parameter 'q' which is displayed while encoding is the current
294   quantizer. The value of 1 indicates that a very good quality could
295   be achieved. The value of 31 indicates the worst quality. If q=31
296   too often, it means that the encoder cannot compress enough to meet
297   your bit rate. You must either increase the bit rate, decrease the
298   frame rate or decrease the frame size.
299
300 @item If your computer is not fast enough, you can speed up the
301   compression at the expense of the compression ratio. You can use
302   '-me zero' to speed up motion estimation, and '-intra' to disable
303   completely motion estimation (you have only I frames, which means it
304   is about as good as JPEG compression).
305
306 @item To have very low bitrates in audio, reduce the sampling frequency
307   (down to 22050 kHz for mpeg audio, 22050 or 11025 for ac3).
308
309 @item To have a constant quality (but a variable bitrate), use the option
310   '-qscale n' when 'n' is between 1 (excellent quality) and 31 (worst
311   quality).
312
313 @item When converting video files, you can use the '-sameq' option which
314   uses in the encoder the same quality factor than in the decoder. It
315   allows to be almost lossless in encoding.
316
317 @end itemize
318
319 @chapter Supported File Formats and Codecs
320
321 You can use the @code{-formats} option to have an exhaustive list.
322
323 @section File Formats
324
325 FFmpeg supports the following file formats through the @code{libavformat}
326 library:
327
328 @multitable @columnfractions .4 .1 .1
329 @item Supported File Format @tab Encoding @tab Decoding @tab Comments
330 @item MPEG audio @tab X @tab X
331 @item MPEG1 systems @tab X  @tab  X 
332 @tab muxed audio and video
333 @item MPEG2 PS @tab X  @tab  X 
334 @tab also known as @code{VOB} file
335 @item MPEG2 TS @tab    @tab  X 
336 @tab also known as DVB Transport Stream
337 @item ASF@tab X @tab X 
338 @item AVI@tab X @tab X 
339 @item WAV@tab X @tab X 
340 @item Macromedia Flash@tab X @tab X
341 @tab Only embedded audio is decoded
342 @item Real Audio and Video @tab X @tab X 
343 @item Raw AC3 @tab X  @tab  X 
344 @item Raw MJPEG @tab X  @tab  X 
345 @item Raw MPEG video @tab X  @tab  X 
346 @item Raw PCM8/16 bits, mulaw/Alaw@tab X  @tab  X 
347 @item SUN AU format @tab X  @tab  X 
348 @item Quicktime        @tab   @tab  X 
349 @item MPEG4            @tab  @tab  X 
350 @tab MPEG4 is a variant of Quicktime
351 @item Raw MPEG4 video  @tab  X @tab  X 
352 @item DV               @tab  @tab X
353 @tab Only the video track is decoded.
354 @item 4xm              @tab    @tab X
355 @tab 4X Technologies format, used in some games
356 @end multitable
357
358 @code{X} means that the encoding (resp. decoding) is supported.
359
360 @section Image Formats
361
362 FFmpeg can read and write images for each frame of a video sequence. The
363 following image formats are supported:
364
365 @multitable @columnfractions .4 .1 .1
366 @item Supported Image Format @tab Encoding @tab Decoding @tab Comments
367 @item PGM, PPM     @tab X @tab X 
368 @item PGMYUV       @tab X @tab X @tab PGM with U and V components in 420
369 @item JPEG         @tab X @tab X @tab Progressive JPEG is not supported
370 @item .Y.U.V       @tab X @tab X @tab One raw file per component
371 @item Animated GIF @tab X @tab   @tab Only uncompressed GIFs are generated
372 @end multitable
373
374 @code{X} means that the encoding (resp. decoding) is supported.
375
376 @section Video Codecs
377
378 @multitable @columnfractions .4 .1 .1 .7
379 @item Supported Codec @tab Encoding @tab Decoding @tab Comments
380 @item MPEG1 video            @tab  X  @tab  X
381 @item MPEG2 video            @tab     @tab  X 
382 @item MPEG4                  @tab  X  @tab  X @tab Also known as DIVX4/5
383 @item MSMPEG4 V1             @tab  X  @tab  X
384 @item MSMPEG4 V2             @tab  X  @tab  X
385 @item MSMPEG4 V3             @tab  X  @tab  X @tab Also known as DIVX3
386 @item WMV7                   @tab  X  @tab  X
387 @item WMV8                   @tab  X  @tab  X @tab Not completely working
388 @item H263(+)                @tab  X  @tab  X @tab Also known as Real Video 1.0
389 @item MJPEG                  @tab  X  @tab  X 
390 @item DV                     @tab     @tab  X 
391 @item Huff YUV               @tab  X  @tab  X
392 @item Asus v1                @tab  X  @tab  X @tab fourcc: ASV1
393 @item Creative YUV           @tab     @tab  X @tab fourcc: CYUV
394 @item H.264                  @tab     @tab  X
395 @item Sorenson Video 1       @tab     @tab  X @tab fourcc: SVQ1
396 @item Sorenson Video 3       @tab     @tab  X @tab fourcc: SVQ3
397 @item On2 VP3                @tab     @tab  X @tab still experimental
398 @item Intel Indeo 3          @tab     @tab  X @tab only works on i386 right now
399 @end multitable
400
401 @code{X} means that the encoding (resp. decoding) is supported.
402
403 Check at @url{http://www.mplayerhq.hu/~michael/codec-features.html} to
404 get a precise comparison of FFmpeg MPEG4 codec compared to the other
405 solutions.
406
407 @section Audio Codecs
408
409 @multitable @columnfractions .4 .1 .1 .1 .7
410 @item Supported Codec @tab Encoding @tab Decoding @tab Comments
411 @item MPEG audio layer 2     @tab  IX  @tab  IX 
412 @item MPEG audio layer 1/3   @tab IX   @tab  IX
413 @tab MP3 encoding is supported through the external library LAME
414 @item AC3                    @tab  IX  @tab  X
415 @tab liba52 is used internally for decoding.
416 @item Vorbis                 @tab  X   @tab  X
417 @tab supported through the external library libvorbis.
418 @item WMA V1/V2              @tab      @tab X
419 @item Microsoft ADPCM        @tab X    @tab X
420 @item IMA ADPCM              @tab X    @tab X
421 @end multitable
422
423 @code{X} means that the encoding (resp. decoding) is supported.
424
425 @code{I} means that an integer only version is available too (ensures highest
426 performances on systems without hardware floating point support).
427
428 @chapter Platform Specific information
429
430 @section Linux
431
432 ffmpeg should be compiled with at least GCC 2.95.3. GCC 3.2 is the
433 preferred compiler now for ffmpeg. All future optimizations will depend on
434 features only found in GCC 3.2.
435
436 @section BSD
437
438 @section Windows
439
440 @section MacOS X
441
442 @section BeOS
443
444 The configure script should guess the configuration itself.
445 Networking support is currently not finished.
446 errno issues fixed by Andrew Bachmann.
447
448 Old stuff:
449
450 Fran├žois Revol - revol at free dot fr - April 2002
451
452 The configure script should guess the configuration itself, 
453 however I still didn't tested building on net_server version of BeOS.
454
455 ffserver is broken (needs poll() implementation).
456
457 There is still issues with errno codes, which are negative in BeOs, and
458 that ffmpeg negates when returning. This ends up turning errors into 
459 valid results, then crashes.
460 (To be fixed)
461
462 @chapter Developers Guide
463
464 @section API
465 @itemize
466 @item libavcodec is the library containing the codecs (both encoding and
467   decoding). See @file{libavcodec/apiexample.c} to see how to use it.
468
469 @item libavformat is the library containing the file formats handling (mux and
470   demux code for several formats). See @file{ffplay.c} to use it in a
471 player. See @file{output_example.c} to use it to generate audio or video
472 streams.
473
474 @end itemize
475
476 @section Integrating libavcodec or libavformat in your program
477
478 You can integrate all the source code of the libraries to link them
479 statically to avoid any version problem. All you need is to provide a
480 'config.mak' and a 'config.h' in the parent directory. See the defines
481 generated by ./configure to understand what is needed.
482
483 You can use libavcodec or libavformat in your commercial program, but
484 @emph{any patch you make must be published}. The best way to proceed is
485 to send your patches to the ffmpeg mailing list.
486
487 @section Coding Rules
488
489 ffmpeg is programmed in ANSI C language. GCC extensions are
490 tolerated. Indent size is 4. The TAB character should not be used.
491
492 The presentation is the one specified by 'indent -i4 -kr'.
493
494 Main priority in ffmpeg is simplicity and small code size (=less
495 bugs).
496
497 Comments: for functions visible from other modules, use the JavaDoc
498 format (see examples in @file{libav/utils.c}) so that a documentation
499 can be generated automatically.
500
501 @section Submitting patches
502
503 When you submit your patch, try to send a unified diff (diff '-u'
504 option). I cannot read other diffs :-)
505
506 Run the regression tests before submitting a patch so that you can
507 verify that there are no big problems.
508
509 Patches should be posted as base64 encoded attachments (or any other
510 encoding which ensures that the patch wont be trashed during 
511 transmission) to the ffmpeg-devel mailinglist, see 
512 @url{http://lists.sourceforge.net/lists/listinfo/ffmpeg-devel}
513
514 @section Regression tests
515
516 Before submitting a patch (or committing with CVS), you should at least
517 test that you did not break anything.
518
519 The regression test build a synthetic video stream and a synthetic
520 audio stream. Then these are encoded then decoded with all codecs or
521 formats. The CRC (or MD5) of each generated file is recorded in a
522 result file. Then a 'diff' is launched with the reference results and
523 the result file.
524
525 The regression test then goes on to test the ffserver code with a 
526 limited set of streams. It is important that this step runs correctly
527 as well.
528
529 Run 'make test' to test all the codecs.
530
531 Run 'make libavtest' to test all the codecs.
532
533 [Of course, some patches may change the regression tests results. In
534 this case, the regression tests reference results shall be modified
535 accordingly].
536
537 @bye