Update after the last API change.
[libav.git] / doc / faq.texi
CommitLineData
7ff56c72
FB
1\input texinfo @c -*- texinfo -*-
2
3@settitle FFmpeg FAQ
4@titlepage
5@sp 7
6@center @titlefont{FFmpeg FAQ}
7@sp 3
8@end titlepage
9
10
d485fed4
DB
11@chapter General Questions
12
13@section When will the next FFmpeg version be released? / Why are FFmpeg releases so few and far between?
14
15Like most open source projects FFmpeg suffers from a certain lack of
16manpower. For this reason the developers have to prioritize the work
17they do and putting out releases is not at the top of the list, fixing
18bugs and reviewing patches takes precedence. Please don't complain or
19request more timely and/or frequent releases unless you are willing to
20help out creating them.
21
22@section I have a problem with an old version of FFmpeg; where should I report it?
23Nowhere. Upgrade to the latest release or if there is no recent release upgrade
24to Subversion HEAD. You could also try to report it. Maybe you will get lucky and
25become the first person in history to get an answer different from "upgrade
26to Subversion HEAD".
27
28@section Why doesn't FFmpeg support feature [xyz]?
29
30Because no one has taken on that task yet. FFmpeg development is
31driven by the tasks that are important to the individual developers.
32If there is a feature that is important to you, the best way to get
4f1ab3ce 33it implemented is to undertake the task yourself or sponsor a developer.
d485fed4
DB
34
35@section FFmpeg does not support codec XXX. Can you include a Windows DLL loader to support it?
36
4f1ab3ce
DB
37No. Windows DLLs are not portable, bloated and often slow.
38Moreover FFmpeg strives to support all codecs natively.
39A DLL loader is not conducive to that goal.
d485fed4 40
831ec935 41@section My bug report/mail to ffmpeg-devel/user has not received any replies.
d485fed4
DB
42
43Likely reasons
44@itemize
45@item We are busy and haven't had time yet to read your report or
46investigate the issue.
47@item You didn't follow bugreports.html.
48@item You didn't use Subversion HEAD.
49@item You reported a segmentation fault without gdb output.
50@item You describe a problem but not how to reproduce it.
51@item It's unclear if you use ffmpeg as command line tool or use
52libav* from another application.
53@item You speak about a video having problems on playback but
54not what you use to play it.
55@item We have no faint clue what you are talking about besides
56that it is related to FFmpeg.
57@end itemize
58
59@section Is there a forum for FFmpeg? I do not like mailing lists.
60
242a2b7e
VP
61You may view our mailing lists with a more forum-alike look here:
62@url{http://dir.gmane.org/gmane.comp.video.ffmpeg.user},
d9fe7eb3 63but, if you post, please remember that our mailing list rules still apply there.
7ff56c72 64
cacf7199 65@section I cannot read this file although this format seems to be supported by ffmpeg.
7ff56c72 66
4f1ab3ce 67Even if ffmpeg can read the container format, it may not support all its
7ff56c72
FB
68codecs. Please consult the supported codec list in the ffmpeg
69documentation.
70
d485fed4
DB
71@section Which codecs are supported by Windows?
72
73Windows does not support standard formats like MPEG very well, unless you
831ec935 74install some additional codecs.
d485fed4
DB
75
76The following list of video codecs should work on most Windows systems:
77@table @option
78@item msmpeg4v2
79.avi/.asf
80@item msmpeg4
81.asf only
82@item wmv1
83.asf only
84@item wmv2
85.asf only
86@item mpeg4
831ec935 87Only if you have some MPEG-4 codec like ffdshow or Xvid installed.
d485fed4
DB
88@item mpeg1
89.mpg only
90@end table
91Note, ASF files often have .wmv or .wma extensions in Windows. It should also
92be mentioned that Microsoft claims a patent on the ASF format, and may sue
93or threaten users who create ASF files with non-Microsoft software. It is
94strongly advised to avoid ASF where possible.
95
96The following list of audio codecs should work on most Windows systems:
97@table @option
98@item adpcm_ima_wav
99@item adpcm_ms
100@item pcm
831ec935 101always
d485fed4 102@item mp3
831ec935 103If some MP3 codec like LAME is installed.
d485fed4
DB
104@end table
105
106
a28d9122
DB
107@chapter Compilation
108
109@section @code{error: can't find a register in class 'GENERAL_REGS' while reloading 'asm'}
110
111This is a bug in gcc. Do not report it to us. Instead, please report it to
112the gcc developers. Note that we will not add workarounds for gcc bugs.
113
5b43368d
DB
114Also note that (some of) the gcc developers believe this is not a bug or
115not a bug they should fix:
116@url{http://gcc.gnu.org/bugzilla/show_bug.cgi?id=11203}.
117Then again, some of them do not know the difference between an undecidable
118problem and an NP-hard problem...
a28d9122 119
d485fed4
DB
120@chapter Usage
121
831ec935 122@section ffmpeg does not work; what is wrong?
d485fed4 123
4f1ab3ce 124Try a @code{make distclean} in the ffmpeg source directory before the build. If this does not help see
d485fed4
DB
125(@url{http://ffmpeg.org/bugreports.html}).
126
831ec935 127@section How do I encode single pictures into movies?
7ff56c72 128
1fee8b3a
VP
129First, rename your pictures to follow a numerical sequence.
130For example, img1.jpg, img2.jpg, img3.jpg,...
131Then you may run:
7ff56c72
FB
132
133@example
a9d21e78 134 ffmpeg -f image2 -i img%d.jpg /tmp/a.mpg
7ff56c72
FB
135@end example
136
1fee8b3a 137Notice that @samp{%d} is replaced by the image number.
7ff56c72 138
1fee8b3a 139@file{img%03d.jpg} means the sequence @file{img001.jpg}, @file{img002.jpg}, etc...
7ff56c72 140
1fee8b3a 141The same logic is used for any image format that ffmpeg reads.
7ff56c72 142
5965e1a9 143@section How do I encode movie to single pictures?
a9d21e78 144
3c88ea24 145Use:
ad21ad45 146
ad21ad45 147@example
3c88ea24 148 ffmpeg -i movie.mpg movie%d.jpg
ad21ad45
VP
149@end example
150
3c88ea24
BC
151The @file{movie.mpg} used as input will be converted to
152@file{movie1.jpg}, @file{movie2.jpg}, etc...
ad21ad45
VP
153
154Instead of relying on file format self-recognition, you may also use
155@table @option
156@item -vcodec ppm
157@item -vcodec png
158@item -vcodec mjpeg
159@end table
160to force the encoding.
161
162Applying that to the previous example:
163@example
3c88ea24 164 ffmpeg -i movie.mpg -f image2 -vcodec mjpeg menu%d.jpg
ad21ad45
VP
165@end example
166
167Beware that there is no "jpeg" codec. Use "mjpeg" instead.
168
5965e1a9 169@section Why do I see a slight quality degradation with multithreaded MPEG* encoding?
f2fe8752
RS
170
171For multithreaded MPEG* encoding, the encoded slices must be independent,
cacf7199
MM
172otherwise thread n would practically have to wait for n-1 to finish, so it's
173quite logical that there is a small reduction of quality. This is not a bug.
f2fe8752 174
5965e1a9 175@section How can I read from the standard input or write to the standard output?
47d944d2 176
831ec935 177Use @file{-} as file name.
47d944d2 178
cbf7878e 179@section Why does FFmpeg not decode audio in VOB files?
db0e9b03 180
cbf7878e
DB
181The audio is AC-3 (a.k.a. A/52). AC-3 decoding is an optional component in FFmpeg
182as the component that handles AC-3 decoding is currently released under the GPL.
183Enable AC-3 decoding with @code{./configure --enable-gpl}. Take care: By
184enabling AC-3, you automatically change the license of libavcodec from
db0e9b03
FB
185LGPL to GPL.
186
9ba42958 187@section Why does the chrominance data seem to be sampled at a different time from the luminance data on bt8x8 captures on Linux?
7c0dc383 188
115329f1 189This is a well-known bug in the bt8x8 driver. For 2.4.26 there is a patch at
0fa5f24c 190(@url{http://svn.ffmpeg.org/michael/trunk/patches/bttv-420-2.4.26.patch?view=co}). This may also
cacf7199 191apply cleanly to other 2.4-series kernels.
7c0dc383 192
87759af9 193@section How do I avoid the ugly aliasing artifacts in bt8x8 captures on Linux?
7c0dc383 194
cacf7199 195Pass 'combfilter=1 lumafilter=1' to the bttv driver. Note though that 'combfilter=1'
0fa5f24c
DB
196will cause somewhat too strong filtering. A fix is to apply (@url{http://svn.ffmpeg.org/michael/trunk/patches/bttv-comb-2.4.26.patch?view=co})
197or (@url{http://svn.ffmpeg.org/michael/trunk/patches/bttv-comb-2.6.6.patch?view=co})
cacf7199 198and pass 'combfilter=2'.
7c0dc383 199
9ba42958 200@section -f jpeg doesn't work.
fc3e9202 201
a9d21e78 202Try '-f image2 test%d.jpg'.
fc3e9202 203
cacf7199 204@section Why can I not change the framerate?
73468318 205
9ba42958 206Some codecs, like MPEG-1/2, only allow a small number of fixed framerates.
cacf7199 207Choose a different codec with the -vcodec command line option.
73468318 208
842eabc5 209@section How do I encode Xvid or DivX video with ffmpeg?
f62e9435 210
842eabc5 211Both Xvid and DivX (version 4+) are implementations of the ISO MPEG-4
f62e9435 212standard (note that there are many other coding formats that use this
831ec935 213same standard). Thus, use '-vcodec mpeg4' to encode in these formats. The
c9a08db9 214default fourcc stored in an MPEG-4-coded file will be 'FMP4'. If you want
115329f1
DB
215a different fourcc, use the '-vtag' option. E.g., '-vtag xvid' will
216force the fourcc 'xvid' to be stored as the video fourcc rather than the
f62e9435
MM
217default.
218
18e7d87c 219@section How do I encode videos which play on the iPod?
b4aead58
MN
220
221@table @option
18e7d87c 222@item needed stuff
095247b1 223-acodec libfaac -vcodec mpeg4 width<=320 height<=240
18e7d87c 224@item working stuff
b4aead58 2254mv, title
18e7d87c
DB
226@item non-working stuff
227B-frames
b4aead58 228@item example command line
cd0e37d3 229ffmpeg -i input -acodec libfaac -ab 128kb -vcodec mpeg4 -b 1200kb -mbd 2 -flags +4mv -trellis 2 -aic 2 -cmp 2 -subcmp 2 -s 320x180 -title X output.mp4
b4aead58
MN
230@end table
231
18e7d87c 232@section How do I encode videos which play on the PSP?
b4aead58
MN
233
234@table @option
18e7d87c 235@item needed stuff
095247b1 236-acodec libfaac -vcodec mpeg4 width*height<=76800 width%16=0 height%16=0 -ar 24000 -r 30000/1001 or 15000/1001 -f psp
18e7d87c 237@item working stuff
b4aead58 2384mv, title
18e7d87c
DB
239@item non-working stuff
240B-frames
b4aead58 241@item example command line
cd0e37d3 242ffmpeg -i input -acodec libfaac -ab 128kb -vcodec mpeg4 -b 1200kb -ar 24000 -mbd 2 -flags +4mv -trellis 2 -aic 2 -cmp 2 -subcmp 2 -s 368x192 -r 30000/1001 -title X -f psp output.mp4
f7709b1a 243@item needed stuff for H.264
b96e074d 244-acodec libfaac -vcodec libx264 width*height<=76800 width%16=0? height%16=0? -ar 48000 -coder 1 -r 30000/1001 or 15000/1001 -f psp
f7709b1a
MN
245@item working stuff for H.264
246title, loop filter
247@item non-working stuff for H.264
248CAVLC
249@item example command line
b96e074d 250ffmpeg -i input -acodec libfaac -ab 128kb -vcodec libx264 -b 1200kb -ar 48000 -mbd 2 -coder 1 -cmp 2 -subcmp 2 -s 368x192 -r 30000/1001 -title X -f psp -flags loop -trellis 2 -partitions parti4x4+parti8x8+partp4x4+partp8x8+partb8x8 output.mp4
084cadab
DS
251@item higher resolution for newer PSP firmwares, width<=480, height<=272
252-vcodec libx264 -level 21 -coder 1 -f psp
253@item example command line
254ffmpeg -i input -acodec libfaac -ab 128kb -ac 2 -ar 48000 -vcodec libx264 -level 21 -b 640kb -coder 1 -f psp -flags +loop -trellis 2 -partitions +parti4x4+parti8x8+partp4x4+partp8x8+partb8x8 -g 250 -s 480x272 output.mp4
b4aead58
MN
255@end table
256
16ab894e 257@section Which are good parameters for encoding high quality MPEG-4?
c62997a5 258
cd0e37d3 259'-mbd rd -flags +4mv+aic -trellis 2 -cmp 2 -subcmp 2 -g 300 -pass 1/2',
16ab894e 260things to try: '-bf 2', '-flags qprd', '-flags mv0', '-flags skiprd'.
c62997a5 261
16ab894e 262@section Which are good parameters for encoding high quality MPEG-1/MPEG-2?
c62997a5 263
cd0e37d3 264'-mbd rd -trellis 2 -cmp 2 -subcmp 2 -g 100 -pass 1/2'
16ab894e
DB
265but beware the '-g 100' might cause problems with some decoders.
266Things to try: '-bf 2', '-flags qprd', '-flags mv0', '-flags skiprd.
c62997a5 267
f278709c 268@section Interlaced video looks very bad when encoded with ffmpeg, what is wrong?
c62997a5 269
16ab894e
DB
270You should use '-flags +ilme+ildct' and maybe '-flags +alt' for interlaced
271material, and try '-top 0/1' if the result looks really messed-up.
c62997a5 272
99f6278e 273@section How can I read DirectShow files?
2c29781d 274
99f6278e
DB
275If you have built FFmpeg with @code{./configure --enable-avisynth}
276(only possible on MinGW/Cygwin platforms),
277then you may use any file that DirectShow can read as input.
278(Be aware that this feature has been recently added,
279so you will need to help yourself in case of problems.)
2c29781d
VP
280
281Just create an "input.avs" text file with this single line ...
282@example
283 DirectShowSource("C:\path to your file\yourfile.asf")
284@end example
99f6278e 285... and then feed that text file to FFmpeg:
2c29781d
VP
286@example
287 ffmpeg -i input.avs
288@end example
289
290For ANY other help on Avisynth, please visit @url{http://www.avisynth.org/}.
291
f7994861
VP
292@section How can I join video files?
293
5449190f 294A few multimedia containers (MPEG-1, MPEG-2 PS, DV) allow to join video files by
f7994861
VP
295merely concatenating them.
296
297Hence you may concatenate your multimedia files by first transcoding them to
298these privileged formats, then using the humble @code{cat} command (or the
5449190f 299equally humble @code{copy} under Windows), and finally transcoding back to your
f7994861
VP
300format of choice.
301
302@example
303ffmpeg -i input1.avi -sameq intermediate1.mpg
304ffmpeg -i input2.avi -sameq intermediate2.mpg
305cat intermediate1.mpg intermediate2.mpg > intermediate_all.mpg
306ffmpeg -i intermediate_all.mpg -sameq output.avi
307@end example
308
309Notice that you should either use @code{-sameq} or set a reasonably high
310bitrate for your intermediate and output files, if you want to preserve
311video quality.
312
5449190f 313Also notice that you may avoid the huge intermediate files by taking advantage
f7994861
VP
314of named pipes, should your platform support it:
315
316@example
317mkfifo intermediate1.mpg
318mkfifo intermediate2.mpg
319ffmpeg -i input1.avi -sameq -y intermediate1.mpg < /dev/null &
320ffmpeg -i input2.avi -sameq -y intermediate2.mpg < /dev/null &
321cat intermediate1.mpg intermediate2.mpg |\
095247b1 322ffmpeg -f mpeg -i - -sameq -vcodec mpeg4 -acodec libmp3lame output.avi
f7994861
VP
323@end example
324
325Similarly, the yuv4mpegpipe format, and the raw video, raw audio codecs also
326allow concatenation, and the transcoding step is almost lossless.
327
328For example, let's say we want to join two FLV files into an output.flv file:
329
330@example
331mkfifo temp1.a
332mkfifo temp1.v
333mkfifo temp2.a
334mkfifo temp2.v
335mkfifo all.a
336mkfifo all.v
337ffmpeg -i input1.flv -vn -f u16le -acodec pcm_s16le -ac 2 -ar 44100 - > temp1.a < /dev/null &
338ffmpeg -i input2.flv -vn -f u16le -acodec pcm_s16le -ac 2 -ar 44100 - > temp2.a < /dev/null &
339ffmpeg -i input1.flv -an -f yuv4mpegpipe - > temp1.v < /dev/null &
340ffmpeg -i input2.flv -an -f yuv4mpegpipe - > temp2.v < /dev/null &
341cat temp1.a temp2.a > all.a &
342cat temp1.v temp2.v > all.v &
343ffmpeg -f u16le -acodec pcm_s16le -ac 2 -ar 44100 -i all.a \
344 -f yuv4mpegpipe -i all.v \
345 -sameq -y output.flv
346rm temp[12].[av] all.[av]
347@end example
348
fa78d895 349@section FFmpeg does not adhere to the -maxrate setting, some frames are bigger than maxrate/fps.
3b36389a 350
fa78d895 351Read the MPEG spec about video buffer verifier.
3b36389a 352
fa78d895 353@section I want CBR, but no matter what I do frame sizes differ.
3b36389a 354
fa78d895
DB
355You do not understand what CBR is, please read the MPEG spec.
356Read about video buffer verifier and constant bitrate.
357The one sentence summary is that there is a buffer and the input rate is
3b36389a
MN
358constant, the output can vary as needed.
359
fa78d895 360@section How do I check if a stream is CBR?
3b36389a
MN
361
362To quote the MPEG-2 spec:
363"There is no way to tell that a bitstream is constant bitrate without
364examining all of the vbv_delay values and making complicated computations."
365
86852499 366
7ff56c72
FB
367@chapter Development
368
5965e1a9 369@section Are there examples illustrating how to use the FFmpeg libraries, particularly libavcodec and libavformat?
a93b9dba 370
cacf7199 371Yes. Read the Developers Guide of the FFmpeg documentation. Alternatively,
115329f1 372examine the source code for one of the many open source projects that
831ec935 373already incorporate FFmpeg at (@url{projects.html}).
a93b9dba 374
5965e1a9 375@section Can you support my C compiler XXX?
7ff56c72 376
e867d9b9
DB
377It depends. If your compiler is C99-compliant, then patches to support
378it are likely to be welcome if they do not pollute the source code
379with @code{#ifdef}s related to the compiler.
7ff56c72 380
a9d5a448 381@section Is Microsoft Visual C++ supported?
2f0b8fbb 382
a9d5a448
DB
383No. Microsoft Visual C++ is not compliant to the C99 standard and does
384not - among other things - support the inline assembly used in FFmpeg.
19671d3f 385If you wish to use MSVC++ for your
c1989552 386project then you can link the MSVC++ code with libav* as long as
2f0b8fbb 387you compile the latter with a working C compiler. For more information, see
c1989552
RP
388the @emph{Microsoft Visual C++ compatibility} section in the FFmpeg
389documentation.
2f0b8fbb 390
c1989552 391There have been efforts to make FFmpeg compatible with MSVC++ in the
2f0b8fbb 392past. However, they have all been rejected as too intrusive, especially
a9d5a448 393since MinGW does the job adequately. None of the core developers
c1989552 394work with MSVC++ and thus this item is low priority. Should you find
2f0b8fbb
DB
395the silver bullet that solves this problem, feel free to shoot it at us.
396
19671d3f
RP
397We strongly recommend you to move over from MSVC++ to MinGW tools.
398
5965e1a9 399@section Can I use FFmpeg or libavcodec under Windows?
7ff56c72 400
c1989552
RP
401Yes, but the Cygwin or MinGW tools @emph{must} be used to compile FFmpeg.
402Read the @emph{Windows} section in the FFmpeg documentation to find more
403information.
7ff56c72 404
46a845d0 405To get help and instructions for building FFmpeg under Windows, check out
e2ef53fc 406the FFmpeg Windows Help Forum at
ab5ce4ae 407@url{http://ffmpeg.arrozcru.org/}.
e2ef53fc 408
5965e1a9 409@section Can you add automake, libtool or autoconf support?
7ff56c72 410
e867d9b9 411No. These tools are too bloated and they complicate the build.
7ff56c72 412
5965e1a9 413@section Why not rewrite ffmpeg in object-oriented C++?
fbf33e4f 414
831ec935 415FFmpeg is already organized in a highly modular manner and does not need to
115329f1 416be rewritten in a formal object language. Further, many of the developers
cacf7199 417favor straight C; it works for them. For more arguments on this matter,
bc155732 418read "Programming Religion" at (@url{http://www.tux.org/lkml/#s15}).
cacf7199 419
5965e1a9 420@section Why are the ffmpeg programs devoid of debugging symbols?
cacf7199
MM
421
422The build process creates ffmpeg_g, ffplay_g, etc. which contain full debug
831ec935 423information. Those binaries are stripped to create ffmpeg, ffplay, etc. If
cacf7199 424you need the debug information, used the *_g versions.
fbf33e4f 425
5965e1a9 426@section I do not like the LGPL, can I contribute code under the GPL instead?
61a1e081 427
e180129f 428Yes, as long as the code is optional and can easily and cleanly be placed
b250f9c6 429under #if CONFIG_GPL without breaking anything. So for example a new codec
831ec935 430or filter would be OK under GPL while a bug fix to LGPL code would not.
61a1e081 431
e180129f 432@section I want to compile xyz.c alone but my compiler produced many errors.
61a1e081 433
e180129f
DB
434Common code is in its own files in libav* and is used by the individual
435codecs. They will not work without the common parts, you have to compile
436the whole libav*. If you wish, disable some parts with configure switches.
437You can also try to hack it and remove more, but if you had problems fixing
438the compilation failure then you are probably not qualified for this.
61a1e081 439
4cb3aa09
PI
440@section I'm using libavcodec from within my C++ application but the linker complains about missing symbols which seem to be available.
441
442FFmpeg is a pure C project, so to use the libraries within your C++ application
443you need to explicitly state that you are using a C library. You can do this by
444encompassing your FFmpeg includes using @code{extern "C"}.
445
446See @url{http://www.parashift.com/c++-faq-lite/mixing-c-and-cpp.html#faq-32.3}
447
2cab6401 448@section I have a file in memory / a API different from *open/*read/ libc how do I use it with libavformat?
f994f61e 449
1c1b5a40
DB
450You have to implement a URLProtocol, see libavformat/file.c in FFmpeg
451and libmpdemux/demux_lavf.c in MPlayer sources.
f994f61e 452
e9766450
RP
453@section I get "No compatible shell script interpreter found." in MSys.
454
455The standard MSys bash (2.04) is broken. You need to install 2.05 or later.
456
e75f8997
RP
457@section I get "./configure: line <xxx>: pr: command not found" in MSys.
458
459The standard MSys install doesn't come with pr. You need to get it from the coreutils package.
460
5c159f40 461@section I tried to pass RTP packets into a decoder, but it doesn't work.
b72ad042 462
241fb0c4
LB
463RTP is a container format like any other, you must first depacketize the
464codec frames/samples stored in RTP and then feed to the decoder.
b72ad042 465
7c1ebf17 466@section Where can I find libav* headers for Pascal/Delphi?
04704a78
MN
467
468see @url{http://www.iversenit.dk/dev/ffmpeg-headers/}
469
7c1ebf17 470@section Where is the documentation about ffv1, msmpeg4, asv1, 4xm?
afe28f7c 471
0fa5f24c 472see @url{http://svn.ffmpeg.org/michael/trunk/docs/}
afe28f7c 473
29569571 474@section How do I feed H.263-RTP (and other codecs in RTP) to libavcodec?
8749180c 475
241fb0c4 476Even if peculiar since it is network oriented, RTP is a container like any
33ed2d84
LB
477other. You have to @emph{demux} RTP before feeding the payload to libavcodec.
478In this specific case please look at RFC 4629 to see how it should be done.
8749180c 479
29569571 480@section AVStream.r_frame_rate is wrong, it is much larger than the framerate.
70fd3975
MN
481
482r_frame_rate is NOT the average framerate, it is the smallest framerate
29569571
DB
483that can accurately represent all timestamps. So no, it is not
484wrong if it is larger than the average!
485For example, if you have mixed 25 and 30 fps content, then r_frame_rate
70fd3975
MN
486will be 150.
487
7ff56c72 488@bye