overdue format updates
[libav.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). (no example yet, the API is likely to
471 evolve).
472 @end itemize
473
474 @section Integrating libavcodec or libavformat in your program
475
476 You can integrate all the source code of the libraries to link them
477 statically to avoid any version problem. All you need is to provide a
478 'config.mak' and a 'config.h' in the parent directory. See the defines
479 generated by ./configure to understand what is needed.
480
481 You can use libavcodec or libavformat in your commercial program, but
482 @emph{any patch you make must be published}. The best way to proceed is
483 to send your patches to the ffmpeg mailing list.
484
485 @section Coding Rules
486
487 ffmpeg is programmed in ANSI C language. GCC extensions are
488 tolerated. Indent size is 4. The TAB character should not be used.
489
490 The presentation is the one specified by 'indent -i4 -kr'.
491
492 Main priority in ffmpeg is simplicity and small code size (=less
493 bugs).
494
495 Comments: for functions visible from other modules, use the JavaDoc
496 format (see examples in @file{libav/utils.c}) so that a documentation
497 can be generated automatically.
498
499 @section Submitting patches
500
501 When you submit your patch, try to send a unified diff (diff '-u'
502 option). I cannot read other diffs :-)
503
504 Run the regression tests before submitting a patch so that you can
505 verify that there are no big problems.
506
507 Patches should be posted as base64 encoded attachments (or any other
508 encoding which ensures that the patch wont be trashed during
509 transmission) to the ffmpeg-devel mailinglist, see
510 @url{http://lists.sourceforge.net/lists/listinfo/ffmpeg-devel}
511
512 @section Regression tests
513
514 Before submitting a patch (or committing with CVS), you should at least
515 test that you did not break anything.
516
517 The regression test build a synthetic video stream and a synthetic
518 audio stream. Then these are encoded then decoded with all codecs or
519 formats. The CRC (or MD5) of each generated file is recorded in a
520 result file. Then a 'diff' is launched with the reference results and
521 the result file.
522
523 The regression test then goes on to test the ffserver code with a
524 limited set of streams. It is important that this step runs correctly
525 as well.
526
527 Run 'make test' to test all the codecs.
528
529 Run 'make libavtest' to test all the codecs.
530
531 [Of course, some patches may change the regression tests results. In
532 this case, the regression tests reference results shall be modified
533 accordingly].
534
535 @bye