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