overdue format updates
[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
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
f151ddac
FB
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.
9181577c 38
6bf40f39 39@section Video and Audio file format conversion
9181577c
FB
40
41* ffmpeg can use any supported file format and protocol as input:
42
43Examples:
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
6bf40f39 87* You can also do audio and video conversions at the same time:
9181577c
FB
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
6bf40f39 112 This is a typical DVD ripper example, input from a VOB file, output
9181577c
FB
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
6bf40f39 118 configuring. The mapping is particularly useful for DVD transcoding
9181577c
FB
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
6bf40f39 140 uses the same audio and video parameter for the outputs as the one
9181577c
FB
141 specified for the inputs.
142
143@section Main options
144
145@table @samp
146@item -L
147show license
148@item -h
149 show help
150@item -formats
151show available formats, codecs, protocols, ...
152@item -f fmt
153force format
154@item -i filename
155input file name
156
157@item -y
158overwrite output files
159
160@item -t duration
161set the recording time in seconds. @code{hh:mm:ss[.xxx]} syntax is also
162supported.
163
164@item -title string
165set the title
166
167@item -author string
168set the author
169
170@item -copyright string
171set the copyright
172
173@item -comment string
174set the comment
175
176@item -b bitrate
177set video bitrate (in kbit/s)
178@end table
179
180@section Video Options
181
182@table @samp
183@item -s size
184set frame size [160x128]
185@item -r fps
186set frame rate [25]
187@item -b bitrate
188set the video bitrate in kbit/s [200]
189@item -vn
190disable video recording [no]
191@item -bt tolerance
192set video bitrate tolerance (in kbit/s)
193@item -sameq
194use same video quality as source (implies VBR)
195
196@item -pass n
197select 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
200select two pass log file name
201
202@end table
203
204@section Audio Options
205
206@table @samp
207@item -ab bitrate
208set 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
223set input stream mapping
224@item -g gop_size
225set the group of picture size
226@item -intra
227use only intra frames
228@item -qscale q
229use fixed video quantiser scale (VBR)
230@item -qmin q
231min video quantiser scale (VBR)
232@item -qmax q
233max video quantiser scale (VBR)
234@item -qdiff q
235max difference between the quantiser scale (VBR)
236@item -qblur blur
237video quantiser scale blur (VBR)
238@item -qcomp compression
239video quantiser scale compression (VBR)
240@item -vd device
241set video device
242@item -vcodec codec
243force video codec
244@item -me method
245set motion estimation method
246@item -bf frames
247use 'frames' B frames (only MPEG-4)
248@item -hq
249activate high quality settings
250@item -4mv
251use four motion vector by macroblock (only MPEG-4)
252@item -ad device
253set audio device
254@item -acodec codec
255force audio codec
256@item -deinterlace
257deinterlace pictures
258@item -benchmark
259add timings for benchmarking
260@item -hex
261dump each input packet
262@item -psnr
263calculate PSNR of compressed frames
264@item -vstats
265dump video coding statistics to file
266@end table
267
268@section Protocols
269
47d944d2
FB
270The filename can be @file{-} to read from the standard input or to write
271to the standard output.
9181577c
FB
272
273ffmpeg 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
6bf40f39 303 completely motion estimation (you have only I frames, which means it
9181577c
FB
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
321You can use the @code{-formats} option to have an exhaustive list.
322
323@section File Formats
324
6bf40f39 325FFmpeg supports the following file formats through the @code{libavformat}
0699d2fe 326library:
9181577c
FB
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
9181577c
FB
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
0699d2fe 351@item Raw MPEG4 video @tab X @tab X
9181577c
FB
352@item DV @tab @tab X
353@tab Only the video track is decoded.
701b603d
MM
354@item 4xm @tab @tab X
355@tab 4X Technologies format, used in some games
9181577c
FB
356@end multitable
357
358@code{X} means that the encoding (resp. decoding) is supported.
359
0699d2fe
FB
360@section Image Formats
361
362FFmpeg can read and write images for each frame of a video sequence. The
363following 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
9181577c
FB
376@section Video Codecs
377
378@multitable @columnfractions .4 .1 .1 .7
379@item Supported Codec @tab Encoding @tab Decoding @tab Comments
4745b5bf 380@item MPEG1 video @tab X @tab X
9181577c
FB
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
701b603d 387@item WMV8 @tab X @tab X @tab Not completely working
9181577c
FB
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
4745b5bf 391@item Huff YUV @tab X @tab X
701b603d
MM
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
9181577c
FB
399@end multitable
400
401@code{X} means that the encoding (resp. decoding) is supported.
402
60837265
FB
403Check at @url{http://www.mplayerhq.hu/~michael/codec-features.html} to
404get a precise comparison of FFmpeg MPEG4 codec compared to the other
405solutions.
406
9181577c
FB
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
6bf40f39 413@tab MP3 encoding is supported through the external library LAME
9181577c
FB
414@item AC3 @tab IX @tab X
415@tab liba52 is used internally for decoding.
34d7008d 416@item Vorbis @tab X @tab X
6bf40f39 417@tab supported through the external library libvorbis.
4745b5bf 418@item WMA V1/V2 @tab @tab X
701b603d
MM
419@item Microsoft ADPCM @tab X @tab X
420@item IMA ADPCM @tab X @tab X
9181577c
FB
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
426performances on systems without hardware floating point support).
427
47d944d2
FB
428@chapter Platform Specific information
429
430@section Linux
431
432ffmpeg should be compiled with at least GCC 2.95.3. GCC 3.2 is the
6bf40f39 433preferred compiler now for ffmpeg. All future optimizations will depend on
47d944d2
FB
434features only found in GCC 3.2.
435
436@section BSD
437
438@section Windows
439
440@section MacOS X
441
442@section BeOS
443
444The configure script should guess the configuration itself.
445Networking support is currently not finished.
446errno issues fixed by Andrew Bachmann.
447
448Old stuff:
449
450